nemo Sub-Commands

The command pixi run nemo help produces a list of the available nemo options and sub-commands:

 usage: nemo [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug]

 NEMO Command Processor

 options:
   --version             show program's version number and exit
   -v, --verbose         Increase verbosity of output. Can be repeated.
   -q, --quiet           Suppress output except warnings and errors.
   --log-file LOG_FILE
                         Specify a file to log output. Disabled by default.
   -h, --help            Show help message and exit.
   --debug               Show tracebacks on errors.

 Commands:
   combine  Combine per-processor files from an MPI NEMO run into single files
   complete  print bash completion command (cliff)
   deflate  Deflate variables in netCDF files using Lempel-Ziv compression
   gather  Gather results from a NEMO run
   help  print detailed help for another command (cliff)
   prepare  Prepare a NEMO run
   run  Prepare, execute, and gather results from a NEMO model run

For details of the arguments and options for a sub-command use pixi run nemo help <sub-command>. For example:

$ pixi run nemo help run

 usage: nemo run [-h] [--max-deflate-jobs MAX_DEFLATE_JOBS]
                 [--nocheck-initial-conditions] [--no-deflate] [--no-submit]
                 [--waitjob WAITJOB] [--queue-job-cmd {qsub,sbatch}] [-q]
                 DESC_FILE RESULTS_DIR

 Prepare, execute, and gather the results from a NEMO run described in
 DESC_FILE. The results files from the run are gathered in RESULTS_DIR. If
 RESULTS_DIR does not exist it will be created.

 positional arguments:
   DESC_FILE             run description YAML file
   RESULTS_DIR           directory to store results into

 optional arguments:
   -h, --help            show this help message and exit
   --max-deflate-jobs MAX_DEFLATE_JOBS
                         Maximum number of concurrent sub-processes to use for
                         netCDF deflating. Defaults to 4.
   --nocheck-initial-conditions
                         Suppress checking of the initial conditions link.
                         Useful if you are submitting a job to wait on a
                         previous job
   --no-deflate          Do not include "nemo deflate" command in the bash
                         script. Use this option if you are using on-the-fly
                         deflation in XIOS-2; i.e. you are using 1 XIOS-2
                         process and have the compression_level="4" attribute
                         set in all of the file_group definitions in your
                         file_def.xml file.
   --no-submit           Prepare the temporary run directory, and the bash
                         script to execute the NEMO run, but don't submit the
                         run to the queue. This is useful during development
                         runs when you want to hack on the bash script and/or
                         use the same temporary run directory more than once.
   --waitjob WAITJOB     use -W waitjob in call to qsub, to make current job
                         wait for on waitjob. Waitjob is the queue job number
   --queue-job-cmd {qsub,sbatch}
                         Command to use to submit the bash script to execute
                         the NEMO run; defaults to qsub.
   -q, --quiet           don't show the run directory path or job submission
                         message

You can check what version of nemo you have installed with:

$ pixi run nemo --version

`run` Sub-command

The run sub-command prepares, executes, and gathers the results from the NEMO run described in the specified run description file. The results are gathered in the specified results directory.

 usage: nemo run [-h] [--max-deflate-jobs MAX_DEFLATE_JOBS]
                 [--nocheck-initial-conditions] [--no-deflate] [--no-submit]
                 [--waitjob WAITJOB] [--queue-job-cmd {qsub,sbatch}] [-q]
                 DESC_FILE RESULTS_DIR

 Prepare, execute, and gather the results from a NEMO run described in
 DESC_FILE. The results files from the run are gathered in RESULTS_DIR. If
 RESULTS_DIR does not exist it will be created.

 positional arguments:
   DESC_FILE             run description YAML file
   RESULTS_DIR           directory to store results into

 optional arguments:
   -h, --help            show this help message and exit
   --max-deflate-jobs MAX_DEFLATE_JOBS
                         Maximum number of concurrent sub-processes to use for
                         netCDF deflating. Defaults to 4.
   --nocheck-initial-conditions
                         Suppress checking of the initial conditions link.
                         Useful if you are submitting a job to wait on a
                         previous job
   --no-deflate          Do not include "nemo deflate" command in the bash
                         script. Use this option if you are using on-the-fly
                         deflation in XIOS-2; i.e. you are using 1 XIOS-2
                         process and have the compression_level="4" attribute
                         set in all of the file_group definitions in your
                         file_def.xml file.
   --no-submit           Prepare the temporary run directory, and the bash
                         script to execute the NEMO run, but don't submit the
                         run to the queue. This is useful during development
                         runs when you want to hack on the bash script and/or
                         use the same temporary run directory more than once.
   --waitjob WAITJOB     use -W waitjob in call to qsub, to make current job
                         wait for on waitjob. Waitjob is the queue job number
   --queue-job-cmd {qsub,sbatch}
                         Command to use to submit the bash script to execute
                         the NEMO run; defaults to qsub.
   -q, --quiet           don't show the run directory path or job submission
                         message

