.. Copyright 2021 – present by the Salish Sea Atlantis project contributors,
.. The University of British Columbia, and CSIRO.
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..
..    https://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

.. SPDX-License-Identifier: Apache-2.0


.. _RunDescriptionFile:

********************
Run Description File
********************

.. _ExampleRunDescriptionYAML-File:

Example Run Description YAML File
=================================

.. literalinclude:: atlantis-example.yaml
   :language: yaml


.. _BasicRunConfiguration:

Basic Run Configuration
=======================

The following key-value pairs provide the basic configuration for the run.

An example of the basic configuration key-value pairs:

.. code-block:: yaml

    run id: SS-Atlantis

    # The name of the boxes .bgm file must match the value of the "geometry" attribute in the
    # global attributes of the initial conditions file.
    boxes: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_xy.bgm

    initial conditions: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_init.nc

    groups: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_grps.csv

    migrations: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SalishMigrations.csv

    fisheries: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SalishFisheries.csv

    output filename base: outputSalishSea


:kbd:`run id`
  An identifier for the run.
  It is used as the first part of the temporary run directory name.
  For example,
  :kbd:`run id: SS-Atlantis` will result in the creation of a temporary run directory with a name like :file:`SS-Atlantis_2021-08-18T102810.108199-0700/`.
  The date/time stamp that is appended to the :kbd:`run id` value is the creation time of the directory.
  That makes the temporary run directory name unique,
  and allows :command:`atlantis run` to be used to execute multiple nearly concurrent runs.

:kbd:`boxes`
  The path to the :file:`.bgm` box geometry file for the run.
  The file name
  (without the path part)
  must match the value of the :kbd:`geometry` global attribute in the initial conditions netCDF file.

:kbd:`initial conditions`
  The path to the initial conditions netCDF file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-i` flag.

:kbd:`groups`
  The path to the groups :file:`.csv` file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-s` flag.

:kbd:`migrations`
  The path to the migrations :file:`.csv` file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-m` flag.

:kbd:`fisheries`
  The path to the fisheries :file:`.csv` file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-q` flag.

:kbd:`output filename base`
  The base filename for the output files generated by the run.
  For example,
  if the value is :kbd:`outputSalishSea`,
  the main netCDF output file name will be :file:`outputSalishSea.nc`,
  and other output file names will start with :kbd:`outputSalishSea`;
  e.g. :file:`outputSalishSeaBoxBiomass.txt`.
  The main netCDF output file name will be passed to the :program:`atlantisMerged` executable by the :kbd:`-o` flag.

The :kbd:`boxes`,
:kbd:`initial conditions`,
:kbd:`groups`,
:kbd:`migrations`,
and :kbd:`fisheries` paths may be relative or absolute,
and may contain :kbd:`~` or :envvar:`$HOME` as alternative spellings of the user's home directory,
and :envvar:`$USER` as an alternative spelling of the user's userid.

Absolute paths with environment variables are strongly recommended for portability and re-usability.

Those files are copied to the temporary run directory during the run set-up phase of :command:`atlantis run`,
and they are copied from there to the results directory when the run script terminates so that they are preserved with the run results.

The file name of the :kbd:`boxes` file in the temporary run directory and the results directory is the same as in the path provided.
For example,
:kbd:`boxes: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_xy.bgm` will result in a file called :file:`SS_xy.bgm` in the temporary run and results directories.

The file name of the :kbd:`initial conditions` file in the temporary run directory and the results directory is always :file:`init_conditions.nc`.

The file name of the :kbd:`groups` file in the temporary run directory and the results directory is always :file:`groups.csv`.

The file name of the :kbd:`migrations` file in the temporary run directory and the results directory is always :file:`migrations.csv`.

The file name of the :kbd:`fisheries` file in the temporary run directory and the results directory is always :file:`fisheries.csv`.


.. _Paths:

:kbd:`paths` Section
====================

The :kbd:`paths` section of the run description file is a collection of directory paths
that are used during the run set-up phase of :command:`atlantis run`.

An example :kbd:`paths` section:

.. code-block:: yaml

    paths:
      atlantis code: /ocean/$USER/Atlantis/atlantis-trunk/
      atlantis executable name: atlantisMerged
      runs directory: /ocean/$USER/Atlantis/runs/

:kbd:`atlantis code`
  The path to the CSIRO Atlantis ecosystem model code Subversion checkout where
  the Atlantis executable for the run is to be found.

  The :command:`atlantis run` sub-command confirms that the :kbd:`atlantis code`
  directory exists,
  and exits with an error message if not.

