Setup, Build, and Run Instructions

First, follow steps in Obtaining source code to obtain the Earthworks source code and the steps in EarthWorks Input Data to obtain input data files. Additional documentation about using CIME: CIME Users Guide

After obtaining the code, creating a case in EarthWorks generally involves a command like:

cime/scripts/create_newcase --run-unsupported --project <project_key> --input-dir </path/to/EWInputdata> \
--compiler <compiler_name> --res <resolution_name> --compset <compset_name> \
--case </path/to/CASENAME> <GPU_FLAGS>

Where:

• cime/scripts/create_newcase is the path to the create_newcase command. This example assumes you are working in the root of an EarthWorks clone.
• --run-unsupported tells the CIME infrastructure to allow a case to be created, even though the case isn't supported by CESM developers. (Most combinations of compilers, compsets, and grids used in EarthWorks aren't scientifically supported in CESM.)
• --project <project_key> provides the key your machine's batch system should use when running the job(s) associated with this case. Ensure is this appropriate for whatever machine, project, or group you are a part of.
• --input-dir </path/to/EWInputdata> where to look for input data files for your case. E.g. on Derecho this is "/glade/campaign/univ/ucsu0085/inputdata". See EarthWorks Inputdata
• --compiler <compiler_name> what compiler to use when building the case. For EarthWorks this is most frequently --compiler nvhpc. (intel, intel-oneapi, and gnu are sometimes tested as well.)
• --res <resolution_name> specifies the model grid to use with this test. E.g. --res mpasa120_oQU120 tells the case to use a grid that uses 120km MPAS-A mesh for the atmosphere and 120km MPAS-O mesh for the ocean.
• --compset <compset_name> specifies the "component set" to use for the case. This value describes what parts of the earth-system model are used in the case being created (and whether they are "active", "stubs", "data models", etc).
• --case </path/to/CASENAME> gives the case a name. If this is just a name (not a path) the case is created in the current directory. If it is a path the final part of the path will be the case name, and the case directory will be created there.
• --pecount <num_cores> (optional) specifies how many "processor elements" to use for the case (i.e. how many threads and nodes). Depending on what you request, this may be an optional value that will override any default value.
• <GPU_FLAGS> (optional) specifies GPU resources and kinds to use for the case. See EarthWorks Case on GPUs

Compset, Grid, and Compiler Combinations

Please refer to the table below for possible values for other options while creating a case. See Known Issues for noted incompatibilities:

Option	FHS94	FKESSLER	F2000Climo	QPC6	Fully Coupled
--compset <compset_name>	FHS94	FKESSLER	F2000climo	QPC6	2000_CAM60_CLM50%SP_MPASSI_MPASO_SROF_SGLC_SWAV
--res <resolution_name>	mpasa120_mpasa120, mpasa060_mpasa060, mpasa030_mpasa030, mpasa015_mpasa015	mpasa120_mpasa120, mpasa060_mpasa060, mpasa030_mpasa030, mpasa015_mpasa015	mpasa120_mpasa120, mpasa060_mpasa060, mpasa030_mpasa030, mpasa015_mpasa015	mpasa120_mpasa120, mpasa060_mpasa060, mpasa030_mpasa030, mpasa015_mpasa015	mpasa120_oQU120, mpasa060_oQU060, mpasa030_oQU030, mpasa015_oQU015
--compiler <compiler_name>	nvhpc, intel-oneapi, intel-classic, gnu	nvhpc, intel-oneapi, intel-classic, gnu	nvhpc, intel-oneapi, intel-classic, gnu	nvhpc, intel-oneapi, intel-classic, gnu	nvhpc, intel-oneapi, intel-classic, gnu

NOTE: FullyCoupled requires the compset's long_name when creating a case/test.

Example case creation

Here is an example command to create a case (named test.FHS94.mpasa060.intel) that will build the FHS94 compset for CPUs-only using the Intel compilers and will run on the 60km MPAS-A grid using 1 node of Derecho.

1. From within your EarthWorks clone run this command:

cime/scripts/create_newcase --run-unsupported --driver nuopc --project <PROJECT_KEY> --input-dir /glade/campaign/univ/ucsu0085/inputdata \
--compiler intel --compset FHS94 --res mpasa060_mpasa060 --case /glade/scratch/derecho/$USER/test.FHS94.mpasa060.intel --pecount 128

2. If the create_newcase command is successful, it will create the case in the specified location (/glade/scratch/derecho/$USER).
3. Go to the directory where your case was created: cd /glade/scratch/derecho/$USER/test.FHS94.mpasa060.intel
4. You can change the configuration options using the xmlchange utility provided by the CIME infrastructure and by editing the user_nl_${component} files.
   • Please refer to our scripts here for the complete set of configurations to change before setting up a specific case.
5. Run ./case.setup to setup the case
6. Run ./case.build to build the case
7. And finally ./case.submit to run the case