The path to the run directory, and the response from the job queue manager (typically a job number) are printed upon completion of the command.

The run sub-command does the following:

Execute the prepare Sub-command via the NEMO-Cmd API to set up a temporary run directory from which to execute the NEMO run.
Create a NEMO.sh job script in the run directory. The job script:
- runs NEMO
- executes the combine Sub-command to combine the per-processor restart and/or results files
- executes the deflate Sub-command to deflate the variables in the large netCDF results files using the Lempel-Ziv compression algorithm to reduce the size of the file on disk
- executes the gather Sub-command to collect the run description and results files into the results directory
Submit the job script to the queue manager via the command given by the --queue-job-cmd option (which defaults to qsub).

See the Run Description File Structure section for details of the run description YAML file.

The run sub-command concludes by printing the path to the run directory and the response from the job queue manager. Example:

$ pixi run nemo run nemo.yaml $HOME/CANYONS/Mackenzie/myrun

 nemo_cmd.run INFO: nemo_cmd.prepare Created run directory ../../runs/38e87e0c-472d-11e3-9c8e-0025909a8461
 nemo_cmd.run INFO: 3330782.orca2.ibb

If the run sub-command prints an error message, you can get a Python traceback containing more information about the error by re-running the command with the --debug flag.

If you are using on-the-fly deflation in XIOS-2; i.e. you are using 1 XIOS-2 process and have the compression_level="4" attribute set in all of the file_group definitions in your file_def.xml file; you should use the --no-deflate option to exclude deflate Sub-command from the NEMO.sh job script.

`prepare` Sub-command

The prepare sub-command sets up a run directory from which to execute the NEMO run described in the specified run description, and output file definitions files:

 usage: nemo prepare [-h] [--nocheck-initial-conditions] [-q] DESC_FILE

 Set up the NEMO run described in DESC_FILE and print the path to the run
 directory.

 positional arguments:
   DESC_FILE             run description YAML file

 optional arguments:
   -h, --help            show this help message and exit
   --nocheck-initial-conditions
                         Suppress checking of the initial conditions link.
                         Useful if you are submitting a job to an HPC qsub
                         queue and want the submitted job to wait for
                         completion of a previous job.
   -q, --quiet           don't show the run directory path on completion

See the Run Description File Structure section for details of the run description file.

The pixi run nemo prepare command concludes by printing the path to the run directory it created. Example:

$ pixi run nemo prepare nemo.yaml

 nemo_cmd.prepare INFO: Created run directory /scratch/dlatorne/MEOPAR/runs/01mar23-11x32_2025-12-24T145433.665751-0800

The name of the run directory is intended to be ephemerally used for a single run. It’s name is composed of the run id from the run description YAML file (see Basic Run Configuration) and the directory’s creation date/time stamp.

If the pixi run nemo prepare command prints an error message, you can get a Python traceback containing more information about the error by re-running the command with the --debug flag.

Run Directory Contents

The run directory contains:

The run description file provided on the command line.
A namelist_cfg (the file name required by NEMO) file that is constructed by concatenating the namelist segments listed in the run description file (see Run Description File Structure).
A symlink to the EXP00/namelist_ref file in the directory of the NEMO configuration given by the config name and NEMO code config keys in the run description file is also created to provide default values to be used for any namelist variables not included in the namelist segments listed in the run description file.
A symlink called bathy_meter.nc (the file name required by NEMO) to the bathymetry file specified in the grid section of the run description file.
A symlink called coordinates.nc (the file name required by NEMO) to the grid coordinates file specified in the grid section of the run description file.
A file called domain_def.xml (the file name required by NEMO) that contains the XIOS output server domain definitions for the run. The file that is copied to domain_def.xml is specified in the output section of the run description file.
A file called field_def.xml (the file name required by NEMO) that contains the XIOS output server field definitions for the run. The file that is copied to field_def.xml is specified in the output section of the run description file.
A file called iodefs.xml (the file name required by NEMO). that file specifies the output files and variables they contain for the run. The file that is copied to iodefs.xml is specified in the output section of the run description file. It is also sometimes referred to as the NEMO IOM defs file.
The nemo.exe executable found in the BLD/bin/ directory of the NEMO configuration given by the config name and NEMO code config keys in the run description file. pixi run nemo prepare aborts with an error message and exit code 2 if the nemo.exe file is not found. In that case the run directory is not created.
The xios_server.exe executable found in the bin/ sub-directory of the directory given by the XIOS key in the paths section of the run description file. pixi run nemo prepare aborts with an error message and exit code 2 if the xios_server.exe file is not found. In that case the run directory is not created.

