Simulation Module

class nwsrfs_py.simulation.NwsrfsRun(autocalb_dir, run_dir=None, forcing_adj=True, return_inst=True, shift_sf=True)[source]

Bases: _NwrfcAcPrep, FA, SacSnow, GammaUh, Lagk, Chanloss

Orchestrates the execution of NWSRFS models (SAC-SMA, Snow17, lagk, etc.) using NWRFC autocalibration data.

Files and folders in autocalb_dir must follow file conventions of the NOAA-NWRFC/nwsrfs-hydro-autocalibration repository optimization tools. Sample calibration data is available on Zenodo.

If no run_dir is provided, the first 'results_*' directory found within the autocalb_dir path will be used.

Parameters:

  • autocalb_dir (str) – Path to a NWRFC autocalibration run directory

  • run_dir (str | None) – Name of optimization run subdirectory within the autocal_dir. If 'None' is provided, defaults to using first 'results_*' directory found within the autocalb_dir.

  • forcing_adj (bool | list[str]) – If True monthly climatological forcing adjustments will be applied to all forcings. Alternatively, a list with with specific forcing to apply climatological forcing adjustments can be supplied: 'map', 'mat', 'ptps', 'pet'. Default: True.

  • return_inst (bool) – Specifies to return instantaneous streamflow, rather than period average. Default: True.

  • shift_sf (bool) – Shifts GammaUh derived streamflow forward on one timestep. Requirement for NWRFC calibrations. Default: True.

pars

Contains all parameters used with NWSRFS models

Type:

pd.DataFrame

forcings_raw

A dictionary with forcings prior to applying FA adjustments

The dictionary keys are:

  • map: Precipitation (units: mm)

  • mat: Air temperature (units: degc)

  • ptps: Fraction of precipitation as snow (units: fraction 0-1)

Type:

dict[str, pd.DataFrame]

zone_names

Names of zones modeled in basin.

Type:

tuple

cu_names

Names of consuse zones modeled in basin.

Type:

tuple

daily_flow

Daily mean observed flow.

Type:

pd.DataFrame

inst_flow

Instantaneous observed flow.

Type:

pd.DataFrame|None

upflow

Upstream flow derived from the adjustq.AdjustQ.

Type:

pd.DataFrame|None

fa_pars

If localflow_logic is True, than dictionary of FAPars classes representing 'map', 'mat', 'ptps', and 'pet', otherwise 'None'.

Type:

dict[str, nwsrfs.FAPars]|None

sacsnow_pars

If localflow_logic is True, than SacSnowPars class, otherwise 'None'.

Type:

nwsrfs.SacSnowPars|None

gammauh_pars

If localflow_logic is True, than GammmaUhPars class, otherwise 'None'.

Type:

nwsrfs.GammaUhPars|None

lagk_pars

If upflow_logic is True, than LagkPars class, otherwise 'None'.

Type:

nwsrfs.LagkPars|None

chanloss_pars

If chanloss_logic is True, than ChanlossPars class, otherwise 'None'.

Type:

nwsrfs.ChanlossPars|None

consuse_pars

If consuse_logic is True, than dictionary of ConsusePars classes representing each cu_names, otherwise 'None'.

Type:

dict[str, nwsrfs.ConsusePars]|None

localflow_logic

Logic if FAPars, SacSnow, and GammaUh models exist in configuration.

Type:

bool

upflow_logic

Logic if Lagk model exist in configuration.

Type:

bool

chanloss_logic

Logic if Chanloss model exist in configuration.

Type:

bool

consuse_logic

Logic if Consuse model exist in configuration.

Type:

bool

n_zones

Number of zones in the configuration.

Type:

integer

chanloss_apply(qin, validate=True)[source]

Runs Chanloss with qin supplied (units: cfs).

Parameters:

  • qin (pd.Series) – Input streamflow to adjust (units: cfs).

  • validate (bool) – Validate that chanloss inputs are correct format/type. Default: True

property consuse_qadj: Series

Generates a Series of flow adjusted by Consuse (units - cfsd).

property consuse_states: dict[str, pandas.DataFrame]

Generates a dictionary of DataFrames containing all Consuse states with a column for each zone.

The dictionary keys are:

  • qadj: Streamflow with all consumptive use adjustments applied (units: cfsd)

  • qdiv: Flow diverted for consumptive use (units: cfsd)

  • qrf_in: Return flow from irrigation area used as input to return flow storage (units:cfsd)

  • qrf_out: Return flow to channel from return flow storage (units: cfsd)

  • qol: Diverted flow other loses [eg transport, subsurface] (units: cfsd)

  • qcd: Crop flow demand (units: cfsd)

  • ce: Crop evapotranspiration demand (units: mm)

  • rfstor: Return flow storage contents (units: mm)

property forcings: dict[str, pandas.DataFrame]

Generates a dictionary of FA adjusted forcings as DataFrames.

The dictionary keys are:

  • map: Precipitation (units: mm)

  • mat: Air temperature (units: degc)

  • ptps: Fraction of precipitation as snow (units: fraction 0-1)

  • pet: Potential evaporation (units: mm)

  • etd: Evaporation demand (units: mm)

property lagk_route: DataFrame

Generates routed flows as a DataFrame using Lagk with a column for each upstream reach (units - cfs).

property lagk_states: dict[str, pandas.DataFrame]

