4.2.3. PERLND Water Movement and Storage

Water movement and storage calculations, logic, and data structures for pervious land segments (PERLND).

4.2.3.1. locaHyperwat.py

Replacement for HSPsquared hperwat which provides for water movement and storage in pervious land segments, i.e. PERLND.

Had to replace HSPsquared hyperwat so that can break into the main time loop at the beginning and end of each day. This required fundamentally restructuring the storage and memory allocation within HSP2.

locaHyperwat functions as a module handling storage for global PERLND variables as well as for parameter and constant definitions.

Internal time unit, DELT60, is in hours for PERLND.

locaHyperwat.AGWET = None

AET from active groundwater, inches/ivld

locaHyperwat.AGWETP = None

Fraction of remaining potential ET which can be satistifed from active groundwater storage if enough is available.

locaHyperwat.AGWI = None

Active groundwater inflow, inches/ivld

locaHyperwat.AGWLI = None

Active groundwater lateral inflow external time series, inches/ivld

locaHyperwat.AGWO = None

Active groundwater outflow, inches/ivld

locaHyperwat.AGWRC = None

Basic groundwater recession rate if KVARY is 0 and there is no inflow to groundwater.

Defined as the rate of flow today divided by the rate of flow yesterday. Units are 1/day.

locaHyperwat.AGWS = None

Active groundwater storage, inches

locaHyperwat.BAD_OUTPUT_LIST = ['GWEL', 'IRDRAW', 'IRRAPP', 'IRRDEM', 'IRSHRT', 'RZWS', 'SURET']

Currently unsupported outputs

locaHyperwat.BASET = None

AET from baseflow, inches/invld

locaHyperwat.BASETP = None

Fraction of remaining potential ET which can be satisfied from baseflow or groundwater outflow.

locaHyperwat.CEPE = None

AET from interception storage, inches/ivld

locaHyperwat.CEPS = None

Interception storage, inches

locaHyperwat.CEPSC = None

Interception storage capacity in inches.

locaHyperwat.CEPSCM = None

Monthly interception storage ET parameter

locaHyperwat.CSNOFG = None

Switch to turn on consideration of snow accumulation and melt.

SNOW calculations are currently unsupported and so this switch is hard coded to off.

locaHyperwat.DAYFG = None

Calculation control to determine when day starts/ends

locaHyperwat.DEEPFR = None

Fraction of groundwater inflow which will enter deep and inactive groundwater.

This water is lost from the HSPF representation and is a model outflow. In coupled mode simulations, this discharge is applied as specified infiltration to the unsaturated zone flow (UZF) package in MODFLOW 6.

locaHyperwat.DEF_DT = None

The data type specification for time series structured array or record array

locaHyperwat.DELT60 = None

Time step in hours to use in calculations

locaHyperwat.ERRMSG = ['PWATER: Sum of irrtgt is not one', 'PWATER: UZRAA exceeds UZRA array bounds', 'PWATER: INTGB exceeds INTGRL array bounds', 'PWATER: Reduced AGWO value to available', 'PWATER: Reduced GWVS to AGWS', 'PWATER: GWVS < -0.02, set to zero', 'PWATER: Proute runoff did not converge', 'PWATER: UZI highly negative', 'PWATER: Reset AGWS to zero']

Defined error messages - can be used with errorsV for error handling.

Currently, these messages written to the log file as errors when encountered.

locaHyperwat.FLAG_DT = None

The data type specification for flag record arrays

locaHyperwat.FLAG_GOOD = ['CSNOFG', 'ICEFG', 'RTOPFG', 'UZFG', 'VCSFG', 'VIFWFG', 'VIRCFG', 'VLEFG', 'VNNFG', 'VUZFG']

Flags that are at least referenced in mHSP2

locaHyperwat.FLAG_UNUSED = ['HWTFG', 'IFFCFG', 'IFRDFG', 'IRRGFG']

Flags that are completely unused and unsupported in mHSP2

locaHyperwat.FOREST = None

FOREST is the fraction of the PERLND which is covered by forest.

This is only relevant if CSNOFG == 1 and then forest fraction will continue to transpire in winter. As SNOW is not supported, this is never relevant in the current mHSP2 implementation.