The run directory also contains symbolic links to forcing directories (e.g. initial conditions, atmospheric, open boundary conditions, rivers run-off, etc.) The names of those symlinks and the directories that they point to are given in the forcing section of the run description file. Please see forcing Section in the Run Description File Structure docs for full details. It is your responsibility to ensure that these symlinks match the forcing directories given in your namelist files.

Finally, if the run description YAML file contains a vcs revisions section, the run directory will contain 1 or more files whose names end with _rev.txt. The file names begin with the root directory names of the version control repositories given in the vcs revisions section. The files contain version control system metadata from the listed version control repositories. Those files provide a record of the last committed revision of the repositories that will be in effect for the run, which is important reproducibility information for the run. If any of the listed repositories contain uncommitted changes, the paths of the files and their status codes, the information from the version control system status command for those files will be appended to the repository’s _rev.txt file. Please see the vcs revisions Section for more details.

`combine` Sub-command

The combine sub-command combines the per-processor results and/or restart files from an MPI NEMO run described in DESC_FILE using the the NEMO rebuild_nemo tool:

 usage: nemo combine [-h] RUN_DESC_FILE

 Combine the per-processor results and/or restart files from an MPI NEMO run
 described in DESC_FILE using the the NEMO rebuild_nemo tool. Delete the per-
 processor files.

 positional arguments:
   RUN_DESC_FILE  file path/name of run description YAML file

 optional arguments:
   -h, --help     show this help message and exit

The per-processor files are deleted.

If the pixi run nemo combine command prints an error message, you can get a Python traceback containing more information about the error by re-running the command with the --debug flag.

`deflate` Sub-command

The deflate sub-command deflates the variables in netCDF files using the Lempel-Ziv compression algorithm to reduce the size of the file on disk:

 usage: nemo deflate [-h] FILEPATH [FILEPATH ...]

 Deflate variables in netCDF files using Lempel-Ziv compression. Converts files
 to netCDF-4 format. The deflated file replaces the original file. This command
 is effectively the same as running ncks -4 -L -O FILEPATH FILEPATH for each FILEPATH.

 positional arguments:
   FILEPATH    Path/name of file to be deflated.

 optional arguments:
   -h, --help  show this help message and exit

You can give the command as many file names as you wish, with or without paths. You can also use shell wildcards and/or regular expressions to produce the list of file paths/names to deflate.

Storage savings can be as much as 80%. Files processed by deflate are converted to netCDF-4 format. The deflated file replaces the original file, but the deflation process uses temporary storage to prevent data loss.

pixi run nemo deflate is equivalent to running:

$ ncks -4 -L4 -O FILEPATH FILEPATH

on each FILEPATH.

If the pixi run nemo deflate command prints an error message, you can get a Python traceback containing more information about the error by re-running the command with the --debug flag.

`gather` Sub-command

The gather sub-command moves results from a NEMO run into a results directory:

 usage: nemo gather [-h] RESULTS_DIR

 Gather the results files from the NEMO run in the present working directory
 into files in RESULTS_DIR. The run description file, namelist(s), and other
 files that define the run are also gathered into RESULTS_DIR. If RESULTS_DIR
 does not exist it will be created.

 positional arguments:
   RESULTS_DIR  directory to store results into

 optional arguments:
   -h, --help   show this help message and exit

If the pixi run nemo gather command prints an error message, you can get a Python traceback containing more information about the error by re-running the command with the --debug flag.

nemo Sub-Commands

run Sub-command

prepare Sub-command

Run Directory Contents

combine Sub-command

deflate Sub-command

gather Sub-command

`run` Sub-command

`prepare` Sub-command

`combine` Sub-command

`deflate` Sub-command

`gather` Sub-command