Getting started

Quickstart

This guide walks you from zero to a running campaign with monitoring UI. It covers both local (workstation/server) and Slurm (HPC cluster) setups.

If you haven't read Core concepts yet, do it first: it takes 5 minutes and will make this page much clearer.

This guide uses code_saturne. For code_aster, the steps are the same with solver = "code_aster" in csauto.toml; examples/codeaster-cube is a complete code_aster campaign.

Prerequisites

Python 3.11+
csauto installed and the csauto alias configured (see Installation)
A working code_saturne runtime (one of):
- native: code_saturne binary installed and in PATH, or path set via solver_bin
- singularity: Apptainer or Singularity + a .sif image file
- docker: Docker engine running (the image defaults to simvia/code_saturne)

For Slurm: sbatch, squeue, scancel in PATH.

1. Project structure

Organize your campaign files like this:

Code
my-campaign/
├── csauto.toml        ← runtime configuration
├── doe.csv            ← parameter table (one row = one case)
├── TEMPLATE/          ← your base case
│   └── DATA/
│       └── setup.xml
│       └── run.cfg
│   └── SRC/
│       └── *.cpp
└── RUNS/              ← generated by csauto (do not version-control this)

Keep RESU/ out of TEMPLATE/. It is generated under each case in RUNS/ during execution.

2. Configuration (`csauto.toml`)

Create csauto.toml in your campaign directory.

Local / workstation:

Code
runtime = "native"
solver_bin = "/opt/code_saturne/bin/code_saturne"
use_slurm = false
max_parallel = 2

host = "127.0.0.1"
port = 8000

HPC with Slurm:

Code
runtime = "native"
solver_bin = "/opt/code_saturne/bin/code_saturne"

use_slurm = true
mpi_exec_options = "--mca btl vader,self,tcp --bind-to core"
max_parallel = 20

host = "127.0.0.1"
port = 8000

Docker:

Code
runtime = "docker"
docker_image = "simvia/code_saturne"   # optional: the default image for code_saturne
use_slurm = false
max_parallel = 2

host = "127.0.0.1"
port = 8000

max_parallel is the default of csauto run --max-parallel; in the web UI, the Run dialog has its own Max Parallel field. See config.md for all available keys and their defaults.

3. Prepare the parameter table (`doe.csv`)

Create doe.csv. The header row defines your parameters. Each subsequent row is one simulation case.

Code
case_id,density_value,turbulence_model,ref_v
case0001,1.2,Spalart-Allmaras,0.5
case0002,1.0,Spalart-Allmaras,0.5
case0003,1.2,kwSST,0.8
case0004,1.0,kwSST,0.8

case_id is optional: omit it and csauto will generate case0001, case0002, ...
Column names must exactly match the placeholders you use in the template.

See doe-format.md for the full format specification.

4. Prepare the template

Take your existing code_saturne case and replace the values you want to vary with placeholders using {column_name} syntax. csauto will substitute them with the DOE values when generating each case.

Minimum required structure:

Code
TEMPLATE/
└── DATA/
    └── setup.xml

Below are two real examples drawn from a setup.xml.

Simple value substitution: density is read from the DOE column density_value:

Code
<property name="density" choice="constant" label="Density">
  <initial_value>{density_value}</initial_value>
</property>

Conditional blocks: the turbulence model section is included only when the DOE column turbulence_model matches the condition. Only one block is active per case:

Code
<!-- IF turbulence_model == "Spalart-Allmaras" -->
<turbulence model="Spalart-Allmaras">
  <reference_velocity>0.5</reference_velocity>
  <variable name="nu_tilda" label="nu_tilda"/>
</turbulence>
<!-- ENDIF -->

<!-- IF turbulence_model == "kwSST" -->
<turbulence model="k-omega-SST">
  <reference_velocity>{ref_v}</reference_velocity>
  <variable name="k" label="k"/>
  <variable name="omega" label="omega"/>
</turbulence>
<!-- ENDIF -->

Note that {ref_v} is inside the kwSST block: it is only active (and therefore required in the DOE) when turbulence_model == "kwSST". For rows where turbulence_model is Spalart-Allmaras, the entire block is dropped and the value of ref_v is ignored.

You can also place placeholders in:

TEMPLATE/run.cfg
TEMPLATE/SRC/*.cpp (user subroutines)
any other text file of the template

See doe-format.md for the full placeholder and IF block syntax.

5. Generate cases

prepare is a terminal-only step: there is no UI equivalent. Run it from the directory that contains doe.csv and TEMPLATE/.

Code
csauto prepare doe.csv TEMPLATE RUNS

Re-running the same command after appending rows to doe.csv adds the missing cases, as long as the already generated cases still match the current DOE rows and template content.

Expected output:

Code
RUNS/
├── registry.json
├── campaign.json          ← the solver of this campaign (code_saturne)
├── case0001/
│   ├── DATA/setup.xml     ← {density_value} replaced with 1.2, etc.
│   └── doe_row.csv        ← the DOE values used for this case
├── case0002/
├── case0003/
└── case0004/

If anything is wrong (missing placeholder column, empty value, missing setup.xml), csauto stops with an error naming the problem.

6. Validate before launching

doctor is terminal-only (csauto status is the terminal view of the Status panel). Once it passes, everything else happens in the web UI.

Code
csauto doctor RUNS

This checks that:

the runtime is available (for Docker, the docker command; the image itself is not checked)
case directories have the expected structure
write access to RUNS/ is available

Fix every [FAIL] before proceeding.

Code
csauto status RUNS

All cases should appear with status PREPARED.

Setup complete. Steps 5 and 6 are the only terminal-only steps in the workflow. From here, the web UI is your primary interface for launching, monitoring, restarting, and cleaning cases.

7. Open the web UI

Start the UI server:

Code
csauto serve RUNS --host 127.0.0.1 --port 8000

This uses the primary FastAPI server.

Open http://127.0.0.1:8000.

On a remote server or HPC cluster, create an SSH tunnel from your laptop first:

Code
ssh -L 8000:127.0.0.1:8000 your-server

Then open http://127.0.0.1:8000 on your laptop.

The web UI is the recommended way to operate your campaign from this point on. See web-ui.md for the full guide.

8. Launch runs from the UI

In the Status panel, all your PREPARED cases appear in the table.

Select all cases: Ctrl/Cmd + A
Click Run
Fill in the popup:
- n: MPI ranks per case (e.g. 4)
- nt: OpenMP threads per rank (e.g. 2)
- Max Parallel: how many cases run at the same time (e.g. 2; left empty, local runs are capped to cpu_count // (n * nt) at once, a scheduler receives every selected case)
Click Run in the popup

Cases move to RUNNING. The case next in line shows PENDING while it waits for a free slot, and the others keep their status until their turn. The table refreshes automatically.

On a Slurm cluster, the same UI flow applies: each case is submitted via sbatch under the hood. You can verify with squeue -u "$USER" in the terminal.

Alternative: launch from the command line

If you prefer the terminal, the run command is equivalent:

Code
# Local
csauto run RUNS --n 4 --nt 2 --max-parallel 2

# Slurm (with use_slurm = true in csauto.toml)
csauto run RUNS --n 64 --nt 1 --max-parallel 20

# Specific cases only
csauto run RUNS --n 4 --nt 2 --case case0002 --case case0003

# Re-launch only failed cases
csauto run RUNS --n 4 --nt 2 --resume

9. Daily workflow from the UI

Once cases are running, everything can be done from the browser:

Status panel: monitor iteration count, duration, disk usage per case
Residuals Plot: inspect solver convergence curves
Log Tail: stream the solver's log live (run_solver.log; select case → Log Tail tab)
Recent Errors: scan for errors and warnings after a case fails
Restart: restart from checkpoint without touching any files
Kill: stop a running case immediately

For terminal-based monitoring:

Code
# Check status table
csauto status RUNS

# Watch the solver's log in real time
csauto tail RUNS --case case0001

# Export residuals as CSV + SVG
csauto residuals RUNS --case case0001 --out residuals.csv --plot residuals.svg

10. Cleanup

In the Status panel, select the cases you want to clean and click Clean. A popup lets you choose which RESU runs to keep or delete. Clean also cuts the solver's logs over 50 MB down to their last 50 MB and removes .csauto.cid. Running and pending cases are left alone.

Alternative: command line

Always preview first with --dry-run:

Code
csauto cleanup RUNS --prune-resu --keep-last 1 --max-log-mb 100 --dry-run

Apply when satisfied:

Code
csauto cleanup RUNS --prune-resu --keep-last 1 --max-log-mb 100 --clear-cid

This keeps the most recent RESU directory per case and truncates logs above the size limit.

If something goes wrong

Code
csauto doctor RUNS

Then check troubleshooting.md for error message → fix mappings.

Last modified on October 15, 2026

Core Concepts Web UI Guide