Skip to content

Part 8: Setting Up a Site-Level FATES Simulation

So far we have run a standard CLM-FATES simulation using global datasets.

Next we will run FATES at a single site using inventory and meteorological observations.

Site-level simulations allow direct comparison with field measurements such as:

  • Forest inventories
  • Flux tower measurements
  • Local meteorological observations
  • Trait measurements

Example Site: Barro Colorado Island (BCI)

For this tutorial we will use:

Barro Colorado Island (BCI), Panama

The simulation uses:

Inventory data
Local meteorological forcing
FATES vegetation dynamics

Creating a Parameter File Directory

Create a directory for custom parameter files:

mkdir $VSC_SCRATCH/cesm/params

Move into it:

cd $VSC_SCRATCH/cesm/params

Copy the Default FATES Parameter File

Copy the default parameter file from the default global simulation:

cp $VSC_SCRATCH/cesm/inputdata/lnd/clm2/paramdata/fates_params_api.32.0.0_12pft_c231215.nc \
   fates_params_default.nc

Inspecting with NCDUMP

FATES parameter files are stored as NetCDF files.

You can easily inspect any netcdf using:

ncdump -h fates_params_default.nc

Where -h makes the output more human readable

As this parameter file is very large, it can be converted to a simple text file and opened using nano or any other text editor.

Convert NetCDF to CDL:

ncdump fates_params_default.nc > fates_params_default.cdl

Read it like any text file: 

nano fates_params_default.cdl

Optionally convert CDL back to NetCDF if you made changes:

ncgen -o fates_params_default.nc fates_params_default.cdl

Verify the files exist:

ls

Create a Single-PFT Parameter File

Copy the PFT manipulation script:

cp $VSC_SCRATCH/cesm/sources/ctsm-5.2.0/src/fates/tools/FatesPFTIndexSwapper.py .

Load SciPy:

old: 

module purge
ml SciPy-bundle/2023.07-gfbf-2023a

Create a parameter file containing only a single tropical PFT:

./FatesPFTIndexSwapper.py \
    --fin=fates_params_default.nc \
    --fout=fates_params_default-1pft.nc \
    --pft-indices=1

The default FATES parameter file contains 12 PFTs. We create a simplified parameter file containing only one PFT.

The resulting file will be used in the site-level simulations described in the following sections.

Then reload the cesm module:

module purge
module load CESM-deps/2-foss-2024a

Part 9: Running a Site-Level FATES Simulation

The easiest way to run FATES is through a create script that automates all four CESM workflow steps:

  1. create_newcase
  2. case.setup
  3. case.build
  4. case.submit

Examples of FATES create scripts which combine all four run steps described before can be found here:

GitHub Runscripts

For this tutorial we will use:

create_clm-fates-bci_jra-init.sh

This script builds and submits a run at Barro Colorado Island (BCI), initializing with inventory data.

Download Tutorial Files

Clone the tutorial repository:

cd $VSC_SCRATCH/cesm

git clone https://github.com/sdeherto/CLM-FATES4UGent.git

Copy the required directories:

cp -r CLM-FATES4UGent/runscripts .
cp -r CLM-FATES4UGent/sitedata .
cp -r CLM-FATES4UGent/inventory .

Modify the Create Script

Move to the runscripts directory:

cd $VSC_SCRATCH/cesm/runscripts

Open the file and check it out. Some paths contain a hardcoded VSC number. We will replace those with your username.

Exit the file ('esc, then ':q!')

Replace directly from the terminal:

Make sure to replace {your_number} below with your vsc user number!

sed -i 's/vsc46573/vsc{your_number}/g' create_clm-fates-bci_jra-init.sh

Check it with:

grep -n "vsc46573" create_clm-fates-bci_jra-init.sh

If it returns nothing it worked.

Run the Create Script

Make the script executable:

chmod u+x create_clm-fates-bci_jra-init.sh

Launch the simulation:

./create_clm-fates-bci_jra-init.sh

The script will automatically:

  • Create the case
  • Configure the case
  • Build the executable
  • Submit the run

You will see a large amount of CESM output as the model compiles.

Monitor Progress

Check the queue:

squeue

When the job status becomes:

R

the simulation is actively running.

Monitor the Output

Navigate to the run directory.

Example:

cd output/fates-tutorial-bci_jra-inventory_init.2024-08-30/run

List the files:

ls

You should begin to see monthly output files such as:

*.elm.h0.1900-01.nc

One file is produced for each output period. Congrats, take a break!