Getting started

This chapter takes you from a bare machine to a solved power flow and a running dashboard: install the SDK, build, run the tests, solve your first case on the CLI, and launch the desktop app.

Prerequisites

You need exactly one thing: the .NET 10 SDK (the SDK, not just the runtime - you will compile source and run the test host). Confirm it is installed:

dotnet --list-sdks      # a 10.0.x line must be present

Everything else is optional and task-specific:

Task	Needs
Build, test, run the CLI	.NET 10 SDK only, any OS
Run the desktop app (`GridSim.Wpf`)	.NET 10 SDK on Windows (it builds everywhere, runs only on Windows)
`crossval` (diff against pandapower)	Python with `pandapower` and `scipy`; degrades gracefully when absent
GPU backends (`--gpu`)	an ILGPU-visible device; a missing device warns and falls back to CPU
GDA-materialised GB cases	the read-only GDA data lake on an authorised machine - never in the repo

There is no database, no service to provision, and no licensed data required: the built-in cases are embedded in GridSim.Core and the editable GB models ship in data/.

Clone and build

git clone <your-remote>/GridSim.git
cd GridSim
dotnet build GridSim.slnx -c Release

The solution builds seven projects (GridSim.Core, Cli, Gda, Gpu, Web, Wpf, and tests/GridSim.Tests). The repo runs a pedantic analyzer gate - Directory.Build.props sets TreatWarningsAsErrors with the .NET analyzers on

so a healthy build ends with 0 warnings, 0 errors. Any warning fails the build; do not suppress it, fix it.

A plain dotnet build GridSim.slnx (Debug) is fine for development. Use Release when you are timing anything (bench, nminus1-sweep, stress, chain): a Debug timing is not a comparable number.

Run the tests

dotnet test tests/GridSim.Tests

Expect 552 tests, all passing:

Passed!  - Failed:     0, Passed:   552, Skipped:     0, Total:   552

The suite is deterministic and self-contained - no network, no GPU, no licensed data - so a single failure is a real regression, not noise. To run a subset while iterating, filter by name:

dotnet test tests/GridSim.Tests --filter "FullyQualifiedName~Case9"

First CLI solve

Solve the WSCC 9-bus benchmark - the project's physics ground truth:

dotnet run --project src/GridSim.Cli case9

GridSim  -  IEEE 9-bus (WSCC)
9 buses  9 branches  3 generators  base 100 MVA  50 Hz
========================================================================
Converged (4 NR iters, 0 OLTC passes, max mismatch 1.84E-014 p.u.)
Generation 0.32 GW  Demand 0.32 GW  Losses 4.6 MW  Inertia 7.5 GVAs
...
Total losses: 4.64 MW, -92.16 MVAr

Learn that signature: 4 iterations, mismatch ~1.8x10^-14 p.u., 4.64 MW total losses. If your build produces anything else on case9, something is wrong with the build, not the case. The same solve is independently cross-checked against pandapower (see 14-validation-tools.md).

Then solve the reduced GB model once:

dotnet run --project src/GridSim.Cli --once

GridSim  -  GB reduced (10-zone)
20 buses  24 branches  29 generators  base 10000 MVA  50 Hz
========================================================================
Converged (3 NR iters, 3 OLTC passes, max mismatch 1.29E-011 p.u.)
Generation 39.56 GW  Demand 39.50 GW  Losses 55.6 MW  Inertia 171.7 GVAs

Note the extra figure: 3 OLTC passes - the on-load tap-changer outer loop settling the ten GSP transformers into their voltage deadbands before the result is declared converged. With no arguments at all (dotnet run --project src/GridSim.Cli) the same model runs live, re-solving a day/night demand curve every tick until you press a key.

First GUI launch (Windows)

dotnet run --project src/GridSim.Wpf

The control-room dashboard opens on the reduced GB model, animating the day/night curve on a tube-map-style network view. Use the NETWORK picker in the header to switch to any other discovered case, and the SOLVER picker to force an engine (Auto is the default and picks per network). The full tour is 04-the-desktop-app.md.

To boot straight onto a specific case, pass its label (or any substring of it) as a launch argument:

dotnet run --project src/GridSim.Wpf -- case118

The rebuild file-lock gotcha

While the desktop app is running - especially under the Visual Studio debugger

its output DLLs are locked, and because GridSim.Core is the root dependency any rebuild that re-links a downstream assembly fails with MSB3027/MSB3021 copy errors. Two fixes:

Stop the app first. Stop the debugger, or from a shell:

taskkill //F //IM GridSim.Wpf.exe     # Git Bash (doubled slashes); in cmd/PowerShell: taskkill /F /IM GridSim.Wpf.exe

Compile-check without disturbing the running app. Redirect the build output so it never touches the locked DLLs:
```
dotnet build src/GridSim.Wpf/GridSim.Wpf.csproj -p:BaseOutputPath=obj/verifybin/
rm -rf src/GridSim.Wpf/obj/verifybin      # discard the scratch output afterwards
```
Treat that as a compile gate only - do not launch the binaries it produces.

If you are batching several UI edits, keep the app closed and build once at the end.