hydroflow-opt

hydroflow-opt is a Linux/Python 3.11–3.13 orchestration package for simulation-based optimization. It uses pygmo's island model, runs concurrent evaluations locally or within Slurm allocations, and supports checkpoints and resume.

Simulation cases are supplied by installed plugins. The package includes a deterministic quadratic case for development and tests; simulation plugins may require additional runtime dependencies.

Installation

From a source checkout, install with uv or pip:

uv sync --extra tests
# or
python -m pip install --editable '.[tests]'

Quick start

Run the included example from the repository root with the installed environment active:

hydroflow-opt check examples/quadratic.toml
hydroflow-opt run examples/quadratic.toml
hydroflow-opt inspect examples/runs/quadratic

For optimization, use hydroflow-opt optimize CONFIG. Continue an interrupted optimization with hydroflow-opt resume RUN_DIRECTORY.

Documentation

See the full documentation for setup and usage details:

• Overview: responsibilities and run modes.
• Configuration and commands: TOML settings, resource budgets, and debugging saved candidates.
• Execution model: staged evaluations and local/Slurm execution.
• Optimization: islands, concurrent initial populations, checkpoints, and resume.
• Node-local scratch: placement and scratch storage across Slurm nodes.
• Output layout: results, logs, and run metadata.
• Writing plugins: the case plugin contract.