4. Data: Input, Model Configuration, and Output Files

This chapter describes the input and model configuration files needed for executing the MOM6-SIS2-COBALT model.

4.1. Input files

There are four types of files needed to execute a run:

  1. Static datasets (fix files containing climatological information)

  2. Grid Description files

  3. Files that depend on time such as initial/boundary conditions

  4. Model configuration files (such as namelists)

4.1.1. Static Datasets (i.e., fix files)

The static input files for regional MOM6-SIS2-COBALT configurations are listed and described in Table 4.1. The script used to generate this file is shown in parentheses.

Table 4.1 *Fix files containing climatological information *

Filename

Description

seawifs-clim-1997-2010.nwa12.nc

climatological chlorophyll concentration

bgc_woa.nc

climatological open boundary conditions for bgc tracers such as no3, po4, sio4, and o2 (tools/boundary/write_bgc_boundary.py)

bgc_cobalt.nc

climatological open boundary conditions for bgc tracers not are not included in bgc_woa.nc or bgc_esper_1993_2022.nc (tools/boundary/write_bgc_boundary.py)

tz_00*.nc

open boundary conditions for tidal amplitude for each tidal constituent (tools/boundary/write_tpxo_boundary.py)

tu_00*.nc

open boundary conditions for tidal current for each tidal constituent (tools/boundary/write_tpxo_boundary.py)

esm4_*.nc

Atmospheric BGC fluxes from ESM4 simulation

4.1.2. Grid Description files

The input files containing grid information for regional MOM6-SIS2-COBALT configurations are listed and described in Table 4.2. Users are referred to this link for more details on how to create grid files for their domain of interest.

Table 4.2 Input files containing grid information for regional MOM6-SIS2-COBALT configurations

Filename

Description

ocean_hgrid.nc

horizonal grid information

ocean_mosaic.nc

specify horizonal starting and ending points index

ocean_topog.nc

ocean topography

ocean_mask.nc

land/sea mask

land_mask.nc

land fraction at T-cell centers

vgrid_75_2m.nc

vertical coordinate level thickness

diag_dz.nc

specify target depth for diag outputs

grid_spec.nc

Contains information on the mosaic grid

****_mosaic_tile1X****_mosaic_tile1.nc

grid files for the FMS coupler

4.1.3. Time-dependent files

The time-dependent files such as ICs, BCs or atmos forcings for regional MOM6-SIS2-COBALT configurations are listed and described in Table 4.3. The script used to generate this file is shown in parentheses.

Table 4.3 Time-dependent files for regional MOM6-SIS2-COBALT configurations

Filename

Description

glorys_ic_1993-01-01.nc

ocean physical initial conditions from Glorys (tools/initial/write_glorys_initial.py)

NWA12_COBALT_2023_10_spinup_2003.nc

ocean biogeochemical initial conditions (tools/initial/write_bgc_initial.py)

so_*.nc, thetao_*.nc, zos_*.nc, uv_*.nc

Open boundary conditions for physical variables (tools/boundary/write_glorys_boundary.py)

bgc_esper_1993_2022.nc

Open boundary conditions for ALK and DIC (tools/boundary/write_bgc_boundary.py; Prerequisite: tools/boundary/esper/run_esper.sh)

ERA5_*.nc

atmos forcings from ERA5 (tools/atmos)

glofas_runoff_****.nc

River runoff from GloFAS data (tools/rivers/write_runoff_glofas.py)

RiverNutrients_Integrated_NWA12_GLOFAS_RC4US1990to2022_2023_04_v2.nc

Biogeochemical tracer concentrations for river runoff

mole_fraction_of_co2_extended_ssp245_v2.nc

mole fraction of carbon dioxide in atmos

4.1.4. Model_configure files

The model configuration files for regional MOM6-SIS2-COBALT configurations are listed and described in Table 4.4.

Table 4.4 Model configuration files

Filename

Description

input.nml

Fortran namelist file containing parameters that control model run.

MOM_input

This input file provides the adjustable run-time parameters for MOM6

MOM_override

