Model configuration#

Reads in model configuration from .yml file

Model setup options and model parameters are read from a .yml file, which can be modified by the user.

See Scaling for details about how parameters are converted.

Modifying the config file#

.yml file contents#

See model_config.yml for an example.

Note

FETCH3 can also use the config file format that is used for optimization runs, as long as value is specified for every parameter.

Model options#

make_experiment_dir (bool, optional): Whether or not FETCH should create a new experiment inside the specified output directory for the results of the model run. If True, FETCH will write the model outputs to a new directory labeled with the experiment name and the timestamp of the run. If False or not provided, the outputs will be written directly inside the output directory.
experiment_name (str, optional): Optional label for the run. This is simply used for labeling the output directory.
input_fname (str): File for input met data
met_column_labels (dict): Dictionary specifying the mapping of the column headers in your input file to the required input variables. This is needed if your column headers differ from the default variable names. See Prepare input files for the model for a list of the default variable names. Each element in the dictionary should be formatted as <your column header>: <standard variable name>, for example:
```
met_column_labels:
  CO2_F_MDS: CO2_F
```
Alternately, the dictionary can also be formatted as:
```
met_column_labels: {'CO2_F_MDS': 'CO2_F'}
```
start_time (str): [“YYYY-MM-DD HH:MM:SS”] Begining of simulation
end_time (str): [“YYYY-MM-DD HH:MM:SS”] End of simulation
``dt``(int): [seconds] Input data resolution
tmin (int): [s] #tmin #TODO

Site information#

latitude (float): Latitude of site in decimal degrees
longitude (longitude): Longitude of site in decimal degrees
time_offset (float): Offset from UTC time, e.g EST = UTC -5 hrs. This is used in the calculation of the zenith angle to figure out the standard meridian of your location. It is not used to shift the timestamps in your input data. Timestamps in the input data should be in local standard time.

Run options - printing#

Options to turn printing off or specify print frequency. Printing the run progress every timestep will slow down the model run (and make your log file very long). The model will run faster if printing is turned off or set to print more infrequently.

print_run_progress (bool): Turns on/off printing for progress of the model run. print_run_progress: False will turn off printing the progress of the timesteps calculated.
print_freq (int): Interval of timesteps to print if print_run_progress = True (e.g. print_freq: 100 will print every 100 timesteps).

Transpiration options#

transpiration_scheme (int): Whether to use the PM transpiration scheme or the NHL transpiration scheme
- 0: PM transpiration
- 1: NHL transpiration
lad_scheme (int) : 0: default scheme, based on Lalic et al 2014; 1: scheme from NHL module
LAD_norm (str): File with normalized LAD data
sum_LAI_plot (float): Total LAI for the plot
Cd (float): Drag coefficient
alpha_ml (float): Mixing length constant

Numerical solution time and space constants (dz and dt0)#

The finite difference discretization constants

dt0 (int): model temporal resolution [s]
dz (float): model spatial resolution [m]
stop_tol (float): stop tolerance of equation converging

Soil boundary conditions#

Here the user can choose the desired soil boundary conditions as described below. The configuration used in the example config file follows Verma et al. 2014.

UpperBC (int): Upper boundary condition Options:
- 1: no flux (Neuman)
- 0: infiltration
BottomBC (int): Bottom boundary condition Options:
- 2: free drainage
- 1: no flux (Neuman)
- 0: constant potential (Dirichlet)
frac_infiltration (float): Fraction of precipitation that should infiltrate to the soil (can use to account for interception & runoff)

Site parameters#

Soil spatial discretization#

Soil_depth (float): [m] depth of soil column

Configuration of soil duplex#

Depths of layer/clay interface

sand_d (float): # Depth of sand layer #m
clay_d (float): Depth of clay layer. #m

Soil initial conditions#

initial_swc_clay (float): initial soil water content for the clay layer [m3 m-3]
initial_swc_sand (float): initial soil water content for the sand layer [m3 m-3]
soil_moisture_bottom_boundary (float): Soil moisture content [m3 m-3] for bottom boundary. Only used if the Dirichlet bottom boundary condition is used

Soil parameters - using Van Genuchten relationships#

Clay:

alpha_1 (float): soil hydraulic parameter [1/m]
theta_S1 (float): saturated volumetric soil moisture content [-]
theta_R1 (float): residual volumetric soil moisture content [-]
n_1 (float): soil hydraulic parameter [-]
Ksat_1 (float): saturated hydraulic conductivity [m/s]

