diff --git a/district scripts/SWF/GateFlow5.py b/district-scripts/SWF/GateFlow5.py similarity index 100% rename from district scripts/SWF/GateFlow5.py rename to district-scripts/SWF/GateFlow5.py diff --git a/district scripts/SWF/GateFlow_MonthlyPumpBackFill.py b/district-scripts/SWF/GateFlow_MonthlyPumpBackFill.py similarity index 100% rename from district scripts/SWF/GateFlow_MonthlyPumpBackFill.py rename to district-scripts/SWF/GateFlow_MonthlyPumpBackFill.py diff --git a/district scripts/SWF/GateFlow_PumpBackFill.py b/district-scripts/SWF/GateFlow_PumpBackFill.py similarity index 100% rename from district scripts/SWF/GateFlow_PumpBackFill.py rename to district-scripts/SWF/GateFlow_PumpBackFill.py diff --git a/district scripts/SWF/GateSettings.py b/district-scripts/SWF/GateSettings.py similarity index 100% rename from district scripts/SWF/GateSettings.py rename to district-scripts/SWF/GateSettings.py diff --git a/district scripts/SWF/InflowCalcComputeEvapAsFlow.py b/district-scripts/SWF/InflowCalcComputeEvapAsFlow.py similarity index 100% rename from district scripts/SWF/InflowCalcComputeEvapAsFlow.py rename to district-scripts/SWF/InflowCalcComputeEvapAsFlow.py diff --git a/district scripts/SWF/InflowCalcComputedInflow.py b/district-scripts/SWF/InflowCalcComputedInflow.py similarity index 100% rename from district scripts/SWF/InflowCalcComputedInflow.py rename to district-scripts/SWF/InflowCalcComputedInflow.py diff --git a/district scripts/SWF/__init__.py b/district-scripts/SWF/__init__.py similarity index 100% rename from district scripts/SWF/__init__.py rename to district-scripts/SWF/__init__.py diff --git a/district scripts/SWL/Big3-GateFlow.py b/district-scripts/SWL/Big3-GateFlow.py similarity index 100% rename from district scripts/SWL/Big3-GateFlow.py rename to district-scripts/SWL/Big3-GateFlow.py diff --git a/district scripts/SWL/Big3-InflowCalcMultipleActions.py b/district-scripts/SWL/Big3-InflowCalcMultipleActions.py similarity index 100% rename from district scripts/SWL/Big3-InflowCalcMultipleActions.py rename to district-scripts/SWL/Big3-InflowCalcMultipleActions.py diff --git a/district scripts/SWL/Millwd-Tri-Lks-GateFlow.py b/district-scripts/SWL/Millwd-Tri-Lks-GateFlow.py similarity index 100% rename from district scripts/SWL/Millwd-Tri-Lks-GateFlow.py rename to district-scripts/SWL/Millwd-Tri-Lks-GateFlow.py diff --git a/district scripts/SWL/Millwd-Tri-Lks-InflowCalcMultipleActions.py b/district-scripts/SWL/Millwd-Tri-Lks-InflowCalcMultipleActions.py similarity index 100% rename from district scripts/SWL/Millwd-Tri-Lks-InflowCalcMultipleActions.py rename to district-scripts/SWL/Millwd-Tri-Lks-InflowCalcMultipleActions.py diff --git a/district scripts/SWL/WhiteR-GateFlow.py b/district-scripts/SWL/WhiteR-GateFlow.py similarity index 100% rename from district scripts/SWL/WhiteR-GateFlow.py rename to district-scripts/SWL/WhiteR-GateFlow.py diff --git a/district scripts/SWL/WhiteR-InflowCalcMultipleActions.py b/district-scripts/SWL/WhiteR-InflowCalcMultipleActions.py similarity index 100% rename from district scripts/SWL/WhiteR-InflowCalcMultipleActions.py rename to district-scripts/SWL/WhiteR-InflowCalcMultipleActions.py diff --git a/district scripts/SWL/__init__.py b/district-scripts/SWL/__init__.py similarity index 100% rename from district scripts/SWL/__init__.py rename to district-scripts/SWL/__init__.py diff --git a/district scripts/SWT/GateFlowGroup1.py b/district-scripts/SWT/GateFlowGroup1.py similarity index 100% rename from district scripts/SWT/GateFlowGroup1.py rename to district-scripts/SWT/GateFlowGroup1.py diff --git a/district scripts/SWT/GateFlowGroup2.py b/district-scripts/SWT/GateFlowGroup2.py similarity index 100% rename from district scripts/SWT/GateFlowGroup2.py rename to district-scripts/SWT/GateFlowGroup2.py diff --git a/district scripts/SWT/GateFlowGroup3.py b/district-scripts/SWT/GateFlowGroup3.py similarity index 100% rename from district scripts/SWT/GateFlowGroup3.py rename to district-scripts/SWT/GateFlowGroup3.py diff --git a/district scripts/SWT/GateFlowGroup4.py b/district-scripts/SWT/GateFlowGroup4.py similarity index 100% rename from district scripts/SWT/GateFlowGroup4.py rename to district-scripts/SWT/GateFlowGroup4.py diff --git a/district scripts/SWT/GateFlowGroup5.py b/district-scripts/SWT/GateFlowGroup5.py similarity index 100% rename from district scripts/SWT/GateFlowGroup5.py rename to district-scripts/SWT/GateFlowGroup5.py diff --git a/district scripts/SWT/GateFlowGroup6.py b/district-scripts/SWT/GateFlowGroup6.py similarity index 100% rename from district scripts/SWT/GateFlowGroup6.py rename to district-scripts/SWT/GateFlowGroup6.py diff --git a/district scripts/SWT/GateFlowGroup7.py b/district-scripts/SWT/GateFlowGroup7.py similarity index 100% rename from district scripts/SWT/GateFlowGroup7.py rename to district-scripts/SWT/GateFlowGroup7.py diff --git a/district scripts/SWT/GateFlowGroup8.py b/district-scripts/SWT/GateFlowGroup8.py similarity index 100% rename from district scripts/SWT/GateFlowGroup8.py rename to district-scripts/SWT/GateFlowGroup8.py diff --git a/district scripts/SWT/GateFlowGroup9.py b/district-scripts/SWT/GateFlowGroup9.py similarity index 100% rename from district scripts/SWT/GateFlowGroup9.py rename to district-scripts/SWT/GateFlowGroup9.py diff --git a/district scripts/SWT/GateFlowHUDS-WS.py b/district-scripts/SWT/GateFlowHUDS-WS.py similarity index 100% rename from district scripts/SWT/GateFlowHUDS-WS.py rename to district-scripts/SWT/GateFlowHUDS-WS.py diff --git a/district scripts/SWT/__init__.py b/district-scripts/SWT/__init__.py similarity index 100% rename from district scripts/SWT/__init__.py rename to district-scripts/SWT/__init__.py diff --git a/docs/PUBLIC_API.md b/docs/PUBLIC_API.md new file mode 100644 index 0000000..9a98f14 --- /dev/null +++ b/docs/PUBLIC_API.md @@ -0,0 +1,97 @@ +# ScriptableCalc Public API + +This document lists the public API for implementations of `ScriptableCalc`. These classes provide scriptable interfaces for various calculation and data management tasks within the REGI environment. + +## Common Base: AbstractScriptableCalc +Most implementations inherit from `AbstractScriptableCalc`, which provides access to core domain objects. + +- `getRegiDomain()`: Returns the `RegiDomain` instance associated with this calculator. +- `getManagerId()`: Returns the `ManagerId` identifying the user or session. +- `getManagerIdProvider()`: Returns a provider for the `ManagerId`. +- `getRegiTimeZone()`: Returns the `TimeZone` of the current `RegiDomain`. + +--- + +## Implementations + +### ScriptableExportTSAssociationsImpl +Handles exporting time series associations. (Found usages in `/regi-headless/src/test/resources/usace/rowcps/headless/examples`) + +- `exportAllTSAssociations(String fileLoc, String lineDelimiter, String valueDelimiter)`: Exports all time series associations for all projects to the specified file. +- `exportTSAssociations(String projectId, String fileLoc, String lineDelimiter, String valueDelimiter)`: Exports time series associations for a specific project to the specified file. + +### ScriptableExportSigStagesImpl +Handles exporting significant stages to a file. + +- `exportSigStages(String file)`: Exports significant stages to the specified file path. +- `setOffice(String office)`: Sets the office ID to be used for the export. +- `getOffice()`: Returns the current office ID. + +### ScriptableImportSigStagesImpl +Handles importing significant stages from a file. + +- `importSigStages(String file, Date effectiveDate)`: Imports significant stages from the specified file, using the provided effective date. + +### RetrieveSigStagesImpl +Retrieves significant stages from external sources and writes them to CSV. + +- `retrieveSigstages(String sourceFile, String outputFile, int milliDelay)`: Reads NWS names from a source file and writes retrieved stages to an output file with a specified delay between requests. +- `setCSVHeader(String csvHeader)`: Sets a custom header for the generated CSV file. +- `getCSVHeader()`: Returns the current CSV header string. +- `setParameter(String parameter)`: Sets the parameter name for retrieval (e.g., Stage). +- `getParameter()`: Returns the current parameter name. +- `setParameterType(String parameterType)`: Sets the parameter type (e.g., Inst). +- `getParameterType()`: Returns the current parameter type. +- `setDuration(String duration)`: Sets the duration for retrieval (e.g., 0). +- `getDuration()`: Returns the current duration. +- `setOffice(String office)`: Sets the office ID for retrieval. +- `getOffice()`: Returns the current office ID. +- `setSpecifiedLevelOverride(Type type, String overrideText)`: Sets an override for a specific level type. +- `getSpecifiedLevelOverride(Type type)`: Returns the override text for a specific level type. + +### ScriptableGateFlowImpl +Computes gate flows for locations. Found usages in `/district scripts`. + +- `computeAll(String officeId, String locationId, Date start, Date end)`: Computes all gate flows for a location within the specified date range. (Used in scripts) +- `computeAll(String officeId, String[] locationIds, Date start, Date end)`: Computes all gate flows for multiple locations within the specified date range. +- `computeFlowGroup(String officeId, String locationId, Date start, Date end, String groupId)`: Computes gate flows for a specific group at a location. (Used in scripts) +- `computeFlowGroup(String officeId, String[] locationIds, Date start, Date end, String groupId)`: Computes gate flows for a specific group across multiple locations. + +### ScriptableGateSettingsImpl +Manages and creates gate settings. Found usages in `/district scripts`. + +- `createGateSettings(String officeId, String locationStr, Date startDate, Date end)`: Creates gate settings for all outlets at a location. +- `createGateSettingsOutlet(String officeId, String locationStr, Date startDate, Date end, String outletId)`: Creates gate settings for a specific outlet. +- `createGateSettingsOutletFromTs(String officeId, String locationStr, Date startDate, Date end, String outletId, String tsId)`: Creates gate settings for an outlet using a specific time series as input. (Used in scripts) +- `createGateSettingsGroup(String officeId, String locationStr, Date startDate, Date end, String groupId)`: Creates gate settings for a specific group of outlets. + +### ScriptableInflowImpl +Handles inflow calculations and adjustments. Found usages in `/district scripts`. + +- `autoAdjust(String officeId, String locationStr, Date startDate)`: Automatically adjusts inflows starting from the specified date. +- `autoAdjust(String officeId, String locationStr, Date startDate, boolean useLimits, boolean freezeRain)`: Automatically adjusts inflows with optional limits and rain freezing. +- `cloneInflows(String officeId, String locationStr, Date startDate)`: Clones inflows at a location starting from the specified date. +- `zeroNegatives(String officeId, String locationStr, Date startDate)`: Sets negative inflow values to zero starting from the specified date. +- `balanceAll(String officeId, String locationStr, Date startDate)`: Balances all inflows for a location starting from the specified date. +- `computeEvapAsFlow(String officeId, String locationStr, Date startDate, Date endDate)`: Computes evaporation as flow for the specified period. (Used in scripts) +- `computeInflow(String officeId, String locationStr, Date startDate, Date endDate)`: Computes inflow for the specified location and period. (Used in scripts) +- `setComputationStorageOptions(InflowComputationStorageOption option, InflowComputationStorageOption... options)`: Sets storage options for inflow computations. (Used in scripts) + +### ScriptablePoolPercentImpl +Calculates pool percentage time series. + +- `calculatePoolPercents(String officeId, String locationStr, Date startDate, Date endDate)`: Calculates pool percentages for a location within the specified date range. +- `retrieveDefaultTsId(RegiPool pool)`: Retrieves the default time series ID mask for a given pool. + +### ScriptableStatusGraphicImpl +Generates status graphic images for reservoirs, streams, and releases. + +- `generateReservoirStatusImage(String officeId, String locationId, String templateName, Date current, int width, int height, String filename)`: Generates a reservoir status image. +- `generateStreamStatusImage(String officeId, String locationId, String templateName, Date current, int width, int height, String filename)`: Generates a stream status image. +- `generateReleasesStatusImage(String officeId, String locationId, String templateName, Date current, int width, int height, String filename)`: Generates a releases status image. +- `generateBasinPieImageForGroup(String officeId, String locationStr, String groupId, Date date, int width, int height, String template, String file)`: Generates a basin pie chart image for a specific group. +- `generateBasinPieImageForBasin(String officeId, String locationStr, String basinId, Date date, int width, int height, String template, String file)`: Generates a basin pie chart image for a specific basin. +- `generateAllBasinPieImagesForBasin(String officeId, String basinId, Date[] dates, int width, int height, String[] templateIds, String file)`: Generates basin pie images for all dates and templates for a basin. +- `generateAllBasinPieImagesForGroup(String officeId, String groupId, Date[] dates, int width, int height, String[] templateIds, String file)`: Generates basin pie images for all dates and templates for a group. +- `getMapTemplates()`: Returns a list of available map templates. +- `getMapTemplateLayer(String templateName)`: Returns a specific map template layer by name. diff --git a/docs/PUBLIC_API_RECOMMENDATIONS.md b/docs/PUBLIC_API_RECOMMENDATIONS.md new file mode 100644 index 0000000..43656de --- /dev/null +++ b/docs/PUBLIC_API_RECOMMENDATIONS.md @@ -0,0 +1,59 @@ +# Java API Recommendations + +## Definitions +- Recent Examples are located in `/regi-headless-installer-solaris/RegiHeadless-Solaris/examples` and `/regi-headless-installer-windows/RegiHeadless/examples` + - The most up to date and recent examples +- District Scripts are located in `/district scripts` + - Scripts currently in use by the USACE Districts +- Older Examples are located in `/regi-headless/src/test/resources/usace/rowcps/headless/examples` and `/regi-headless/src/test/resources/usace/rowcps/headless/tests` + - Older scripts used as examples, but have not been updated since 2019. See `SCRIPT_RECOMMENDATIONS.md` for more information. + +## Public API Recommendations +### Public API Removal Recommendations +| Classes | Description | Used in recent Examples | Used in District Scripts | Used in older Examples | Recommended for Removal | Notes | +|----------------------------------------|-----------------------------------------------------------------|-------------------------|--------------------------|------------------------|-------------------------|----------------| +| **ScriptableExportTSAssociationsImpl** | [Description](PUBLIC_API.md#scriptableexporttsassociationsimpl) | No | No | Yes | Yes | Unused calc | +| **ScriptableExportSigStagesImpl** | [Description](PUBLIC_API.md#scriptableexportsigstagesimpl) | Yes | No | Yes | Yes | Unused calc | +| **ScriptableImportSigStagesImpl** | [Description](PUBLIC_API.md#scriptableimportsigstagesimpl) | Yes | No | Yes | Yes | Unused calc | +| **RetrieveSigStagesImpl** | [Description](PUBLIC_API.md#retrievesigstagesimpl) | Yes | No | Yes | Yes | Unused calc | +| **ScriptableGateFlowImpl** | [Description](PUBLIC_API.md#scriptablegateflowimpl) | Yes | Yes | Yes | No | | +| **ScriptableGateSettingsImpl** | [Description](PUBLIC_API.md#scriptablegatesettingsimpl) | Yes | Yes | Yes | No | | +| **ScriptableInflowImpl** | [Description](PUBLIC_API.md#scriptableinflowimpl) | Yes | Yes | Yes | No | | +| **ScriptablePoolPercentImpl** | [Description](PUBLIC_API.md#scriptablepoolpercentimpl) | Yes | No | Yes | Yes | Being replaced | +| **ScriptableStatusGraphicImpl** | [Description](PUBLIC_API.md#scriptablestatusgraphicimpl) | Yes | No | Yes | Yes | Being replaced | + +### Public API Changes + +#### ScriptableInflowImpl +See [ScriptableInflowImpl](PUBLIC_API.md#scriptableinflowimpl) + +| Method | Used in recent Examples | Used in District Scripts | Used in older Examples | Recommended for Removal | Notes | +|---------------------------------------------------------------------------------------------------|-------------------------|--------------------------|------------------------|-------------------------|------------------------------------------------------| +| `autoAdjust(String, String, Date)` | Yes | Yes | Yes | No | | +| `autoAdjust(String, String, Date, boolean, boolean)` | No | No | No | Maybe | Unused overload | +| `cloneInflows(String, String, Date)` | Yes | Yes | Yes | No | | +| `zeroNegatives(String, String, Date)` | Yes | Yes | Yes | No | | +| `balanceAll(String, String, Date)` | Yes | Yes | Yes | No | | +| `computeEvapAsFlow(String, String, Date, Date)` | Yes | Yes | Yes | No | | +| `computeInflow(String, String, Date, Date)` | Yes | Yes | Yes | No | | +| `setComputationStorageOptions(InflowComputationStorageOption, InflowComputationStorageOption...)` | No | No | No | Maybe | No longer used in recent scripts or District Scripts | + +#### **ScriptableGateSettingsImpl** +See [ScriptableGateSettingsImpl](PUBLIC_API.md#scriptablegatesettingsimpl) + +| Method | Used in recent Examples | Used in District Scripts | Used in older Examples | Recommended for Removal | Notes | +|------------------------------------------------------------------------------|-------------------------|--------------------------|------------------------|-------------------------|-----------------------------------------------------------| +| `createGateSettings(String, String, Date, Date)` | Yes | No | Yes | Maybe | Unused by District Scripts, may want to consider removing | +| `createGateSettingsOutlet(String, String, Date, Date, String)` | Yes | Yes | Yes | No | | +| `createGateSettingsOutletFromTs(String, String, Date, Date, String, String)` | Yes | Yes | Yes | No | | +| `createGateSettingsGroup(String, String, Date, Date, String)` | Yes | No | Yes | Maybe | Unused by District Scripts, may want to consider removing | + +#### **ScriptableGateFlowImpl** +See [ScriptableGateFlowImpl](PUBLIC_API.md#scriptablegateflowimpl) + +| Method | Used in recent Examples | Used in District Scripts | Used in older Examples | Recommended for Removal | Notes | +|----------------------------------------------------------|-------------------------|--------------------------|------------------------|-------------------------|-----------------| +| `computeAll(String, String, Date, Date)` | Yes | Yes | Yes | No | | +| `computeAll(String, String[], Date, Date)` | No | No | No | Maybe | Unused overload | +| `computeFlowGroup(String, String, Date, Date, String)` | Yes | Yes | Yes | No | | +| `computeFlowGroup(String, String[], Date, Date, String)` | No | No | No | No | Unused overload | \ No newline at end of file diff --git a/docs/SCRIPT_COMPATABILITY.md b/docs/SCRIPT_COMPATABILITY.md new file mode 100644 index 0000000..aadf62b --- /dev/null +++ b/docs/SCRIPT_COMPATABILITY.md @@ -0,0 +1,19 @@ +# Python 3.14 Compatibility Analysis + +The scripts located in `district scripts/`, `regi-headless-installer-solaris/`, and `regi-headless-installer-windows/` are currently **not compatible** with Python 3.14 (or any Python 3.x version). + +## Incompatibilities + +1. **Print Syntax**: + - **Issue**: Most scripts use the Python 2 `print` statement (e.g., `print "message"`). In Python 3, `print()` is a function and requires parentheses. + - **Example**: `print "Error Computing..."` will cause a `SyntaxError` in Python 3.14. + +## Recommendations for Compatibility + +To make these scripts compatible with Python 3.14, the following changes would be necessary: + +- **Syntax Updates**: Convert all `print` statements to `print()` functions. This can be done immediately even in Python 2.7 by adding `from __future__ import print_function` at the top of each script. + +## Feasibility of Update + +- **Syntax**: Updating the syntax (print functions, exception handling) is trivial and can be automated. \ No newline at end of file diff --git a/docs/SCRIPT_RECOMMENDATIONS.md b/docs/SCRIPT_RECOMMENDATIONS.md new file mode 100644 index 0000000..1ef4c09 --- /dev/null +++ b/docs/SCRIPT_RECOMMENDATIONS.md @@ -0,0 +1,29 @@ +# Python Script Recommendations +## Notes +- Four sets of example scripts exist in the current repo and they're all slightly different. This will require an agreement on how to consolidate them into a single set of examples. +- The Solaris build will be removed in the future + +## Recommendations +1. Remove the /regi-headless/src/test/resources/usace/rowcps/headless/examples and /regi-headless/src/test/resources/usace/rowcps/headless/tests scripts as they are not up to date. +2. Replace Windows and Solaris example scripts and with the district scripts. The district scripts already use all features of the recommended new public API. See [PUBLIC_API_RECOMMENDATIONS.md](PUBLIC_API_RECOMMENDATIONS.md#public-api-changes). +3. Update python files to be compatible with the latest Python version. + +## Python Script Locations +### /district scripts +Scripts provided by the districts. These are currently running and actively used by their associated districts. + +- SWF Scripts were provided by **James Moffitt** +- SWT Scripts were provided by **Andrew Miller** +- SWL Scripts were provided by **Erin Krebs** + +### /regi-headless/src/test/resources/usace/rowcps/headless/examples +These appear to be older example scripts that haven't been updated since 2019. They are out of sync with other scripts. + +### /regi-headless/src/test/resources/usace/rowcps/headless/tests +These appear to be older test scripts that haven't been updated since 2019. They are out of sync with other scripts. + +### /regi-headless-installer-windows/RegiHeadless/examples +These scripts and bash files are provided to the Solaris installer to provide an example of how to use regi-headless. The scripts are slightly different from the Windows installer scripts, and the bash files are specifically for Solaris. + +### /regi-headless-installer-solaris/RegiHeadless/examples +These scripts and batch files are provided to the Windows installer to provide an example of how to use regi-headless. The scripts are slightly different from the Solaris installer scripts, and the batch files are specifically for Windows.