Override MOM6 run-time parameters

MOM_layout

Control MOM6 model’s layout

SIS_input

This input file provides the adjustable run-time parameters for SIS2

SIS_override

Override SIS2 run-time parameters

SIS_layout

Control SIS2 model’s layout

field_table

An ASCII table that is used to register tracer fields

diag_table

An ASCII table that is used to control model outputs

data_table

An ASCII file that is used to control external data forcing fields, such as surface forcings or river runoff

The best practice when configuring a new simulation or tuning parameters is to make all changes in the MOM_override or SIS_override files. Not all parameters need to be specified within MOM_input, if no value is given the default will be used. See the MOM_parameter_doc file described in the next section to find the default value of the parameter. When using the MOM_override file to set a parameter which is not defined in the MOM_input file, it can be set as PARAMETER = Value within the MOM_override file. To override a parameter that is specified within the MOM_input file, the prefix #override must be included, so an overridden value would be specified as #override PARAMETER = Value. Only one parameter per line should be specified within the override file. MOM and SIS input and override files follow the same formatting guidelines.

The data_table is commonly formatted by specifying each of the fields in the order listed below, with a new line for each entry.

gridname: The component of the model this data applies to. eg. atm ocn lnd ice.
fieldname_code: The field name according to the model component. eg. salt
fieldname_file: The name of the field within the source file.
file_name: Path to the source file.
interpol_method: Interpolation method eg. bilinear
factor: A scalar by which to multiply the field ahead of passing it onto the model. This is a quick way to do unit conversions for example.

Example Format:

"ATM", "t_bot",  "t2m", "./INPUT/2t_ERA5.nc", "bilinear", 1.0

Users can also set a constant value by entering empty quotes for fieldname_file and file_name and setting interpol_method to none. Below is an example of setting a constant atmospheric oxygen value:

"ATM", "o2_flux_pcair_atm",  "",       "",                           "none",      0.214

4.2. Outputs

Model output is controlled via the FMS diag_manager using the diag_table.

The diag_table file has three kinds of section: Title, File and Field. The title section is mandatory and always the first. There can be multiple file and field sections typically either in pairs or grouped in to all files and all fields, but always with the file section preceding the corresponding field section.

The new FMS2 comes with a new rewritten diag manager. The old diag_manager code has been kept intact and will be used by default. The rewritten diag manager can be enabled via use_modern_diag = .true. to your diag_manager_nml. Keep in mind that the rewritten diag manager only supports the YAML format of diag_Table (this requires the additional third-party libyaml when building FMS2). Users can refer to this page for more details of the diag_table yaml format. An example diag_table.yaml can be found in our 1D case: exps/OM4.single_column.COBALT/diag_table.yaml.

4.2.1. Title Section

The first two lines are mandatory and comprise a line with a title and a line with six integers defining a base date against which time will be referenced.

"My  ocean-only  test  case"
1900  1  1  0  0  0

4.2.2. File Section

This section defines an arbitrary number of files that will be created. Each file is limited to a single rate of either sampling or time-averaging.

"file_name",  output_freq,  "output_freq_units",  file_format,  "time_axis_units",  "time_axis_name"

These file section entries are described in Table 4.5.

Table 4.5 Description of the variables used to define the files written to the output files.

Field Entry

Description

file_name

The name of the file that contains diagnostics at the given frequency (excluding the “.nc” extension).

output_freq

The period between records in file_name, if positive. Special values of 0 mean write every time step and -1 write only at the end of the run.

output_freq_units

The units in which output_freq is given. Valid values are “years”, “months”, “days”, “hours”, “minutes” or “seconds”.

file_format

Always set to 1, meaning netcdf.

time_axis_units

The units to use for the time-axis in the file. Valid values are “years”, “months”, “days”, “hours”, “minutes” or “seconds”.

time_axis_name

The name of the time-axis (usually “Time”).

4.2.3. Field Section

A line in the field section of the diag_table file contains eight variables with the following format:

"module_name", "field_name", "output_name", "file_name", "time_sampling", "reduction_method", "regional_section", packing

