NWSRFS Wrapper Module

class nwsrfs_py.nwsrfs.ChanlossPars(year, month, day, hour, periods, factors, cl_type, min_flow, qin)

Bases: object

Container for all inputs required to run the NWSRFS CHANLOSS model via F2PY bindings.

This class supports vectorized execution across multiple CHANLOSS periods and timesteps simultaneously. Input arrays should adhere to the following shape conventions:

Dimensions:

• T: Number of timesteps.

• C: Number of CHANLOSS periods.

Array Shapes:

• Time Arrays and Streamflow (e.g., year, qin): Shape (T,)

• CHANLOSS Factors (e.g., factors): Shape (C,)

• CHANLOSS Periods (e.g., periods): Shape (C,2)

Parameters:

• year (np.ndarray) – Array of years for each timestep (units: time).

• month (np.ndarray) – Array of months corresponding to each timestep (units: time).

• day (np.ndarray) – Array of days for each timestep (units: time).

• hour (np.ndarray) – Array of hours for each timestep (units: time).

• factors (np.ndarray) – The CHANLOSS factors to be applied for each period (if cl_type = 1 units: NA, otherwise units: cfs).

• periods (np.ndarray) – The beginning and ending months that the CHANLOSS factors are applied (units: month).

• cl_type (numbers.Number) – 1=varp (percentage of flow), 2=varc (constant value)

• min_flow (numbers.Number) – Minimum required qin flow for CHANLOSS to be applied (units: cfs).

• qin (np.ndarray) – Input streamflow to adjust for CHANLOSS (units: cfs).

validate()

Checks that all inputs meet shape, type, and value constraints.

class nwsrfs_py.nwsrfs.ConsusePars(year, month, day, area, irr_eff, min_flow, rf_accum_rate, rf_decay_rate, pet_adj, peadj_m, pet, qin)

Bases: object

Container for all inputs required to run the NWSRFS CONS_USE model via F2PY bindings.

This class supports vectorized all timesteps simultaneously. Only a single CONS_USE zone can be ran at a time.

Input arrays should adhere to the following shape conventions:

Dimensions:

• T: Number of timesteps.

Array Shapes:

• Time Arrays, Streamflow, and PET (e.g., year, qin): Shape (T,)

• PEadj_table: Shape (12,)

Parameters:

• year (np.ndarray) – Array of years for each timestep (units: time).

• month (np.ndarray) – Array of months corresponding to each timestep (units: time).

• day (np.ndarray) – Array of days for each timestep (units: time).

• area (numbers.Number) – Area of CONS_USE zone (units: km**2).

• irr_eff (numbers.Number) – Irrigation efficiency (units: fraction 0-1).

• min_flow (numbers.Number) – Minimum flow (units: cfs).

• rf_accum_rate (numbers.Number) – Return flow accumulation rate (units: fraction 0-1).

• rf_decay_rate (numbers.Number) – Return flow decay rate (units: NA).

• pet_adj (numbers.Number) – Potential evaporation (PET) adjustment factor (units: NA).

• peadj_m (np.ndarray) – Monthly pe adjust table (units: NA).

• pet (np.ndarray) – Input CONS_USE zone pet (units: mm).

• qin (np.ndarray) – Input daily average streamflow to adjust for CONS_USE (units: cfs).

validate()

Checks that all inputs meet shape, type, and value constraints.

class nwsrfs_py.nwsrfs.FAPars(year, month, day, hour, pars, area, alat, limits, forcings=None, peadj_m=None, climo=None)

Bases: object

Container for all inputs required to apply monthly climatological forcing adjustments (FA) to either MAP, MAT, PTPS, or PET. This dataclass can handle multiple zones.

This dataclass is designed to be generic to all four forcing types. The units for limits, forcings, and climo depend on the forcing type being processed:

• map (Precipitation): mm

• mat (Temperature): deg C

• ptps (Precip Typing): fraction (0-1)

• pet (Potential Evap): mm

pet is calculated using a temperature index approach and does not require the forcing argument passed. None should be passed instead.

This class supports vectorized execution across multiple zones and timesteps simultaneously. Input arrays should adhere to the following shape conventions:

