Skip to content

StateDMI / Command / LimitDiversionHistoricalTSMonthlyToRights

Overview

The LimitDiversionHistoricalTSMonthlyToRights command (for StateMod) limits diversion historical time series (monthly) values to the water rights that were in effect at the time of the diversion, based on the appropriation date corresponding to water right administration numbers. For each diversion station being processed, the cumulative rights are determined at each point in time, creating a step-function in CFS units. Very junior water rights with administration numbers greater than or equal to 90000.00000 can be assigned an appropriate date, which is then used to compute an administration number for the check. The water rights must be supplied from a StateMod diversion rights file – they are not taken from rights that may be in memory and the rights used by this command cannot be further modified and written. For boundary purposes during the check, a zero flow condition is imposed at 1800-01-01 and carried forward until a right is found. A summary of the rights is printed to the log file.

This command does NOT reset recorded diversions. In order to detect recorded diversion values StateDMI checks the command file for the LimitDiversionHistoricalTSMonthlyToRights command. If the command is found, then after reading data using the ReadDiversionHistoricalTSMonthlyFromHydroBase and SetDiversionHistoricalTSMonthly commands, each time series is copied into a backup. Any subsequent filling of the time series does not alter this backup. When limiting to rights, the backup diversion data are checked and any observed values are enforced in the result. Consequently, the rights values are only used for estimated data. A side effect of using the original data is that any values that may have been set with other commands will be reset back to observed values. If necessary, place set commands after the LimitDiversionHistoricalTSMonthlyToRights command so that the set commands will not be impacted by the LimitDiversionHistoricalTSMonthlyToRights command(s).

The water rights switch in the StateMod rights file is handled as follows:

  • If the switch is zero, the water right is ignored in processing (it is not used to limit the data).
  • If the switch is 1, no adjustments are done to the appropriation date for the water right.
  • If the switch is +YYYY (indicating that the right should turn on in the given year):
    • If the UseOnOffDate parameter is True, the appropriation date for the water right is set to YYYY-01-01 during the limit process.
    • If the UseOnOffDate parameter is False, the appropriation date from the administration number is used.
  • If the switch is -YYYY (indicating that the right should turn off after the given year):
    • If the UseOnOffDate parameter is True, the appropriation date for the water right is set to (YYYY+1)-01-01 and the decree is set to negative during the limit process.
    • If the UseOnOffDate parameter is False, the appropriation date from the administration number is used.

If the administration number cannot be converted to an appropriation date, then the water right OnOff switch can be set to a year for each water right and UseOnOffDate=True should be specified.

If the sum of the water rights decrees is less than zero, it is reset to zero.

A summary of the logic is as follows:

For each diversion station (ignored stations are skipped):

  1. Determine the water rights for the diversion station. If no rights are available, skip the remaining steps.
  2. Determine the diversion historical time series (monthly). If no time series is available, skip the remaining steps.
  3. Process the water rights for the diversion station.
    1. Convert the administration number to appropriation date. Use the same code as the Tools / Administration Number Calculator tool in StateDMI. The prior adjudication date associated with the administration number is ignored. See the explanation above for how the water rights switch is handled.
    2. Sort the rights according to the Julian day value for the appropriation date.
    3. If the diversion station has a free water right (those with administration numbers greater than or equal to 90000.00000): If the diversion station has a senior water right, convert the free water right appropriation date to that of the senior water right (therefore the free water right is in effect since the time of the senior right). If the diversion station has no senior water right (it has only free water right[s]), use the appropriation date corresponding to the FreeWaterAppropriationDate parameter described below.
    4. Add a bounding zero decree for 1800-01-01 for the early period of the step function.
    5. Generate a step function of sorted dates and decrees using the information described above. These values will be in CFS. Because appropriation dates are used, the sort order may be different from that of the numerical administration number.
    6. Because the decrees are in CFS, convert to ACFT, considering the number of days in each month.
  4. Constrain the monthly time series to the step function, where the step function is defined by a list of dates and decrees, determined from the previous step. If a value in the time series is greater than the step function, set the value to the step function. Because of the conversion from CSFS to ACFT, monthly values in the step function will vary.
  5. Reset observed values from the original data (as read from HydroBase or a replacement time series read from a StateMod file – time series that are NOT read from HydroBase or StateMod will NOT have a copy saved as original data).

Command Editor

The following dialog is used to edit the command and illustrates the command syntax.

LimitDiversionHistoricalTSMonthlyToRights command editor

LimitDiversionHistoricalTSMonthlyToRights Command Editor (see also the full-size image)

Command Syntax

The command syntax is as follows:

LimitDiversionHistoricalTSMonthlyToRights(Parameter="Value",...)

Command Parameters

Parameter                                       Description Default          
ID A single diversion station identifier to match or a pattern using wildcards (e.g., 20*). None – must be specified.
InputFile The name of the StateMod diversion rights file, surrounded by double quotes. The rights in the file are read and are used to constrain the historical diversion time series. The rights are assumed to be sorted by structure. None – must be specified.
IgnoreID A list of diversion stations to ignore when processing this command. A list of comma-separated values can be specified, where each value is a single identifier, or a pattern using wildcards (similar to ID). Do not ignore any diversion stations.
FreeWaterAppropriationDate A date to be used for the free water rights found in the rights file. Free water rights are typically inserted to represent very junior rights. Rights having an administration number greater than or equal to 90000.00000 are assumed to be free water rights and will use the specified free water appropriation date when constraining the time series. The date corresponding to an administration number of 0, which is Dec 31, 1849.
UseOnOffDate If False, the appropriation date is always computed from the administration number. If True and the value of the OnOff switch is YYYY or –YYYY, assign the appropriation date using the switch value (see notes earlier in the command description). False
SetFlag If specified as a single character, data flags will be enabled for the time series and each set value will be tagged with the specified character. The flag can then be used later to label graphs, etc. The flag will be appended to existing flags if necessary. No flag is assigned.

Examples

See the automated tests.

The following command file excerpt illustrates how time series can be limited to rights prior to writing the StateMod time series file:

#
#  Step 8 - fill historical diversion using pattern approach
#
FillDiversionHistoricalTSMonthlyPattern(ID="36*",PatternID="09034500")
...similar commands omitted...
#
#   Step 9 - Fill remaining missing with month average
#
FillDiversionHistoricalTSMonthlyAverage(ID="*")
#
#   Step 10 - Limit filled diversion to water rights. Exceptions include structure
#             receiving significant reservoir supply, carrier structures, etc.
#
LimitDiversionHistoricalTSMonthlyToRights(InputFile="..\statemod\cm2005.ddr",ID="*",IgnoreID="954683,952001,950010,950011")
#
#   Step 11 - sort structures and create historical diversion file
#
SortDiversionHistoricalTSMonthly(Order=Ascending)
WriteDiversionHistoricalTSMonthlyToStateMod(OutputFile="..\StateMod\cm2005.ddh")
#
#  Step 12 - update capacities and create final direct diversion station file
#
SetDiversionStationCapacitiesFromTS(ID="*")
WriteDiversionStationsToStateMod(OutputFile="..\statemod\cm2005.dds")
#
# Check the results.
CheckDiversionHistoricalTSMonthly(ID="*")
WriteCheckFile(OutputFile="ddh.commands.StateDMI.check.html")

Troubleshooting

See the main troubleshooting documentation

See Also

ReadDiversionHistoricalTSMonthlyFromHydroBase command SetDiversionHistoricalTSMonthly command