FETCH3.14¶
This notebook documents the process of running the FETCH3.14 model using BOA. Because FETCH3.14 model is more difficult to install than SWAT+ currently (SWAT+ is a single not very large executable), it is not included in this repository, so only instructions on how to run it are provided. All the necessary files are included in the repository, so you can run the model on your own machine or on a SLURM cluster.
FETCH3.14 has first class support for Bayesian optimization through BOA. This means that you can run FETCH3.14 with BOA to optimize your FETCH3.14 model with BO without needing to write any additional code. This is done directly in the FETCH3.14 configuration file giving users a convenient and seamless experience.
1# This notebook uses hidden cells to import and display things so
2# that it can be ran regullary to make sure the documentation
3# is up to date and not broken (as opposed to a markdown file
4# that would have an exmaple written once and get out of date
5# as the code base changes)
6
7# These hidden cells are only responsible for rerunning
8# the documentation to ensure it is correct.
9# the actual relavent part of the documentation
10# are the non hidden parts
Configuration File¶
The FETCH3.14 and BOA boa_moo_2_obj_norm_2015_scale.yaml in one
{% set fetch_run_time = '1:30:00' %}
{% set model_dir = '.' %}
{% set data_path = './data/' %}
{% set model_trees = ({
'USA_UMB_CON_Aru_Js_28': {
'Hspec': 17.5,
'dbh': 10.2,
'mean_crown_area_sp': 34.16,
'sapwood_depth': 2.669080975,
'scale_nhl': 0.7854047094285671}
}) %}
{% set tree_names = model_trees.keys()|list %}
{% set hpft = 'maple' %}
objective:
metrics:
{% for tree in tree_names %}
- metric: "RootMeanSquaredError"
name: rmse_{{ tree }}_sapflux
properties:
obs_file: {{ data_path }}USA_UMB_CON_sapf_data_tz.csv
obs_var: {{ tree }}
output_fname: ds_sapflux.nc
output_var: {{ tree }}
fetch_data_func: get_model_sapflux
normalize: True
scaling_factor: 1.1
hour_range: [9, 21]
minimize: True
- metric: "RootMeanSquaredError"
name: rmse_{{ tree }}_wwc
properties:
obs_file: {{ data_path }}wwc_trees_2016.csv
obs_var: m9b
output_fname: ds_sapflux.nc
output_var: theta
species: {{ tree }}
normalize: True
fetch_data_func: get_model_obs
scaling_factor: 1.1
hour_range: [9, 21]
minimize: True
{% endfor %}
scheduler:
n_trials: 200
tolerated_trial_failure_rate: 0.5
ttl_seconds_for_trials: 6000
run_trials_in_batches: true
max_pending_trials: 10
generation_strategy:
num_initialization_trials: 20
max_parallelism_override: 10
script_options:
exp_name: fetch3_moo_2_obj_norm_2015_scale
output_dir: ./output
run_cmd: python main.py --config_path {config_path} --data_path {data_path} --output_path {trial_dir}
# run_cmd: sbatch --output={trial_dir}/slurm_log_%j.log --time={{ fetch_run_time }} {{ model_dir }}/scripts/slurm_main.sh {config_path} {data_path} {trial_dir}
wrapper_path: {{ model_dir }}/fetch3/optimize/fetch_wrapper.py
wrapper_name: Fetch3Wrapper
rel_to_launch: true
model_options:
data_path: {{ data_path }}
make_experiment_dir: False
# File for input met data
input_fname: "umbs_flux_adjustedP5.csv"
# input_fname: FLX_US-UMB_FLUXNET2015_SUBSET_HH_2007-2017_beta-4.csv
met_column_labels:
CO2_F_MDS: CO2_F
# Start and end for the model
start_time: "2016-05-29 00:00:00"
end_time: "2016-08-05 00:00:00"
dt: 1800 #seconds - input data resolution
tmin: 0 #tmin [s]
# Site information
latitude: 45.5598 # From AmeriFlux UMBS page
longitude: -84.7138
time_offset: -5 #Offset from UTC time, e.g EST = UTC -5 hrs
# Run options
# Printing slows down model run
# Options to turn printing off or specify print frequency
print_run_progress: True # Turn on/off printing for progress of time steps calculated
print_freq: 2000 # Interval of timesteps to print if print_run_progress = True (e.g. 1 will print every time step)
# Transpiration options: NHL or PM transpiration scheme
transpiration_scheme: 1 # 0: PM transpiration; 1: NHL transpiration
# Numerical solution time and space constants
#The finite difference discretization constants
dt0: 20 #model temporal resolution [s]
dz: 0.2 #model spatial resolution [m]
stop_tol: .0001 #0.0001 #stop tolerance of equation converging
# Soil boundary conditions
# Upper Boundary condition
# 1 = no flux (Neuman)
# 0 = infiltration
# Bottom Boundary condition
# 2 = free drainage
# 1 = no flux (Neuman)
# 0 = constant potential (Dirichlet)
UpperBC: 0
BottomBC: 0
# Tree information
LAD_norm: 'LAD_data.csv' # File with LAD data
LAD_column_labels:
{% for tree in tree_names %}
{{ tree }}: {{ hpft }}
{% endfor %}
# Leaf area density formulation
lad_scheme: 1 #0: default scheme, based on Lalic et al 2014; 1: scheme from NHL module
groups:
site_parameters:
Soil_depth: 6.0 # [m] depth of soil column
sand_d: 6.0 #4.2----top soil #m
clay_d: 1.0 #0------4.2 #m
# Soil initial conditions
initial_swc_clay: 0.28 #from Verma et al
initial_swc_sand: 0.08 # [m3 m-3] from Verma et al
# soil bottom boundary condition
soil_moisture_bottom_boundary: 0.28 # [m3/m3]
#SOIL PARAMETERS - USING VAN GENUCHTEN RELATIONSHIPS
#CLAY
alpha_1: 0.8 #soil hydraulic parameter [1/m]
theta_S1: 0.55 #saturated volumetric soil moisture content [-]
theta_R1: 0.03 #residual volumetric soil moisture content [-]
n_1: 1.5
Ksat_1: 1.94e-7 #saturated hydraulic conductivity [m/s]
#SAND
alpha_2: 14.5
theta_S2: 0.47
theta_R2: 0.045
n_2: 2.4
Ksat_2: 3.45e-5
#For NHL
sum_LAI_plot: 4.03 # Value from 2015 optical LAI measurements
Cd: 0.1 # Drag coefficient
alpha_ml: 0.1 # Mixing length constant
{{ hpft }}:
# Roots parameters
Root_depth: 0.6 # [m] depth of root column
#Soil stress parameters
theta_1_clay: 0.08
theta_2_clay: 0.12
theta_1_sand: 0.05
theta_2_sand: 0.09
#ROOT PARAMETERS
Kr: 7.2e-10 #soil-to-root radial conductance [m/sPa]
qz: 9 #unitless - parameter for the root mass distribution - Verma et al., 2014
Ksax: 1.0e-05 #specific axial conductivity of roots [ m/s]
Aind_r: 1 #m2 root xylem/m2 ground]
#XYLEM PARAMETERS
kmax: # Max conductivity of saturated stem xylem [m s-1]
type: range
bounds: [1.0e-6, 01.0e-4] #arbitrary range
ap: 2.0e-6 #xylem cavitation parameter [Pa-1]
bp:
type: range
bounds: [-1.5e+7, -1.5e+5] #arbitrary range: xylem cavitation parameter [Pa]
Phi_0: 5.74e+8 #From bohrer et al 2005
p: 20 #From bohrer et al 2005
sat_xylem: 0.573 # From bohrer et al 2005
#TREE PARAMETERS
taper_top: 1.0 # Taper of xylem from base to crown
stand_density_sp: 160.9195402 # Species-specific stand density [trees ha-1]
LAI: 0.779051285 # From 2015 litter trap measurements (adjusted by optical measurements)
#########################################################################3
#NHL PARAMETERS
###########################################################################
Cf: 0.85 #Clumping fraction [unitless], assumed to be 0.85 (Forseth & Norman 1993) unless otherwise specified
x: 1.0 #Ratio of horizontal to vertical projections of leaves (leaf angle distribution), assumed spherical (x=1)
Vcmax25: 50.0 # Default value from Mirfenderesgi et al 2016
m: 4.0 # Default value from Mirfenderesgi et al 2016
alpha_p: 0.8 # Default value from Mirfenderesgi et al 2016
wp_s50:
type: range
bounds: [-2.0e+6, -1.0e+5] # Range from Mirfenderesgi et al 2016, Table 2
c3:
type: range
bounds: [0.1, 20.0] # Range from Mirfenderesgi et al 2016, Table 2
model_trees:
{% for tree, params in model_trees.items() %}
{{ tree }}:
parents: ['site_parameters', {{ hpft }}]
scale_nhl: {{ params['scale_nhl'] }}
Hspec: {{ params['Hspec'] }}
dbh: {{ params['dbh'] }}
mean_crown_area_sp: {{ params['mean_crown_area_sp'] }}
sapwood_depth: {{ params['sapwood_depth'] }}
{% endfor %}
Run Model Wrapper Script¶
FETCH3.14 does not have a run model script because it utilizes the BOA python API to run the model. This is done by overriding the BOA wrapper methods to control the model execution. FETCH3.14 then specifies to BOA how to find this subclassed wrapper under the script_options section in the above config. All of this is directly part of the FETCH3.14 model, so the user does not need to worry about it giving FETCH3.14 first class support through BOA to Bayesian optimization, and allowing users to access that optimization through their normal FETCH3.14 configuration.
Running our script¶
To run our script we would just need to pass the config file to BOA’s CLI
python -m boa --config-file path/to/config.yaml
or
python -m boa -c path/to/config.yaml