Executable playbook · Executable playbook

Smart Grid Storage Playbook

Trace a grid-support request through every constraint that can change it.

Dependency-free Python references compose voltage, frequency, ramp, temperature, energy, reserve, and P-Q limits while preserving each intermediate request and curtailment for review.

Open repository Read documentation Run or reproduce Inspect tests and evidence

Engineering question

How can grid-support commands be composed so every curtailment, capability limit, energy boundary, and illustrative assumption remains inspectable?

Follow active power, reactive power, voltage, frequency, temperature, ramp, and SOC requests through visible constraint layers.

System and evidence boundary

Signals move; assumptions stay visible.

The order of operations matters. The playbook records the request at each layer instead of presenting only the final active and reactive power.

Grid-following and grid-forming review

01Grid measurementsVoltage, frequency, breaker and mode
02Following or forming objectiveTrack grid or establish local reference
03P / Q requestService and transition intent
04Common plant constraintsCapability, power, ramp, energy, temperature
05Evidence + handoffDelivered command, limiting layer, operator review

Constraint propagation

01Raw f and VIllustrative event profiles
02Measurement filterFirst-order exact update
03Frequency-watt + Volt-VARActive and reactive requests
04Ramp + temperatureReachable and derated active power
05SOC + durationStored-energy boundary
06P-Q envelopeCircular, sampled, or directional
07Multi-interval stateDelivered P/Q, SOC, reserves, evidence

Verified results

Figures keep scenario, units, source, and evidence class attached.

Every visual below points to its source data or retained source format and to the release- or commit-specific implementation behind it.

Illustrative four-quadrant active and reactive power capability envelope with different charge, discharge, injection, and absorption boundaries — Illustrative CSV · regenerated
Directional P–Q capability envelope

Generated from the committed four-quadrant CSV. The values deliberately differ by direction to demonstrate the allocator and are not a PCS rating or grid-code setting.

Provenance
3ce0b4b · 3ce0b4b2fd4a · verified 2026-07-28

Reproduce
`python scripts/generate-open-engineering-figures.py --sources-root <audit-root>`

Download source data Download source SVG Download source PNG Inspect repository source
Open full-size figure

Validation and evidence

What passed, what was demonstrated, and what remains unvalidated.

One hundred fifty-one tests and 372 subtests passed across capability, support, filtering, ramp, derating, SOC, reserve, and sequence references.

Executable coverage

151 tests and 372 subtests passed across P-Q allocation, Volt-VAR, frequency-watt, filtering, ramping, derating, SOC, reserves, and multi-interval sequences.

Illustrative curves

Default Volt-VAR, frequency-watt, capability, and temperature tables are educational test inputs, visibly labeled and replaceable.

Energy accounting

Sequence results separate AC and stored-energy throughput, conversion loss, standing losses, SOC balance, and a non-degradation equivalent-cycle normalization.

Dynamic boundary

The references do not model network dynamics, converter switching, PLL or grid-forming control loops, protection, voltage feedback, or electromagnetic transients.

Shortest verified path

Pin the audited source before running it.

git clone https://github.com/mohammadrezwankhan/smart-grid-storage-playbook.git
cd smart-grid-storage-playbook
git checkout 3ce0b4b2fd4af2bea743013eac2eee1042b6bdd3
python models/pq_capability.py --active-mw -65 --reactive-mvar -70 --directional-curve-csv models/data/illustrative_directional_capability.csv --priority active
python models/grid_support_sequence.py --frequency-hz-profile 50,49.5,50.5 --voltage-pu-profile 1,0.92,1.08 --baseline-active-mw-profile 20,20,20 --duration-minutes-profile 15,15,15 --limit-mva 100 --energy-capacity-mwh 100 --initial-soc 0.50 --minimum-soc 0.20 --charge-efficiency 1 --discharge-efficiency 1
python -m unittest discover -s tests -v

Verification environment: Python 3.14.6 on Windows 11. Distinguish running the scientific model from rebuilding site figures (which uses scripts/generate-open-engineering-figures.py in the portfolio website repository). Commands are concise entry points; repository documentation remains authoritative for setup details.

Documentation map

Go directly to the useful evidence.

Engineering boundary

The artifact cannot qualify the decision by itself.

All default response curves and sampled envelopes are illustrative, not equipment ratings, plant settings, market commitments, or grid-code requirements.
The sequence is a static or interval-based audit composition, not a dynamic network, converter-control, protection, stability, or EMT simulation.
Project use must supply sign conventions, grid-code settings, capability and temperature envelopes, SOC policy, efficiencies, auxiliary behavior, ramp rules, and acceptance criteria.
The playbook cannot qualify weak-grid operation, grid forming, black start, protection coordination, or hardware performance.

Related professional context

Follow the evidence into adjacent work.

Use the pinned source, inspect the evidence, and keep project authority with a qualified human reviewer. Open 3ce0b4b Return to open engineering

Evidence summary

Reviewed 2026-11-12; evidence records retain their own scope and dates.

Documentation snapshot: 2026-10-06 · caf54a8 · caf54a81b4d76aa09a2ab8069d343c44e0e5467b
Portfolio source record: 151 tests · 372 subtests · source-reported · 3ce0b4b · 3ce0b4b2fd4af2bea743013eac2eee1042b6bdd3
Current release: Unknown from the reviewed evidence.
Current verification: Successful hosted run · 2026-11-04 · target 84f6c43aafb234c139152074888323f14993d4b2
Repository head at 2026-10-17 inventory: caf54a81b4d76aa09a2ab8069d343c44e0e5467b · inventory snapshot only