Dimensions:

• T: Number of timesteps.

• Z: Number of zones.

• N_pars: Number of fa parameters (4).

Array Shapes:

• Time Arrays (e.g., year): Shape (T,)

• Forcings (e.g., forcings): Shape (T, Z)

• Scalar Parameters (e.g., alat): Shape (Z,)

• Vector Parameters (e.g., pars): Shape (N_pars, Z) - Axis 0 corresponds to the ordered parameter list.

• Climo Parameter (e.g., climo): Shape (12, ) - A value for each month (Jan-Dec)

Parameters:

• year (np.ndarray) – Array of years for each timestep (units: time).

• month (np.ndarray) – Array of months corresponding to each timestep (units: time).

• day (np.ndarray) – Array of days for each timestep (units: time).

• hour (np.ndarray) – Array of hours corresponding to each timestep (units: time).

• pars (np.ndarray) –

  Contains the forcing adjustment parameters (ordered array).

  0. scale: Multiplication factor to apply directly to the forcing (units: NA).

  1. p_redist: The percentage of the climatological forcing to redistribute (units: fraction 0-1).

  2. std: Controls the weighting factor on how the p_redist is partitioned out to each climatological month based on ranking (units: NA).

  3. shift: Shift the climatological values by x numbers of days in the positive or negative (units: days)

• area (np.ndarray) – Array of each zone’s area (units: km**2).

• alat (np.ndarray) – Array of each zone’s centroid latitude (units: decimal degrees).

• limits (np.ndarray) – Contains the forcing adjustment upper and lower limits for each of the 12 months. Units vary by forcing type (see above).

• forcings (np.ndarray | None) – Input forcings to adjust using pars and limits. None must be passed for pet. Units vary by forcing type (see above).

• peadj_m (np.ndarray | None) – Input required for PET forcing adjustment. Contains potential evaporation adjustment factors [pet -> etd] for each of the 12 months [Not required for other forcing types] (units: NA).

• climo (np.ndarray | None) – Optional input to provide the monthly climatology which will be used the limits parameter to establish allowable adjustments. Otherwise climatology will be calculated with forcings inputs. Units vary by forcing type (see above).

validate()

Checks that all inputs meet shape, type, and value constraints.

class nwsrfs_py.nwsrfs.GammaUhPars(dt_hours, area, shape, scale=None, toc=None)

Bases: object

Container for all inputs required to create a gamma UNIT-HG models via F2PY bindings. Multiple gamma unit hydrograph parameter sets can be ran simultaneously.

This class supports vectorized execution across multiple zones. Input arrays should adhere to the following shape conventions:

Dimensions:

• Z: Number of zones.

Array Shapes:

• Parameters (e.g., shape): Shape (Z,)

Parameters:

• dt_hours (np.ndarray) – UH timestep. (units: hours)

• area (np.ndarray) – Array of each zone’s area. (units: km**2)

• shape (np.ndarray) – Array of each zone’s shape parameter. (units: NA)

• scale (np.ndarray | None) – Optional array of each zone’s scale parameter. If scale is None, toc parameter must be provided. (units: NA)

• toc (np.ndarray | None) – Optional array of each zone’s time of concentration (toc) parameter. If toc is None, the scale parameter must be provided. (units: hours)

validate()

Checks that all inputs meet shape, type, and value constraints.

class nwsrfs_py.nwsrfs.LagkPars(year, month, day, hour, tbl_lageq_a, tbl_lageq_b, tbl_lageq_c, tbl_lageq_d, tbl_keq_a, tbl_keq_b, tbl_keq_c, tbl_keq_d, tbl_lagmax, tbl_lagmin, tbl_kmax, tbl_kmin, tbl_qmax, tbl_qmin, init_co, init_qin, init_qout, init_stor, qin)

Bases: object

Container for all inputs required to run the NWSRFS Lag-K model via F2PY bindings.

This class supports vectorized execution across multiple upstream reaches and timesteps simultaneously. Input arrays should adhere to the following shape conventions:

Dimensions:

• T: Number of timesteps.

• R: Number of upstream reaches.

Array Shapes:

• Time Arrays (e.g., year): Shape (T,)

