TACTUS Scripting System

About

The tactus scripting system provides a tactus python package.

See the project's documentation page for more information.

Set up environment

Make sure you have python>=3.10

Start by adding the $HOME/.local/bin directory in your PATH:

export PATH="$HOME/.local/bin:$PATH"

We highly recommend you to also put the statement listed above in your shell configuration file, so you don't need to do this the next time you log in. Then, run:

• On Atos (hpc-login)

  module load python3/3.10.10-01
  module load ecflow

• On LUMI

  ml use /scratch/project_465000527/jasinskas/scl/modules/
  ml pyeccodes_23
  ml scl-ecflow_23

• On Belenos

  conda create -n <env_name> python=3.10.* gdal=3.6.2 ecflow -c conda-forge
  conda activate <env_name>

See also lumi doc for more details.

• On Macs (local install only)

  brew install pyenv
  pyenv install 3.10.10
  # (or which ever version you want to universalise)
  pyenv global 3.10.10

  Add eval "$(pyenv init --path)" to ~/.zprofile (or ~/.bash_profile or ~/.zshrc, whichever you need). Relaunch the shell and check that Python works, or run $ source ~/.zprofile

Installation

First checkout the tactus source code from github:

git clone git@github.com:ACCORD-NWP/tactus.git
cd tactus

For development, use forks as specified in the Development guidelines. To clone the forked repository, use the following command, replacing <username> with your GitHub username:

git clone git@github.com:<username>/tactus.git
cd tactus

Then install/reinstall poetry by runnning the following commands in your shell:

# Clean eventual previous install
curl -sSL https://install.python-poetry.org | python3 - --uninstall
rm -rf ${HOME}/.cache/pypoetry/ ${HOME}/.local/bin/poetry ${HOME}/.local/share/pypoetry
# Download and install poetry
curl -sSL https://install.python-poetry.org | python3 -  
poetry install
# Add the poetry shell command as a plugin (for poetry >= v2.0.0)
poetry self add poetry-plugin-shell

Finally, install pygdal, which is required for climate generation. pygdal depends on gdal, which is notoriously troublesome as dependency when targeting many systems. The versions of pygdal and the system's gdalshould match.

To install gdal and pygdal run the follow in commands in your shell:

• On Atos (hpc-login)

  module load gdal/3.6.2
  poetry shell
  pip install pygdal==3.6.2.11

On Belenos, you should install the project in the conda environment that was created, directly with the pip command.

pip install -e . --no-cache --prefer-binary

If installation is not succesful, please contact the IT support in your organisation or HPC facility.

Important

Tactus should be installed in a folder accessible by ecflow server.

On Atos, it should be installed in your $HOME or $PERM directory.

Usage

Initially set up the environment by repeating the steps in Set up environment, navigate to the root level of the tactus install directory and activate python virtual environment:

poetry shell

Alternatively, to activate a tactus installation located in an arbitrary directory MY_TACTUS_SOURCE_DIRECTORY, please run:

poetry shell --directory=MY_TACTUS_SOURCE_DIRECTORY

Test that tactus works by running:

tactus -h

The Configuration File

Before you can use tactus (apart from the -h option), you will need a configuration file written in the TOML format. Please take a look at the default config.toml file, as well as the project's Doc Page, for more information about this.

To see all configs currently in place in your tactus setup, please run

tactus show config

Command line options

After completing the setup, you should be able to run

tactus [opts] SUBCOMMAND [subcommand_opts]

where [opts] and [subcommand_opts] denote optional command line arguments that apply, respectively, to tactus in general and to SUBCOMMAND specifically.

Please run tactus -h for information about the supported subcommands and general tactus options. For info about specific subcommands and the options that apply to them only, please run tactus SUBCOMMAND -h (note that the -h goes after the subcommand in this case).

Examples

These examples assume that you have successfully Set up environment installed tactus, navigated to the root level of your tactus install directory and loaded the python environment. The examples also assume that the binaries and input data for the ACCORD CSCs is in place. Please contact your local ACCORD members for advice if this is not the case.

Running ecflow suite on ATOS or LUMI

The following command will run the full suite using the default experiment:

tactus case ?tactus/data/config_files/configurations/cy48t3_arome -o cy48t3_arome.toml --start-suite

Running the "Forecast" task from the hpc-login's command line

The command below runs tactus's task "Forecast" for the member specified in the config file using the batch system rules defined in your config.toml:

tactus run --task Forecast --config-file cy48t3_arome.toml

Note that this requires a previous run of the ecflow suite for the given config file to have finished succesfully.

To run the Forecast task for a different member, simply point to the config file with the desired member number specified.

NOTE: the config file used by a given task, is always saved to the working directory, when the task is run. Thus one can e.g. point to the config file used by the mbr001/Cycle/Forecasting/Forecast task to rerun the Forecast task for member 1):

This way, the stand alone forecast will pick the input data from the existing run and output the result in the same directories (as defined by the config file).

For other platforms a new config file would have to be created first. Please consult the configure cases section in the documentation for more information.