feat: Parsl-based simulation orchestration (Issue #16)

.gitignore

@@ -194,4 +194,7 @@ charmm36.ff/
 !docs/public/diagrams/**/*.png
 !docs/public/mdfactory-logo-v1.0.png
 
+# Allow GROMACS test fixtures
+!mdfactory/tests/fixtures/**
+
 .pixi/

CONTRIBUTORS.md

@@ -2,3 +2,4 @@
 
 - Marc Siggel — Merck KGaA, Darmstadt, Germany
 - Maximilian Scheurer — Merck KGaA, Darmstadt, Germany
+- Gregor Weiss — Merck KGaA, Darmstadt, Germany

README.md

@@ -19,7 +19,7 @@ MDFactory is a high-throughput library for setting up molecular dynamics (MD) si
 
 - **System building** — Mixedbox, bilayer, and LNP build types from YAML or CSV input
 - **Parametrization** — OpenFF/SMIRNOFF and CGenFF with automatic per-molecule caching
-- **Batch processing** — CSV-driven Nextflow pipelines for parallel builds and GROMACS runs on HPC
+- **Batch processing** — CSV-driven Parsl pipelines for parallel builds and GROMACS runs on HPC
 - **Analysis** — Registered analysis and artifact types with parquet output, local or SLURM execution
 - **Data integration** — Push/pull/sync across SQLite, CSV, and Palantir Foundry backends
 
@@ -83,7 +83,7 @@ pip install -e .[dev]
    mdfactory build system.yaml simulation_dir
    ```
 
-See the [Quick Start guide](https://emdgroup.github.io/mdfactory/docs/quick-start) for details on bulk CSV input and Nextflow pipelines.
+See the [Quick Start guide](https://emdgroup.github.io/mdfactory/docs/quick-start) for details on bulk CSV input and running simulations.
 
 ## Configuration
 

docs/README.md

@@ -4,7 +4,24 @@ This folder contains the Fumadocs + Next.js application that renders the MDFacto
 documentation. The site mixes hand-written guides with API pages generated straight from the
 Python package.
 
-## Prerequisites
+## Quick start with pixi
+
+The root `pyproject.toml` defines a `docs` environment that installs Bun, the JS
+dependencies, and `fumapy-generate` automatically:
+
+```bash
+pixi run -e docs docs-dev      # dev server with hot-reload
+pixi run -e docs docs-build    # full static build to docs/out/
+pixi run -e docs docs-generate # regenerate API docs only
+```
+
+Each command chains through `docs-install` → `docs-fumapy` automatically, so a
+single command handles all setup. On subsequent runs the dependency steps are
+fast (no-op when already satisfied).
+
+## Manual setup (without pixi)
+
+### Prerequisites
 
 - [Bun](https://bun.sh/) 1.0+ (fast JavaScript runtime and package manager)
 - Python 3.11 (to install `mdfactory` and `fumapy`)
@@ -18,7 +35,7 @@ python3.11 -m pip install -e ..                         # expose the local packa
 python3.11 -m pip install ./node_modules/fumadocs-python
 ```
 
-## Commands
+### Commands
 
 ```bash
 bun run docs:generate  # runs fumapy-generate + converts JSON into MDX

docs/content/docs/developer-guide/architecture.mdx

@@ -29,7 +29,7 @@ graph TD
 flowchart LR
     A[CSV or YAML inputs] --> B[prepare-build or build]
     B --> C[Simulation directories]
-    C --> D[Local run or Nextflow]
+    C --> D[Local run or Parsl orchestration]
     D --> E[Trajectory and output files]
     E --> F[Simulation.run_analysis / run_artifact]
     F --> G[.analysis parquet, artifacts, metadata.json]
@@ -164,12 +164,26 @@ For analysis and artifact sync, the code uses:
 
 ## Workflow orchestration
 
-The repository contains Nextflow scripts under `workflows/`. The scripts that most directly align with the current CLI are:
+The `mdfactory/orchestration/` package provides Parsl-based parallel orchestration for both building and simulating systems on local machines or SLURM clusters.
 
-- `build.nf`
-- `simulate.nf`
+### Architecture layers
 
-These scripts wrap the checked-in `mdfactory prepare-build` and `mdfactory build` commands plus a fixed GROMACS run chain.
+```mermaid
+graph TD
+    A[CLI: build --slurm / simulate --slurm] --> B[config.py: ExecutorConfig / SlurmExecutorConfig]
+    B --> C[session.py: parsl_session context manager]
+    C --> D[apps.py: Parsl python_app / bash_app definitions]
+    D --> E[stages.py: STAGE_REGISTRY + run_stage dispatch]
+    E --> F[build.py: build_systems / simulate.py: run_simulations]
+    F --> G[Rich progress UI + result collection]
+```
+
+- **`config.py`**: Pydantic models for local and SLURM execution. `ExecutorConfig` handles local runs; `SlurmExecutorConfig` adds SLURM-specific fields (account, partition, walltime, gres, per-stage overrides). Both serialize to/from YAML via `from_yaml()` and `model_dump()`.
+- **`session.py`**: `parsl_session()` context manager that owns the Parsl DataFlowKernel lifecycle. On exit it calls `parsl.clear()` and explicitly `scancel`s any lingering SLURM job IDs.
+- **`apps.py`**: Defines `get_build_app()` (python\_app for system building), `get_grompp_app()` and `get_mdrun_app()` (bash\_apps for GROMACS). Nearly all conditional logic (GPU, MPI, thread counts, restart flags) is resolved in Python before generating the bash script — the only permitted runtime branch is a small `if/elif/else/fi` block for binary detection when `gmx_binary` is set to `auto`.
+- **`stages.py`**: `STAGE_REGISTRY` declares the canonical pipeline (EM → NVT → NPT → Production) as `StageSpec` dataclasses. `run_stage()` is the single generic dispatch function for all stages.
+- **`build.py`** / **`simulate.py`**: Top-level entry points. `build_systems()` submits parallel build tasks; `run_simulations()` chains stages sequentially per simulation with checkpoint detection and trajectory validation.
+- **`tui.py`**: Interactive SLURM configuration wizard using `questionary`. Auto-discovers cluster hardware via `sinfo`/`sacctmgr` and persists the result as a reusable YAML file.
 
 ## Extension points
 

docs/content/docs/index.mdx

@@ -19,7 +19,7 @@ MDFactory is an open source, end-to-end simulation manager for high-throughput m
 />
 
 <FeatureCards>
-  <FeatureCard icon="layers" title="Batch Processing" description="CSV-driven: one row = one system. Run hundreds of systems in parallel via Nextflow on HPC." />
+  <FeatureCard icon="layers" title="Batch Processing" description="CSV-driven: one row = one system. Run hundreds of systems in parallel via Parsl on HPC." />
   <FeatureCard icon="puzzle" title="Modular Pipeline" description="Pluggable build types (mixedbox, bilayer, LNP) with swappable force fields (OpenFF, CGenFF)." />
   <FeatureCard icon="bar-chart" title="Analysis Framework" description="11+ registered analysis types with parquet + JSON metadata output and extensible registry." />
   <FeatureCard icon="database" title="Data Integration" description="SQLite, CSV, and Palantir Foundry backends with intelligent push/pull/sync via CLI." />

docs/content/docs/quick-start.mdx

@@ -78,29 +78,29 @@ This writes GROMACS-ready build output into `simulation_dir`.
 </Step>
 <Step>
 
-## Run with Nextflow (optional)
+## Run simulations (optional)
 
-For high-throughput runs, use the checked-in workflows:
+Run the GROMACS simulation chain (EM → NVT → NPT → Production) locally:
 
-Build many systems from CSV:
+```bash
+mdfactory simulate output_systems/
+```
+
+For high-throughput runs on a SLURM cluster, generate a config interactively and pass it:
 
 ```bash
-nextflow run workflows/build.nf \
-  --csv_file sample_input.csv \
-  --output_dir output_systems
+mdfactory config slurm              # interactive wizard → saves slurm_executor.yaml
+mdfactory simulate output_systems/ --slurm slurm_executor.yaml
 ```
 
-Run the GROMACS chain using the generated summary YAML:
+Or use `--slurm tui` to launch the wizard inline:
 
 ```bash
-nextflow run workflows/simulate.nf \
-  -c workflows/simulate.config \
-  --base_dir output_systems \
-  --config_yaml output_systems/sample_input.yaml
+mdfactory simulate output_systems/ --slurm tui
 ```
 
-<Callout type="warn" title="Cluster-specific configuration">
-The shipped `simulate.config` contains SLURM settings tuned for a specific cluster. Edit this file to match your HPC environment before running. See [Running on HPC Clusters](/docs/user-guide/running-on-hpc) for details.
+<Callout type="info" title="Parsl dependency">
+SLURM orchestration requires the `parsl` extra: `pip install "mdfactory[parsl]"`. See [Running on HPC Clusters](/docs/user-guide/running-on-hpc) for details.
 </Callout>
 
 </Step>

docs/content/docs/user-guide/cli-reference.mdx

@@ -17,12 +17,22 @@ mdfactory prepare-build <input.csv> [output_dir]
 
 ### `mdfactory build`
 
-Build one simulation from a YAML file into the chosen output directory.
+Build MD system(s) from YAML, CSV, or summary input. Supports three input modes:
+
+- **Single YAML**: builds one system locally
+- **CSV file**: builds systems from each row (parallel with `--slurm`, sequential without)
+- **Summary YAML**: dispatches builds for previously prepared systems
 
 ```bash
-mdfactory build <input.yaml> [output_dir]
+mdfactory build <input> [options]
 ```
 
+Options:
+
+- `--output` — output directory (default: `.`)
+- `--slurm` — SLURM executor config: path to YAML file, or `'tui'` for interactive setup
+- `--dry-run` — print what would be built without executing
+
 ### `mdfactory check-csv`
 
 Validate a CSV by converting each row into a `BuildInput` model and, for bilayers, running the current buildability checks.
@@ -31,6 +41,79 @@ Validate a CSV by converting each row into a `BuildInput` model and, for bilayer
 mdfactory check-csv <input.csv>
 ```
 
+## Simulation commands
+
+### `mdfactory simulate`
+
+Run GROMACS MD simulations via Parsl. The simulation pipeline runs four stages by default: EM → NVT → NPT → Production.
+
+```bash
+mdfactory simulate <source> [options]
+```
+
+Options:
+
+- `--slurm` — SLURM config YAML or `'tui'` for interactive setup
+- `--stages` — stages to run (EM, NVT, NPT, Production); defaults to all
+- `--checkpoint` — checkpoint mode: `auto` (default), `skip`, `force`
+- `--hash` — filter by hash prefix (can specify multiple)
+- `--dry-run` — preview plan without executing
+- `--clean` — remove simulation outputs before running (respects `--stages` filter)
+- `--max-rescue` — max rescue tiers for physics failures (default: 3; set to 0 to disable)
+
+Usage examples:
+
+```bash
+# Local execution (all stages)
+mdfactory simulate output_dir/
+
+# SLURM with interactive config
+mdfactory simulate output_dir/ --slurm tui
+
+# Resume from checkpoint with existing config
+mdfactory simulate output_dir/ --slurm gpu.yaml --checkpoint auto
+
+# Equilibration only
+mdfactory simulate output_dir/ --stages EM NVT NPT
+
+# Filter specific simulations
+mdfactory simulate output_dir/ --hash abc123 def456
+
+# Dry-run preview
+mdfactory simulate output_dir/ --slurm gpu.yaml --dry-run
+
+# Clean outputs and re-run (e.g. after a killed job left stale checkpoints)
+mdfactory simulate output_dir/ --clean --slurm gpu.yaml
+
+# Clean only Production stage before re-running it
+mdfactory simulate output_dir/ --clean --stages Production --slurm gpu.yaml
+
+# Preview what --clean would delete without acting
+mdfactory simulate output_dir/ --clean --dry-run
+```
+
+## Configuration commands
+
+### `mdfactory config slurm`
+
+Interactive wizard to configure a SLURM executor and save to YAML. Queries the local SLURM scheduler for available accounts, partitions, and hardware, then walks through resource selection interactively.
+
+The result is saved to a YAML file that can be reused with `mdfactory build --slurm <file>` or `mdfactory simulate --slurm <file>`.
+
+On non-SLURM machines, falls back to manual text entry.
+
+```bash
+mdfactory config slurm
+```
+
+### `mdfactory config cluster`
+
+Show discovered SLURM cluster information. Queries the local SLURM scheduler and displays available partitions, accounts, and QOS policies. Useful for verifying autodiscovery before submitting jobs.
+
+```bash
+mdfactory config cluster [--json]
+```
+
 ## Utility commands
 
 ### `mdfactory clean`