• Upstream Reach (e.g., qin): Shape (T, R)

• Scalar Parameters (e.g., tbl_keq_c): Shape (R,)

Lag/K Table Equation:

Lag/K_table=a*(Q-d)**2+b*Q+c

Parameters:

• year (np.ndarray) – Array of years for each timestep (units: time).

• month (np.ndarray) – Array of months corresponding to each timestep (units: time).

• day (np.ndarray) – Array of days for each timestep (units: time).

• hour (np.ndarray) – Array of hours corresponding to each timestep (units: time).

• tbl_lageq_a (np.ndarray) – Parameter used to calculate the lag table (units: NA).

• tbl_lageq_b (np.ndarray) – Parameter used to calculate the lag table (units: NA).

• tbl_lageq_c (np.ndarray) – Parameter used to calculate the lag table (units: NA).

• tbl_lageq_d (np.ndarray) – Parameter used to calculate the lag table (units: NA).

• tbl_keq_a (np.ndarray) – Parameter used to calculate the k table (units: NA).

• tbl_keq_b (np.ndarray) – Parameter used to calculate the k table [(units: NA).

• tbl_keq_c (np.ndarray) – Parameter used to calculate the k table (units: NA).

• tbl_keq_d (np.ndarray) – Parameter used to calculate the k table (units: NA).

• tbl_lagmax (np.ndarray) – max lag value for lag table (units: hours).

• tbl_lagmin (np.ndarray) – min lag value for lag table (units: hours).

• tbl_kmax (np.ndarray) – max k value for k table (units: hours).

• tbl_kmin (np.ndarray) – min k value for k table (units: hours).

• tbl_qmax (np.ndarray) – max q value for both lag and k table (units: cfs).

• tbl_qmin (np.ndarray) – min q value for both lag and k table (units: cfs).

• init_co (np.ndarray) – Initial carry over (units: cfs).

• init_qin (np.ndarray) – Initial inflow (units: cfs).

• init_qout (np.ndarray) – Initial outflow (units: cfs).

• init_stor (np.ndarray) – Initial storage (units: cfs).

• qin (np.ndarray) – Input streamflows to route. (units: cfs).

validate()

Checks that all inputs meet shape, type, and value constraints.

class nwsrfs_py.nwsrfs.SacSnowPars(year, month, day, hour, alat, elev, sac_pars, snow_pars, init_swe, pxadj, peadj, forcings_map, forcings_mat, forcings_ptps, forcings_etd)

Bases: object

Container for all inputs required to run the NWSRFS SAC-SMA and SNOW-17 models via F2PY bindings.

This class supports vectorized execution across multiple zones and timesteps simultaneously. Input arrays should adhere to the following shape conventions:

Dimensions:

• T: Number of timesteps.

• Z: Number of zones.

• N_pars: Number of parameters (varies by model).

Array Shapes:

• Time Arrays (e.g., year): Shape (T,)

• Forcings (e.g., forcings_map): Shape (T, Z)

• Scalar Parameters (e.g., alat): Shape (Z,)

• Vector Parameters (e.g., sac_pars, snow_pars): Shape (N_pars, Z) - Axis 0 corresponds to the ordered parameter list.

  • For SAC-SMA: N_pars = 17

  • For SNOW-17: N_pars = 13

ADC Table Equation:

swe/ai = a * AESC**b+(1-a)*AESC**c

Parameters:

• year (np.ndarray) – Array of years for each timestep (units: time).

• month (np.ndarray) – Array of months corresponding to each timestep (units: time).

• day (np.ndarray) – Array of days for each timestep (units: time).

• hour (np.ndarray) – Array of hours corresponding to each timestep (units: time).

• alat (np.ndarray) – array of each zone’s centroid latitude (units: decimal degrees).

• elev (np.ndarray) – array of each zone’s centroid elevation (units: m).

• sac_pars (np.ndarray) –

  SAC-SMA model parameters (ordered array).

  0. uztwm: Upper zone tension water capacity (units: mm).

  1. uzfwm: Upper zone free water capacity (units: mm).

  2. lztwm: Lower zone tension water capacity (units: mm).

  3. lzfpm: Lower zone primary free water capacity (units: mm).

  4. lzfsm: Lower zone supplemental free water capacity (units: mm).

  5. adimp: Fraction of additional impervious area (units: fraction 0-1).

  6. uzk: Upper zone free water storage depletion coefficient (units: NA).

  7. lzpk: Lower zone primary free water storage depletion coefficient (units: NA).

  8. lzsk: Lower zone supplementalfree water storage depletion coefficient (units: NA).

  9. zperc: Maximum percolation rate multiplier (units: NA).

  10. rexp: Exponent for the percolation equation (units: NA).

  11. pctim: Minimum impervious area (units: fraction 0-1).

  12. pfree: Fraction of percolated water which always goes directly to lower zone free water storages (units: fraction 0-1).

  13. riva: Fraction of riparian vegetation area (units: fraction 0-1).

  14. side: Fraction of non-channel baseflow (deep groundwater recharge) to channel baseflow (units: fraction 0-1).

  15. rserv: Fraction of lower zone free water which cannot be transferred to lztw (units: fraction 0-1).

  16. efc: fraction of effective forest cover (units: fraction 0-1).

• snow_pars (np.ndarray) –

  SNOW-17 model parameters (ordered array).

  0. scf: Snowfall correction factor (units: NA).

  1. mfmax: Maximum non-rain melt factor per time step (units: mm/degc).

  2. mfmin: Minimum non-rain melt factor per time step (units: mm/degc).

  3. uadj: Average wind function per time step (units: mm/mb).

  4. si: SWE threshold above which there is always 100% snow cover (units: mm).

  5. nmf: Maximum negative melt factor per time step (units: mm/degc).

  6. tipm: Antecedent snow temperature index parameter (units: fraction 0-1).

  7. mbase: Base temperature for non-rain melt factor (units: degc).

  8. plwhc: Maximum amount of liquid waterheld against gravity drainage (units: fraction 0-1).

  9. daygm: Daily melt at the snow-soil interface (units: mm).

  10. adc_a: Parameter used to calculate the areal depletion curve parameter (units: NA).

  11. adc_b: Parameter used to calculate the areal depletion curve parameter (units: NA).

  12. adc_c: Parameter used to calculate the areal depletion curve parameter (units: NA).

• init_swe (np.ndarray) – Initial snow water equivalent values (units: NA).

• pxadj (np.ndarray) – Precipitation adjustment factor (units: NA).

• peadj (np.ndarray) – Evapotranspiration adjustment factor (units: NA).

• forcings_map (np.ndarray) – Precipitation array for each timestep (units: mm).

• forcings_mat (np.ndarray) – Air temperature array for each timestep (units: degc).

• forcings_ptps (np.ndarray) – Fraction of precipitation as snow array for each timestep (units: fraction 0-1).

• forcings_etd (np.ndarray) – Evaporation demand array for each timestep (units: mm).

validate()

Checks that all inputs meet shape, type, and value constraints.

class nwsrfs_py.nwsrfs.GammaUh(pars_dataclass, validate=True)

Bases: object

Class to generate Gamma UNIT-HG and route flows via F2PY bindings.

Parameters:

• pars_dataclass (GammaUhPars) – Dataclass which contains all inputs needed for gamma UNIT-HG calculations.

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

gamma_uh_pars

Dataclass which contains all inputs needed for gamma UNIT-HG calculations.

Type:

GammaUhPars

return_sf(tci, return_inst=True)

Return a timeseries of streamflow for each zone.

Parameters:

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

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

Returns:

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

Return type:

pd.DataFrame

return_uh(tstep)

Returns a unit hydrograph as a DataFrame 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 uh: DataFrame

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

class nwsrfs_py.nwsrfs.SacSnow(pars_dataclass, validate=True)

Bases: object

Class to run the NWSRFS SAC-SMA and SNOW-17 models via F2PY bindings. Multiple SAC-SMA and SNOW-17 parameter sets can be ran simultaneously.

Parameters:

• pars_dataclass (SacSnowPars) – Dataclass which contains all inputs to run SAC-SMA and SNOW-17.

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

sacsnow_dataclass

Dataclass which contains all inputs to run SAC-SMA and SNOW-17.

Type:

SacSnowPars

property sacsnow_states: dict[str, pandas.DataFrame]

Returns a dictionary of DataFrames containing all 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 total channel inflow (tci) as a DataFrame with a column for each zone (units - mm).

class nwsrfs_py.nwsrfs.Lagk(pars_dataclass, validate=True)

Bases: object

Class to run the NWSRFS Lag-K models via F2PY bindings. Multiple upstream routes can be ran simultaneously.

Parameters:

• pars_dataclass (LagkPars) – Dataclass which contains all inputs to run Lag-K.

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

lagk_pars

Dataclass which contains all inputs to run Lag-K.

Type:

LagkPars

property lagk_route: DataFrame

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

property lagk_states: dict[str, pandas.DataFrame]

Generates a dictionary of DataFrames containing all 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).

