2025 E3SM All-Hands EAMxx Tutorial

Housekeeping

Open a terminal and ssh into NERSC account

ssh <username>@perlmutter-p1.nersc.gov

Make a git clone of E3SM (if you don’t already have a copy):

git clone git@github.com:E3SM-Project/E3SM.git
git submodule update --init --recursive

E3SM Case Setup

For the sake of time, compile E3SM case by running provided script at

/global/cfs/cdirs/e3sm/eamxx-tutorial-2025/runscript/run_e3sm.template.sh

For reference see: https://docs.e3sm.org/E3SM/EAMxx/

Agenda

Part 1: Running and changing an EAMxx case
Runtime options, controlling output, DPxx, running unit tests

Part 2: Adding a new process to EAMxx
AtmosphereProcess interface, adding a process, running it

Running EAMxx cases

Identical to typical E3SM cases, but using compset F2010-SCREAMv1

Edit the run script provided to suit your needs

/global/cfs/cdirs/e3sm/eamxx-tutorial-2025/runscript/run_e3sm.template.sh

Update CODE_ROOT to point to your E3SM clone

Run the script!

Goals of Part 1

Build E3SM with EAMxx

Make runtime changes to EAMxx

Add, remove, and adjust output streams

Primer on DPxx

Run unit tests

Runtime options

namelist options are in YAML now!

 nudge_tprof            = 0
 nudge_ucoef            = 1.
 nudge_uprof            = 2
 nudge_vcoef            = 1.
 nudge_vprof            = 2
 nudge_vwin_hdelta              = 0.1
 nudge_vwin_hi          = 1.
 nudge_vwin_hindex              = 80.
 nudge_vwin_ldelta              = 0.1
 nudge_vwin_lindex              = 0.
 nudge_vwin_lo          = 0.
/
&phys_ctl_nl
 cam_chempkg            = 'chemuci_linozv3_mam5_vbs'
 cam_physpkg            = 'default'
 cflx_cpl_opt           =  2
 cld_macmic_num_steps           =  6
 conv_water_in_rad              =  1
 convproc_do_aer                = .true.
 convproc_do_gas                = .false.
 convproc_method_activate               = 2
 deep_scheme            = 'ZM'
 demott_ice_nuc         = .true.
 do_aerocom_ind3                = .true.
...

################################################################
# Do NOT modify this file. It is generated by scream/buildnml using
# the data from $case/namelist_scream.xml. If you want to make some
# local changes, you can edit this XML file or use atmchange.
################################################################
Scorpio:
  model_restart:
    iotype: default
    output_control:
      Frequency: 6
      frequency_units: ndays
  output_yaml_files: !strings
  - /path/to/run/data/output_file.yaml
atmosphere_processes:
  Type: Group
  atm_procs_list: !strings
  - sc_import
  - homme
  - physics
  - sc_export
  compute_tendencies: !strings []
  enable_postcondition_checks: true
  enable_precondition_checks: true
  homme:
    BfbHash: 18
    Moisture: moist
    compute_tendencies: !strings []
    enable_postcondition_checks: true
...

Runtime options in EAMxx

YAML has support in C++ and more human readable

EAMxx introduces atmchange and atmquery that mimic and expand upon xmlchange and xmlquery. In EAMxx, changes are recorded via atmchange not through files like user_nl_eam.

cat << EOF >> user_nl_eam
 cld_macmic_num_steps = 12
EOF

./atmchange mac_aer_mic::number_of_subcycles=12

Runtime options exercise

1. Navigate to the case_scripts directory of the case you built

2. Issue the following commands: ./atmquery --help, ./atmchange --help

3. Experiment with changing the namelist, e.g., ./atmchange mac_aer_mic::number_of_subcycles=12

4. Run with the new options with ./case.submit

Output control

cat << EOF >> user_nl_eam
 mfilt = 1
 nhtfrq = 1
 fincl1 = 'Q','CLDLIQ','CLDICE'
EOF

Averageing Type: Average
Fields:
  Physics PG2:
    Field Names:
      - Q
      - CLDLIQ
      - CLDICE
Max Snapshots Per File: 1
filename_prefix: output.scream_monthly.NAME_1
output_control:
  Frequency: 1
  frequency_units: nmonths

Output control exercise

The runscript should have copied an output yaml file to the case_scripts directory called tutorial_output.yaml

Copy this file to a differently named file, e.g., tutorial_output_2.yaml and change options. Be sure to change the filename_prefix!

Add this new output stream to the run using the atmchange command, then rerun the case.

./atmchange output_yaml_files+=tutorial_output_2.yaml
./atmquery output_yaml_files

Running Doubly Periodic EAMxx

• Intensive Observation Period (IOP) specializationm, now fully supported C++.
• Compsets: FIOP-SCREAMv1-DP (general) and FRCE-SCREAMv1-DP (RCE).
• Over 30 cases, can easily run on any machine with a CIME config.

DPxx resource page:
https://github.com/E3SM-Project/scmlib/wiki/Doubly-Periodic-SCREAM-Home

Running the unit test suite

EAMxx has a simple utility, test-all-eamxx, to manage the suite of unit tests.

salloc --nodes 1 --qos interactive --time 01:00:00 --constraint gpu --gpus 4 --account e3sm
./components/eamxx/scripts/test-all-eamxx -m pm-gpu -t dbg

Note: see test-all-eamxx --help for more options, including --config-only and -w $NEW_LOC.