:kbd:`atlantis executable name`
  The name of the Atlantis executable to use for the run.
  The executable name is typically :program:`atlantisMerged`,
  but it may be different if you are with code that is under active development to add new
  features.

  This is not actually a path,
  but it is included here because it is closely associated with :kbd:`atlantis code`.
  The Atlantis executable is assumed to be located in the :kbd:`atlantis code` tree,
  specifically,
  at :file:`{{atlantis code}}/atlantis/atlantismain/{{atlantis executable name}}`.

  The :command:`atlantis run` sub-command confirms that the
  :kbd:`atlantis executable name` file exists,
  and exits with an error message if not.


:kbd:`runs directory`
  The path to the directory where run directories will be created by
  the :command:`atlantis run` sub-command.

:kbd:`atlantis command`
  .. note::
     **DEPRECATED.**
     The ``atlantis command`` path is not required when you have installed :py:obj:`AtlantisCmd`
     using Pixi.
     The path required to run the :program:`atlantis` command is calculated in the code.

  The path to the :program:`atlantis` command processor executable file installed from
  the :py:obj:`AtlantisCmd` Python package.

  The :command:`atlantis run` sub-command confirms that the
  :program:`atlantis` command processor executable file exists,
  and exits with an error message if not.

The paths may be relative or absolute,
and may contain :kbd:`~` or :envvar:`$HOME` as alternative spellings of the
user's home directory,
and :envvar:`$USER` as an alternative spelling of the user's userid.

Absolute paths with environment variables are strongly recommended for portability and
re-usability.


.. _Parameters:

:kbd:`parameters` Section
=========================

The :kbd:`parameters` section of the run description file is a collection of file paths that :program:`atlantis` uses to find the :file:`.prm` files for the run.
The :file:`.prm` files are copied to the temporary run directory during the run set-up phase of :command:`atlantis run`,
and they are copied from there to the results directory when the run script terminates so that they are preserved with the run results.

An example :kbd:`parameters` section:

.. code-block:: yaml

    parameters:
      # The run, forcing, physics, and biology parameters files are required for all runs,
      # and they must be identified by those exact keys.
      run: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_run.prm
      forcing: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_forcing.prm
      physics: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_physics.prm
      biology: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_biology.prm
      harvest: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_harvest.prm

The paths may be relative or absolute,
and may contain :kbd:`~` or :envvar:`$HOME` as alternative spellings of the user's home directory,
and :envvar:`$USER` as an alternative spelling of the user's userid.

Absolute paths with environment variables are strongly recommended for portability and re-usability.

The 5 keys :kbd:`run`,
:kbd:`forcing`,
:kbd:`physics`,
:kbd:`biology`,
and :kbd:`harvest` are required for all runs.

:kbd:`run`
  The path to the run parameters file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-r` flag.
  The file name of the :kbd:`run` parameters file in the temporary run directory and the results directory is always :file:`run.prm`.

:kbd:`forcing`
  The path to the forcing parameters file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-f` flag.
  The file name of the :kbd:`forcing` parameters file in the temporary run directory and the results directory is always :file:`forcing.prm`.

:kbd:`physics`
  The path to the physics parameters file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-p` flag.
  The file name of the :kbd:`physics` parameters file in the temporary run directory and the results directory is always :file:`physics.prm`.

:kbd:`biology`
  The path to the biology parameters file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-b` flag.
  The file name of the :kbd:`biology` parameters file in the temporary run directory and the results directory is always :file:`biology.prm`.

:kbd:`harvest`
  The path to the harvest parameters file that will be passed to the :program:`atlantisMerged` executable by the :kbd:`-h` flag.
  The file name of the :kbd:`harvest` parameters file in the temporary run directory and the results directory is always :file:`harvest.prm`.

Additional,
optional,
parameter file key-value pairs may be included as required.
The file names of those extra parameters files in the temporary run directory and the results directory is the key with :file:`.prm` appended;
i.e. :kbd:`contaminants: /ocean/$USER/Atlantis/salish-sea-atlantis-model/SS_contaminant.prm` would result in a file named :file:`contaminants.prm` in the temporary run and results directories.
Extra parameter files are generally associated with entries in the :kbd:`forcing` parameter file.


.. _Forcing:

:kbd:`forcing` Section
======================

The :kbd:`forcing` section of the run description file contains sub-sections that provide the names of directories and files that are to be symlinked in the run directory for Atlantis to use to read forcing values from.

