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:
Uses a cookiecutter template in the AtlantisCmd package to set up a temporary run directory from which to execute the Atlantis run.
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
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.