0.16.0

[birnbaum]

This release introduces a native simulation backend, structured experiment results, and a rebuilt viewer for simulation studies.
We also simplified the modeling API and now model grid connections explicitly as dispatchable resources.

Native simulation backend

• Vessim now runs simulations directly through a native backend, reducing scheduling overhead for parameter sweeps, optimization, and probabilistic studies.
• Mosaik remains available for connecting external simulators, including models running in other processes or on other computers.
  Install vessim[mosaik] and select backend="mosaik" when creating the environment.
• Trace lookups, dispatch, and recording have been optimized for repeated simulations.
• Environment.run() now returns a RunResult with the final state and execution information.

Recording and metrics

• Added Recorder for metrics, optional time series, and experiment metadata.
  Use Recorder("results/run") to save a run, or Recorder(timeseries=False) to collect metrics without retaining its trajectory.
• Built-in metrics track energy production and consumption, grid imports and exports, and peak grid demand.
• Added Metric, ElectricityImportCost, ElectricityExportRevenue, and GridImportEmissions for custom objectives and price or carbon accounting.
• Added ExperimentResult for loading, inspecting, and saving recorded runs.
  Results include configuration, parameters, metric definitions, and execution status.

Vessim Viewer

• Rebuilt the viewer around simulation studies, with comparisons across configurations and repeated runs.
• Added configurable results tables, scatter plots, distributions, and Pareto-front selection for exploring trade-offs.
• Compare time series across runs and configurations, with shared controls for signals, aggregation, and units.
• The selected study and view are stored in the URL so results can be linked directly.
• Export an interactive report for static hosting with python -m vessim view results/study --export report.
• Published examples are available directly in the documentation viewer.

Modeling API

• Added Consumer and Producer for demand and generation.
  Both accept a number or a Signal, while Actor supports components that can change direction.
• Added GridConnection as a dispatchable resource with import and export limits, ramp constraints, and disconnection support.
• The default dispatch policy allocates power in resource order while respecting operating limits.
  Infeasible demand or surplus now raises an error.
• Added Trace.select() to use different columns of a shared input trace.
• Controllers and REST clients can replace an actor's signal to change future demand or generation.

Breaking changes

• Recording: Recorder replaces MemoryLogger and CsvLogger.
  Saved results now use experiment.json and an optional timeseries.csv, replacing the previous metadata.yaml format.
  The new viewer requires recordings in the new format.
• Grid connections: Add GridConnection() explicitly to a microgrid's dispatchables when it can exchange power with the grid.
  DefaultDispatchPolicy(mode=...) was removed.
  Custom policies must assign balanced resource setpoints and return None instead of returning residual grid power.
• Actors: The consumer argument was removed.
  Replace Actor("load", StaticSignal(700), consumer=True) with Consumer("load", signal=700).
  Custom actors now implement sample(elapsed) to return power and diagnostic state, replacing the separate power() and state() hooks.
• Live integrations: The sil extra is now live, and SilSignal is now LiveSignal.
  Install live integrations with pip install 'vessim[live]'.
• Mosaik coupling: Mosaik is now optional, and individual actors are no longer exposed as simulator entities.
  Call env.prepare() and connect external simulators through env.entities[microgrid_name].
• Environment lifecycle: Environments are single-use, and ordinary simulations require a finite duration.
  Use Environment.live() for indefinite runs.
• Signals: The environment now starts and finalizes attached signals, including shared signals.
  Live polling starts when the simulation runs, and closed live signals cannot be reused.
  Standalone use of Vessim signals as a data-access API is deprecated.

Documentation and examples

• Reworked Getting Started, concept pages, and the API reference around building, running, and inspecting a simulation.
• Added guides for simulation studies, optimization, live modeling, and connecting external simulators.
• Added reproducible examples for infrastructure sizing, Optuna searches, probabilistic dispatch, parallel battery-sizing studies, demand response, and custom metrics.
• Unified example setup and output handling, including seeded inputs and protection against overwriting existing results.

Fixes and compatibility

• Battery state now advances through the full requested duration, including a shortened final interval.
• Fixed minimum-charge handling in ClcBattery and strengthened validation of battery parameters and resource setpoints.
• Traces now reject invalid timestamps, duplicate entries, nonfinite data, and sampling outside their bounds.
• Improved cleanup after failed or interrupted runs, including live polling, API brokers, external simulators, and recording status.
• Added support for Python 3.14 and 3.15.

---

Full Changelog: 0.15.1...0.16.0

---

This discussion was created from the release 0.16.0.