Use the templating system#

About#

This example demonstrates how to customize woom’s job script generation by extending the built-in templates.

Woom automatically generates job scripts for each task using default templates. This example shows how to override and extend these templates to add custom functionality.

The example customizes two templates:

templates/job.sh - Custom job script header:

Uses {% extends "!job.sh" %} to inherit from the built-in job template (the ! prefix refers to woom’s internal templates)
Overrides the {% block header %} section to add workflow metadata
Uses {{ super() }} to include the parent template’s content before adding custom lines
Demonstrates accessing workflow context variables like app_name, app_conf, app_exp, and task.name

templates/env.sh - Custom environment setup:

Extends the built-in environment template
Adds a custom OMP_NUM_THREADS configuration in the {% block env_vars %} section
Creates a new {% block custom %} with utility functions like log_message()
Shows how to add reusable bash functions for task scripts

This example is essential for users who need to customize job script headers, add environment setup, integrate with specific HPC systems, or add logging and debugging utilities.

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=echo 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/latest/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/latest/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    Task path: CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/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/latest/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/latest/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.job    : INFO     Started job manager: BackgroundJobManager()
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/latest/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/latest/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     Fake submission: CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco → bash /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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.workflow: DEBUG    Fake submission:
--------------- submission command ---------------
bash /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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
# - handler for graceful termination
on_sigterm() {
    echo "Received termination signal, cleaning up..."
    # Just exit cleanly, let on_exit handle status
    exit 0
}
# - handler for killing termination
on_sigkill() {
    echo "Received kill signal, cleaning up..." >&2
    # Just exit cleanly, let on_exit handle status
    exit 1
}
# - handler for exit (always called)
on_exit() {
    status=$?
    if [ ! -f "/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco/job.terminating" ]; then
        echo $status > "/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco/job.status"
    fi
    exit $status
}
trap on_sigterm SIGKILL
trap on_sigkill SIGTERM SIGINT
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_WORKFLOW="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/workflow.cfg"
export WOOM_HOST="local"
export WOOM_TASKMANAGER="/home/docs/checkouts/readthedocs.org/user_builds/woom/envs/latest/lib/python3.11/site-packages/woom/tasks.cfg:/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/tasks.cfg"
export WOOM_JOBMANAGER="BackgroundJobManager"
export WOOM_TASK_TREE_CYCLES_RUN="['run_croco']"
export WOOM_CYCLES="2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00"
export WOOM_NMEMBERS="0"
export WOOM_MEMBERS=""
export WOOM_PATHS_PATH="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/bin"
export WOOM_PATHS_PYTHONPATH="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/lib/python"
export WOOM_PATHS_LIBRARY_PATH="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/lib"
export WOOM_PATHS_INCLUDE_PATH="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/include"
export WOOM_APP_PATH="CROCO/MANGA/exp23"
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_CYCLES_HORIZON=""
export WOOM_SCRATCH_DIR="/home/docs/woom/scratch"
export WOOM_WORK_DIR="/home/docs/woom/work"
export WOOM_WORKFLOW_DIR="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates"
export WOOM_LOG_DIR="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/log"
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_MEMBER=""
export WOOM_TASK="run_croco"
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_TASK_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_TASK_SUBMISSION_DIR="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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_TASK_SCRIPT_PATH="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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 WOOM_SUBMISSION_DIR="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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_SCRIPT_PATH="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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 WOOM_TASK_ENV=""
export WOOM_ENV=""
export WOOM_TASK_CONTEXT_JSON="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco/context.json"
export WOOM_CONTEXT_JSON="/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00/run_croco/context.json"
export PATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/bin:$PATH
export PYTHONPATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/lib/python:$PYTHONPATH
export LIBRARY_PATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/examples/academic/templates/lib:$LIBRARY_PATH
export INCLUDE_PATH=/home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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; } || exit 1

# Run the commandline(s)
echo croco
--------------------------------------------------
woom.workflow: INFO     Submitted task: cycles/run/run_croco with job id 932510
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.workflow: DEBUG    Terminating non-blocking jobs
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/latest/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/latest/examples/academic/templates/jobs/CROCO/MANGA/exp23/2020-01-01T00:00:00+00:00-2020-01-02T00:00:00+00:00
woom.job    : INFO     Started job manager: BackgroundJobManager()
woom.workflow: INFO     Created directory: /home/docs/checkouts/readthedocs.org/user_builds/woom/checkouts/latest/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/latest/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.workflow: INFO     Submitted task: cycles/run/run_croco with job id 953
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                                                                       │
├──────────┼─────────┼───────────┼─────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────┤
│ SUCCESS  │     953 │ 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 │
╰───────────┴─────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Use the templating system

Contents