Overview

Overview#

Many aspects of a CESM3 simulation can be customized through namelist settings. Namelists control how the model is configured and run, allowing users to modify component behavior without changing the source code.

The namelist variables are used to control model output, select physics options, specify input datasets, tune model behavior, and configure many other aspects of a simulation. For example, the frequency and content of output history files can be customized through namelist settings.

In CESM3, namelist modifications are typically made using the component-specific user_nl_* files located in the case directory ($CASEROOT).

The steps to modify the namelists are:

In $CASEROOT

  • edit the user_nl_xxx files.

  • generate the namelists by running ./preview_namelists.

This results in the creation of component namelists, the *_in files (i.e. atm_in, lnd_in, and so on, except for MOM6, where the runtime parameters are specified in MOM_input and the changes are in MOM_override).

The *_in files are located in $CASEROOT/CaseDocs/ and in $RUNDIR.

An overview of the CESM directories and the location of the namelist files is shown in Figure 1

CESM directories and namelists

Figure 1: Overview of the CESM directories and the location of namelist files.

Important: The *_in files should not be directly edited. Any manual changes of the *_in files will be overwritten when you compile or submit the run.

Note that the step ./preview_namelists is optional since namelists are automatically generated as part of the build workflow. However, running ./preview_namelists is often useful for verifying that your namelist changes are being applied correctly before building or submitting a case.

Once a simulation has been submitted, most namelist settings cannot be changed. In particular, changes to namelist variables are generally not applied when:

  • The run has already been submitted.

  • or when CONTINUE_RUN=TRUE is used to continue an existing simulation.

Therefore, it is important to verify your namelist settings before starting a production run.

Complete documentation about the namelist variables can be found on the CESM webpage. component user guides, and the namelist tools described in the next section.

Note: CESM3 documentation is still under development. Therefore, throughout this tutorial we will occasionally refer to CESM2 documentation and examples. While some details may differ between CESM2 and CESM3, the overall approach to finding, understanding, and modifying namelist variables remains the same.