locaHyperwat.FZG = None

Parameter that adjusts for the effect of ice in the snow pack on infiltration when IFFCFG is 1.

It is not used if IFFCFG is 2. Units are 1/inch. Not used in this implementation because SNOW is not supported.

locaHyperwat.FZGL = None

Lower limit of INFFAC as adjusted by ice in the snow pack when IFFCFG is 1.

If IFFCFG is 2, FZGL is the value of INFFAC when the lower layer temperature is at or below freezing. Dimensionless parameter, not used in this implementation because SNOW is not supported.

locaHyperwat.GOOD_OUTPUT_LIST = ['AGWET', 'AGWI', 'AGWO', 'AGWS', 'BASET', 'CEPE', 'CEPS', 'GWVS', 'IFWI', 'IFWO', 'IFWS', 'IGWI', 'INFFAC', 'INFIL', 'LZET', 'LZI', 'LZS', 'RPARM', 'PERC', 'PERO', 'PERS', 'PET', 'PETADJ', 'SUPY', 'SURI', 'SURO', 'SURS', 'TAET', 'TGWS', 'UZET', 'UZI', 'UZS']

List of currently supported time series outputs.

These can be written to the HDF5 file at the end of simulation time.

locaHyperwat.GWVS = None

Index to available groundwater slope, inches

locaHyperwat.HOLD_DEC = None

Carry over calculation variable in case is not daily

locaHyperwat.HOLD_IFWK1 = None

Carry over calculation variable in case is not daily

locaHyperwat.HOLD_IFWK2 = None

Carry over calculation variable in case is not daily

locaHyperwat.HOLD_LZFRAC = None

Carry overs between calculations

locaHyperwat.HOLD_MSUPY = None

Value of MSUPY to cover over between time steps

locaHyperwat.HOLD_RLZRAT = None

Carry overs between calculations

locaHyperwat.HOLD_SRC = None

Carry over calculation variable in case is not daily

locaHyperwat.IFWI = None

Interflow inflow, inches/ivld

locaHyperwat.IFWLI = None

Interflow lateral inflow external time series, inches/ivld

locaHyperwat.IFWO = None

Interflow outflow, inches/ivld

locaHyperwat.IFWS = None

Interflow storage, inches

locaHyperwat.IGWI = None

Inflow to inactive groundwater, inches/ivld

locaHyperwat.INFEXP = None

Exponent in infiltration equation, dimensionless.

locaHyperwat.INFFAC = None

Factor to account for frozen ground.

Not currently implemented because SNOW is not implemented and always set to 1.

locaHyperwat.INFIL = None

Infiltration to soil, inches/ivld

locaHyperwat.INFILD = None

Ratio between maximum and mean infiltration capacities, dimensionless

locaHyperwat.INFILT = None

Index to infiltration capacity of the soil, inches/invl

locaHyperwat.INFLOW_TS_GOOD = ['PREC', 'PETINP', 'AGWLI', 'IFWLI', 'LZLI', 'SURLI', 'UZLI']

All supported inflow time series

locaHyperwat.INFLOW_TS_UNUSED = ['GATMP', 'DTMPG', 'WINMOV', 'SOLRAD', 'CLOUD', 'SLSED', 'PQADFX', 'PQADCN', 'PEADFX', 'PEADCN', 'NIADFX', 'NIADCN', 'PHADFX', 'PHADCN', 'TRADFX', 'TRADCN', 'RAINF', 'SNOCOV', 'WYIELD', 'PACKI', 'LGTMP']

Unsupported inflow time series names

locaHyperwat.INTFW = None

Interflow inflow parameter, dimensionless.

locaHyperwat.INTFWM = None

Monthly interflow inflow parameter

locaHyperwat.INTGRL = array([0.000e+00, 1.290e+00, 1.580e+00, 1.920e+00, 2.360e+00, 2.810e+00,        3.410e+00, 3.800e+00, 7.100e+00, 3.478e+03])

Function coordinates for evaluating upper zone behavior

locaHyperwat.IRC = None

Interflow recession parameter.

Under zero inflow, the ratio of todays interflow outflow rate to yesterday’s rate. Units are 1/day

