Ctrl+K

Auxiliary Tool

Auxiliary Tool#

When using various EMU tools described earlier, users may want to create some input files themselves—for example, by specifying model diagnostic output for the Modified Simulation (msim) Tool.
To achieve this, EMU provides an additional utility called the Auxiliary Tool. This tutorial demonstrates how to use it.

Run Auxiliary Tool#

Request an Interactive Node#

The Auxiliary Tool is one of the few tools typically run as a shell script without being submitted as a batch job (see EMU Introduction). As described in EMU Introduction, we first request an interactive node:”

salloc --ntasks=2 --ntasks-per-node=2 --partition=sealevel-c5xl-demand --time=01:00:00

Once the requested node is available (see Reproducing ECCO Version 4 Release 4 for examples on how to use squeue to check job status), we proceed with running the tool.

Configure and Run Auxiliary Tool#

We start EMU (as in, e.g., Adjoint Tool) and choose the Auxiliary Tool by entering 9.

choice is 9) Auxiliary Tools (aux)
See /efs_ecco/ECCO/EMU2/emu_userinterface_dir/README_aux


************************************
    EMU Auxiliary Tool
************************************

 The Auxiliary Tool generates examples of what other EMU tools employ as
 user input files.
 See /efs_ecco/ECCO/EMU2/emu_userinterface_dir/README_aux

Choose among the following examples ...

  1) Masks defining objective function [samp, adj, atrb]
  2) Specify model integration period [msim]
  3) Specify model diagnostic output [msim]
  4) Replace model forcing with its time-mean [msim]
  5) Replace model initial condition with time-mean state [msim]
  6) Use end state from another simulation as model initial condition [msim]

Enter choice ... (1-6)?

For demonstration purposes, we choose to create a simple mask by entering 1. The mask can be used as an input file for the Sampling, Adjoint, and Attribution Tools, although each tool can aslo create the mask directly without using the Auxiliary Tool. In addition to creating a mask, the Auxiliary Tool can geneate various input files for the Modified Simulation (msim) Tool.

choice is 1) Create mask (running misc_mask.sh)

 ******************
  This version of EMU is implemented in Singularity
 ******************

Read from file emu_env.singularity ...
   EMU singularity image: /efs_ecco/ECCO/EMU2/emu_dir/emu.sif
   EMU input directory: /efs_ecco/ECCO/EMU2/emu_input_dir
   EMU compatible mpiexec: /efs_ecco/ECCO/EMU2/emu_dir/ompi/bin/mpiexec
   Command to submit batch job: sbatch
   Number of CPU cores used for MITgcm: 96

This routine interactively creates example mask files for EMU
equivalent to what is created by EMU Sampling and Adjoint Tools.
The examples are masks for computing area or volume mean quantities
or for computing horizontal volume transport perpendicular to a
great circle.

Enter directory name for replacement files to be created in ... (rundir)?

We then specify the output directory name aux_output_dir, where the output results will be saved. If the directory does not exist, EMU will create it automatically.

Creating /efs_ecco/owang/ECCO/EMU/tryout/aux_output_dir
 inputdir read : /emu_input_dir
 Creating mask for EMU ...
   Choose mask(s) for horizontal area mean (1), volume mean (2),
     or horizontal volume transport (3) ... (1/2/3)?

We will create a mask for the horizontal area mean of the Niño 3.4 region by entering 1, along with the longitudinal and latitudinal ranges of the region.

   ... Mask will be for horizontal area mean (2d).

 Enter west most longitude (-180E to 180E)... x1?
-170
 Enter east most longitude (-180E to 180E)... x2?
    (choose x2=x1 for zonally global volume)
-120
 Enter south most latitude (-90N to 90N)... y1?
-5
 Enter north most latitude (-90N to 90N)... y2?
5

Mask west/east/south/north boundary:  -170.0 -120.0  -5.0   5.0
   Should area mean be relative to global mean ... (enter 1 for yes)?

We will then be prompted to choose whether the area mean should be relative to the global mean, and we select yes by entering 1.

Interactively specify MASK (1) or read from user file (2) … (1/2)?

We then choose to interactively define the mask by entering `1` and specify the spatial range for the the Niño 3.4 box: `-170`, `-120`, `-5`, `5`, `10`, and `0`, as done in the [Tracer Tool](trc.ipynb).

1

Interactively creating MASK for volume mean.

Enter west most longitude (-180E to 180E)… x1? -170 Enter east most longitude (-180E to 180E)… x2? (choose x2=x1 for zonally global volume) -120 Enter south most latitude (-90N to 90N)… y1? -5 Enter north most latitude (-90N to 90N)… y2? 5 Enter deepest depth (0-6000m) … z1? 10 Enter shallowest depth (0-6000m)… z2? 0

We are then prompted with the following question:

Should volume mean be relative to global mean … (enter 1 for yes)?

We choose to make the volume mean relative to the global mean by entering `1`, and the tool starts creating the mask.

… 2d Mask will be relative to global mean

2d Mask output:

mask2d.-170.0_-120.0_-5.0_5.0-gmn

Changed files: mask.info mask2d.-170.0_-120.0_-5.0_5.0-gmn my_commands.sh

misc_mask.sh execution complete.

EMU interactive execution complete. Tue May 13 18:35:40 UTC 2025


The masking file can be used as an input file for the Sampling, Adjoint, and Attribution Tools when prompted, by ptoviding the path and filename.
Contents