Skip to content

quickstart.md

Latest commit

 

History

History
350 lines (244 loc) · 8.66 KB

quickstart.md

File metadata and controls

350 lines (244 loc) · 8.66 KB

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.

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 saturne_bin
    • singularity: Apptainer or Singularity + a .sif image file
    • docker: Docker engine running + a code_saturne image

For Slurm: sbatch, squeue, scancel in PATH.

1. Project structure

Organize your campaign files like this:

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:

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

host = "127.0.0.1"
port = 8000

HPC with Slurm:

runtime = "native"
saturne_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:

runtime = "docker"
docker_image = "simvia/code_saturne"
use_slurm = false
max_parallel = 2

host = "127.0.0.1"
port = 8000

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.

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:

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:

<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:

<!-- 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)

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/.

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:

RUNS/
├── registry.json
├── case0001/
│   ├── DATA/setup.xml     ← {u_inlet} replaced with 12.0, 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 reports the error before creating any files.

6. Validate before launching

doctor and status are terminal-only steps. Once they pass, everything else happens in the web UI.

csauto doctor RUNS

This checks that:

  • the runtime binary/image is accessible
  • case directories have the expected structure
  • write access to RUNS/ is available

Fix every [FAIL] before proceeding.

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:

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:

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.

  1. Select all cases: Ctrl/Cmd + A
  2. Click Run Selected
  3. 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 simultaneously (e.g. 2)
  4. Click Submit

Cases move to RUNNING status. 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:

# 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 listing file live (select case → Log Tail tab)
  • Recent Errors — scan for errors and warnings after a case fails
  • Restart Selected — restart from checkpoint without touching any files
  • Kill Selected — stop a running case immediately

For terminal-based monitoring:

# Check status table
csauto status RUNS

# Watch a log in real time
csauto tail RUNS --case case0001 --file listing -n 100

# 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 Selected. A popup lets you choose which RESU runs to keep or delete, and whether to truncate heavy logs.

Alternative: command line

Always preview first with --dry-run:

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

Apply when satisfied:

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

csauto doctor RUNS

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