class nwsrfs_py.nwsrfs.Chanloss(pars_dataclass, validate=True)

Bases: object

Class to run the NWSRFS CHANLOSS model via F2PY bindings.

Parameters:

• pars_dataclass (ChanlossPars) – Dataclass which contains all inputs to run CHANLOSS.

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

chanloss_pars

Dataclass which contains all inputs to run CHANLOSS.

Type:

ChanlossPars

property chanloss_qadj: Series

Generates a Series of streamflow with CHANLOSS adjustments applied (units - cfs).

class nwsrfs_py.nwsrfs.FA(map_dataclass, mat_dataclass, ptps_dataclass, pet_dataclass, validate=True)

Bases: object

Class to apply monthly climatological forcing adjustments (FA) to forcings via F2PY bindings.

Parameters:

• map_dataclass (FAPars) – Dataclass containing inputs for precipitation adjustments.

• mat_dataclass (FAPars) – Dataclass containing inputs for temperature adjustments.

• ptps_dataclass (FAPars) – Dataclass containing inputs for precipitation typing adjustments.

• pet_dataclass (FAPars) – Dataclass containing inputs for potential evaporation adjustments.

• validate (bool) – Validate that map, mat, ptps, and pet FAPars dataclass inputs are correct format/type. Default: True.

fa_pars

