Use the templating system

Use the templating system#

About#

In the example, we extend the job.sh and env.sh template to generate custom job scripts.

Path: examples/academic/templates.

Configuring#

workflow.cfg#
[app]
name=CROCO
conf=MANGA
exp=exp23

[cycles]
begin_date=2020-01-01
end_date=2020-01-02


[stages]
    [[cycles]]
    run=run_croco
tasks.cfg#
[run_croco]
    [[content]]
    commandline=./croco
hosts.cfg#
[local]
# defaults

Running#

Overview#

Let’s have an overview of stages before running the workflow.

$ woom show overview
##################################### APP ######################################
name: CROCO
conf: MANGA
exp: exp23
################################## TASK TREE ###################################
cycles:
    - run: run_croco
#################################### CYCLES ####################################
2020-01-01T00:00:00+00:00 -> 2020-01-02T00:00:00+00:00 (1 days 00:00:00)
################################### ENSEMBLE ###################################
no member

Dry run#

Now let’s run the workflow in test (dry) and debug modes.

$ woom run --log-no-color --log-level debug --dry-run
woom.log    : DEBUG    *** STARTED LOG SESSION ***
woom.cli    : DEBUG    Run the workflow
woom.cli    : DEBUG    Loading extensions
woom.cli    : INFO     No extension to load
woom.cli    : DEBUG    Load workflow config: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/workflow.cfg
woom.cli    : INFO     Loaded workflow config
woom.cli    : INFO     App name: CROCO
woom.cli    : INFO     App conf: MANGA
woom.cli    : INFO     App exp: exp23
woom.cli    : DEBUG    Initialize the host manager
woom.cli    : INFO     Initialized the host manager
woom.cli    : DEBUG    Load hosts config file: hosts.cfg
woom.cli    : INFO     Loaded hosts config file: hosts.cfg
woom.cli    : DEBUG    Infer host
woom.cli    : INFO     Infered host: local
woom.cli    : DEBUG    Initialize the task manager
woom.cli    : INFO     Initialized the task manager
woom.cli    : DEBUG    Load the task config file: tasks.cfg
woom.cli    : INFO     Loaded the task config file: tasks.cfg
woom.cli    : DEBUG    Initialize the workflow
woom.workflow: DEBUG    Task tree:
cycles:
    - run: run_croco
woom.workflow: INFO     User templates directory enabled: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/templates
woom.cli    : INFO     Initialized the workflow
woom.cli    : INFO     Successfully setup the workflow!
woom.cli    : DEBUG    Run the workflow
woom.workflow: DEBUG    Running the workflow in fake mode
woom.workflow: DEBUG    Entering stage: prolog
woom.workflow: DEBUG    No sequence of task. Skipping...
woom.workflow: DEBUG    Entering stage: cycles
woom.workflow: INFO     Single cycle with unique date: 2020-01-01 00:00:00+00:00
woom.workflow: DEBUG    Running cycle: 2020-01-01T00:00:00+00:00 -> 2020-01-02T00:00:00+00:00 (1 days 00:00:00)
woom.workflow: DEBUG    Entering sequence: run
woom.workflow: DEBUG    Running task: cycles/run/run_croco
woom.workflow: DEBUG    Cleaning task: cycles/run/run_croco
woom.workflow: DEBUG    Creating directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.workflow: INFO     Created directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.workflow: DEBUG    Submitting task: cycles/run/run_croco
woom.workflow: DEBUG      Dependencies: 
woom.workflow: DEBUG    Creating directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.workflow: INFO     Created directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.workflow: DEBUG    Creating directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.workflow: INFO     Created directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.workflow: DEBUG    Creating directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco
woom.workflow: INFO     Created directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco
woom.job    : INFO     Started job manager: BackgroundJobManager()
woom.workflow: DEBUG    Fake submission:
--------------- submission command ---------------
bash /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco/job.sh
-------------- batch script content --------------
#!/bin/bash

# Prolog
set -eo pipefail
on_exit() {
    status=$?
    echo $status > "$WOOM_SUBMISSION_DIR/job.status"
    exit $status
}
trap on_exit EXIT

# Workflow: CROCO
# Configuration: MANGA
# Experiment: exp23
# Task: run_croco

