Configuration

Every knob that changes GridSim's behaviour from outside the code, one table per surface. All three faces pin InvariantCulture at process start, so number parsing and CSV output are locale-independent everywhere - you never need DOTNET_SYSTEM_GLOBALIZATION_INVARIANT.

CLI environment variables

The CLI is configured almost entirely by its arguments (19-cli-reference.md); it reads two environment variables of its own and honours the standard .NET ones.

Variable	Read by	Effect
`GDA_ROOT`	`gda` verb	Fallback for `--root`: the path to the read-only GDA data lake. An explicit `--root` always wins. With neither set, `gda` prints usage and exits 2.
`ROCM_PATH`	ROCm GPU interop	Root of the ROCm install for native library discovery; defaults to `/opt/rocm`.
`DOTNET_gcServer` / `DOTNET_gcConcurrent`	.NET runtime	Override the CLI's Server GC default without a rebuild. The active mode is stamped into every report header (`GC=Server\\|Workstation`).
`DOTNET_GCHeapHardLimit` / `...Percent`	.NET runtime	Cap the managed heap so a large `bench` sweep raises a catchable OOM instead of exhausting the box (the server regime driver sets a 48 GiB cap).

There are no other GPU-related variables: GPU selection is the --gpu[=rocm|opencl|cuda] switch, resolved AMD-first (ROCm -> OpenCL -> CUDA) with CPU fallback. ROCM_PATH (read by the native-library resolver) is honoured when locating the ROCm .sos on a bare box.

WPF desktop app

Launch arguments (all optional):

Argument	Example	Effect
`<model>`	`case9`	Boot straight onto the first model source whose label contains the token.
`--zone <case>`	`--zone zone-ukpn`	Pre-select the bridge case before connecting.
`--back <days>`	`--back 30`	Pre-select the bridge start offset (days behind now) - handy because the settled lake lags "now"; the pre-solved window is ~30 days back.
`--bridge-source <s>`	`--bridge-source estimated`	Pre-select the reconstruction source: `presolved`, `estimated` or `live`.
`--tab <name>`	`--tab OPERATOR`	Open a specific tab on boot (used for screenshots/demos).

Persisted settings live in %LOCALAPPDATA%\GridSim\settings.json (best-effort load and save - a corrupt file never stops the app). The one operationally significant key:

Key	Default	Meaning
`BridgeEndpoint`	`ws://127.0.0.1:8770/ws/bridge`	The GDA<->GridSim bridge WebSocket. Non-empty => the model picker lists a "Live bridge" source; blank hides it.

The rest (LastSource, ColorVoltage, Minimap, overlay toggles, ...) are UI state the app rewrites as you use it.

Web app (ASP.NET Core)

GridSim.Web is a stock ASP.NET Core host, so the full standard configuration stack applies (appsettings.json, environment variables, command line, in the usual precedence). It adds one key of its own:

Key / variable	Effect
`GridSim:BridgeEndpoint`	GDA bridge WebSocket URI for `bridge:<case>[@<source>]` sessions. Environment form: `GridSim__BridgeEndpoint=ws://host:8770/ws/bridge`. Empty/unset => any bridge request fails with `No GDA bridge endpoint is configured`.
`ASPNETCORE_URLS` (or `--urls`)	Host binding addresses/ports.
`ASPNETCORE_ENVIRONMENT`	`Development` enables the developer exception page.

GridSim__BridgeEndpoint=ws://10.0.0.5:8770/ws/bridge \
  ASPNETCORE_URLS=http://0.0.0.0:5000 dotnet run --project src/GridSim.Web

Case discovery runs once per process - restart the host to pick up newly dropped run directories.

The live cycle engine

The Cycle: section governs the real-time prioritised analysis cycle (the CYCLE tab, the same engine as gridsim cycle - see 19-cli-reference.md) that runs the post-solve fan-out behind a live session. Environment forms use the usual double underscore (Cycle__Enabled=false).

Key	Default	Effect
`Cycle:Enabled`	`true` (live sessions)	Run the background cycle engine on each solved frame. Set `false` to disable it entirely.
`Cycle:WindowMs`	1000	Wall-clock deadline per cycle (ms); the compute budget is `Workers x WindowMs` core-ms.
`Cycle:Workers`	`min(4, cores-1)`	Fan-out worker pool size - deliberately modest so the background fan-out does not starve the web server.
`Cycle:Shards`	-	Rotating Low-priority N-1 shard count (full branch coverage is reached over this many cycles).

GDA-side environment (the lake tooling)

These belong to the GDA pipeline scripts, not the GridSim repo, but you set them when running the estimated-state workflow (11-estimating-gb-history.md).

Variable	Read by	Effect
`GRIDSIM_CLI`	`NetworkModel/build_estimated_state.py` (and `calibrate_sigmas.py`)	Path to `GridSim.Cli.exe`. Default: the repo's Release binary if built, else Debug. Build Release first - backfill days are CLI-bound and Release is 2-3x faster per period.
`SPINE_ETYS`	`NetworkModel/spine/build_spine.py`	`1` opts in to the ETYS 2025 circuit overlay. Era-mismatch warning: ETYS describes today's network; under the real 2025 circuits the 2019 event day regressed from 46/46 chi-square clean to 32/46 with removal churn, because post-2019 reinforcements do not exist in 2019 reality. Until the overlay is era-aware, the validated synthetic+curated spine stays the default; leave this off for backfill.
`GRIDRADAR_API_TOKEN`	`Ingest/gridradar/gridradar_acquire.py`	PMU-feed access token (register at service.gridradar.net; a gitignored `config.json` beside the script works too). Data-gated: without it the Gridradar products simply are not built.

Paths and conventions

Path	Convention
`results/`	Run directories: `transient-*`, `replay-<id>`, `scenario-<id>`, `estimate-<case>`, `crossval-<case>`, ... Each contains its artefacts plus `run-metadata.json`. The WPF LOAD RUN picker auto-discovers here. Report verbs run from your current directory write `results/` there; the evidence/estimate/crossval family default to `results/` beside the executable - pass `--out` to control it.
`exports/`	Default home of `--enableExport` solve dumps (`<case>-solve.json`), created in the current directory.
`data/uk`	The UK reduced 10-zone JSON case (the no-verb default model).
`data/matpower/`	Drop `.m` files here (e.g. via `tools/fetch-cases.sh`); `bench`, `nminus1-sweep --all` and `LoadNamed` pick them up recursively.
`data/gb-synthetic/`	Default output of `synth`.
`data/neso/frequency-sample.csv`	Default input of `freq` and `replay`.
`data/events/`	Event-catalogue JSON files (`gridsim-event-catalog/1`).
GDA lake (`GDA_ROOT`)	Read-only; materialised replicas go wherever `gda --out` points (git-ignored). Estimated states land in the lake under `DataSources/Derived/estimated_state/`.

A build note that bites here: Directory.Build.props turns on TreatWarningsAsErrors with the .NET analyzers in Recommended mode - a Release build must be 0 warnings / 0 errors, and any new code you configure in must clear the same bar (17-troubleshooting.md).