Skip to content

Detailed Instructions

Jump to bottom
Alper Altuntas edited this page Jul 24, 2021 · 26 revisions

Contents:

1. Downloading CESM with MOM6

2. Creating a MOM6 case

3. Running a MOM6 case

4. Customizing MOM6 cases

1. Downloading CESM with MOM6

Prerequisite: Make sure that CESM 2.0+ is already ported to your machine.

MOM6 is an optional ocean component in CESM 2.2 and CESM 2.3, along with the primary ocean component POP2. The following instructions describe how to download a beta version of CESM2.3 with MOM6.

  • Clone the CESM Github repository as follows. The specific CESM tag below includes MOM6 as an optional component.

    git clone -b cesm2_3_beta04 https://github.com/alperaltuntas/CESM.git

  • After having cloned CESM, run the checkout_externals script to download all the individual components. Note that -o flag instructs checkout_externals to download also the optional components including MOM6.

    (cd CESM/; ./manage_externals/checkout_externals -o)

See the following instructions for more detailed information on how to download CESM: https://escomp.github.io/CESM/release-cesm2/downloading_cesm.html

2. Creating a MOM6 case:

  • Run CESM's create_newcase script to create a MOM6 case instance. The script expects the following three required arguments: --compset, --res, and --case. As the names suggest, --compset and --res arguments are to specify the component set and the model resolution, respectively. (See Table: Available compsets and resolutions below for a full list of available MOM6 compsets and resolutions.) The third argument, --case, specifies the name of the case to be created. In the below example, we happen to name our case c.e22.CMOM.T62_t061.001, Although any case name is acceptable, users are advised to adhere to CESM naming conventions. Additionally, for MOM6 cases, users need to provide the --run-unsupported flag since MOM6 compsets are currently experimental.

    CESM/cime/scripts/create_newcase --res T62_t061 --compset CMOM --case c.e22.CMOM.T62_t061.001 --run-unsupported

    Some of the other useful create_newcase options when creating a MOM6 case:

    • --walltime: Set the wallclock limit, e.g., --walltime 01:00:00
    • --driver: e.g., --driver mct or --driver nuopc
    • --project: Specify a project id for the case
    • --compiler, e.g., --compiler gnu

    Table: Available compsets and resolutions

    Compset Active Components Forcing Compatible Resolutions
    CMOM MOM6 only CORE2 NYF T62_t061, T62_g16, T62_t025
    CMOM_IAF MOM6 only CORE2 IAF T62_t061, T62_g16, T62_t025
    CMOM_JRA MOM6 only JRA-55 TL319_t061, TL319_g16
    GMOM MOM6 and CICE only CORE2 NYF T62_t061, T62_g16, T62_t025
    GMOM_IAF MOM6 and CICE only CORE2 IAF T62_t061, T62_g16, T62_t025
    GMOM_JRA MOM6 and CICE only JRA-55 TL319_t061, TL319_g16
    BMOM Fully Coupled n/a f09_t061

    For more information on MOM6 grids, check out Grids.

3. Running MOM6 cases:

  • After having initialized the case, cd into the case root and run ./case.setup to prepare the case for the compilation: (The above command will create user_nl_mom text file, which is to be used for customizing the case. More on that later...)

    c.e22.CMOM.T62_t061.001
./case.setup

  • Within the case root, run /case.build to compile MOM6+CESM executable. Depending on the compset and the compiler of your choice, this step may take 5 to 10 minutes.

    ./case.build

    Note: cheyenne users need to run this command on a compute node, as follows:

    qcmd -- ./case.build

  • Finally, submit the job to the batch queue using the case.submit script:

    ./case.submit

  • Note for fully coupled (BMOM) compsets only: run the following command after setting up the case and before building it:

    ./xmlchange CLM_BLDNML_OPTS="-bgc bgc -crop -no-chk_res"

    Locating input and output files:

  • MOM_RPS module in CESM stages and places all runtime MOM6 parameter files in the run directory (RUNDIR). Query your run directory as follows:

    ./xmlquery RUNDIR

  • Once the run finishes, you can access the output files in the short term archive directory if short term archiving is turned on. To find out whether short term archiving is on, run the following command in your case root.

    ./xmlquery DOUT_S

    To query your short term archive directory (DOUT_S_ROOT), run the following command:

    ./xmlquery DOUT_S_ROOT

    If the short term archiver is turned off, the output files are located in your case run directory along with the input files.

    Note: Check out the following section to get more information on MOM6 input and output files: Understanding files located in the run directory

