GridSim technical manual
The subsystem reference for maintaining, extending or auditing GridSim: the mathematics as implemented, the
parameters and defaults, the invariants and the tests that pin them, the wire formats and the architecture. How to
use GridSim is in the user manual.
Chapter files are named NNNN Chapter title.md, where NNNN is the chapter number. Chapters marked in preparation
are being written.
Foundations
| Ch |
Chapter |
What it covers |
| 1 |
Architecture |
Projects, seams and data flows. |
| 2 |
Data model and per-unit |
GridModel records, per-unit conventions, the Y-bus. |
| 4 |
Sparse and GPU numerics |
CSR storage, sparse LU, ILU/BiCGSTAB, GPU backends, the tolerance table. |
| 8 |
Provenance and invariants |
Provenance tags, [VERIFY], the 169-hour guard, determinism rules. |
| 10 |
File and wire formats |
Every schema and wire format. |
| 12 |
Glossary |
Terms, symbols and reference tables. |
| 28 |
The v2 JSON schema |
The v2 case, network, library and kind schemas. |
Steady state
| Ch |
Chapter |
What it covers |
| 3 |
Power flow |
Dense and sparse Newton-Raphson, Q-limits, the OLTC loop, ZIP loads, the sweep, bit-identity. |
| 23 |
Contingency and security analysis |
N-k, N-2, N-1-1 and their cost. |
| 29 |
OPF, CPF, taps, distribution factors and loss allocation |
DC power flow, DC-OPF and the security simplex, the AC loss loop, CPF, PTDF/LODF, loss allocation, the tap optimiser. |
Dynamics
| Ch |
Chapter |
What it covers |
| 5 |
Frequency dynamics |
The centre-of-inertia swing model, DynamicsConfig, forming, distributed inertia. |
| 13 |
Asset-dynamics data grounding |
Which asset parameters are grounded and which are [VERIFY]. |
| 14 |
Cascade validation and blind prediction |
Blind cross-event validation of the asset cascade. |
| 24 |
Standard dynamic-model library |
Machines, exciters, governors, PSS, RMS transient stability. |
| 30 |
Small-signal and impedance stability |
Classical swing and CCT search, modal analysis, converter impedance and Nyquist stability. |
| 21 |
Electromagnetic transient simulation |
Companion models, the EMT engine, three-phase EMT. |
| 19 |
Harmonics |
Y(h), frequency scan, harmonic power flow, harmonic state estimation. |
| 27 |
Battery energy storage |
The chemistry-first cell, pack and ageing model. |
Protection
Estimation and evidence
| Ch |
Chapter |
What it covers |
| 6 |
State estimation |
WLS, robust estimators, chi-square, bad-data identification. |
| 16 |
Physics conformance and the constrained estimator |
The physical-law audit and the Feasible estimator. |
| 18 |
Real-time, distribution and dynamic estimation |
DSE, three-phase distribution, PMU, CIM and telemetry. |
| 7 |
The evidence engine |
Events, replay, scenarios and the dossier. |
| 9 |
GDA integration |
The bridge protocol, LTDS assembly and lake products. |
| 11 |
Validation |
Cross-checks against MATPOWER, pandapower and scipy, and the tolerance summary. |
Integration and operations
| Ch |
Chapter |
What it covers |
| 20 |
The RTU/SCADA interposer |
The interposer pipeline and protocols. |
| 22 |
Licensing: key format and trust model |
Key layout, signature, trust model. |
| 31 |
Audit log and diagnostics |
gridsim-audit/1 and its hash chain, SolveTrace, the forward-inference guard and its seams, provenance, restriction review. |
| 32 |
CIM/CGMES import and export |
RDF/XML import, merge by mRID, the bridge to GridModel with three-winding star points, and the exporter. |
| 33 |
C37.118 synchrophasor ingest |
Frame, CRC, CONFIG and DATA decoding, the phasor data concentrator, the measurement mapper, the linear PMU estimator and the pmu-ingest verb. |
| 34 |
Web host, REST/WebSocket, SSO and sessions |
GridSim.Web: start-up, routes, the REST status contract, the /ws/sim protocol, sessions and the replay-only gate. |
| 35 |
Deployment and security |
Docker, compose, nginx, the web host, SSO, sessions, CI and release workflows, assurance claims against the code. |
| 36 |
Known limitations and design decisions |
Behaviour kept on purpose after the October 2026 review, why it stays, and where it lives. |
| 37 |
Quasi-static time series and hosting capacity |
The QSTS engine, its time model and controllers (OLTC, banks, IEEE 1547 inverters, storage), the OpenDSS cross-check, and the hosting-capacity bisection. |
| 38 |
Deterministic mathematics |
Why platform maths is not bit-reproducible, the FDLIBM port (DetMath), the canonical NaN, the fixed-order SIMD kernels, the FMA policy, parallel loops, the frozen sort, the tolerances register, and how the IL analyser and the CI tier matrix enforce bit-identity across CPUs and operating systems. |
Design records
These are the designs written before implementation. Each opens with a status block naming what was built and where;
the chapters above document current behaviour.
The per-asset dynamics framework is documented in ch. 5 (the pAssetFleet term) and authored through
user manual ch. 29; ch. 13-15 cover its data grounding, validation and the
protections layer built on the same seam.