Generates a dictionary of DataFrames containing all Lagk model states with a column for each upstream reach.

The dictionary keys are:

  • routed: Routed flow with lag and k applied (units: cfs).

  • lag_time: Lag applied to upstream flow (units: hours).

  • k_inflow: upstreamflow with only lag applied (units: cfs).

  • k_storage: Attenuation storage (units: cfs).

classmethod load_example(lid='NRKW1', **kwargs)[source]

Generates a NwsrfsRun for the package provided example data.

Example data are NWRFC auto calibration results for two locations:

  • NRKW1: Nooksack River at North Cedarville, WA (USGS-12210700). The following models are being utilized: SacSnow, GammaUh, Lagk.

  • SFLN2: Salmon Falls Creek NR San Jacinto NV (USGS 13105000). The following models are being utilized: SacSnow, GammaUh, Chanloss, Consuse.

Any optional arguments associated with NwsrfsRun, can be passed.

Parameters:

  • lid (str) – Five letter identifier of example data. Input can either be 'NRKW1' or 'SFLN2'. Default: 'NRKW1'.

  • **kwargs –

    Optional keyword arguments passed to NwsrfsRun.

    Common options include:

    • forcing_adj (bool | list[str]): Apply monthly climatological adjustments. Default: True.

    • return_inst (bool): Return instantaneous vs. period-average flow. Default: True.

    • shift_sf (bool): Shift streamflow forward one timestep. Default: True.

nwsrfs_run()[source]

Prepares and creates instances of all nwsrfs models with parameters provided in the pars attribute.

return_sf(tci)[source]

Generates a timeseries of streamflow as a Series using GammaUh and input tci.

Parameters:

tci (SACSnowTCI) – Custom type alias for total channel inflow from SacSnow (units: mm).

Returns:

A DataFrame containing streamflow with a column for each zone (units: cfs).

Return type:

pd.DataFrame

return_uh(tstep)[source]

Generates a unit hydrograph as a DataFrame, using GammaUh, at a timestep specified by tstep.

Parameters:

tstep (int) – Specifies timestep of unit hydrograph (units: hours).

Returns:

A DataFrame containing unit hydrograph (uh) with a column for each zone (units: cfs/in).

Return type:

pd.DataFrame

property sacsnow_sf: DataFrame

Calculates streamflow for each zone using SacSnow and GammaUh models (units - cfs).

property sacsnow_states: dict[str, pandas.DataFrame]

Returns a dictionary of DataFrames containing all SacSnow model states with a column for each zone.

The dictionary keys are:

  • tci: Total channel inflow (units: mm).

  • map_pxadj: Precipitation after pxadj applied (units: mm).

  • etd_peadj: Evaporation demand after peadj, efc, and aesc adjustments applied (units: mm).

  • aet: Actual evapotranspiration (units: mm).

  • uztwc: Upper zone tension water contents (units: mm).

  • uzfwc: Upper zone free water contents (units: mm).

  • lztwc: Lower zone tension water contents (units: mm).

  • lzfsc: Lower zone free supplemental water contents (units: mm).

  • lzfpc: Lower zone free primary water contents (units: mm).

  • adimc: Additional impervious area water contents (units: mm).

  • roimp: Impervious runoff prior to riparian vegetation adjustment (units: mm).

  • sdro: Direct runoff prior to riparian vegetation adjustment (units: mm).

  • ssur: Surface runoff prior to riparian vegetation adjustment (units: mm).

  • sif: Interflow prior to riparian vegetation adjustment (units: mm).

  • bfs: Baseflow supplemental runoff prior to riparian vegetation adjustment (units: mm).

  • bfp: Baseflow primary runoff prior to riparian vegetation adjustment (units: mm).

  • swe: Snow water equivalent (units: mm).

  • aesc: Areal extent of snow cover (units: fraction 0-1).

  • neghs: Snowpack heat deficit (units: mm).

  • liqw: Liquid water held by snow against gravity drainage (units: mm).

  • raim: Total rain plus snowmelt (units: mm).

  • psfall: Precipitation falling as snow after scf adjustment has been applied (units: mm).

  • prain: Precipitation falling as rain (units: mm).

property sacsnow_tci: SACSnowTCI

Generates a custom type alias for total channel inflow (tci) using SacSnow with a column for each zone (units - mm).

property sim: Series

Generates a Series of the sum of any local flow runoff (SacSnow + GammaUh) and upstream routed (Lagk) flow for each timestep with chanloss (Chanloss) and consuse (Consuse) applied (units - cfs).

property uh: DataFrame

Generates a unit hydrograph as a DataFrame, using GammaUh, at a timestep specified by the dt_hours attribute (units - cfs/in).

update_pars(new_pars)[source]

Updates the pars file with new values.

DataFrame Format

new_pars must have a 'p_name' and 'value' column. All values in the 'p_name' columns must map to an row in the exiting pars DataFrame attribute.

Parameters:

new_pars (pd.DataFrame) – dataframe with parameters to update nwsrfs models

nwsrfs_py.simulation.SACSnowTCI

Custom type alias for total channel inflow (tci) output.

This type represents a pandas DataFrame containing tci values with a column for each zone (units: mm). It is strictly used to ensure type safety when passing tci data between the SacSnow and GammaUh classes.

alias of DataFrame