Repo roadmap¶

Two halves. The SDK loads and serves data and runs on the base install; the engine is the theory (power flow, meters, attacks) and needs [generate]. The public surface is fg.* and the analysis packages fdia_graph.se, fdia_graph.localization, fdia_graph.trust and fdia_graph.federated; everything else serves them.

the package map: the public API over dataset, timeline, registry, se, localization and trust in the base install, generation and engine behind the generate extra, models and formulas read by every package

The two paths¶

fg.generate from ISO load series through the AC pool, the timeline walk and one scan per frame to one registered HDF5 file, and fg.load from registry.resolve through the cached download to FdiaGraph in random or time order

Files¶

file	what it is
`__init__.py`	public API; the heavy helpers resolve lazily so `load()` never imports torch or pandapower
`dataset/`	`FdiaGraph` from `graph` (static graph), `physics` (admittances, clean flows), `records` (items, collate, DataLoader), `export` (whole-split arrays), `sequence` (windows, episodes) over `base` (shared state)
`registry.py`, `download.py`	`(name, release)` to a download spec with that release's file layout; fetch to `~/.cache/fdia_graph`, sha256-verified
`timeline.py`, `generation.py`, `profiles.py`	the timeline walker and writer; the pool, frame context and file attributes; ISO load profiles to AC operating-state pools
`streams.py`	the deprecated stream entry points, kept for reading the v0.7 stream files
`se/`	`SEBase` (measurement model, chord-Newton, calibration) plus one class per estimator
`localization/`	`LocalizerBase` (false-alarm calibration, metrics) plus threshold and learned classes
`trust/`	`TrustSelector` plus the greedy row-reduction (`TrustedMeters`) and deep Q-network (`TrustedMetersDQN`) meter selections, and `secured_copy` of a timeline with the chosen meters pinned
`federated/`	the client partition (`spectral_partition`), the FedAvg localizers (`FedBusMLP`, `FedBusCNN`) and the per-client subspace prior (`RegionalPrior`); needs `[federated]`
`schema.py`	the file protocol: every HDF5 group, dataset and attribute name, defined once
`models/`	every value bundle a function returns, grouped `grid`, `frames`, `data`, `scores`, `assets`
`formulas/`	the mathematics as pure functions with source keys; catalogue in `reference/FORMULAS.md`
`engine/`	`FdiaGenerator` = `MeasurementMixin` (meters, noise) + `PhysicsMixin` (AC solves) + `AttackMixin` (every attack, the `engine/attacks/` package: the attacker's area, the local false state, the redistribution, the stealthy and in-place frames, each episode's design) over `GridBase`; `records.py` emits a benign scan and hands an attacked family to the mixin

Docs¶

folder	holds
`reference/`	data dictionary, glossary, concepts to code, formulas, examples, benchmarks
`guides/`	task walkthroughs: `generation.md` (how a timeline is built), `state_estimation.md`
`se/`, `localization/`, `trust/`, `federated/`	`run_*.py` fits one system and writes runs to the results store (`results/`); `make_report.py` (where present) draws the figures from it and `tools/results_docs.py` fills the README tables
`figures/`	shared images with their data sidecars
`plans/`	the design documents behind the 0.16 and 0.17 refactors (history, not instructions)

Tests and releases¶


`python tools/review_ledger.py <num>`	records the automated reviewer's findings per pull request in `docs/reference/review_ledger.csv` and prints the tally by kind, so a recurring kind becomes a check
`python tools/prereview.py`	every CI gate, the test suite and the checks CI does not run, on this checkout's source; run before a review is requested (`docs/reference/REVIEW_CHECKLIST.md`)
`pytest tests`	builds a tiny IEEE-14 timeline in a throwaway cache (about a minute) and checks the documented contracts
`FDIA_SLOW=1 pytest tests`	adds a sanity test on the published IEEE-118 file
CI	tests on Linux (3.12 and 3.9) and Windows, pyright, ruff format and check, the readability gate, the class-diagram check, install on 3.9 and 3.12
release	bump PR, then `python tools/release.py vX.Y.Z notes.md` (tag, GitHub release, PyPI); see `CONTRIBUTING.md`

Reading order¶

step	read	to learn
0	`CONTRIBUTING.md`	the rules and the pull-request flow
1	`README.md`	install and quickstart
2	`guides/generation.md`	how a timeline is generated, and which layers a feature may read
3	`reference/GLOSSARY.md`	every term, with where it lives in the code
4	`reference/DATA_DICTIONARY.md`	every array and shape
5	this page	which file does what
6	`reference/CONCEPTS_TO_CODE.md`	paper formulas to code
7	`reference/CLASS_MAP.md`	the class and module diagrams, drawn from the code by `tools/class_diagrams.py`
8	`reference/EXAMPLES.md`	training examples to copy from
9	`se/README.md`, `guides/state_estimation.md`	measurements in, better-than-WLS state out
10	`localization/README.md`	which buses are under attack, and why the slow ramp is open
11	`trust/README.md`	which meters to secure so a stealthy attack stops being stealthy
12	`federated/README.md`	the localizers and the prior trained across clients that never pool their records