4. Customizing MOM6 cases:

The available mechanisms for customizing MOM6 cases within CESM are:

  1. xmlchange
  2. user_nl_mom
  3. SourceMods

4.1 xmlchange

  • Users can control some general case variables defined in case *.xml files using the xmlchange tool in the case root. The variables that can be changed via xmlchange usually correspond to general, component-agnostic settings. Some examples:

    ./xmlchange DOUT_S=FALSE       # Turn off short term archiving
./xmlchange STOP_OPTION=nmonth 
./xmlchange STOP_N=3           # set run length to 3 months
./xmlchange NCPL_OCN=48        # set ocn coupling frequency to 48 (a day)

  • Additionally, users can change the following two xml variables that control MOM6 diagnostics on a high level.

    • OCN_DIAG_MODE: This variable is used to choose from a set of predefined ocean diagnostics configurations. Each configuration corresponds to a different combination of frequency, precision, and field lists. Predefined onfigurations ordered in increasing scope/frequency: "spinup", "production", "development". Further customization of diagnostics may be done by copying an edited version of diag_table file in SourceMods/src.mom/
    • OCN_DIAG_SECTIONS: Flag to turn on/off the MOM6 sections diagnostics.

    Examples:

    ./xmlchange OCN_DIAG_MODE="spinup"
./xmlchange OCN_DIAG_SECTIONS=FALSE

    The current value of any xml variable may be checked via xmlquery, e.g.:

    ./xmlquery NTASKS_OCN

4.2 user_nl_mom

Users can override out-of-the-box MOM6 runtime parameters via the user_nl_mom file located in the case root. An empty user_nl_mom file gets created when the user runs the ./case.setup script. If users add entries in this file, MOM_RPS module in CESM creates a corresponding MOM_override file in the run directory. While this MOM_override file is the actual input file to be read by MOM6, any changes made in this file will be overriden by the MOM_RPS module. Thus, all parameter changes must be specified via user_nl_mom (or via SourceMods).

The syntax of user_nl_mom entries is as follows:

! some optional comment line here
VARNAME = NEWVAL

Examples:

DT = 900.0
DT_THERM = 1800.0

If the parameter to be overridden belongs to a module, e.g., KPP, the change is specified as follows. Example:

KPP%
MATCH_TECHNIQUE = MatchGradient
%KPP

Note: Unlike original MOM input files, user_nl_mom does not require #override keyword. MOM_RPS module adds this keyword in automatically generated MOM_override file if needed.

To check out the out-of-the-box MOM6 parameter values in CESM, run ./case.setup and ./preview_namelist commands. This will create the MOM_input file in the run directory. This file contains

4.3 SourceMods

Warning: This mechanism is for development purposes only. End users are strongly advised to use user_nl_mom for changing runtime parameters. Note, however, that currently the only mechanism for low-level control of diagnostics is via SourceMods. For high-level control of diagnostics, see xmlchange.

You can place your own versions of the following four MOM6 runtime input files in SourceMod/src.mom to override out-of-the-box CESM configuration:

  • MOM_input
  • MOM_override
  • diag_table
  • input.nml

Note: You can run ./case.setup and ./preview_namelist commands to generate out-of-the-box versions of these files in the run directory. You can then copy them intoSourceMod/src.mom and edit them.

See GFDL's MOM6 documentation for more information on how to prepare/edit MOM_input, MOM_override, and input.nml: https://mom6.readthedocs.io/en/dev-gfdl/api/generated/pages/Runtime_parameter_system.html

Also see the following documentation on how to prepare/edit diag_table: https://mom6.readthedocs.io/en/dev-gfdl/api/generated/pages/Diagnostics.html

User Manual: MOM6 in CESM

Clone this wiki locally