pre-CFE2.0_PR

.github/workflows/ngen_integration.yaml

@@ -84,5 +84,5 @@ jobs:
       - name: Run Ngen Test for CFE Couple with PET
         run: |
           mv ${{ steps.ngen_id1.outputs.build-dir }} ./ngen-build/
-          inputfile='extern/cfe/cfe/realizations/realization_cfe_pet.json'
+          inputfile='extern/cfe/cfe/realizations/realization_cfe_pet_surfgiuh.json'
           ./ngen-build/ngen ./data/catchment_data.geojson "cat-27" ./data/nexus_data.geojson "nex-26" $inputfile

INSTALL.md

@@ -80,9 +80,9 @@ See general instructions [here](https://github.com/NOAA-OWP/ngen/wiki/NGen-Tutor
      - cmake -B cmake_build -S . -DBMI_C_LIB_ACTIVE=ON -DBMI_FORTRAN_ACTIVE=ON -DNGEN_ACTIVATE_PYTHON=ON
      - make -j4 -C cmake_build
   - #### CFE
-    - git submodule update --remote extern/cfe/cfe 
-    - cmake -B extern/cfe/cmake_build -S extern/cfe/cfe/ -DNGEN=ON
-    - make -C extern/cfe/cmake_build
+    - git submodule update --remote extern/cfe/cfe
+    - cmake -B extern/cfe/cfe/cmake_build -S extern/cfe/cfe/ -DNGEN=ON
+    - make -C extern/cfe/cfe/cmake_build
   - #### SLoTH
     SLoTH is also needed to run SFT in the ngen framework. SLoTH is a BMI that is used to set a bmi variable(s) that is not provided by other BMIs but required by the model. So build [SLoTH](https://github.com/NOAA-OWP/SLoTH) using the following instructions
     - cd extern/sloth/ && git checkout latest 
@@ -103,7 +103,7 @@ The following pre-process step needs to be completed before running the example.
   **Note:** Make sure the "library_file" and "init_config" in the BMI blocks in the realization file are pointing to the right files, these paths depend on how you build your models.
 
   ```
-  Run: ../cmake_build/ngen data/catchment_data.geojson cat-27 data/nexus_data.geojson nex-26 realizations/realization_cfe_pet.json
+  Run: ../cmake_build/ngen data/catchment_data.geojson cat-27 data/nexus_data.geojson nex-26 realizations/realization_cfe_pet_surfgiuh.json
   ```
 
 ## Alternative: Compiling and Running CFE

configs/README.md

@@ -26,32 +26,35 @@ Example configuration files are provided in this directory. To build and run the
 | 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 |    |
+| surface_water_partitioning_scheme | *char* | `Xinanjiang` or `Schaake`  |  | parameter_adjustable | infiltraton exces |    |
 | surface_runoff_scheme | *char* | GIUH or NASH_CASCADE | | parameter_adjustable | surface runoff | also supports 1 for GIUH and 2 for NASH_CASCADE; default is GIUH |
 | N_nash_surface | *int* |   |   | parameter_adjustable | surface runoff | number of Nash reservoirs for surface runoff   |
-| K_nash_surface | *double* |   | 1/meters [m^-1]  | parameter_adjustable | surface runoff | Nash Config param for surface runoff   |
+| K_nash_surface | *double* |   | 1/hour [h^-1]  | parameter_adjustable | surface runoff | Nash Config param for surface runoff   |
 | nash_storage_surface | *double* |   | meters [m]  | parameter_adjustable | surface runoff | Nash Config param; reservoir surface storage; default is zero storage |
-| *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`   |
-| urban_decimal_fraction  | *double*  |  0.0 - 1.0 |   |  parameter_adjustable | direct runoff | when `surface_partitioning_scheme=Xinanjiang` |
+| nsubsteps_nash_surface | *int* |   |   | parameter_adjustable | surface runoff | optional (default = 10); number of subtimstep for Nash runoff |
+| Kinf_nash_surface | *double* |   | 1/hour [h^-1] | parameter_adjustable | surface runoff | optional (default = 0.05); storage fraction per hour that moves from reservoirs to soil |
+| retention_depth_nash_surface | *double* |   | m | parameter_adjustable | surface runoff | optional (default = 0.001); water retention depth threshold (only applied to the first reservoir) |
+| *a_Xinanjiang_inflection_point_parameter | *double* |   |  | parameter_adjustable | infiltration excess runoff | when `surface_water_partitioning_scheme=Xinanjiang`   |
+| *b_Xinanjiang_shape_parameter=1  | *double* |   |   | parameter_adjustable  | infiltration excess runoff | when `surface_water_partitioning_scheme=Xinanjiang`   |
+| *x_Xinanjiang_shape_parameter=1  | *double* |   |   | parameter_adjustable | infiltration excess runoff | when `surface_water_partitioning_scheme=Xinanjiang`   |
+| urban_decimal_fraction  | *double*  |  0.0 - 1.0 |   |  parameter_adjustable | infiltration excess runoff | when `surface_water_partitioning_scheme=Xinanjiang` |
 | is_aet_rootzone                    | *boolean* | True, true or 1  |  | coupling parameter | `rootzone-based AET` | when `CFE coupled to SoilMoistureProfile` |
 | max_rootzone_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
 | is_sft_coupled                   | *boolean* | True, true or 1  |  | coupling parameter | `ice_fraction-based runoff` | when `CFE coupled to SoilFreezeThaw`|
 
-## Direct runoff options in CFE
+## Infiltration excess runoff options in CFE
 
-The user has the option to pick a particular direct runoff (aka surface partitioning) method:
+The user has the option to pick a particular infiltration excess runoff (aka surface water partitioning) method:
 
-1. Schaake function (configuration: `surface_partitioning_scheme=Schaake`)
-2. Xinanjiang function (configuration: `surface_partitioning_scheme=Xinanjiang`). When using this runoff method the user must also include four parameters.
+1. Schaake function (configuration: `surface_water_partitioning_scheme=Schaake`)
+2. Xinanjiang function (configuration: `surface_water_partitioning_scheme=Xinanjiang`). When using this runoff method the user must also include four parameters.
 
 If the **Xinanjiang** scheme is choosen, four parameters need to be included in the configuration file:
 1. a_Xinanjiang_inflection_point_parameter
 2. b_Xinanjiang_shape_parameter
 3. x_Xinanjiang_shape_parameter
-4. urban_decimal_fraction 
+4. urban_decimal_fraction
 
 ## Surface runoff options in CFE
 The user has the option to pick a particular surface runoff (aka surface runoff scheme) method:
@@ -63,7 +66,7 @@ The user has the option to pick a particular surface runoff (aka surface runoff
 ## Rootzone-based Actual Evapotranspiration (AET)
 The user has the option to turn ON and OFF rootzone-based AET, default option is OFF. To turn it ON, the following parameters need to be included in the configuration file.
 1. `is_aet_rootzone=true`
-2. `soil_layer_depths` 
+2. `soil_layer_depths`
 3. `max_rootzone_layer`
 
 ## CFE coupled to Soil freeze-thaw model (SFT)
@@ -74,6 +77,6 @@ The Soil Freeze-Thaw (SFT) model is a standalone model.  For detailed informatio
     * If the runoff scheme is Xinanjiang, no additional parameters are needed in the CFE config files.
     * If the runoff scheme is Schaake, the CFE config file will need an additional parameter, namely:
       * `ice_content_threshold` : (type double, unit m). This represent the ice content above which soil is impermeable.
-  
+
 
 **Note:** By defualt `is_sft_coupled` and `is_aet_rootzone` are set to `OFF`, that means these changes do not affect the basic functionality of CFE.

configs/cat_87_bmi_config_cfe.txt

@@ -20,12 +20,13 @@ nash_storage=0.0,0.0
 giuh_ordinates=0.06,0.51,0.28,0.12,0.03
 num_timesteps=1
 verbosity=2
-surface_partitioning_scheme=Xinanjiang
+surface_runoff_scheme=GIUH
+surface_water_partitioning_scheme=Xinanjiang
 a_Xinanjiang_inflection_point_parameter=1
 b_Xinanjiang_shape_parameter=1
 x_Xinanjiang_shape_parameter=1
 urban_decimal_fraction=0.0
 DEBUG=0
-#surface_partitioning_scheme=Schaake
+#surface_water_partitioning_scheme=Schaake
 #ice_fraction=0
 #ice_content_threshold=0.15

configs/cat_87_bmi_config_cfe_pass.txt

@@ -20,12 +20,12 @@ nash_storage=0.0,0.0
 giuh_ordinates=0.06,0.51,0.28,0.12,0.03
 num_timesteps=1
 verbosity=1
-surface_partitioning_scheme=Xinanjiang
+surface_runoff_scheme=GIUH
+surface_water_partitioning_scheme=Xinanjiang
 a_Xinanjiang_inflection_point_parameter=1
 b_Xinanjiang_shape_parameter=1
 x_Xinanjiang_shape_parameter=1
 urban_decimal_fraction=0.0
-#surface_partitioning_scheme=Schaake
+#surface_water_partitioning_scheme=Schaake
 #ice_fraction=1
 #ice_content_threshold=0.15
-

configs/cat_87_config_cfe_pass_surfnash.txt

@@ -20,16 +20,8 @@ nash_storage=0.0,0.0
 surface_runoff_scheme=2
 N_nash_surface=2
 K_nash_surface=0.83089
-nsubsteps_nash_surface=12
+nsubsteps_nash_surface=10
 nash_storage_surface=0.0,0.0
 num_timesteps=1
 verbosity=1
-surface_partitioning_scheme=Xinanjiang
-a_Xinanjiang_inflection_point_parameter=1
-b_Xinanjiang_shape_parameter=1
-x_Xinanjiang_shape_parameter=1
-urban_decimal_fraction=0.0
-#surface_partitioning_scheme=Schaake
-#ice_fraction=1
-#ice_content_threshold=0.15
-
+surface_partitioning_scheme=Schaake

configs/cat_89_bmi_config_cfe_unit_test.txt

@@ -20,4 +20,5 @@ nash_storage=0.0,0.0
 giuh_ordinates=0.06,0.51,0.28,0.12,0.03
 num_timesteps=1
 verbosity=2
-surface_partitioning_scheme=Schaake
+surface_runoff_scheme=GIUH
+surface_water_partitioning_scheme=Schaake

configs/laramie_bmi_config_cfe_pass_aet_rz.txt

@@ -20,8 +20,9 @@ nash_storage=0.0,0.0
 giuh_ordinates=0.06,0.51,0.28,0.12,0.03
 num_timesteps=1
 verbosity=1
-surface_partitioning_scheme=Schaake
-#surface_partitioning_scheme=Xinanjiang
+surface_runoff_scheme=GIUH
+surface_water_partitioning_scheme=Schaake
+#surface_water_partitioning_scheme=Xinanjiang
 #a_Xinanjiang_inflection_point_parameter=1
 #b_Xinanjiang_shape_parameter=1
 #x_Xinanjiang_shape_parameter=1

include/bmi_cfe.h

@@ -50,6 +50,7 @@ struct cfe_state_struct {
     double timestep_rainfall_input_m;
     double soil_reservoir_storage_deficit_m;
     double infiltration_depth_m;
+    double* infiltration_excess_m;
     double gw_reservoir_storage_deficit_m;
 
     double timestep_h;
@@ -64,7 +65,7 @@ struct cfe_state_struct {
     struct massbal vol_struct;
 
     /* xinanjiang_dev */
-    struct direct_runoff_parameters_structure direct_runoff_params_struct;
+    struct infiltration_excess_parameters_structure infiltration_excess_params_struct;
 
     // Epoch-based start time (BMI start time is considered 0.0)
     long epoch_start_time;
@@ -82,16 +83,16 @@ struct cfe_state_struct {
 
     //LKC Changed this to N_nash for consistency
     //int num_lateral_flow_nash_reservoirs;
-    
+
     //LKC: added N_nash the same way as the other Nash parameters - making this consistent
     double K_lf;
-    double K_nash;   
+    double K_nash;
     int N_nash;
 
     int num_giuh_ordinates;
 
     int surface_runoff_scheme;   // options: giuh-based runoff and nash cascade-based runoff
-  
+
     // ***********************************************************
     // ******************* Dynamic allocations *******************
     // ***********************************************************
@@ -106,13 +107,8 @@ struct cfe_state_struct {
     double* runoff_queue_m_per_timestep;
 
     struct nash_cascade_parameters nash_surface_params;
-
-    /* xinanjiang_dev
-        changing the name to the more general "direct runoff"
-    double* flux_Schaake_output_runoff_m;*/
-    double* flux_output_direct_runoff_m ;
 
-    double* flux_surface_runoff_m;
+    double* flux_direct_runoff_m;
     double* flux_nash_lateral_runoff_m;
     double* flux_from_deep_gw_to_chan_m;
     double* flux_perc_m;
@@ -141,13 +137,13 @@ extern void get_word_cfe(char *theString,int *start,int *end,char *theWord,int *
 
 /*int read_init_config_cfe(const char* config_file, cfe_state_struct* model, double* alpha_fc, double* soil_storage,
                      int* is_soil_storage_ratio);*/
-//LKC removed double alpha_fc since it has been added to the soil parameter structure                     
+//LKC removed double alpha_fc since it has been added to the soil parameter structure
 int read_init_config_cfe(const char* config_file, cfe_state_struct* model);
 
 
 /*extern void init_soil_reservoir(cfe_state_struct* cfe_ptr, double alpha_fc, double max_storage, double storage,
                      int is_storage_ratios);*/
-//LKC removed double alpha_fc since it has been added to the soil parameter structure                 
+//LKC removed double alpha_fc since it has been added to the soil parameter structure
 extern void init_soil_reservoir(cfe_state_struct* cfe_ptr);
 
 //extern double init_reservoir_storage(int is_ratio, double amount, double max_amount);

include/cfe.h

@@ -17,7 +17,7 @@
 
 // t-shirt approximation of the hydrologic routing funtionality of the National Water Model v 1.2, 2.0, and 2.1
 // This code was developed to test the hypothesis that the National Water Model runoff generation, vadose zone
-// dynamics, and conceptual groundwater model can be greatly simplified by acknowledging that it is truly a 
+// dynamics, and conceptual groundwater model can be greatly simplified by acknowledging that it is truly a
 // conceptual model.  The hypothesis is supported by a number of observations made during a 2017-2018 deep dive
 // into the NWM code.  Thesed are:
 //
@@ -26,7 +26,7 @@
 //    function by Moore, 1985.   The Schaake function is a single valued function of soil moisture deficit,
 //    predicts 100% runoff when the soil is saturated, like the curve-number method, and is fundamentally simple.
 // 2. Run-on infiltration is strictly not calculated.  Overland flow routing applies the Schaake function repeatedly
-//    to predict this phenomenon, which violates the underlying assumption of the PDM method that only rainfall 
+//    to predict this phenomenon, which violates the underlying assumption of the PDM method that only rainfall
 //    inputs affect soil moisture.
 // 3. The water-content based Richards' equation, applied using a coarse-discretization, can be replaced with a simple
 //    conceptual reservoir because it never allows saturation or infiltration-excess runoff unless deactivated by
@@ -99,8 +99,9 @@ typedef struct evapotranspiration_structure evapotranspiration_structure;
 struct massbal
 {
     double volstart            ;
-    double vol_runoff          ;   
-    double vol_infilt          ;   
+    double vol_runoff          ;
+    double vol_infilt          ;
+    double vol_runon_infilt    ;
     double vol_out_surface     ;
     double vol_end_surface     ;
     double vol_to_gw           ;
@@ -116,8 +117,8 @@ struct massbal
     double vol_soil_to_gw      ;  // this should equal vol_to_gw
     double vol_soil_end        ;
     double vol_et_from_soil    ;
-    double vol_et_from_rain    ; 
-    double vol_et_to_atm       ;   
+    double vol_et_from_rain    ;
+    double vol_et_to_atm       ;
     double volin               ;
     double volout              ;
     double volend              ;
@@ -131,29 +132,29 @@ typedef enum {Schaake=1, Xinanjiang=2} surface_water_partition_type;
 typedef enum {GIUH=1, NASH_CASCADE=2} surface_runoff_scheme;
 
 /* xinanjiang_dev*/
-struct direct_runoff_parameters_structure{
-    surface_water_partition_type surface_partitioning_scheme;
+struct infiltration_excess_parameters_structure {
+    surface_water_partition_type surface_water_partitioning_scheme;
     double Schaake_adjusted_magic_constant_by_soil_type;
     double a_Xinanjiang_inflection_point_parameter;
     double b_Xinanjiang_shape_parameter;
     double x_Xinanjiang_shape_parameter;
     double urban_decimal_fraction;
     double ice_content_threshold; // ice content above which soil is impermeable
 };
-typedef struct direct_runoff_parameters_structure direct_runoff_parameters_structure;
+typedef struct infiltration_excess_parameters_structure infiltration_excess_parameters_structure;
 
 
 // function prototypes
 // --------------------------------
 extern void Schaake_partitioning_scheme(double dt, double field_capacity_m, double magic_number, double deficit, double qinsur,
-					double smcmax, double soil_depth, double *runsrf, double *pddum, double ice_fraction_schaake,
-					double ice_content_threshold);
+                                        double smcmax, double soil_depth, double *runsrf, double *pddum, double ice_fraction_schaake,
+                                        double ice_content_threshold);
 
-// xinanjiang_dev: XinJiang function written by Rachel adapted by Jmframe and FLO, 
+// xinanjiang_dev: XinJiang function written by Rachel adapted by Jmframe and FLO,
 extern void Xinanjiang_partitioning_scheme(double water_input_depth_m, double field_capacity_m,
-					   double max_soil_moisture_storage_m, double column_total_soil_water_m,
-					   struct direct_runoff_parameters_structure *parms, double *surface_runoff_depth_m,
-					   double *infiltration_depth_m, double ice_fraction_xinanjiang);
+                                           double max_soil_moisture_storage_m, double column_total_soil_water_m,
+                                           struct infiltration_excess_parameters_structure *parms, double *infiltration_excess_m,
+                                           double *infiltration_depth_m, double ice_fraction_xinanjiang);
 
 extern void et_from_rainfall(double *timestep_rainfall_input_m, struct evapotranspiration_structure *et_struct);
 
@@ -167,19 +168,13 @@ extern void cfe(
         struct NWM_soil_parameters NWM_soil_params_struct,
         struct conceptual_reservoir *soil_reservoir_struct,
         double timestep_h,
-
-        /* xinanjiang_dev: since we are doing the option for Schaake and XinJiang, 
+        /* xinanjiang_dev: since we are doing the option for Schaake and XinJiang,
                            instead of passing in the constants
                            pass in a structure with the constants for both subroutines.
         //double Schaake_adjusted_magic_constant_by_soil_type,*/
-        struct direct_runoff_parameters_structure direct_runoff_param_struct,
-
+        struct infiltration_excess_parameters_structure infiltration_excess_params_struct,
         double timestep_rainfall_input_m,
-
-        /* xinanjiang_dev:
-        double *Schaake_output_runoff_m_ptr,*/
-        double *flux_output_direct_runoff_m,
-
+        double *infiltration_excess_m_ptr,
         double *infiltration_depth_m_ptr,
         double *flux_perc_m_ptr,
         double *flux_lat_m_ptr,
@@ -194,12 +189,12 @@ extern void cfe(
         int num_lateral_flow_nash_reservoirs,
         double K_nash,
         double *nash_storage_arr,
-	struct nash_cascade_parameters *nash_surface_params,
+        struct nash_cascade_parameters *nash_surface_params,
         struct evapotranspiration_structure *evap_struct,
         double *Qout_m_ptr,
         struct massbal *massbal_struct,
         double time_step_size,
-	int surface_runoff_scheme
+        int surface_runoff_scheme
     );
 
 #endif //CFE_CFE_H