Sand: same definitions as above, but for sand

alpha_2 (float):
theta_S2 (float):
theta_R2 (float):
n_2 (float):
Ksat_2 (float):

Species parameters#

Each species will have a section in the config file, labeled with the species name, that must include these parameters.

Soil stress parameters:

theta_1_clay (float)
theta_2_clay (float)
theta_1_sand (float)
theta_2_sand (float)

Root parameters#

Root_depth (float): Depth of root column
Kr (float): soil-to-root radial conductance [m/sPa]
qz (float): unitless - parameter for the root mass distribution - Verma et al., 2014
Ksax (float): specific axial conductivity of roots [m/s]
Aind_r (float): [m2 root xylem/m2 ground]

Xylem parameters#

kmax (float): conductivity of xylem [m2/sPa]
ap (float): xylem cavitation parameter [Pa-1]
bp (float): xylem cavitation parameter [Pa]
Phi_0 (float): From bohrer et al 2005
p (float): From bohrer et al 2005
sat_xylem (float): From bohrer et al 2005

Tree parameters#

sapwood_depth: [cm]
Hspec (float): Height average of trees [m]
LAI (float): [-] Leaf area index
dbh: [cm]
stand_density_sp: species-specific stand density [trees ha-1]

NHL transpiration scheme parameters#

If using the NHL transpiration scheme.

scale_nhl (float): scaling parameter for NHL transpiration
mean_crown_area_sp (float):
Cf (float): Clumping fraction [unitless], assumed to be 0.85 (Forseth & Norman 1993) unless otherwise specified
x (float): Ratio of horizontal to vertical projections of leaves (leaf angle distribution), assumed spherical (x=1)
Vcmax25 (float):
alpha_gs (float):
alpha_p (float):
wp_s50 (float):
c3 (float):

Penman-Monteith transpiration parameters#

parameters if using penman-monteith transpiration scheme, based on Lalic et al 2014 if using NHL transpiration scheme, LAD is calculated in NHL module

L_m (float): maximum value of LAD a canopy layer
z_m (float): height in which L_m is found [m]

Penman-Monteith equation parameters Note: W m^-2 is the same as J s^-1 m^-2 1J= 1 kg m2/s2 therefore 1W/m2 = kg/s3

gb (float): [m/s] Leaf boundary layer conductance
Cp (float): [J/m3 K] Heat capacity of air
ga (float): [m/s] Aerodynamic conductance
lamb (float): [J/m3] latent heat of vaporization
gama (float): [Pa/K] psychrometric constant

Jarvis parameters

gsmax (float): [m/s] Maximum leaf stomatal conductance
kr (float): [m2/W] Jarvis radiation parameter
kt (float): [K-2] Jarvis temperature parameter
Topt (float): [K] Jarvis temperature parameter (optimum temperature)
kd (float): *[Pa-1] Jarvis vapor pressure deficit temperature
hx50 (float): [Pa] Jarvis leaf water potential parameter
nl (float): [-] Jarvis leaf water potential parameter
Emax (float): [m/s] maximum nightime transpiration

class NHLModelOptions(input_fname: str, start_time: str, end_time: str, dt: int, tmin: int, latitude: float, longitude: float, time_offset: float, print_run_progress: bool, print_freq: int, lad_scheme: int, dt0: int, dz: float, stop_tol: float, species: str, UpperBC: int, BottomBC: int, LAD_norm: Optional[str] = None, LAD_column_labels: Optional[dict] = None, make_experiment_dir: bool = False, experiment_name: Optional[str] = None, met_column_labels: Optional[dict] = None, model_dir: Optional[str] = None, data_path: Optional[str] = None, zenith_method: str = 'CN')#: NHL Model Options

class TranspirationScheme(value)#: An enumeration.

get_enum(val, enum)#: Get enum from string or int, normalize string, returning enum value

get_multi_config(config_path: Optional[Union[str, PathLike]] = None, config: Optional[dict] = None, species: Optional[Union[str, list[str]]] = None) → list[fetch3.model_config.ConfigParams]#: Get a list of ConfigParams objects from a config file or dict

get_single_config(config_path: Optional[Union[str, PathLike]] = None, config: Optional[dict] = None, species: Optional[str] = None) → ConfigParams#: Get a list of ConfigParams objects from a config file or dict