4.2.5. Coupling Specific Methods and Data Structures

Module that contains the coupling specific methods and data structures. These are mostly complement new items relative to HSPsquared.

4.2.5.1. locaCoupling.py

Methods and data set respository specifically for coupling.

Repository for global-level variables that introduced as part of coupling HSP2 and MODFLOW 6. Also contains functions specifically related to coupling.

Note queue communications and handling are by necessity in the main block or module for each process.

locaCoupling.GWILZONE = None

MODFLOW discharge assigned to the lower zone in inches.

locaCoupling.GWIOVOL = None

MODFLOW discharge that becomes runoff and goes directly to a RCHRES in acre-ft.

Includes spring discharge from DRN boundaries in MODFLOW 6

locaCoupling.GWITOTAL = None

Total inflow from MODFLOW discharge to HSPF in af/day.

locaCoupling.GWITOTPL = None

Total inflow from MODFLOW discharge in af/day by pervious HRU

locaCoupling.GWITOTRR = None

Total inflow from MODFLOW discharge in af/day by RCHRES.

Does not include runoff from MODFLOW discharge to pervious lands.

locaCoupling.GWIUATOTAL = None

Total inflow from MODFLOW discharge that is outside of HSPF area in af/day.

locaCoupling.GWIUZONE = None

MODFLOW discharge assigned to the upper zone in inches.

locaCoupling.GWIVOL = None

Volume of water coming into each RCHRES directly from MODFLOW 6 in af/day.

locaCoupling.GWOTOTAL = None

Total outflow to MODFLOW UZF in af/day

locaCoupling.GWOVOL = None

Volume of water sent to MODFLOW 6 as losses to groundwater for each RCHRES in af/day.

locaCoupling.IGWOVOL = None

Volume of water sent to MODFLOW 6 as inflow to inactive groundwater for each PERLND in af/day.

locaCoupling.NUM_CPL = 0

Number of MODFLOW 6 cells in a layer.

Provides the array size for receiving from MODFLOW 6

locaCoupling.NUM_SPRINGS = 0

Number of spring locations that are represented by MODFLOW 6 drain cells in the model.

Used to route discharge to ground surface appropriately.

locaCoupling.NUM_UZF = 0

Number of UZF MODFLOW 6 cells in the model.

Provides the array size for passing discharges to MODFLOW 6

locaCoupling.PL_GW_MAPPING = {}

Dictionary of mappings for PERLND areas to GW model cells.

Keys are TargID, e.g. ‘P001’, and values are a list that is enumerated below.

  1. (list): sub-list with np.arrays with dimension NCPL as items

    1. (np.array): Cell ID, 2D 1-based

    2. (np.array): weighting factor

    3. (np.array): cell area within the target ID

    4. (np.array): Layer index for top active, 1-based

    5. (np.array): UZF index, 1-based

  2. (list): np.arrays with dimension NUZF as items

    1. (np.array): UZF index, 1-based

    2. (np.array): weighting factor

    3. (np.array): cell area within the target ID

    4. (np.array): Layer index for top active, 1-based

    5. (np.array): Cell ID, 2D 1-based

locaCoupling.RR_GW_MAPPING = {}

Dictionary of mappings for RCHRES segments to GW model cells.

Keys are TargID, e.g. ‘R001’, and values are a list whose members are enumerated below.

  1. (int): groundwater exit index

  2. (list): sub-list enumerated below
    1. (list): another sublist with np.arrays with dimension NCPL as items

      1. (np.array): Cell ID, 2D 1-based

      2. (np.array): weighting factor

      3. (np.array): cell area within the target ID

      4. (np.array): Layer index for top active, 1-based

      5. (np.array): UZF index, 1-based

    2. (list): sublist np.arrays with dimension NUZF as items

      1. (np.array): UZF index, 1-based

      2. (np.array): weighting factor

      3. (np.array): cell area within the target ID

      4. (np.array): Layer index for top active, 1-based

      5. (np.array): Cell ID, 2D 1-based

locaCoupling.SP_GW_MAPPING = {}

Dictionary of mappings for defined springs in the area covered by the HSPF model.

Keys are a spring index and values are a list of descriptive values.

  1. (str): target ID for this spring

  2. (int): 2D cell ID, 1-based

  3. (int): top active layer for spring location

  4. (float): cell surface area

  5. (str): spring name or label

locaCoupling.adjustPervWStorage(iI, targID, totVolafd)

Adjust the pervious water storage to account for groundwater discharged to the land surface in MODFLOW 6.

