OpenShipDT

Open, reproducible benchmark for risk-aware energy management in a hybrid-electric ship.

OpenShipDT compares four controllers on identical load profiles:

1. rule-based control;
2. deterministic model predictive control (MPC);
3. scenario stochastic MPC;
4. risk-aware scenario MPC with Conditional Value-at-Risk (CVaR).

The digital twin tracks generator output, battery state of charge (SOC), fuel use, unserved demand, battery throughput and a transparent degradation proxy. The default experiment is synthetic, deterministic under a fixed seed, and requires no confidential vessel data. A documented adapter is included for real CSV data.

Research question

Under load forecast uncertainty, can risk-aware MPC reduce high-cost and constraint-violation outcomes compared with deterministic MPC without causing excessive battery degradation?

Quick start

Requires Python 3.10+.

python -m venv .venv
source .venv/bin/activate
pip install -e .
python -m openshipdt.experiment --config configs/default.yaml
python -m unittest discover -s tests -v

Outputs are written to results/:

• summary.csv: controller-level performance;
• timeseries.csv: dispatch trajectories;
• comparison.png: publication-ready comparison plot;
• manifest.json: configuration, seed and runtime metadata.

Model

At each time step, demand is met by the generator and battery:

generator + battery_discharge - battery_charge + unserved = load.

SOC dynamics include charging and discharging efficiency. The optimization minimizes fuel, generator ramping, battery throughput, SOC deviation and a very large unserved-energy penalty. Risk-aware MPC adds CVaR of scenario loss.

This is a research benchmark, not certified vessel-control software. The linear fuel and degradation models are deliberately interpretable and must be recalibrated before operational use.

Reproduce the benchmark

python -m openshipdt.experiment --config configs/default.yaml

The comparison uses the same realized load for every controller. Forecast scenarios are generated from independent, seeded errors. Statistical replication can be run with:

python scripts/run_replications.py --seeds 11 22 33 44 55

Use real data

Prepare a CSV with columns timestamp and load_kw, then set data.csv_path in the YAML configuration. If sampling is irregular, resample it before use. The public NAUTILUS SOFC-battery demonstrator dataset is a relevant candidate: https://zenodo.org/records/14643552.

Scientific extension plan

• calibrate fuel and battery ageing models using manufacturer or test data;
• compare against distributionally robust ambiguity sets;
• perform out-of-sample tests and paired statistical inference;
• add forecast models and ablation studies;
• validate on an industrial vessel dataset under an approved data agreement.

Repository map

src/openshipdt/       digital twin, controllers, data, metrics, experiment CLI
configs/              versioned experiment definitions
scripts/              replication runner
tests/                unit and smoke tests
docs/                 protocol and data dictionary
results/              generated outputs (example results included after run)

Citation

See CITATION.cff. Archive a tagged GitHub release in Zenodo before citing a specific version.

License

MIT. Data providers retain their own licences.

Benchmark Results

The initial reproducible benchmark compares rule-based control, deterministic MPC, stochastic MPC, and risk-aware CVaR-MPC.