Skypro

Skypro is the smart grid simulation and reporting engine behind Skyprospector, by Simtricity. It models the electricity flows, costs and revenues of a battery-and-solar smart grid — the kind that runs a UK community-energy site — to answer two questions:

• What would happen? — skypro simulate projects how a site behaves under a chosen battery control strategy over historical (or synthetic) load, solar and price data, and reports the resulting energy flows, costs and revenues.
• What actually happened? — skypro report collates real metering data into performance reports and supplier-invoice estimates, flagging data-quality problems as Notices.

It is both a command-line tool and an importable Python engine.

Install

pip install --upgrade skypro

Requires Python 3.10+. Run skypro --help (or skypro <command> --help) for the full flag reference — this README covers the concepts and capabilities behind the commands rather than repeating their usage.

Quick start

A scenario is one YAML file containing one or more named simulations; select one and run it:

skypro simulate -c scenario.yaml --sim my-scenario --plot

This writes the detail and summary CSVs named in the scenario's output block. A report over a billing month:

skypro report -c report.yaml -m 2025-04

Both read the environment file described below. See skypro <command> --help for every flag.

Commands

• skypro simulate — project smart grid behaviour, cost and revenue over a time frame under a control strategy. Reads a YAML scenario config; writes detail and summary CSVs (and, for MPC, a per-tick NDJSON replay sidecar).
• skypro report — analyse real metering data for a billing period: reconstruct the smart grid flows, estimate the supplier bill, and surface metering inconsistencies as Notices.
• skypro pull-elexon-imbalance — fetch and cache Elexon imbalance volume/price data, used by imbalance-priced tariffs and forecasters.
• skypro replay validate — check a replay NDJSON against the schema (structural → per-line → cross-line → reconciliation layers). Downstream consumers use it to verify their own output.
• skypro replay solve-replay — re-solve a single recorded tick through the engine's own builder, trust-gate it against the recorded plan, and --swap one input to attribute why a decision differs.

Core concepts

A little of the domain model goes a long way for authoring scenarios and reading results.

Seven energy flows

In every interval, energy moves along seven flows:

solar_to_load   solar_to_batt   solar_to_grid
grid_to_load    grid_to_batt
batt_to_load    batt_to_grid

Costs, revenues and levies are attributed per flow.

Rates

Each flow carries rates in four categories:

• Volumetric (p/kWh) — DUoS, supplier fees, final-consumption levies.
• Fixed (p/day, p/kVA/day) — standing and capacity charges.
• Market — the actual cashflow with a supplier or counterparty.
• Internal — a notional opportunity-cost value the optimiser dispatches against.

Rates are supplied per flow, from JSON/YAML files or a rates database.

Control strategies

Pick one per scenario under strategy::

• perfectHindsightOptimiser — an LP that finds the optimal dispatch given perfect foresight of prices. The upper-bound benchmark.
• mpc — model-predictive control: a rolling-horizon LP re-solved each tick against forecast inputs. The realistic deployable; emits a replay NDJSON.
• priceCurveAlgo — a real-time heuristic (NIV chase, peak shaving, load following) driven by a price/state-of-energy curve.
• extension — a proprietary or external strategy loaded via a plugin seam (see CLAUDE.md).

MPC forecasters

MPC drives its LP from forecasts, configured under the strategy. Solar and load forecasts resolve independently. Rate forecasters: rates_block, baseline, composer, dayahead_rollforward, persistence, naive_seasonal. Profile (solar/load) forecasters: meteo_solar (weather-driven solar), naive_profile_persistence, perfect.

OSAM (P395)

The On-site Allocation Methodology for final-demand levies runs alongside Skypro's own flow methodology; any discrepancy between the two is reported as a Notice.

Replay NDJSON

An MPC run can emit a per-tick NDJSON replay sidecar: a manifest, each tick's forecast/LP/dispatch, half-hourly settlement records, and a summary trailer. It is the shared format between the simulator, live edge producers, and replay viewers, and is checked by skypro replay validate.

Configuration

Environment file (~/.simt/env.json)

Skypro reads a JSON environment file for directory shortcuts and database credentials (override the path with --env):

{
  "vars":  { "PROFILE_DIR": "/path/to/profiles" },
  "flows": { "dbUrl": "postgres://…" },
  "flux":  { "dbUrl": "postgres://…", "schema": "flux" },
  "rates": { "dbUrl": "postgres://…" }
}

• vars — arbitrary path variables. $PROFILE_DIR anywhere in a config path resolves from here.
• flows — the Flows database (plot meter tables).
• flux — the Flux database (meter and BESS readings, market data). schema defaults to flux; set it to flows for legacy single-schema databases.
• rates — the Rates database.

Only the sections a given run actually uses are required.

Scenario config (YAML)

A simulation is described by a YAML scenario. The main sections are timeFrame, site.gridConnection, site.bess, site.solar / site.load (profiles), rates (per-flow rate files), strategy, and output. An annotated, runnable example ships at src/tests/integration/fixtures/simulation/config.yaml.

Skypro is developed and maintained by Simtricity Limited. Developer, release and engine-embedding docs are in CLAUDE.md; version history is in CHANGELOG.md.