Configure Forcings (case.configure_forcings)

configure_forcings declares every forcing your case needs, initial conditions, open boundary conditions, tides, biogeochemistry, chlorophyll, runoff, and is always required before Process Forcings. What arguments you owe it depends on your compset (see Case Setup, Section 2 for how to discover the required list before you get here).

This notebook covers:

• Section 1: the one always-required argument, date_range

• Section 2: switching data products/access functions (not GLORYS)

• Section 3: tides

• Section 4: chlorophyll

• Section 5: runoff (GLOFAS/JRA via compset, or a custom product)

• Section 6: biogeochemistry (MARBL), the kwargs half of Case Setup, Section 4

• Section 7: sea ice (CICE6), the kwargs half of Case Setup, Section 3

• Section 8: waves (WW3), the kwargs half of Case Setup, Section 5

📖 CrocoDash configure_forcings docs · Datasets

Section 1: The Required Argument, date_range¶

We need to cut out our ocean forcing. The package expects an initial condition and one time-dependent segment per non-land boundary. Naming convention is "east_unprocessed" for segments and "ic_unprocessed" for the initial condition.

By default, configure_forcings forces with the Copernicus Marine “Glorys” reanalysis dataset. date_range is always required. It drives the initial and boundary condition extraction that every case needs, and optional configurators (like tides) derive their reference dates from it.

Section 2: Switching Data Products¶

This module can be used with case.configure_forcings to find different ways to access raw data from data sources. Just supply a data product name and function name:

Available products and functions can be found in the documentation and in the raw_data_access helper functions shown below.

Accessing Non-Forcing Raw Data¶

Apart from accessing forcing products through case.configure_forcings(), we can access products like GEBCO, SEAWIFS, GLOFAS, etc. by importing the raw data access module directly.

Section 3: Tides¶

MOM6 can take tides data as a boundary condition in the regional domain. Many tides parameters are impacted by this and can be seen in case.process_forcings.

In our workflow, we take data from the TPXO tidal model and regrid onto our grid. TPXO model data can be requested off of the TPXO website or is available on Derecho.

The file paths of the tidal files can be passed into configure_forcings as shown below with all wanted tidal constituents, like M2. There are three parameters in configure_forcings and many parameters adjusted in MOM6.

Section 4: Chlorophyll¶

MOM6 can take chlorophyll data as a file in the regional domain. It impacts shortwave penetration. MOM6 parameters that are impacted by it are CHL_FROM_FILE, CHL_FILE, VAR_PEN_SW, and PEN_SW_NBANDS. In our workflow, we take raw data from SeaWIFS, process it globally, and subset to our regional domain.

Chlorophyll can be added into a CrocoDash case using functions from mom6_forge and called from configure_forcings. There is one parameter in configure_forcings and three parameters in MOM6.

CrocoDash Parameters¶

In case.configure_forcings(), the argument chl_processed_filepath takes in a processed global chlorophyll file. The global processed chlorophyll file is hosted on the CESM inputdata svn server under ocn/mom/croc/chl/data and can be accessed through the CrocoDash raw_data_access module like below:

The file path of the global file (after running the script from the code block) can be passed into configure_forcings as shown in this demo:

Section 5: Runoff¶

River runoff adds fresh-water discharge at the ocean surface. CrocoDash supports two routes:

• Section 5.1: use GLOFAS or JRA runoff that ships with CESM (recommended starting point). The compset choice for this lives in Case Setup (see the compset quick-reference table).

• Section 5.2: plug in a custom runoff dataset (advanced).

Section 5.1: GLOFAS or JRA via Compset¶

Both GLOFAS and JRA runoff products ship with CESM. To activate either, build your Case with a compset alias that includes runoff (e.g. CR_JRA_GLOFAS, see Case Setup), then pass the ESMF mesh file for your chosen dataset to configure_forcings so CrocoDash can compute the remapping weights.

Section 5.2: Custom Runoff Product (Advanced)¶

To use a custom runoff dataset you need three things: an ESMF mesh file, a stream definition file, and the grid dimensions of your raw data.

Step 1: Create an ESMF Mesh File¶

Generate a mesh file from a Grid that matches your raw data’s grid:

Step 2: Stream Definition File¶

In your case directory, create drof.streams.xml with the content below, replacing all <PLACEHOLDER> values with your actual paths and variable names:

<?xml version="1.0"?>
<file id="stream" version="2.0">
  <stream_info name="rof.<PRODUCT_NAME>">
    <taxmode>cycle</taxmode>
    <tintalgo>upper</tintalgo>
    <readmode>single</readmode>
    <mapalgo>bilinear</mapalgo>
    <dtlimit>3.0</dtlimit>
    <year_first>START_YEAR</year_first>
    <year_last>END_YEAR</year_last>
    <year_align>START_YEAR</year_align>
    <vectors>null</vectors>
    <meshfile>PATH_TO_ESMF_MESH_FILE</meshfile>
    <lev_dimname>null</lev_dimname>
    <datafiles>
      <file>PATH_TO_RAW_DATA_NETCDF3_64BIT_OFFSET</file>
    </datafiles>
    <datavars>
      <var>NETCDF_VARIABLE_NAME Forr_rofl</var>
    </datavars>
    <offset>0</offset>
  </stream_info>
</file>

Also register your product in components/cdeps/drof/namelist_definition_drof.xml and config_component. See the CESM docs for details.

Step 3: Set Grid Dimensions¶

Run these xmlchange commands in your case directory:

./xmlchange ROF_NY=1500
./xmlchange ROF_NX=3600
./xmlchange ROF_DOMAIN_MESH=<MESH_PATH>

Then pass your mesh file to configure_forcings as shown in Section 5.1 so CrocoDash generates the ocean remapping weights.

Section 6: Biogeochemistry (MARBL)¶

The compset choice for MARBL is covered in Case Setup, Section 4. Once that Case exists, here’s the configure_forcings half:

Section 7: Sea Ice (CICE6)¶

The compset choice for CICE is covered in Case Setup, Section 3. Here’s the configure_forcings half.

CICE forcing is a single restoring file: your regional domain plus a halo of n_halo_cells T-cells on every side, regridded from a CICE-shaped source onto every point of that expanded grid. It carries no time dimension, it’s one static snapshot, so unlike MOM6’s OBC there’s no date chunking.

The arguments¶

These mirror the product_name/function_name pattern Sections 1–2 use for MOM6’s IC and OBC, and they’re validated: passing a MOM6 forcing product as cice_product_name is an error, it has to be a registered CICE forcing product.

The products¶

What it writes¶

user_nl_cice gets the regional-domain settings, no arguments of yours involved:

To start from ice rather than open water, see the warm-start note in Case Setup, Section 3.

Section 8: Waves (WW3)¶

The compset choice and the grid input files WW3 needs are covered in Case Setup, Section 5. Here’s the configure_forcings half.

WW3’s boundary forcing is a set of 2-D spectra, energy density E(f, θ), at stations along your open boundaries. It runs through the same GET → REGRID → MERGE engine as MOM6’s OBC, so the same date-chunking controls apply.

The arguments¶

boundaries is shared with MOM6’s OBC, the sides you already pass in Section 1 are the sides WW3 generates spectra for.

The products¶

What it writes¶

process_forcings writes the per-station boundary spectrum files into the case’s wave input directory, along with the spec.list that lists them and the ww3_bounc.nml that reads them (INTERP = 2, linear interpolation between stations). It also sets WW3_GRID_INP_DIR and the coupler history options HIST_OPTION/HIST_N in the case XML.

Next steps¶

Once configured, move to Process Forcings to actually generate the files.