Run Demo Projects

Gridalyn projects are reproducible workspaces. Each project owns a project.yaml, a workflow.yaml, input references, generated outputs, manifests, reports, and validation checks. The same commands work for compact demos and larger studies.

The public documentation should teach the project pattern, not anchor the platform to one unpublished study. Use the small demos first, then move to the larger flexibility workflow only when you want an end-to-end operations example.

Recommended Order

Project	Why run it first
`projects/minimal_grid_project`	Fastest smoke test for project contracts, reports, and figures.
`projects/ieee_33_bus_demo`	Familiar benchmark feeder with planning-style outputs.
`projects/synthetic_geojson_feeder`	Shows the GeoJSON-to-network generation path.
`projects/prosumer_battery_market`	Demonstrates prosumer assets, forecasts, and market clearing.
`projects/der_voltage_optimization`	Demonstrates CVXPY plus pandapower verification.
`projects/rl_voltage_control_lightsim`	Demonstrates a Gridalyn voltage-control environment backed by LightSim2Grid.
`projects/dr_agent_interaction`	Runs a day of OpenADR 3.1.0 demand-response events through the `dr_program` protocol over a lossy channel, in seconds.
`projects/ev_hosting_flex`	EV hosting capacity and flexibility on a Québec all-electric feeder.
`projects/admm_thermal_consensus`	Distributed ADMM coordination of cold-climate electric heating, on a 500 kVA LV feeder.

Common Commands

Validate a project contract. --check-artifacts also requires the declared reports and figures to exist; those are git-ignored, so drop the flag on a fresh checkout and add it back after the run below, or the command exits non-zero on the missing artifacts:

uv run gridalyn project validate projects/minimal_grid_project --check-artifacts

Inspect its planned stages:

uv run gridalyn project plan projects/minimal_grid_project

Run it (per-stage progress streams to the terminal):

uv run gridalyn project run projects/minimal_grid_project

While iterating on one stage, run only that stage and its dependencies:

uv run gridalyn project run projects/minimal_grid_project --stage run_minimal_powerflow

Check outputs and required artifacts:

uv run gridalyn project status projects/minimal_grid_project --check-artifacts

Run the publication-style verification ladder:

uv run gridalyn project verify projects/minimal_grid_project

Verify all governed demos:

uv run gridalyn project verify-all

verify-all covers every project in the table above and only passes a project whose outputs already exist, so it exits non-zero until each has been run. The six compact demos take about 80 s in total; a fully green verify-all also needs the two long-running studies (ev_hosting_flex, admm_thermal_consensus).

Check pinned result metrics against the project's regression baseline (every demo ships one under baselines/results_baseline.json):

uv run gridalyn project regression projects/minimal_grid_project

If a command fails with an import error, uv run gridalyn doctor shows which optional capabilities are installed; domain CLIs also print the exact pip install "gridalyn[<extra>]" command they need.

Project Outputs

Most projects follow this output layout:

projects/<name>/outputs/data/
projects/<name>/outputs/json/
projects/<name>/outputs/figures/
projects/<name>/outputs/reports/
projects/<name>/outputs/manifests/
projects/<name>/outputs/operations/

Not every project uses every folder. Small demos may only write reports and one figure; operations demos usually write outputs/operations/ as well.

Larger Research Workflow

The EV Hosting Flexibility project is a comprehensive research arc. It starts from project-declared inputs, builds a synthetic topology cache, generates stochastic building and EV profiles, computes dynamic thermal limits, clears locational flexibility contracts, validates selected actions with pandapower, writes figures and materializes operation artifacts, and closes with build_study_reports, which assembles the study-level report from every stage's report and the run manifest.

Run it only when you need the full stack:

uv run gridalyn project run projects/ev_hosting_flex
uv run gridalyn project verify projects/ev_hosting_flex

Its generated artifacts live under:

projects/ev_hosting_flex/outputs/

It is the repo's flagship study, and it is long-running: a full source regeneration takes roughly six hours across 23 stages (operator-verified, receipt-pinned), while warm runs against an existing cache take minutes. See verification.md for the staged protocol.

Synthetic Network Inputs

Projects that build synthetic networks can start from building-footprint GeoJSON. The default tutorial path is:

examples/tutorials/data/buildings_inside_polygon.geojson

To prepare footprints from OpenStreetMap or Microsoft Building Footprints, see Synthetic Networks From GeoJSON.