# Environment variables
export WOOM_TASK_NAME="run_croco"
export WOOM_RUN_DIR="/home/docs/woom/scratch/woom/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco"
export WOOM_APP_NAME="CROCO"
export WOOM_APP_CONF="MANGA"
export WOOM_APP_EXP="exp23"
export WOOM_CYCLES_BEGIN_DATE="2020-01-01T00:00:00+00:00"
export WOOM_CYCLES_END_DATE="2020-01-02T00:00:00+00:00"
export WOOM_CYCLES_ROUND=""
export WOOM_CYCLES_FREQ=""
export WOOM_CYCLES_NCYCLES="0"
export WOOM_CYCLES_INDEP="0"
export WOOM_CYCLES_AS_INTERVALS="1"
export WOOM_APP_PATH="CROCO/MANGA/exp23"
export WOOM_TASK_PATH="CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco"
export WOOM_CYCLE="2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00"
export WOOM_CYCLE_BEGIN_DATE="2020-01-01T00:00:00+00:00"
export WOOM_CYCLE_LABEL="2020-01-01T00:00:00+00:00 -> 2020-01-02T00:00:00+00:00 (1 days 00:00:00)"
export WOOM_CYCLE_TOKEN="2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00"
export WOOM_CYCLE_END_DATE="2020-01-02T00:00:00+00:00"
export WOOM_CYCLE_DURATION="P1DT0H0M0S"
export WOOM_CYCLE_IS_FIRST="1"
export WOOM_CYCLE_IS_LAST="1"
export WOOM_CYCLE_NEXT=""
export WOOM_CYCLE_PREV=""
export WOOM_NMEMBERS="0"
export WOOM_WORKFLOW_DIR="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates"
export WOOM_SUBMISSION_DIR="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco"
export WOOM_LOG_DIR="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/log"
export WOOM_SCRIPT_PATH="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco/job.sh"
export PATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/bin:$PATH
export PYTHONPATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/lib/python:$PYTHONPATH
export LIBRARY_PATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/lib:$LIBRARY_PATH
export INCLUDE_PATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/include:$INCLUDE_PATH

export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK:-4}

# Utilities
function log_message() {
    echo "[$(date +%Y-%m-%d_%H:%M:%S)] $*" | \
        tee -a ${WOOM_LOG_DIR}/custom.log
}

# Initialization
log_message "Environment is initialized for ${WOOM_TASK_NAME}"

# Go to run dir
mkdir -p /home/docs/woom/scratch/woom/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco && cd /home/docs/woom/scratch/woom/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco

# Run the commandline(s)
./croco
--------------------------------------------------
woom.workflow: INFO     Submitted task: cycles/run/run_croco with job id 439401
woom.workflow: INFO     Successfully submitted cycle: 2020-01-01T00:00:00+00:00 -> 2020-01-02T00:00:00+00:00 (1 days 00:00:00)
woom.workflow: DEBUG    Entering stage: epilog
woom.workflow: DEBUG    No sequence of task. Skipping...
woom.cli    : INFO     Successfully ran the workflow!

Normal run#

And finally in run it.

$ woom run --log-no-color
woom.cli    : INFO     No extension to load
woom.cli    : INFO     Loaded workflow config
woom.cli    : INFO     App name: CROCO
woom.cli    : INFO     App conf: MANGA
woom.cli    : INFO     App exp: exp23
woom.cli    : INFO     Initialized the host manager
woom.cli    : INFO     Loaded hosts config file: hosts.cfg
woom.cli    : INFO     Infered host: local
woom.cli    : INFO     Initialized the task manager
woom.cli    : INFO     Loaded the task config file: tasks.cfg
woom.workflow: INFO     User templates directory enabled: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/templates
woom.cli    : INFO     Initialized the workflow
woom.cli    : INFO     Successfully setup the workflow!
woom.workflow: INFO     Single cycle with unique date: 2020-01-01 00:00:00+00:00
woom.workflow: INFO     Created directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.workflow: INFO     Created directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco
woom.workflow: INFO     Created batch script: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/v2025.10.1/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco/job.sh
woom.job    : INFO     Started job manager: BackgroundJobManager()
woom.workflow: INFO     Submitted task: cycles/run/run_croco with job id 886
woom.workflow: INFO     Successfully submitted cycle: 2020-01-01T00:00:00+00:00 -> 2020-01-02T00:00:00+00:00 (1 days 00:00:00)
woom.cli    : INFO     Successfully ran the workflow!

Check status#

Check what is running or finished.

$ woom show status
╭──────────┬─────────┬───────────┬─────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────╮
│ STATUS   │   JOBID │ TASK      │ CYCLE                                               │ SUBMISSION DIR                                                                       │
├──────────┼─────────┼───────────┼─────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────┤
│ ERROR    │     886 │ run_croco │ 2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00 │ jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco │
╰──────────┴─────────┴───────────┴─────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────╯

Show run directories#

Show where tasks were executed.

$ woom show run_dirs
╭───────────┬─────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ TASK      │ CYCLE                                               │ RUN DIR                                                                                                      │
├───────────┼─────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ run_croco │ 2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00 │ /home/docs/woom/scratch/woom/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco │
╰───────────┴─────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Contents