Dictionary of dataclasses representing 'map', 'mat', 'ptps', and 'pet' parameters.

Type:

dict[str, FAPars]

property fa_factors: DataFrame

Generates a DataFrame of monthly adjustment factors (index 1-12).

The columns correspond to:

• map_fac: Monthly precipitation adjustment factors (units: NA)

• mat_fac: Monthly temperature adjustment shifts (units: degc)

• pet_fac: Monthly potential evaporation adjustment factors (units: NA)

• ptps_fac: Monthly precip-as-snow adjustment factors (units: NA)

property forcings: dict[str, pandas.DataFrame]

Generates a dictionary of adjusted forcings as DataFrames.

The dictionary keys are:

• map_fa: Precipitation (units: mm)

• mat_fa: Air temperature (units: degc)

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

• pet_fa: Potential evaporation (units: mm)

• etd_fa: Evaporation demand (units: mm)

property forcings_climo: DataFrame

12-month climatology values as DataFrame (index 1-12).

The columns correspond to:

• map_climo: Monthly precipitation climatology (units: mm/month total)

• mat_climo: Monthly temperature climatology (units: degc monthly avg)

• pet_climo: Monthly potential evaporation climatology (units: mm/month)

• ptps_climo: Monthly precip-as-snow climatology (units: fraction 0-1 monthly avg)

class nwsrfs_py.nwsrfs.Consuse(pars_dataclass, validate=True)

Bases: object

Function to run the NWSRFS CONS_USE model via F2PY bindings. Only a single CONS_USE zone can be ran at a time. Timestep is daily average.

Parameters:

• pars_dataclass (ConsusePars) – Dataclass which contains all inputs to run CONS_USE.

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

consuse_pars

Dataclass which contains all inputs to run CONS_USE.

Type:

ConsusePars

property consuse_qadj: Series

Generates a Series of daily streamflow with consumptive use adjustments applied (units - cfsd).

property consuse_states: DataFrame

Generates a DataFrame with a column for each CONS_USE model states.

The column states 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)