locaHyperwat.IRCM = None

Monthly interflow recession parameter

locaHyperwat.IRRAPPV = array([0., 0., 0., 0., 0., 0., 0.])

Irrigation paramater? - set to zeros so does not matter for logic.

locaHyperwat.IRRCEP = 0.0

Unknonwn parameter - set to zero so does not matter

locaHyperwat.I_AGWS = None

Initial active groundwater storage in inches

locaHyperwat.I_CEPS = None

Initial interception storage in inches

locaHyperwat.I_GWVS = None

Initial index to groundwater slope in inches

locaHyperwat.I_IFWS = None

initial interflow storage in inches

locaHyperwat.I_LZS = None

Initial lower zone storage in inches

locaHyperwat.I_SURS = None

Initial surface or overland flow storage in inches

locaHyperwat.I_UZS = None

Initial upper zone storage in inches

locaHyperwat.KEY_TS_PET = 'PETINP'

External time series key for input PET

locaHyperwat.KEY_TS_PRECIP = 'PREC'

External time series key for precipitation

locaHyperwat.KGWV = None

Groundwater outflow recession parameter 1/day.

Calculated internally from AGWRC.

locaHyperwat.KVARY = None

Parameter that affects behavior of groundwater recession flow.

Purpose is to allow recession flow to be non-exponential in its decay time. Units are 1/in.

locaHyperwat.LATIN_CONTROL = None

Control structure telling which lateral inflows are active

locaHyperwat.LAT_INFLOW_TS = ['AGWLI', 'IFWLI', 'LZLI', 'SURLI', 'UZLI']

List of possible lateral inflow time series

locaHyperwat.LSUR = None

Length of the assumed overland flow plane in feet

locaHyperwat.LZEPTM = None

Monthly lower zone ET parameter

locaHyperwat.LZET = None

Lower soil zone AET, inches/ivld

locaHyperwat.LZETP = None

Lower zone ET parameter.

Index to the density of deep-rooted vegetation, dimensionless.

locaHyperwat.LZI = None

Lower soil zone inflow, inches/ivld

locaHyperwat.LZLI = None

Lower soil zone lateral inflow external time series, inches/ivld

locaHyperwat.LZS = None

Lower soil zone storage, inches

locaHyperwat.LZSN = None

Lower soil zone nominal storage depth in inches.

locaHyperwat.MAXLOOPS = 100

Newton method max loops

locaHyperwat.MON_FLAGS = ['VLEFG', 'VCSFG', 'VIFWFG', 'VIRCFG', 'VNNFG', 'VUZFG']

Flag names for monthly flags

locaHyperwat.MON_PARAMS = ['LZETPM', 'CEPSCM', 'INTFWM', 'IRCM', 'NSURM', 'UZSNM']

Parameter names for values that can be specified as monthly

locaHyperwat.NSUR = None

Manning’s n for the assumed overland flow plane.

Use English/Standard units versions from tables.

locaHyperwat.NSURM = None

Monthly overland flow Manning’s n

locaHyperwat.OUTPUT_CONTROL = None

Control structure telling which time series are to be output

locaHyperwat.PARAM_GOOD = ['AGWETP', 'AGWRC', 'BASETP', 'CEPSC', 'DEEPFR', 'FOREST', 'FZG', 'FZGL', 'INFEXP', 'INFILD', 'INFILT', 'INTFW', 'IRC', 'KVARY', 'LSUR', 'LZETP', 'LZSN', 'NSUR', 'PETMAX', 'PETMIN', 'SLSUR', 'UZSN']

Input, non-state parameters that are used in mHSP2

locaHyperwat.PARAM_UNUSED = ['BELV', 'DELTA', 'GWDATM', 'IFWSC', 'LELFAC', 'MELEV', 'PCW', 'PGW', 'SREXP', 'SRRC', 'STABNO', 'UELFAC', 'UPGW']

Input parameters that are unused or unsupported in mHSP2

locaHyperwat.PERC = None

Percolation from upper to lower soil zones, inches/ivld

locaHyperwat.PERO = None

Total outflow from pervious land, inches/ivld

locaHyperwat.PERS = None

Total water stored in pervious land, inches

locaHyperwat.PET = None