The adjustment is implemented between time steps and so the adjustment results in addition to the lower zone and upper zone storages. The additions can only result in lower zone and upper zone storage that is less than or equal to the nominal storage capacity. If the additions, exceed what can be applied to lower and upper zone storage, the excess is routed to the appropriate stream segment or RCHRES target.

Note that we need the current storage for the soil zones from time step iI - 1 as this is called at the beginning of the HSPF time loop, prior to the iI calculations.

This should never be called for iI == 0. In the current formulation this is prevented by the if statement in locaMain, time loop.

Parameters

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

  • targID (str) – current PERLND target

  • totVolafd (float) – total volume in acre-ft per day to add to the specified PERLND target

locaCoupling.calcSendArray(iI)

Calculate the numpy array to send to MODFLOW 6.

This array is 1D and has size/length == NUM_UZF. It provides the specified inflow/recharge rate for that day (day == iI) in m/day for the UZF package. It is calculated by adding first the RCHRES mappings to each cell and then the PERLND mappings for each cell.

Parameters

iI (int) – current day, 0-based in the simulation

Returns

NUZF array of m/day inflow to UZF surface for

each cell

Return type

numpy.array

locaCoupling.getGWIOVOLbyTargTS(iI, targID)

Get the excess groundwater discharge from MODFLOW 6 that is routed to stream segments.

This value returned in acre-ft/day

Parameters

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

  • targID (str) – current PERLND target

Returns

oVolAF, outflow volume in acre-feet/day to streams

Return type

float

locaCoupling.getGWIVOLbyTargTS(iI, targID)

Return the value for groundwater inflow to RCHRES by target ID and by time step index.

Parameters

  • iI (int) – index of current simulation day

  • targID (str) – ID for recarray columns

Returns

ivol, inflow volume in acre-ft per day

Return type

float

locaCoupling.getIGWIbyTS(iI, targID)

Get inflow to inactive groundwater (IGWI) to pass to MODFLOW 6.

Inflow to inactivate groundwater is stored in inches per interval. Convert this to acre-ft per day before returning

IGWI is the DEEPFR percentage of the inflow to groundwater from the Lower Zone. Inflow to groundwater is the total percolation from Upper Zone to Lower Zone plus the infiltraton from the surface directly to the Lower Zone less the calculated Lower Zone inflow.

Parameters

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

  • targID (str) – current PERLND target

Returns

oVol, outflow to UZF in acre-ft/day

Return type

float

locaCoupling.getNUM_CPL()

Get the module level global NUM_CPL

Requires that mapSetup has already been called

Returns

NUM_CPL, number of MODFLOW 6 cells per layer

Return type

int

locaCoupling.getNUM_UZF()

Get the module level global NUM_UZF

Requires that mapSetup has already been called

Returns

NUM_UZF, number of MODFLOW 6 cells per layer

Return type

int

locaCoupling.getOVOLbyExitandTime(iI, targID, gwExit)

Get the calculated OVOL for day, iI, and exit, gwExit

Parameters

  • iI (int) – index of current simulation day

  • targID (str) – ID for recarray columns

  • gwExit (int) – gw discharge exit

Returns

exOvol, exit outflow volume in acre-ft per day

Return type

float

locaCoupling.mapSetup(tDict, ncpl, nuzf, rr_file, pl_file, sp_file)

Create our mapping setup and check the passed information.

Mapping files are passed in as paths to pickle files that contain a mapping dictionary. There are three mapping dictionaries.

1. RCHRES dictionary, in rr_file, has keys that are the HSPF target Id, i.e., ‘R001’. The values are a list, L, with 3 items.

  1. (int): HSPF RCHRES exit that goes to groundwater. Must be > 1 and <= 5.

  2. (float): total UZF cell area in this target ID

2. (pd.DataFrame): DataFrame that describes the UZF cell specifications within this target ID. The DataFrame index is the 2D Cell ID, 1-based. The DataFrame has four columns.

  • “iuzno” (int): UZF cell ID, 1-based

  • “TopActive” (int): the top active layer for this model cell, 1-based

  • “SArea_m2” (float): surface area of this cell within the HSPF target

    ID in m2

  • “Weight” (float): dimensionless weight for allocating flows from HSPF

    to this cell. Should be > 0 and <= 100.0

2. PERLND dictionrary, in pl_file, is similar to the RCHRES dictionary. The dictionary keys are the HSPF target Id, i.e., ‘P001’. The values are a list, L, with 2 items.

  1. (float): total UZF cell area in this target ID

