ELM Example Case I. Point Mode

ELM Examples of Setting-up, Configuring, Building, and Running I

Updated: 05-23-2024

NOTE:

• In these examples, there are 4 user-defined ENVs variables of directories: $E3SM_INPUTDATA, $E3SM_ROOT, $PROJECT_E3SM, for inputdata, e3sm model source codes, and root directory for cases and runs, respectively. USERS must have created these, and cloned both data and e3sm codes.

• $E3SM_INPUTDATA is cloned repository of a few site-level full datasets to run offline ELM, from pt-e3sm-inputdata

• Upon user's machine, $MACH_NAME is needed for E3SM. In these examples, 'mymac' for MacOS/linux, 'WSL2' for Windows Subsystem for Linux, OR, 'cades' for a cluster in ORNL, may be directly used. Additionally the example assumes using mpich for MPI, and if not, change '-mpilib mpich' STEP 1 to what in your system, e.g. ' -mpilib openmpi' for OPENMPI.

- CASE I. Single-Point User-Defined datm-elm.

An extra note (04-04-29): If you're using python 3.12 or above, 'distutils' IS totally removed but which are required by CIME. The alternative is 'setuptools', and if install it like: pip3 install setuptools, it will work seamlessly.

As briefed before (https://github.com/fmyuan/E3SM/wiki#1-codes-inputdata-and-scripts-for-configuring-building-and-running), There are 3 consecutive stages: accelerated spinup -> (normal) spinup -> transient, with later stage depending on previous one. Each stage requires 3 steps: create, setup/build, and run.

• STEP 1. Create a ELM_USRDAT case

(1) If in 'accelerated spinup' stage.

  cd $E3SM_ROOT/cime/scripts

  ./create_newcase -case $PROJECT_E3SM/cases/Test_elm-I1850CNRDCTCBC_adspinup -mach $MACH_NAME -compiler gnu -mpilib mpich -res ELM_USRDAT -compset I1850CNRDCTCBC

NOTE: $MACH_NAME is one of machines supported in E3SM, which names could be found in $E3SM_ROOT/cime_config/machines/config_machine.xml.

(2) If in '(normal) spinup' stage.

  cd $E3SM_ROOT/cime/scripts

  ./create_newcase -case $PROJECT_E3SM/cases/Test_elm-I1850CNPRDCTCBC -mach $MACH_NAME -compiler gnu -mpilib mpich -res ELM_USRDAT -compset I1850CNRDCTCBC

(3) If in 'transient' stage.

  cd $E3SM_ROOT/cime/scripts

  ./create_newcase -case $PROJECT_E3SM/cases/Test_elm-I20TRCNPRDCTCBC -mach $MACH_NAME -compiler gnu -mpilib mpich -res ELM_USRDAT -compset I20TRCNPRDCTCBC

• STEP 2. Setup and Build the case created in STEP 1 (user-defined 1 point dataset, namely '1x1pt_US-Brw' from 1985-2015)

(1) If in 'accelerated spinup' stage.

cd $PROJECT_E3SM/cases/Test_elm-I1850CNRDCTCBC_adspinup

./xmlchange (or, vi env_run.xml)
             DATM_MODE=CLM1PT
             DATM_CLMNCEP_YR_START=1985
             DATM_CLMNCEP_YR_END=2015
             ELM_USRDAT_NAME=1x1pt_US-Brw_GRID

./xmlchange ELM_FORCE_COLDSTART=on  
./xmlchange --append --id ELM_BLDNML_OPTS --val "-bgc_spinup on"
./xmlchange STOP_N=200
./xmlchange STOP_OPTION=nyear

(2) If in '(normal) spinup' stage.

cd $PROJECT_E3SM/cases/Test_elm-I1850CNPRDCTCBC

./xmlchange (or, vi env_run.xml)
             DATM_MODE=CLM1PT
             DATM_CLMNCEP_YR_START=1985
             DATM_CLMNCEP_YR_END=2015
             ELM_USRDAT_NAME=1x1pt_US-Brw_GRID

./echo " 
 finidat = '$PROJECT_E3SM/runs/Test_elm-I1850CNRDCTCBC_adspinup/run/Test_elm-I1850CNRDCTCBC_adspinup.elm.r.0201-01-01-00000.nc'
" >> user_nl_elm;

./xmlchange STOP_N=600
./xmlchange STOP_OPTION=nyear

NOTE, $PROJECT_E3SM/runs/ is the root for your simulations, WHICH totally upon your machine setting in model. You MUST know where exactly it is on your machine. AND the file is from the previous 'accelerated spinup' stage, which you MUST make sure is in referred path.

(3) If in 'transient' stage.

cd $PROJECT_E3SM/cases/Test_elm-I20TRCNPRDCTCBC

./xmlchange (or, vi env_run.xml)
             DATM_MODE=CLM1PT
             DATM_CLMNCEP_YR_START=1985
             DATM_CLMNCEP_YR_END=2015
             ELM_USRDAT_NAME=1x1pt_US-Brw_GRID


./echo " 
 finidat = '$PROJECT_E3SM/runs/Test_elm-I1850CNPRDCTCBC/run/Test_elm-I1850CNPRDCTCBC.elm.r.0601-01-01-00000.nc'
" >> user_nl_elm;

./xmlchange STOP_N=165
./xmlchange STOP_OPTION=nyear

NOTE, AGAIN - $PROJECT_E3SM/runs/ is the root for your simulations, WHICH totally upon your machine setting in model. You MUST know where exactly it is on your machine. AND the file is from the previous '(normal) spinup' stage, which you MUST make sure is in referred path.

After configuration above,

./case.setup 
(./case.setup --clean FOR cleaning-up)

NOTE that,

If it's the first time, the ./case.setup will generate a long sentence of error message something like:

failed with error 'ERROR : CLM build-namelist::ELMBuildNamelist::add_default() : No default value found for fsurdat.
            Are defaults provided for this resolution and land mask?' from dir '/Users/f9y/project_e3sm/cases/Test_elm-I1850CNRDCTCBC_spinup/Buildconf/elmconf'

It indicates 'fsurdat' NOT correctly set up, and mostly it's due to 'pt-e3sm-inputdata' 's file name issue. So do a softlink to the correct file, such as:

./case.build
(./case.build --clean FOR cleaning-up ALL components, and you may want to clean-up one or two)

The above steps will create a 'bld/' and '/run' directories, for model building and running (which you can look for results):

(1) If in 'accelerated spinup' stage.

$PROJECT_E3SM/runs/Test_elm-I1850CNRDCTCBC_adspinup/

(3) If in '(normal) spinup' stage.

$PROJECT_E3SM/runs/Test_elm-I1850CNPRDCTCBC/

(3) If in 'transient' stage.

$PROJECT_E3SM/runs/Test_elm-I20TRCNPRDCTCBC/

• STEP 3. Run the case

  ./case.submit

NOTE: THIS Case example would be simulating AmeriFlux US-Brw tower site more reasonably, if using a phenologically-modified ELM, in which upper 3 soil-layer averaged temperature is used to drive leaf-out for stressed PFTs, SEE modified ELM phenology