Potential evapotranspiration, inches/ivld

locaHyperwat.PETADJ = None

Adjusted PET for temperature restrictions, inches/ivld

locaHyperwat.PETMAX = None

Air temperature below which ET will be arbitrarily reduced.

Only used if CSNOFG == 1. Units are degrees Fahrenheit. Not supported in this implementation because SNOW is not available.

locaHyperwat.PETMIN = None

Air temperature below which ET will be set to zero.

Only used if CSNOFG == 1. Units are degrees Fahrenheit. Not supported in this implementation because SNOW is not available.

locaHyperwat.RPARM = None

Maximum ET opportunity, inches/ivld

locaHyperwat.RTOPFG = None

Flag to select the algorithm for overland flow.

RTOPFG == 1 then overland flow done as in predeccesor models - HSPX, ARM, and NPS. RTOPFG == 0 then a different algorithm is used.

locaHyperwat.SLSUR = None

Slope of the assumed overland flow plane, ft/ft

locaHyperwat.SPEC_DT = None

The data type specification for the calculation and input record arrays

locaHyperwat.STATE_PARMS = ['CEPS', 'SURS', 'UZS', 'IFWS', 'LZS', 'AGWS', 'GWVS']

The list of state parameters

locaHyperwat.SUPY = None

Moisture supplied to the land segment by precipitation, inches/ivld

locaHyperwat.SURI = None

Surface storage inflow, inches/ivld

locaHyperwat.SURLI = None

Surface storage lateral inflow external time series, inches/ivld

locaHyperwat.SURO = None

Surface storage outflow, inches/ivld

locaHyperwat.SURS = None

Surface storage, inches

locaHyperwat.TAET = None

Total PERLND AET, inches/ivld

locaHyperwat.TGWS = None

Total groundwater storage, should be equal to active groundwater storage prior to ET, inches/ivld

locaHyperwat.UZET = None

Upper soil zone AET, inches/ivld

locaHyperwat.UZFG = None

UZFG selects the method for computing inflow to the upper zone.

If UZFG is 1, upper zone inflow is computed in the same way as in the predecessor models HSPX, ARM and NPS. A value of 0 results in the use of a different algorithm, which is less sensitive to changes in DELT

locaHyperwat.UZI = None

Upper soil zone inflow, inches/ivld

locaHyperwat.UZLI = None

Upper soil zone lateral inflow external time series, inches/ivld

locaHyperwat.UZRA = array([0.  , 1.25, 1.5 , 1.75, 2.  , 2.1 , 2.2 , 2.25, 2.5 , 4.  ])

Function coordinates for evaluating upper zone behavior

locaHyperwat.UZS = None

Upper soil zone storage, inches

locaHyperwat.UZSN = None

Upper zone nominal storage in inches

locaHyperwat.UZSNM = None

Monthly upper soil zone nominal storage

locaHyperwat.VCSFG = None

Flag for monthly variation in interception storage capacity.

locaHyperwat.VIFWFG = None

Flag for monthly variation in interflow inflow parameter.

locaHyperwat.VIRCFG = None

Flag for monthly variation in interflow recession paramater.

locaHyperwat.VLEFG = None

Flag for monthly variation in lower zone ET parameter.

If 1 then the flag is on.

locaHyperwat.VNNFG = None

Flag for monthly variation in Manning’s n for overland flow.

locaHyperwat.VUZFG = None

Flag for monthly variation in upper zone nominal storage.

locaHyperwat.WS_AREAS = None

Watershed areas for pervious segments in acres

locaHyperwat.configExternalTS(sim_len, TSMapList, AllTSDict)

Transfer external time series from HDF5 input to module data structures.

Parameters

• sim_len (int) – the length of the simulation

• TSMapList (list) – nested list with sublists, L, of time series

• for a particular target ID (metadata) –

  0. time series type

  1. time series ID

  2. target ID

• AllTSDict (dict) – dictionary of time series by time series ID

Returns

function status; 0 == success

Return type

int

locaHyperwat.configFlagsParams(targID, cFlagVals, allIndexes)

Set and configure flags and parameters for PERLND

Parameters

• targID (str) – the target location ID

• cFlagVals (dict) – collected flag values

