Run compound flood models on shared clusters.

AutoCF HPC 1.0.0 is a portable, scheduler-neutral command-line package for Apptainer or Singularity. Start a model on the cluster or transfer a complete Windows/macOS run.

Supported execution

Install & verify

Upload the release archive and checksum sidecar, verify before extraction, then run the package doctor.

1. Load the container module when required.Use your site’s Apptainer or Singularity environment module before AutoCF.
2. Verify the archive.The checksum sidecar must report OK.
3. Extract and enter the package.Keep the package directory intact.
4. Make the launcher executable.Then run the offline doctor.

sha256sum -c AutoCF_release_v1.0.0.tar.gz.sha256
tar -xzf AutoCF_release_v1.0.0.tar.gz
cd AutoCF_release_v1.0.0
chmod +x autocf
./autocf doctor

Published archive SHA-256:

af36619541a0498208fbdbf6c57d185ba20a332b0e794d398cbaea9deeb225c3

What doctor checks

doctor verifies the complete package manifest, public CPU/GPU image hashes, executables and linkage, dependencies, path resolution, SFINCS input closure, validation logic, attribution mathematics, and excluded payloads. It needs no internet.

New model on HPC

Copy the complete example, edit the scientific choices, inspect the resolved configuration, and build where providers are reachable.

1. Create and inspect YAML

cp examples/sfincs_agent_config.yml my_project.yml
./autocf show-config my_project.yml

At minimum, set:

• project.name and a unique project.output_dir.
• geojson.path.
• simulation.event_name, simulation.start, and simulation.end.
• model.mode: regular or subgrid.
• Terrain, surface, forcing, and validation providers appropriate to the case.

Relative paths resolve from the YAML directory. An infiltration: block is enabled by its presence; remove the complete block to disable infiltration. Use a different output directory for every distinct build.

2. Build inputs

./autocf build my_project.yml

Build prepares configured inputs and writes the SFINCS engine model under <run-root>/data/model/main/. It does not execute the solver.

CPU & GPU runs

Request the desired resources first, then use run-only. Simulation requires no internet.

export OMP_NUM_THREADS=8
./autocf run-only my_project.yml --cpu

nvidia-smi
./autocf run-only my_project.yml --gpu

run-only never rebuilds, downloads inputs, or changes YAML. It validates every active file referenced by sfincs.inp, streams SFINCS progress to the terminal, and writes the run log under <run-root>/logs/simulation/. run is an alias for run-only.

Transfer a desktop run

Windows, macOS, and HPC use the same layout-version-2 run structure. Transfer the complete clean run root whenever possible.

Recommended destination and layout

AutoCF_release_v1.0.0/runs/<case-name>/
  data/
    model/main/**                  REQUIRED: complete engine model
    validation/water_level/**      cached observations
    surface/**                     attribution land-mask inputs
    geospatial/**                  custom geometry and vectors
    attribution/exposure/**        optional attribution cache
    exposure/source/**             optional single-run impact cache
  work/hydromt/**                  resolved configuration and provenance
  metadata/**                      recommended run metadata

Earlier desktop result files such as sfincs_map.nc, sfincs_his.nc, and sfincs.log are unnecessary when HPC will rerun the model. AutoCF rebases the resolved snapshot under work/hydromt/. Transfer any custom input outside the run root and replace desktop-absolute paths with portable paths.

Run the transferred model

./autocf run-only runs/<case-name> --gpu
./autocf evaluate runs/<case-name>
./autocf attribute runs/<case-name> --prepare
./autocf attribute runs/<case-name> --run --gpu
./autocf attribute runs/<case-name> --report

Replace --gpu with --cpu for CPU execution. TARGET may be the run root, its inner model directory, or a project YAML; the run root is recommended. Every active sfincs.inp reference must be relative and included. Drive-qualified Windows paths are rejected, never guessed or rewritten.

Evaluation

Evaluate a completed simulation after the necessary model and observation files are present.

./autocf evaluate my_project.yml
./autocf evaluate my_project.yml --no-hydromt-basemap

Use --no-hydromt-basemap for a fully offline map when observations have already been transferred or cached. Products are written below <run-root>/results/evaluation/.

Attribution

Use the staged workflow because preparation/reporting and simulation commonly belong on different node types.

./autocf attribute my_project.yml --prepare
./autocf attribute my_project.yml --run --gpu
./autocf attribute my_project.yml --report

Use --cpu instead of --gpu for CPU resources. Attribution products are written below <run-root>/results/attribution/.

Internet & node planning

Prepare and report on internet-enabled nodes; run SFINCS inside offline CPU or GPU allocations on the shared filesystem.

On clusters with offline GPU nodes, build and prepare before requesting the GPU. Run only simulation stages inside the allocation, then evaluate and report on an internet-enabled node. All stages share the same run directory.

Restart safely

Attribution is restart-safe at scenario boundaries, not within a running SFINCS scenario.

Repeating attribute --run skips a scenario only when its nonempty sfincs_map.nc exists and the solver-written sfincs.log contains both Simulation finished and Closing off SFINCS. An interrupted scenario restarts; completed scenarios remain untouched.

Flat SFINCS folders

A standalone directory containing sfincs.inp remains a valid target.

./autocf run-only /path/to/model --cpu

The directory acts as both run root and model root. AutoCF does not migrate it into layout version 2.

Datum helper

The preserved solver images are not modified for datum conversion.

export AUTOCF_TRANSFORMEZ_EXECUTABLE=/path/to/transformez-helper
./autocf build my_project.yml

See helpers/transformez/README.md. With datum_engine: auto, an unavailable helper is recorded and local alignment is used. With datum_engine: transformez, absence of the helper is an error.

Scheduler scripts

Request resources with the local scheduler, then place the ordinary AutoCF command in the script body.

#!/usr/bin/env bash
set -euo pipefail
cd /path/to/AutoCF_release_v1.0.0
export OMP_NUM_THREADS=8
./autocf run-only runs/<case-name> --cpu

AutoCF does not generate scheduler directives. Add the partition, account, wall time, memory, CPU, GPU, and notification directives required by your site.

Ready to run?

Verify the package, inspect the resolved configuration, and request the correct resources.

Start installation