This project is in early development. Expect breaking changes until v1.0.
csauto automates code_saturne CFD simulation campaigns. It offers:
- Generation of tens or hundreds of cases from one template + one CSV, in seconds
- Local and Slurm job execution with status tracking
- A web dashboard for monitoring residuals, probes, logs, and job status in real time
- Restart from checkpoint, input file comparison, and cleanup utilities
No manual case duplication. No directory juggling. Just simulations.
csauto requires Python 3.11+ and has no external dependencies for core features (pure standard library). The web dashboard requires a few extra packages.
# One-line install (clones to ~/.local/share/csauto, creates venv, adds alias)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/simvia-tech/csauto/main/install.sh)"
# Reload your shell
source ~/.bashrc # or: source ~/.zshrcTo update an existing installation, re-run the same command — the script detects the existing install, pulls the latest changes, and reinstalls.
Manual installation (for contributors or custom locations)
git clone https://github.com/simvia-tech/csauto.git ~/tools/csauto
cd ~/tools/csauto
# Option A: use the install script (creates venv, adds alias)
./install.sh
# Option B: manual setup
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[web]"The csauto command is available inside the venv. To use it globally, add an alias:
echo "alias csauto='$HOME/tools/csauto/.venv/bin/csauto'" >> ~/.bashrcTo install without a venv: ./install.sh --no-venv
Verify:
csauto --helpYou need at least one code_saturne runtime:
| Runtime | Requirement |
|---|---|
native |
code_saturne binary in PATH or set via config |
singularity |
Apptainer/Singularity + a .sif image |
docker |
Docker engine + image |
First time? Follow the Quickstart guide for a complete walkthrough from zero to a running campaign.
# 1. Generate cases from your DOE and template
csauto prepare doe.csv TEMPLATE RUNS
# 2. Validate environment
csauto doctor RUNS
# 3. Launch the web dashboard
csauto serve RUNS --host 127.0.0.1 --port 8000Open http://127.0.0.1:8000, then launch runs from the Status panel: Ctrl+A → Run Selected.
my-campaign/
├── csauto.toml
├── doe.csv
├── TEMPLATE/
│ └── DATA/
│ └── setup.xml ← uses {u_inlet}, {turbulence_model}, etc.
└── RUNS/ ← generated by csauto prepare
├── registry.json
├── case0001/
└── case0002/
The web UI (csauto serve) is the primary interface for runtime monitoring and operations — launching, killing, restarting, comparing, and inspecting cases. The CLI covers initial setup (prepare, doctor), data export (residuals, perf), and offers terminal alternatives for common actions.
| Command | Description | UI equivalent |
|---|---|---|
prepare |
Generate cases from a DOE CSV and a template | — (CLI only) |
doctor |
Validate runtime environment and configuration | — (CLI only) |
serve |
Start the web monitoring dashboard | — (starts the UI) |
run |
Launch cases locally or on Slurm (--n, --nt required) |
Status → Run Selected |
status |
Show case status in the terminal | Status panel |
tail |
Stream a case log file (like tail -f) |
Log Tail panel |
residuals |
Export residuals data and/or SVG plot | Residuals Plot panel |
perf |
Extract performance metrics from logs | Timing Snapshot panel |
cleanup |
Remove old RESU dirs, logs (--prune-resu, etc.) |
Status → Clean Selected |
The web UI also provides features beyond the CLI: kill running cases, edit case files, add notes, mark convergence, compare runs side-by-side, plot probes/profiles, and scan logs for recent errors.
Run csauto doctor RUNS to diagnose common issues (missing runtimes, broken paths, configuration errors).
For more details, see the troubleshooting guide.
csauto collects anonymous usage statistics to help us understand how the tool is used and prioritize improvements. No personal data, file paths, simulation data, or case names are ever sent.
What is collected:
- A random anonymous identifier (persistent across sessions)
- csauto version
- Timezone offset
- Runtime type (docker, singularity, or native)
- Event type (install or serve session)
When it is sent:
- Once during first install
- Once when
csauto servestarts - A daily heartbeat while the web server is running
How to opt out:
# Via the CLI
csauto disable-telemetry
# During installation
./install.sh --no-telemetry
# Via the web UI
# Open Settings (gear icon) and uncheck "Send anonymous usage statistics"To re-enable: csauto enable-telemetry
- Quickstart
- Core concepts
- Web UI guide
- CLI reference
- Configuration
- DOE format
- Run lifecycle
- HTTP API
- Task cookbook
- Limitations
Please check out our CONTRIBUTING.md file if you want to contribute to the project.
Thank you to all our contributors :
# Install with dev + web dependencies
pip install -e ".[dev,web]"
# Run full test suite
pytest -q
# Run by scope
pytest tests/unit -q
pytest tests/integration -q
pytest tests/web -q
# Run a single test
pytest tests/unit/test_foo.py::test_bar -qThe web dashboard is a SvelteKit app in frontend/. The pre-built output (frontend/dist/) is committed, so end users don't need Node.js.
To work on the frontend:
# Install dependencies (requires Node.js and pnpm)
cd frontend && pnpm install
# Start the dev server (hot reload, proxies /api to the backend)
pnpm dev
# In another terminal, start the backend
csauto serve RUNS
# Build for production (updates frontend/dist/)
pnpm buildSee architecture for an overview of the codebase.
- code_saturne — the open-source CFD solver csauto automates
- Simvia's website
This project is licensed under the GNU General Public License version 3 (GPL-3.0). See the full license text in the LICENSE file.
- Summary: You are free to use, copy, modify, and redistribute this software.
- Conditions: Redistributions and derivative works must be licensed under GPL-3.0 and include source or a written offer to provide the source.
- More information: https://www.gnu.org/licenses/gpl-3.0.en.html
Contact us at ulysse.bouchet@simvia.tech or florian.hermet@simvia.tech.