• allIndexes (list) – list of indexes for cFlagVals

Returns

function status; 0 == success

Return type

int

locaHyperwat.errorsV = array([0, 0, 0, 0, 0, 0, 0, 0, 0])

Error handling in liftedloop from original HSPF formulation.

locaHyperwat.getCurrentStorages(iI, targID)

Get the current storage values for this watershed in inches.

Parameters

• iI (int) – time step index to extract the storage values

• targID (str) – current PERLND target

Returns

uzs, upper zone current storage in inches float: lzs, lower zone currernt storage in inches

Return type

float

locaHyperwat.getIGWIbyTargTS(iI, targID)

Get IGWI, outflow to inactive groundwater for a specified target and time step index.

Parameters

• iI (int) – current simulation day index, 0-based

• targID (str) – current PERLND target

Returns

ovol, outflow to inactive groundwater in acre-ft/day

Return type

float

locaHyperwat.getLatInflowByTypeTarget(targID, liType, iI)

Get a lateral inflow by type and target for the specified time interval.

Parameters

• targID (str) – target ID

• liType (str) – lateral inflow type

• iI (int) – current time index

Returns

inflow rate for time interval

Return type

float

locaHyperwat.getNominalStorages(targID)

Get the nominal storage values for this watershed in inches

Parameters

targID (str) – current PERLND target

Returns

uzsn, upper zone nominal storage in inches float: lzsn, lower zone nominal storage in inches

Return type

float

locaHyperwat.getPERObyTargTS(iI, targID)

Get the total outflow from pervious land, inches/day

Parameters

• iI (int) – time step index to extract the storage values

• targID (str) – current PERLND target

Returns

pero, total outflow in inches/day

Return type

float

locaHyperwat.getWatershedAreabyTarg(targID)

Get WS_AREA or watershed area by target id

Parameters

targID (str) – current PERLND target

Returns

watershed areas in acres

Return type

float

locaHyperwat.proute(psur, rtopfg, delt60, dec, src, surs)

Determine how much potential surface detention (PSUR) runs off in one simulation interval.

Modified real number comparisons to be more numerically reliable.

Parameters

• psur (float) – potential surface detention

• rtopfg (int) – calculation flag to tell how to calculate

• delt60 (float) – model time step adjusted to hours from minutes

• dec (float) – calculated routing variable

• src (float) – calculated routing variable

• surs (float) – surface or overland flow storage

• ans (np.array) – calculation vector

Returns

three item array, ans, of return values

0. suro ; surface outflow

1. surs ; adjusted surface storage

2. err ; counter for errors encountered

Return type

np.array

locaHyperwat.pwater_liftedloop(iI, mon, targID)

Modified version of liftedloop to do a single time step and return to the main time loop.

Module-wide recarrays are used to store all results and calculation variables between calls. Modified real number comparisons to be more numerically reliable.

Water supply to the ground surface, MSUPY, is the starting point for the calculation.

1. MSUPY is divided into infiltration (infilt) to the Lower Zone

   and potential direct runoff (PDRO)

2. Calculated Upper Zone Inflow (UZI) is taken out of PDRO and

   the remainder is available for interflow inflow (ifwi) and potential surface storage (psur)

3. Interflow storage does not have a nominal capacity. Like

   active groundwater storage, interflow storage is adjusted by outflow and inflow but does not overflow. The recession in interflow outflow which is controlled by IRC which is the interflow recession parameter (1/day).

4. Percolation (perc) for Upper Zone to Lower Zone is calculated

   based on Upper Zone storage plus UZI and the uzs/uzsn being larger than lzs/lzsn

5. Inflow to the lower zone and active groundwater is infilt +

   perc + lateral inflows (iperc). This is partitioned to Lower Zone percolation (lperc) which provides the Lower Zone inflow (lzi)

6. The remainder of total percolation (iperc) after removing

   lzi is groundwater water inflow (gwi) and is split between active groundwater inflow (agwi) and inflow to inactive groundwater (igwi)

7. IGWI is the DEEPFR percentage of gwi and leaves the soil

   column and HSPF calculations.

