Create Scripts
The create_fates_run.sh script is a set of instructions specifying the configuration of the FATES run.
An example script is found in the fates-tutorial repository under run_scripts (outside the container) or scripts (insdie the container).
To run the create script and launch a FATES simualtion, from inside the elm-fates container,
change directory to the scripts directory and type:
./create_elm-fates-singlepoint-1pft_bci_invinit.sh
In the page below we explain what key parts of the script do.
Open create_elm-fates-singlepoint-1pft_bci_invinit.sh
with your text editor of choice and then see below for details.
#!/bin/sh
# =======================================================================================
# =======================================================================================
export CIME_MODEL=e3sm
export COMPSET=2000_DATM%QIA_ELM%BGC-FATES_SICE_SOCN_SROF_SGLC_SWAV
export RES=ELM_USRDAT
export MACH=docker # Name your machine
export COMPILER=gnu # Name your compiler
export SITE=bci # Name your site
The first line indicates that this is a shell script. Next is a block of code indicating some model configurations. The CIME model is the infrastructure that allows different model components to communicate, for example, the land model and the atmospheric model. The COMPSET specifies which components are active. Here we will run land only simulations. RES is the model resolution. In a global run this would be the size of each model grid cell. Here we specify that we are running FATES as a single point. MACH is the machine being used. In this case we specify docker since we are running FATES via docker. FATES and the host land model code is written in Fortran which is a compiled language. The COMPILER option specifies which compiler to use. Here we use gnu as this is installed in the docker environment. Finally, SITE is where we tell FATES which site we are going to run the simulation, in this case BCI.
We make some variables to use in the rest of the script.
export TAG=fates-tutorial-${SITE}-inventory_init # give your run a name
export CASE_ROOT=/output/${SITE} # where in scratch should the run go?
export PARAM_FILES=/paramfiles # FATES parameter file location
The next code block specifies where the surface and domain files needed to run FATES are located.
# surface and domain files
export SITE_BASE_DIR=/sitedata
export ELM_USRDAT_DOMAIN=domain_${SITE}_fates_tutorial.nc
export ELM_USRDAT_SURDAT=surfdata_${SITE}_fates_tutorial.nc
export ELM_SURFDAT_DIR=${SITE_BASE_DIR}/${SITE}
export ELM_DOMAIN_DIR=${SITE_BASE_DIR}/${SITE}
export DIN_LOC_ROOT_FORCE=${SITE_BASE_DIR}
The surface dataset contains information on the soil properties and the fraction of the grid cell that is natural vegetation. The domain file contains information on the lat and lon of the site and what fraction of the grid cell is active i.e. running FATES. DIN_LOC_ROOT_FORCE forces the model to use climate driving data located within the site directory.
Climate data is stored in the sitedata directory. For simulations at new sites we will use GSWP3 reanalysis data that has been subset to only the grid cell of each site. Since this data is only available from the years 2003 to 2014 we tell the model to keep cycling the climate data so that we can run longer simulations. For BCI, we have meterological data from a tower at the site, and we can use this data which is available between 2003 and 2016.
# climate data will recycle data between these years
export DATM_START=2003
export DATM_STOP=2016
The next code block changes into the directory where the scripts needed to create a FATES case are located. We make a case name by appending today’s date to the tag defined above.
# DEPENDENT PATHS AND VARIABLES (USER MIGHT CHANGE THESE..)
# =======================================================================================
export SOURCE_DIR=/E3SM/cime/scripts # change to the path where your E3SM/cime/sripts is
cd ${SOURCE_DIR}
export CASE_NAME=${CASE_ROOT}/${TAG}.`date +"%Y-%m-%d"`
Within the E3SM/cime/scripts directory is the create_newcase script which we call with arguments defined above to set up the FATES simualtion. When the case has been created we change into the case directory.
# REMOVE EXISTING CASE IF PRESENT
rm -r ${CASE_NAME}
# CREATE THE CASE
./create_newcase --case=${CASE_NAME} --res=${RES} --compset=${COMPSET} --mach=${MACH} --compiler=${COMPILER} --project=${PROJECT}
cd ${CASE_NAME}
The next two blocks of code can be ignored as they relate to the inner workings of the host land model.
The next chunk of code relevant for the tutorial is where we specify run type preferences.
# SPECIFY RUN TYPE PREFERENCES (USERS WILL CHANGE THESE)
# =================================================================================
./xmlchange DEBUG=FALSE
./xmlchange STOP_N=10 # how many years should the simulation run
./xmlchange RUN_STARTDATE='1900-01-01'
./xmlchange STOP_OPTION=nyears
./xmlchange REST_N=10 # how often to make restart files
./xmlchange RESUBMIT=0 # how many resubmits
./xmlchange DATM_CLMNCEP_YR_START=${DATM_START}
./xmlchange DATM_CLMNCEP_YR_END=${DATM_STOP}
Here we set DEBUG to FALSE as (hopefully) everything should be running smoothly in the tutorial. If you are ever encountering errors when trying to get FATES to compile or run, then setting DEBUG to true might mean you get more informative error messages. STOP_N is how many time steps to run the simulation, with the unit of time specified by STOP_OPTION - in this case years. REST_N specifies how often to write restart files - these are a snapshot of the simulation containing all necessary information on the ecosystem to be able to restart the run from that point. RUN_STARTDATE is fairly arbitrary in this case - we chose 1900 for no particular reason. RESUBMIT is set to 0 here. In very long simulations (decades or centuries) it can help to run FATES in smaller chunks by setting STOP_N to a factor of the total length of the simulation and increasing RESUBMIT such that RESUBMIT x STOP_N equals the total simulation length.
The next block of code specifies where to build the case and where to save model outputs.
# MACHINE SPECIFIC, AND/OR USER PREFERENCE CHANGES (USERS WILL CHANGE THESE)
# =================================================================================
./xmlchange GMAKE=make
./xmlchange RUNDIR=${CASE_NAME}/run
./xmlchange EXEROOT=${CASE_NAME}/bld
The next bit is where we edit the user_nl_elm file. The user_nl_elm file specifies namelist options, such as which optional modules to turn on, and points to the parameter file and inventory data. It also defines which history variables to output.
# point to your parameter file
# add any history variables you want
cat >> user_nl_elm <<EOF
fsurdat = '${ELM_SURFDAT_DIR}/${ELM_USRDAT_SURDAT}'
fates_paramfile='${PARAM_FILES}/fates_params_default-1pft.nc'
use_fates=.true.
use_fates_inventory_init = .true.
fates_inventory_ctrl_filename = '/inventorydata/inventory_ctrl/fates_${SITE}_inventory_ctrl'
fluh_timeseries=''
hist_fincl1=
'FATES_VEGC_PF', 'FATES_VEGC_ABOVEGROUND',
'FATES_NPLANT_SZ', 'FATES_CROWNAREA_PF',
'FATES_LAI', 'FATES_BASALAREA_SZPF', 'FATES_CA_WEIGHTED_HEIGHT', 'Z0MG',
'FATES_MORTALITY_CSTARV_CFLUX_PF', 'FATES_MORTALITY_CFLUX_PF',
'FATES_MORTALITY_HYDRO_CFLUX_PF', 'FATES_MORTALITY_BACKGROUND_SZPF',
'FATES_MORTALITY_HYDRAULIC_SZPF', 'FATES_MORTALITY_CSTARV_SZPF',
'FATES_MORTALITY_IMPACT_SZPF', 'FATES_MORTALITY_TERMINATION_SZPF',
'FATES_MORTALITY_FREEZING_SZPF', 'FATES_MORTALITY_CANOPY_SZPF',
'FATES_MORTALITY_USTORY_SZPF', 'FATES_NPLANT_SZPF',
'FATES_NPLANT_CANOPY_SZPF', 'FATES_NPLANT_USTORY_SZPF',
'FATES_NPP_PF', 'FATES_GPP_PF', 'FATES_NEP', 'FATES_FIRE_CLOSS',
'FATES_ABOVEGROUND_PROD_SZPF', 'FATES_ABOVEGROUND_MORT_SZPF',
'FATES_NPLANT_CANOPY_SZ', 'FATES_NPLANT_USTORY_SZ',
'FATES_DDBH_CANOPY_SZ', 'FATES_DDBH_USTORY_SZ',
'FATES_MORTALITY_CANOPY_SZ', 'FATES_MORTALITY_USTORY_SZ'
EOF
More information on history outputs is in the ‘FATES History Outputs’ section of the Read the Docs.
use_fates_inventory_init = .true.
fates_inventory_ctrl_filename = '/inventorydata/inventory_ctrl/fates_${SITE}_inventory_ctrl'
These two lines tell FATES that we want to start the run by reading in the forest size structure from inventory data, which is detailed in the control file. hist_fincl1 is followed by a list of the history files to output. Some files are output by default but larger files we have to specify here. These are the outputs that we will use to plot results of the simulation. Think carefully about these because it is a real pain to wait days or hours for a simulation to finish and then realize it didn’t include the history variables you need.
In the next bit of code we tell the model to recycle the three climate data streams (solar, precipitation and wind) so that we can run simulations longer than the length of the climate time series.
cat >> user_nl_datm <<EOF
taxmode = "cycle", "cycle", "cycle"
EOF
We then set up the case and check the namelist options with the two following commands
./case.setup
./preview_namelists
We copy the climate data information to the user_datm.streams.txt.CLM1PFT.ELM_USRDAT so that the simulation will know where to look for it and modify it using sed so it is in the correct format.
cp run/datm.streams.txt.CLM1PT.ELM_USRDAT user_datm.streams.txt.CLM1PT.ELM_USRDAT
`sed -i '/FLDS/d' user_datm.streams.txt.CLM1PT.ELM_USRDAT`
And that is it! We are ready to build the run and launch it with the following two commands:
./case.build --skip-provenance-check # skipping provenance avoids calling git (for this tutorial only)
./case.submit
To kick off the simulation we run the create script from the command line. In terminal, from inside the scripts directory (within the container) run the following:
./create_elm-fatese-singlepoint-1pft_bci_invinit.sh
A lot of text will go zooming by as the code is compiled and the case is built. To see if it has worked you can change directory to the case and watch the .elm.h0. files appear.