add interflow

README.md

@@ -1,7 +1,7 @@
 # Catchment Arid/Semi-arid Model (CASAM) for streamflow simulation
 CASAM (formerly known as LASAM) is a catchment scale hydrolgic model originally designed for arid or semi arid areas, in which the partitioning of precipitation into infiltration and runoff is important. CASAM is composed of a vadose zone model, which is Layered Green & Ampt with redistribution (LGAR) and represents a layered soil matrix, and a nonlinear reservoir which is filled via a simple formulation for preferential flow. LGAR is a model which partitions precipitation into infiltration and runoff, and is designed for use in arid or semi-arid climates. LGAR closely mimics precipitation partitioning results simulated by the Richards/Richardson equation (RRE), without the inherent reliability and stability challenges the RRE poses. Therefore, this model is useful when accurate, stable precipitation partitioning simulations are desired in arid or semi-arid areas. LGAR in Python (no longer supported) is available [here](https://github.com/NOAA-OWP/LGAR-Py).
 
-CASAM is theoretically a skillful catchment scale hydrolgic model in the event that precipitation partitioning into infiltration and runoff is the most important process for streamflow generation in a given catchment. Nonetheless, CASAM also includes a nonlinear reservoir so that some water stored in the catchment can contribute directly to streamflow (currently, we assume soil water does not directly contribute to streamflow).
+CASAM is theoretically a skillful catchment scale hydrolgic model in the event that precipitation partitioning into infiltration and runoff is the most important process for streamflow generation in a given catchment. Nonetheless, CASAM also includes a nonlinear reservoir and interflow so that some water stored in the catchment can contribute directly to streamflow.
 
 ![Alt text](CASAM_diagram.png)
 

configs/README.md

@@ -3,6 +3,8 @@ Example configuration files are provided in this directory. To build and run the
 
 A detailed description of the parameters for model configuration (i.e., initialize/setup) is provided below. 
 
+CASAM streamflow can be produced by surface runoff routed through the GIUH, by optional nonlinear conceptual reservoir outflow, and by optional lateral flow, or interflow, from LGAR wetting fronts. When lateral flow is disabled, water stored in the LGAR vadose zone domain does not directly contribute to streamflow except through configured lower boundary or bypass pathways. When lateral flow is enabled, eligible wetting fronts can lose water laterally, and that lateral flow volume is routed through the GIUH with surface runoff.
+
 
 | Variable | Datatype |  Limits  | Units | Role | Process | Description |
 | -------- | -------- | ------ | ----- | ---- | ------- | ----------- |
@@ -27,14 +29,16 @@ A detailed description of the parameters for model configuration (i.e., initiali
 | adaptive_timestep | Boolean | true, false | - | adaptive timestep flag | impacts timestep | If set to true, LGAR will use an internal adaptive timestep, and the above timestep is used as a minimum timestep (recommended value of 300 seconds). The adaptive timestep will never be larger than the forcing resolution. If set to false, LGAR will use the above specified timestep as a fixed timestep. Testing indicates that setting this value to true substantially decreases runtime while negligibly changing the simulation. We recommend this to be set to true. |
 | free_drainage_enabled | Boolean | true, false | - | controls lower boundary condition | affects recharge | If free_drainage_enabled is true, then free drainage will be enabled as the lower boundary condition, where fluxes from the vadose zone to groundwater are controlled by the hydraulic conductivity at the bottom of the model domain. If free_drainage_enabled is set to false, then the lower boundary condition will be no flow. If LGAR is used in an area with substantially more PET than precipitation, the choice of no flow vs free drainage should be less impactful, because the majority of water that leaves the vadose zone will do so as AET. Defaults to false.|
 | free_drainage_to_CR | Boolean | true, false | - | controls lower boundary condition | affects recharge | If this is set to true, then free drainage water will contribute to the conceptual reservoir. Defaults to false.|
+| lateral_flow_psi_threshold | double (scalar) | >=0 | cm | parameter for wetting front lateral flow/interflow | vadose storage that contributes directly to streamflow | Lateral flow is enabled only when both lateral_flow_psi_threshold and lateral_flow_factor are specified. A wetting front can contribute lateral flow when its capillary head is less than or equal to this threshold. LGAR uses positive absolute capillary head values, so smaller psi values represent wetter conditions. Aliases accepted by the config parser are lateral_flow_psi_threshold_cm and lateral_flow_threshold_psi. Defaults to disabled.|
+| lateral_flow_factor | double (scalar) | 1.E-4 <= lateral_flow_factor <= 1.E4 | - | parameter for wetting front lateral flow/interflow | vadose storage that contributes directly to streamflow | Lateral flow is enabled only when both lateral_flow_psi_threshold and lateral_flow_factor are specified. Candidate lateral flow for an eligible wetting front is proportional to K(theta) times lateral_flow_factor, scaled by the fraction of the LGAR domain represented by that front. Lateral flow is removed from LGAR storage and routed through the GIUH with surface runoff. Defaults to disabled.|
 | mbal_tol | double (scalar) | >0 | cm | mass balance error resulting from a substep that will trigger a model crash | mass balance accounting | If the mass balance error is greater than this number in a single substep, then the model will abort. Global mass balance errors over the course of year long simulations (i.e. the sum of all mass balance errors over the course of a long simulation) tend to be small, where a value greater than 1E-4 cm tends to be rare, occuring less than 1 in 10000 prameter sets. LGAR in theory should both be mass conservative, however the presence of unlikely but possible edge cases can cause mass balance errors. Flux caching can also cause small mass balance errors. While the model will usually converge with a small mbal_tol value, if general convergence is desired across a large number of parameter sets / forcing datasets, then we recommend that this value is not specified and therefore the default value of 1E1cm will be used. |
 | PET_affects_precip | Boolean | true, false | - | specifies whether PET is subtracted from precip | forcing data manipulation | If enabled, then PET will be subtracted from precipitation. Defaults to false.|
-| a | double (scalar) | 1E-8 < a < 1E-1 | cm^(1-b) h^-1 | parameter for nonlinear reservoir | storage that contributes directly to streamflow | CASAM fundamentally has two different types of water storage: water stored in the vadose zone that does not contribute to streamflow, and water stored in a nonlinear reservoir that does contribute to streamflow. The nonlinear reservoir has an input of simple bypass through the vadose zone (controlled by frac_to_CR and spf_factor), and free drainage if desired. The nonlinear reservoir releases water to the stream at a rate of a*S^b, where S is the water stored in the reserovir in cm, and a and b are nonlinear reservoir parameters. Note that the units of a depend on the value of b. Defaults to 0.|
-| b | double (scalar) | 0.01 < b < 5 | - | parameter for nonlinear reservoir | storage that contributes directly to streamflow | CASAM fundamentally has two different types of water storage: water stored in the vadose zone that does not contribute to streamflow, and water stored in a nonlinear reservoir that does contribute to streamflow. The nonlinear reservoir has an input of simple bypass through the vadose zone (controlled by frac_to_CR and spf_factor), and free drainage if desired. The nonlinear reservoir releases water to the stream at a rate of a*S^b, where S is the water stored in the reserovir in cm, and a and b are nonlinear reservoir parameters. Defaults to 0.|
+| a | double (scalar) | 1E-8 < a < 1E-1 | cm^(1-b) h^-1 | parameter for nonlinear reservoir | storage that contributes directly to streamflow | The nonlinear reservoir is one route by which catchment water storage contributes to streamflow. Its input can include simple bypass through the vadose zone, controlled by frac_to_CR and spf_factor, and free drainage if desired. The nonlinear reservoir releases water to the stream at a rate of a*S^b, where S is the water stored in the reservoir in cm, and a and b are nonlinear reservoir parameters. Note that the units of a depend on the value of b. Defaults to 0.|
+| b | double (scalar) | 0.01 < b < 5 | - | parameter for nonlinear reservoir | storage that contributes directly to streamflow | The nonlinear reservoir is one route by which catchment water storage contributes to streamflow. Its input can include simple bypass through the vadose zone, controlled by frac_to_CR and spf_factor, and free drainage if desired. The nonlinear reservoir releases water to the stream at a rate of a*S^b, where S is the water stored in the reservoir in cm, and a and b are nonlinear reservoir parameters. Defaults to 0.|
 | frac_to_CR | double (scalar) | 0.0 <= frac_to_CR <= 1 | - | parameter for nonlinear reservoir | storage that contributes directly to streamflow | Simple bypass of water at the soil surface to the nonlinear conceptual reservoir will occur when the most superficial surface wetting front achieves the theta_e value of its layer times spf_factor. When this occurs, the amount of water sent to the nonlinear reservoir is equal to the precipitation plus any ponded water times frac_to_CR. This is a rather simple representation of preferential flow that intends to simulate the episodic nature of streamflow events in arid or semi arid environments. Note that either all or none of a, b, and frac_to_CR must be specified. If none are specified then the model will not simulate a nonlinear reservoir. Defaults to 0.|
 | spf_factor | double (scalar) | 0.1 <= spf_factor <= 1 | - | parameter for fluxes to nonlinear reservoir | storage that contributes directly to streamflow | Simple bypass of surface water to the nonlinear reservoir will occur when the most superficial wetting front achieves the theta_e value of its layer times spf_factor. When this occurs, the amount of water sent to the nonlinear reservoir is equal to the precipitation plus any ponded water times frac_to_CR. This is a rather simple representation of preferential flow that intends to simulate the episodic nature of streamflow events in arid or semi arid environments. Defaults to 0.98. |
-| allow_flux_caching | Boolean | true, false | - | trades a small amount of accuracy for a lot of speed | flux caching | During dry periods, it is often the case that wetting fronts will move very slowly and AET will be significantly less than PET. In these cases, in the context of streamflow simulation, it is not efficient to recompute fluxes and soil moisture dynamics for each time step. If this is set to true, then fluxes and wetting front movement will only be recomputed once every 24 hours, or when the conditions resulting in dry and slow wetting fronts and low AET cease. During the times for which fluxes are not recomputed, instead they are stored in a cache and fluxes for subsequent time steps are set using this cache. Sligtly different strategies are used for fluxes through the lower boundary and AET. Also note that because NextGen models should ideally provide output for each hour, simply setting an adaptive time step to be larger than one hour is not a preferred runtime reduction method here. Note that this can cause small mass balance errors when the lower boundary condition is set to free drainage. Defaults to false. |
-| log_mode | Boolean | true, false | - | helps calibration search space exploration | log transform of parameters | When this is set to true, then all inputs for the van Genuchten parameter alpha, saturated hydraulic conductivity, and the nonlinear reservoir parameter a must be input as their log values rather than the normal values. For example, if an saturated hydraulic conductivity of 0.1 cm/h is desired, then the input value must be -1 because 10^-1 = 0.1. The reasoning for this is that these parameters are not distributed normally in nature but rather are distributed log normally, such that simply sampling the parameter space normally during calibration will vastly undersample a big region of the parameter space in which we expect useful parameter sets to be. Defaults to false. |
+| allow_flux_caching | Boolean | true, false | - | trades a small amount of accuracy for a lot of speed | flux caching | During dry periods, it is often the case that wetting fronts will move very slowly and AET will be significantly less than PET. In these cases, in the context of streamflow simulation, it is not efficient to recompute fluxes and soil moisture dynamics for each time step. If this is set to true, then fluxes and wetting front movement will only be recomputed once every 24 hours, or when the conditions resulting in dry and slow wetting fronts and low AET cease. During the times for which fluxes are not recomputed, instead they are stored in a cache and fluxes for subsequent time steps are set using this cache. Sligtly different strategies are used for fluxes through the lower boundary and AET. Flux caching is disabled whenever lateral flow is enabled and at least one wetting front is eligible to contribute lateral flow. Also note that because NextGen models should ideally provide output for each hour, simply setting an adaptive time step to be larger than one hour is not a preferred runtime reduction method here. Note that this can cause small mass balance errors when the lower boundary condition is set to free drainage. Defaults to false. |
+| log_mode | Boolean | true, false | - | helps calibration search space exploration | log transform of parameters | When this is set to true, then all inputs for the van Genuchten parameter alpha, saturated hydraulic conductivity, the nonlinear reservoir parameter a, lateral_flow_psi_threshold, and lateral_flow_factor must be input as their log10 values rather than the normal values. For example, if an saturated hydraulic conductivity of 0.1 cm/h is desired, then the input value must be -1 because 10^-1 = 0.1. The reasoning for this is that these parameters are not distributed normally in nature but rather are distributed log normally, such that simply sampling the parameter space normally during calibration will vastly undersample a big region of the parameter space in which we expect useful parameter sets to be. Defaults to false. |
 | a_slow | double (scalar) | 1E-8 < a_slow < 1E-1 | cm^(1-b) h^-1 | parameter for second nonlinear reservoir | storage that contributes directly to streamflow | This is exactly like the parameter a, except it corresponds to a second nonlinear reservoir, which was added to simulate cases where receding limbs have behaviors that can not easily be captured by one reservoir. Defaults to 0.|
 | b_slow | double (scalar) | 0.01 < b_slow < 5 | - | parameter for second nonlinear reservoir | storage that contributes directly to streamflow | This is exactly like the parameter b, except it corresponds to a second nonlinear reservoir, which was added to simulate cases where receding limbs have behaviors that can not easily be captured by one reservoir. Defaults to 0.|
-| frac_slow | double (scalar) | 0.0 < frac_slow <= 1 | - | parameter for second nonlinear reservoir | storage that contributes directly to streamflow | This describes the partitioning of water to the two reservoris, where the the input to the slow reservoir is equal to the total input for the nonlinear reservoirs times frac_slow. Note that either all or none of a_slow, b_slow, and frac_slow must be specified. If none are specified then the model will not simulate a second nonlinear reservoir. Defaults to 0.|
+| frac_slow | double (scalar) | 0.0 < frac_slow <= 1 | - | parameter for second nonlinear reservoir | storage that contributes directly to streamflow | This describes the partitioning of water to the two reservoris, where the the input to the slow reservoir is equal to the total input for the nonlinear reservoirs times frac_slow. Note that either all or none of a_slow, b_slow, and frac_slow must be specified. If none are specified then the model will not simulate a second nonlinear reservoir. Defaults to 0.|