An example :kbd:`forcing` section:

.. code-block:: yaml

    forcing:
      # The keys must match the forcing file names in the forcing.prm file.
      # The file names in the forcing.prm file must be just file names, not path/filename.
      # The keys will be the names used for the symlinks created in the temporary run
      # directory.
      SS_hydro.nc:
        link to: /ocean/$USER/Atlantis/salish-sea-atlantis-model/inputs/SS_hydro.nc
      SS_temp.nc:
        link to: /ocean/$USER/Atlantis/salish-sea-atlantis-model/inputs/SS_temp.nc
      SS_salt.nc:
        link to: /ocean/$USER/Atlantis/salish-sea-atlantis-model/inputs/SS_salt.nc

The sub-section keys
(:kbd:`SS_hydro.nc`,
:kbd:`SS_temp.nc`,
and :kbd:`SS_salt.nc` above)
are the names of the symlinks that will be created in the run directory.
Those names are expected to appear in the appropriate places in the :file:`forcing.prm` file.
The values associated with the :kbd:`link to` keys are the targets of the symlinks that will be created in the run directory.

The paths may be relative or absolute,
and may contain :kbd:`~` or :envvar:`$HOME` as alternative spellings of the user's home directory,
and :envvar:`$USER` as an alternative spelling of the user's userid.

Absolute paths with environment variables are strongly recommended for portability and re-usability.

You are free to use any keys that you wish with the understanding that the key will be the name of the symlink that will be created in the run directory,
and that name will also need to appear as a file name in the :file:`forcing.prm` file.

The :command:`atlantis run` command confirms that the targets of the symlinks exist,
and exits with an error message if not.


.. _VCS-Revisions:

:kbd:`vcs revisions` Section
============================

The *optional* :kbd:`vcs revisions` section of the run description file contains lists of version control system repositories for which the revision and status will be recorded in the temporary run and run results directories.

.. note::
    Generation of a revision and status record file for the :file:`atlantis-trunk` Subversion repository checkout is not yet implemented.

An example :kbd:`vcs revisions` section:

.. code-block:: yaml

    vcs revisions:
      git:
        - /ocean/$USER/Atlantis/salish-sea-atlantis-model/
        - /ocean/$USER/Atlantis/AtlantisCmd/

The sub-section key(s)
(:kbd:`git` above)
are the names of the version control tools to use for the repositories listed below them.
At present only Git
(:kbd:`git`)
and Mercurial
(:kbd:`hg`)
are supported.

The paths listed under the version control tool keys are the repositories of which the revision and status will be recorded.

The repository paths may be relative or absolute,
and may contain :kbd:`~` or :envvar:`$HOME` as alternative spellings of the user's home directory,
and :envvar:`$USER` as an alternative spelling of the user's userid.

Absolute paths with environment variables are strongly recommended for portability and re-usability.

For each repository,
a file will be created in the temporary run directory.
The file names are the repository directory names with :kbd:`_rev.txt` appended.
So,
from the example above,
the files created will be:

.. code-block:: text

    salish-sea-atlantis-model_rev.txt
    AtlantisCmd_rev.txt

For Git repositories,
each :file:`_rev.txt` file will contain the output of the commands:

.. code-block:: bash

    git branch --show-current
    git log -1
    git show --pretty="" --name-only

for the repository.
That is a record of the last committed revision of the repository that will be in effect for the run.
For example,
:file:`salish-sea-atlantis-model_rev.txt` might contain:

.. code-block:: text

    branch: master
    commit: 9c87f2789a6fe4acfa84545d0d243b404dda9dbe
    author: por07g
    date:   Wed Jun 09 09:32:38 2021 +10:00
    files:  RunTrack.org
    message:
    update

If any of the listed repositories contain uncommitted changes,
the :command:`nemo prepare` command that :command:`atlantis run` uses will generate a warning message like:

.. code-block:: text

    nemo_cmd.prepare WARNING: There are uncommitted changes in /ocean/$USER/Atlantis/salish-sea-atlantis-model/

and the list of uncommitted changes and their status codes,
the output of the :command:`git diff --name-status` command,
will be appended to the :file:`_rev.txt` file.
Example:

.. code-block:: text

    branch: master
    commit: 9c87f2789a6fe4acfa84545d0d243b404dda9dbe
    author: por07g
    date:   Wed Jun 09 09:32:38 2021 +10:00
    files:  RunTrack.org
    message:
    update

    uncommitted changes:
    M SS_forcing.prm
    M SS_run.prm