1. (pd.DataFrame): DataFrame that describes the UZF cell specifications within this target ID. The DataFrame index is the 2D Cell ID, 1-based. The DataFrame has four columns.

  • “iuzno” (int): UZF cell ID, 1-based

  • “TopActive” (int): the top active layer for this model cell,

    1-based

  • “SArea_m2” (float): surface area of this cell within the HSPF

    target ID in m2

  • “Weight” (float): dimensionless weight for allocating flows from

    HSPF to this cell. Should be > 0 and <= 100.0

3. SPRING dictionary, in sp_file, provides locations of the springs within the HSPF model that could be discharging to the ground surface. The dictionary keys are the labels/names for the springs as represented in the .drn and .drn.obs files. The values are lists, described below.

  1. (str): target ID for the HSPF location

  2. (int): 2D cell Id, 1-based, for the cell where the drain is placed

  3. (int): top active layer, 1-based, for the cell where the drain

    is placed

  4. (float): surface area for the cell where the drain is located

The main outcome of this function is to fill in the module-level global mapping dictionaries (RR_GW_MAPPING, PL_GW_MAPPING, SP_GW_MAPPING). These dictionaries have targID as keys and a list for values.

  1. RR_GW_MAPPING is a dictionary with Targ ID for keys and a list

    for values.

    1. (int): groundwater exit index

    2. (list): sub-list holding another sub-list of arrays

      1. (list): with numpy.arrays with dimension NCPL as items

        1. (numpy.array): Cell ID, 2D 1-based

        2. (numpy.array): weighting factor

        3. (numpy.array): cell area within the target ID

        4. (numpy.array): Layer index for top active, 1-based

        5. (numpy.array): UZF index, 1-based

      2. (list): numpy.arrays with dimension NUZF as items

        1. (numpy.array): UZF index, 1-based

        2. (numpy.array): weighting factor

        3. (numpy.array): cell area within the target ID

        4. (numpy.array): Layer index for top active, 1-based

        5. (numpy.array): Cell ID, 2D 1-based

2. PL_GW_MAPPING is a dictionary with Targ ID for keys and a list of values.

  1. (list): sub-list with numpy.arrays with dimension NCPL as items

    1. (numpy.array): Cell ID, 2D 1-based

    2. (numpy.array): weighting factor

    3. (numpy.array): cell area within the target ID

    4. (numpy.array): Layer index for top active, 1-based

    5. (numpy.array): UZF index, 1-based

  2. (list): np.arrays with dimension NUZF as items

    1. (numpy.array): UZF index, 1-based

    2. (numpy.array): weighting factor

    3. (numpy.array): cell area within the target ID

    4. (numpy.array): Layer index for top active, 1-based

    5. (numpy.array): Cell ID, 2D 1-based

3. SP_GW_MAPPING is a dictionary with spring index, 1-based, as the keys and a list of values.

  1. (str): target ID for this spring

  2. (int): 2D cell ID, 1-based

  3. (int): top active layer for spring location

  4. (float): cell surface area

  5. (str): spring name/label

Parameters

  • tDict (dict) – TARG_DICT from locaMain

  • ncpl (int) – number of cells per layer in the MODFLOW 6 model

  • nuzf (int) – the number of UZF cells in the MODFLOW 6 model

  • rr_file (str) – fqdn path for file that has RCHRES mapping dictionary

  • pl_file (str) – fqdn path for file that has PERLND mapping dictionary

  • sp_file (str) – fqdn path for file that has SPRING mapping dictionary

Returns

function status; 0 == success

Return type

int

locaCoupling.processReceivedArray(tDict, iI, fromGWArray)

Process the array of received, rejected infiltration and discharge to the ground surface.

Assumes that the received array is in m3/day.

Parameters

  • tDict (dict) – TARG_DICT from locaMain

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

  • fromGWArray (np.array) – 1D array received from MODFLOW 6 dimension should be NCPL

Returns

function status; 0 == success

Return type

int

locaCoupling.setIVOLfromGW(iI, targID, volAFpd)

Set the external inflow volume value for inflow from MODFLOW 6.

Parameters

  • iI (int) – index of current simulation day

  • targID (str) – ID for recarray columns

  • volAFpd (float) – volume in acre-ft/day

locaCoupling.setUpPLRecArrays(pwList, sim_len)

Create and initialize pervious land, coupling tracking arrays.

Parameters

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

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

locaCoupling.setUpRRRecArrays(pwList, sim_len)

Create and initialize RCHRES coupling tracking arrays

Parameters

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

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

locaCoupling.writeOutputs(store, tIndex)

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

Parameters

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

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

Returns

function status; 0 == success

Return type

int