Skip to content

Latest commit

 

History

History
81 lines (76 loc) · 7.19 KB

README.md

File metadata and controls

81 lines (76 loc) · 7.19 KB
Raw

Python version of the NWM Conceptual Functional Equivalent (CFE) model

Note this version is for prototyping, research and development.
The official CFE code lives here: https://github.com/NOAA-OWP/cfe/

Files

environment.yml:

This is an environment file with the required Python libraries needed to run the model with BMI. Create the environment with this command: conda env create -f environment.yml, then activate it with conda activate bmi_cfe

cfe.py

This is the main model code. The input to this model is a CFE State, which can be either a Python class, or a dictionary. The only requirement is that the object contains the entire model running state (Not just state variables), which concists of the following:

  • Forcings
    • timestep_rainfall_input_m
    • potential_et_m_per_s
  • Parameters
    • soil_params
    • K_nash
    • etc.
  • Volume trackers
    • volin
    • vol_to_gw
    • volout
    • etc.
  • Fluxes
    • flux_Qout_m
    • flux_giuh_runoff_m
    • flux_nash_lateral_runoff_m
    • flux_from_deep_gw_to_chan_m
    • total_discharge
  • Etc.
    The model code takes the running state and calculates all the fluxes and corresponding state changes. The running state contains the single timestep changes, nothing is "returned" from the function. All the processing and interpretation of the model should take place in the driving code. An example of driving code is below.

bmi_cfe.py

This is the code for the Basic Model Interface (BMI) that is used to call the cfe and interact with other models via the Framework, or driving code. This code contains all the required BMI functions to run the CFE, including

  • initialize: Perform startup tasks for the model.
  • update: Advance model state by one time step. Calls the function run_cfe from cfe.py
  • update_until: Advance model state until the given time.
  • finalize: Perform tear-down tasks for the model.
  • get_value: Get a copy of values of a given variable.
  • set_value: Set the values of a given variable.
  • etc.
    These functions need to be called by a framework or driving code, an example of which is below.

run_cfe_bmi.ipynb

This is an example run for the CFE. The Jupyter notebook is good for visualizing the results. Notice that there are blocks of code that call all the functions listed above. These are the main BMI functions that allow us to control and run the model. This example requires a configuration file, which BMI uses to set the specifics of the model, including how to use Forcings. More on the configuration file below.

cat58_config_cfe.json

This file has all the information to configure the model for a specific basin. The forcing file can be specified to run the a comparison with the origional model code, and there should be a corresponding file with the output from the test (compare_results_file). In general the model should be run getting forcing from the driver using the set_value function. Some of the values in the config file will come from the NWM parameters, and some will be calibrated. Some values are basin specific, and need to be set to get the correct results for the basin, for instance the catchment_area_km2 is needed to convert the runoff to a volume flux, rather than a depth.

Parameters

Copy and pasted from official repo. To be edited.

Variable Datatype Limits Units Role Process Description
forcing_file char 256 filename path to forcing inputs csv; set to BMI if passed via bmi.set_value*()
soil_params.depth double meters [m] state soil depth
soil_params.b double state beta exponent on Clapp-Hornberger (1978) soil water relations
soil_params.satdk double meters/second [m s-1] state saturated hydraulic conductivity
soil_params.satpsi double meters [m] state saturated capillary head
soil_params.slop double meters/meters [m/m] state this factor (0-1) modifies the gradient of the hydraulic head at the soil bottom. 0=no-flow.
soil_params.smcmax double meters/meters [m/m] state saturated soil moisture content
soil_params.wltsmc double meters/meters [m/m] state wilting point soil moisture content
soil_params.expon double parameter_adjustable optional; defaults to 1.0
soil_params.expon_secondary double parameter_adjustable optional; defaults to 1.0
max_gw_storage double meters [m] parameter_adjustable maximum storage in the conceptual reservoir
Cgw double meters/hour [m h-1] parameter_adjustable the primary outlet coefficient
expon double parameter_adjustable exponent parameter (1.0 for linear reservoir)
gw_storage double meters/meters [m/m] parameter_adjustable initial condition for groundwater reservoir - it is the ground water as a decimal fraction of the maximum groundwater storage (max_gw_storage) for the initial timestep
alpha_fc double parameter_adjustable field capacity
soil_storage double meters/meters [m/m] parameter_adjustable initial condition for soil reservoir - it is the water in the soil as a decimal fraction of maximum soil water storage (smcmax * depth) for the initial timestep
K_nash int parameter_adjustable number of Nash lf reservoirs (optional, defaults to 2, ignored if storage values present)
K_lf double parameter_adjustable Nash Config param - primary reservoir
nash_storage double parameter_adjustable Nash Config param - secondary reservoir
giuh_ordinates double parameter_adjustable Giuh ordinates in dt time steps
num_timesteps int time_info set to 1 if forcing_file=BMI
verbosity int 0-3 option prints various debug and bmi info
surface_partitioning_scheme char Xinanjiang or Schaake parameter_adjustable direct runoff
a_Xinanjiang_inflection_point_parameter double parameter_adjustable direct runoff when surface_partitioning_scheme=Xinanjiang
b_Xinanjiang_shape_parameter=1 double parameter_adjustable direct runoff when surface_partitioning_scheme=Xinanjiang
x_Xinanjiang_shape_parameter=1 double parameter_adjustable direct runoff when surface_partitioning_scheme=Xinanjiang
aet_rootzone boolean True, true or 1 coupling parameter rootzone-based AET when CFE coupled to SoilMoistureProfile
max_root_zone_layer double meters [m] parameter_adjustable AET layer of the soil that is the maximum root zone depth. That is, the depth of the layer where the AET is drawn from
soil_layer_depths 1D array meters [m] parameter_adjustable AET an array of depths from the surface. Example, soil_layer_depths=0.1,0.4,1.0,2.0
sft_coupled boolean True, true or 1 coupling parameter ice-fraction based runoff when CFE coupled to SoilFreezeThaw