atlantis Sub-Commands

The command atlantis help produces a list of the available atlantis options and sub-commands:

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

Atlantis Ecosystem Model Command Processor

optional arguments:
--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:
complete       print bash completion command (cliff)
help           print detailed help for another command (cliff)
run            Prepare, execute, and gather results from a CSIRO Atlantis ecosystem model run.

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

$ atlantis help run

usage: atlantis run [-h] [--no-submit] [-q] DESC_FILE RESULTS_DIR

Prepare, execute, and gather the results from an Atlantis 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
--no-submit  Prepare the temporary run directory, and the bash script to
            execute the Atlantis run, but don't launch the run.
            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.
-q, --quiet  don't show the run directory path

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

atlantis --version

run Sub-command

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

usage: atlantis run [-h] [--no-submit] [-q] DESC_FILE RESULTS_DIR

Prepare, execute, and gather the results from an Atlantis 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
--no-submit  Prepare the temporary run directory, and the bash script to
            execute the Atlantis run, but don't launch the run.
            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.
-q, --quiet  don't show the run directory path

The path to the run directory, and a message indicating that the run has been launched are printed upon completion of the command.

The run sub-command does the following:

  1. Uses a cookiecutter template in the AtlantisCmd package to set up a temporary run directory from which to execute the Atlantis run.

  2. The cookiecutter processing generates an Atlantis.sh job script in the run directory. The job script:

    • runs atlantisMerged

    • executes the gather Sub-command to collect the run configuration and results files into the results directory

  3. Launches job script as a background job.

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 a message indicating that the run has been launched. Example:

$ atlantis run atlantis.yaml /ocean/$USER/Atlantis/runs/my-run/

atlantis_cmd.run INFO: Created temporary run directory: /ocean/$USER/Atlantis/runs/SS-Atlantis_2021-08-18T153416.049642-0700
atlantis_cmd.run INFO: launched SS-Atlantis run via /ocean/$USER/Atlantis/runs/SS-Atlantis_2021-08-18T153416.049642-0700/Atlantis.sh

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 there are uncommitted changes in any of the version control repositories included in the vcs revisions Section of the run description YAML file, a warning message for each repository will appear. Example:

$ atlantis run atlantis.yaml /ocean/$USER/Atlantis/runs/my-run/

nemo_cmd.prepare WARNING: There are uncommitted changes in /ocean/$USER/Atlantis/salish-sea-atlantis-model
nemo_cmd.prepare WARNING: There are uncommitted changes in /ocean/$USER/Atlantis/AtlantisCmd
atlantis_cmd.run INFO: Created temporary run directory: /ocean/$USER/Atlantis/runs/SS-Atlantis_2021-08-18T153416.049642-0700
atlantis_cmd.run INFO: launched SS-Atlantis run via /ocean/$USER/Atlantis/runs/SS-Atlantis_2021-08-18T153416.049642-0700/Atlantis.sh

The warning messages start with nemo_cmd.prepare because the VCS recording feature is provided by the NEMO-Cmd package.

gather Sub-command

The gather sub-command moves results from an Atlantis temporary run directory into a results directory. It is provided by the NEMO-Cmd package. Please use:

$ atlantis help gather

to see its usage, and see gather Sub-command for more details.

If the gather 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.