8. There is no nominal storage limitation on active groundwater.

   Active groundwater outflow to baseflow is calculated using AGWRC and KVARY which essentially provide for delayed outflow rates and spread the outflow over time.

• INTFW is the interflow inflow parameter (dimensionless)

• ratio = max( 1.0001, ( intfw * pow( 2.0, lzrat ) ) )

• lzrat = lzs / lzsn

Parameters

• iI (int) – index of current time step (0 to (sim_len-1))

• mon (int) – current simulation month

• targID (str) – ID for recarray columns

Returns

count of the number of errors. Should generally be 0

but used to reference errorsV for error handling

Return type

int

locaHyperwat.setCurrentStorages(iI, targID, uzs, lzs)

Set the current storage values for this watershed in inches.

Parameters

• iI (int) – time step index to extract the storage values

• targID (str) – current PERLND target

• uzs (float) – upper zone current storage in inches

• lzs (float) – lower zone currernt storage in inches

locaHyperwat.setDelT(sim_delt)

Set the pervious land delt for calculations.

The delt is stored as a module wide global. Also sets DELT60 module-wide global. Once have this adjust the other module-wides that depend on this value to go to internal units

Parameters

sim_delt (float) – overall simulation time step in minutes

locaHyperwat.setGoodFlag(targID, tFlag, fVal)

Set the value for the specified flag structure

Parameters

• targID (str) – ID or recarray header to set

• tFlag (str) – flag string to identify the data structure

• fVal (int) – flag value to set

locaHyperwat.setGoodParam(targID, tParam, pVal)

Set the value for the specified parameter structure

Parameters

• targID (str) – ID or recarray header to set

• tParam (str) – param string to identify the data structure

• pVal (float) – parameter value to set

locaHyperwat.setLatInflowTS(sim_len, targID, inflowType, tsVals)

Method to setup lateral inflow time series

Parameters

• sim_len (int) – the simulation length

• targID (str) – target ID

• inflowType (str) – type of lateral inflow

• tsVals (np.array) – array of time series values

locaHyperwat.setMonthlyParams(targID, monName, monTuple)

Set the value for the specified monthly parameter structures

Parameters

• targID (str) – ID or recarray header to set

• monName (str) – name for data structure to set the monthly values

• monTuple (tuple) – tuple of 12 floats which are the values.

locaHyperwat.setOutputControlFlags(targID, savetable, stTypes)

Set the output control flags

Parameters

• targID (str) – target id

• savetable (np.array or dict) – boolean array of which outputs to save

• stTypes (list) – keys or indexes to save

Returns

function status; 0 == success

Return type

int

locaHyperwat.setPETTS(targID, npTS)

Set the PET time series from one data set to one target.

PET is where pet is stored for calculations. Might be adjusted by various activities.

Parameters

• targID (str) – the target identifier - must be same as used to create the rec array

• npTS (np.array) – 1D array with the time series values

locaHyperwat.setPrecipTS(targID, npTS)

Set the precipitation time series from one data set to one target.

SUPY is where precipitation is stored for calculations

Parameters

• targID (str) – the target identifier - must be same as used to create the rec array

• npTS (np.array) – 1D array with the time series values

locaHyperwat.setStateParams(targID, tParam, pVal)

Set the value for the specified initial state structure

Parameters

• targID (str) – ID or recarray header to set

• tParam (str) – param string to identify the data structure

• pVal (float) – parameter value to set

locaHyperwat.setUpRecArrays(pwList, sim_len)

Create and initialize pervious land output arrays

Parameters

• pwList (list) – list of IDs for this target type

• sim_len (int) – number of output intervals in the simulation

locaHyperwat.setWSAreas(targID, area)

Set the watershed area to the global information structure.

Area is in acres

Parameters

• targID (str) – ID or recarray header to set

• area (float) – area in acres

locaHyperwat.setupDAYFG(tIndex)

Set the module-level global DAYFG

Parameters

tIndex (pd.DateIndex) – datetime index for the simulation output

locaHyperwat.writeOutputs(store, tIndex)

Write the outputs to the hdf file at the end of the simulation

Parameters

• store (pd.HDFStore) – hdf5 file store to write to

• tIndex (pd.DateIndex) – time index for the simulation

Returns

function status; 0 == success

Return type

int