These field section entries are described in Table 4.6.

Table 4.6 Description of the eight variables used to define the fields written to the output files.

Field Entry

Variable Type

Description

module_name

CHARACTER(len=128)

Module that contains the field_name variable. (e.g. dynamic, gfs_phys, gfs_sfc)

field_name

CHARACTER(len=128)

The name of the variable as registered in the model.

output_name

CHARACTER(len=128)

Name of the field as written in file_name.

file_name

CHARACTER(len=128)

Name of the file where the field is to be written.

time_sampling

CHARACTER(len=50)

Currently not used. Please use the string “all”.

reduction_method

CHARACTER(len=50)

“none” means sample or snapshot. “average” or “mean” performs a time-average. “min” or “max” diagnose the minium or maxium over each time period.

regional_section

CHARACTER(len=50)

“none” means global output. A string of six space separated numbers, “lon_min lon_max lat_min lat_max vert_min vert_max”, limits the diagnostic to a region.

packing

INTEGER

Fortran number KIND of the data written. Valid values: 1=double precision, 2=float, 4=packed 16-bit integers, 8=packed 1-byte (not tested).

A brief example of the diag_table is shown below.

CEFI_NWA12_COBALT_V1
1993 1 1 0 0 0
# MOM6 ocean diagnostics files
"ocean_daily",            1, "days",   1, "days", "time"
"ocean_month_snap",       1, "months", 1, "days", "time"
"ocean_month",            1, "months", 1, "days", "time"
"ocean_month_z",          1, "months", 1, "days", "time"
"ocean_annual",          12, "months", 1, "days", "time"
"ocean_annual_z",        12, "months", 1, "days", "time"
"ocean_static",          -1, "months", 1, "days", "time" # ocean_static is a protected name. Do not change this line.
# -----------------------------------------------------------------------------------------
"ocean_model_z", "volcello",     "volcello",         "ocean_annual_z",      "all", "mean", "none",2 # Cell measure for 3d data
"ocean_model_z", "volcello",     "volcello",         "ocean_month_z",       "all", "mean", "none",2 # Cell measure for 3d data
"ocean_model",   "volcello",     "volcello",         "ocean_annual",        "all", "mean", "none",2 # Cell measure for 3d data
"ocean_model",   "pbo",          "pbo",              "ocean_annual",        "all", "mean", "none",2
"ocean_model",   "pbo",          "pbo",              "ocean_month",         "all", "mean", "none",2
"ocean_model",   "masscello",    "masscello",        "ocean_annual",        "all", "mean", "none",2
"ocean_model",   "ssh",          "ssh",              "ocean_annual",        "all", "mean", "none",2
"ocean_model",   "zos",          "zos",              "ocean_month",         "all", "mean", "none",2
"ocean_model",   "ssh",          "ssh",              "ocean_month",         "all", "mean", "none",2
"ocean_model",   "ssh",          "ssh",              "ocean_daily",         "all", "mean", "none",2

4.2.4. Parameter Files

In additon to model output, MOM6 also records runtime parameters used during the model intialization. Each parameter_doc file includes different information.

Table 4.7 Parameter Doc Files

Filename

Description

MOM_parameter_doc.all

The values of all run-time parameters for MOM6 and their defaults

MOM_parameter_doc.short

The values of only run-time parameters for MOM6 that differ from their defaults

MOM_parameter_doc.debugging

The values of only run-time parameters used for debugging MOM6

MOM_parameter_doc.layout

The values of only run-time parameters that control MOM6 model’s layout

SIS_parameter_doc.all

The values of all run-time parameters for SIS2 and their defaults

SIS_parameter_doc.short

The values of only run-time parameters for SIS2 that differ from their defaults

SIS_parameter_doc.debugging

The values of only run-time parameters used for debugging SIS2

SIS_parameter_doc.layout

The values of only run-time parameters that control SIS2 model’s layout

To easily see how experiments differ, the MOM_parameter_doc files can be compared. These files include short descriptions of what parameters control, their default, and different options.