CLI quick reference

Generated from docs/manual/0019 CLI reference.md by tools/wiki/gen_cli_reference.py; do not edit by hand.

CLI quick reference

The gridsim command line tool, verb by verb. Every verb answers gridsim <verb> --help with its usage, flags, defaults and exit codes. The full chapter is CLI reference on the site.

Verb index

Group	Verbs
Software licence	licence
Help	help (and gridsim <verb> --help)
Running a case	no verb
Contingency and analysis	trip, screen, nminus1, nminus2, n-1-1, nminus1-sweep, stress, chain, cycle
Network analysis	pf, ptdf, lodf, dcpf, dcopf, acopf, acopf-full, scuc, scopf, qsts, hosting, cpf, taps, restore, losses, dist3ph (experimental)
Physics and protection	physics-check, conformance, protection-check, grade, fault, iec60909, experimental
Frequency and dynamics	freq, replay, transient, domains, stability, modal, fit-frequency, inertia-placement
Harmonics, impedance and EMT	harmonics, impedance-stability, emt
Evidence	replay-event, scenario, h0-study, fleet, evidence
Data	gda, gda-replay, synth, export, convert, validate, zonal, pmu-ingest (experimental), pmu-estimate, estimate, estimate-noise-floor, crossval
Real-time and telemetry	serve, interpose
Benchmarking and preflight	bench, bench --estimate, bench --perf, gpucheck, simdcheck, batchsolve, audit, compliance
Electrical references	ref

All verbs (74)

Verb	Summary	Full section
licence	Inspect and install the software licence (ch. 4).	licence
help	With a verb, prints that verb's section of this chapter as plain text: its usage line, every flag with its default, its exit codes and the notes its group shares, then the general exit-code rule, and exits 0.	help
no verb	Solve a case without naming a verb, for example gridsim case14 --once; a built-in case name, a MATPOWER file or --dir <path>.	Running a case (no verb)
trip	Trip a generator and report the peak RoCoF (Peak RoCoF, the largest |df/dt| over the run), the nadir and the settling frequency, plus the same trip at half inertia.	trip
screen	N-1 RoCoF screening: rank every credible single infeed loss against the GB limits (RoCoF 0.125 Hz/s, statutory 49.5 Hz, LFDD risk) and report the binding case's inertia floor and headroom.	screen
nminus1	Sequential N-1 branch outage screening on one model: each branch out in turn, re-solved, classified secure / violations / islanded.	nminus1
nminus2	N-2 branch screening: two elements lost at once.	nminus2
n-1-1	N-1-1 sequential screening: lose one element, let the operator take corrective action, then lose a second element from that corrected state.	n-1-1
nminus1-sweep	Parallel N-1 branch sweep with throughput reporting, over one case or the whole case registry (--all is the embedded classics plus every .m under data/matpower/).	nminus1-sweep
stress	Load-to-collapse: scale the operating point until the flow stops converging and report max loadability.	stress
chain	Consecutive warm-started solves: each step feeds the previous solution in as the initial condition.	chain
cycle	The real-time prioritised parallel analysis cycle: one single-core Newton-Raphson base solve per cycle, then a worker-pool fan-out of every downstream analysis (N-1 sweep, harmonics, RoCoF screening, physics conformance and the watch...	cycle
pf	One AC power flow on the engine the shared rule picks (radial sweep, dense or sparse Newton), 100 iterations with reactive limits on, printed: convergence, iterations, mismatch, losses, the voltage range and the --top lowest bus voltages.	pf
ptdf	Power transfer distribution factors: +1 MW injected at --bus and withdrawn at the slack, and the share that flows on each branch, largest first (factors below 1e-4 are not listed).	ptdf
lodf	Line-outage distribution factors: how the flow of the outaged branch redistributes onto the others, largest first.	lodf
dcpf	DC power flow: bus angles and branch flows from the linearised network, through the same DC model the PTDF, LODF and DC-OPF use (DistributionFactors; Core DcPowerFlow).	dcpf
dcopf	DC optimal power flow: the cheapest dispatch that meets demand, with line limits enforced unless --no-limits.	dcopf
acopf	DC dispatch with an AC loss loop (AcOptimalPowerFlow): NOT a full AC optimal power flow.	acopf
acopf-full	The full AC optimal power flow (AcOpfInteriorPoint): a primal-dual interior point method, MATPOWER's MIPS with its defaults, starting point and stopping conditions.	acopf-full
scuc	Security-constrained unit commitment (UnitCommitment): which units run in each period, and at what output, at least total cost.	scuc
scopf	Preventive security-constrained DC optimal power flow (DcScopf): the cheapest dispatch that keeps every rated branch within RATE_A in the intact network and within its post-outage rating after each secured single-branch outage, with...	scopf
qsts	Quasi-static time series (QstsEngine): a sequence of power flows, one per step, over the load, generation, PV and storage profiles of a study file, warm-started from the previous step, with the controllers acting in time and their...	qsts
hosting	Hosting capacity (HostingCapacity): the largest PV (or, with --resource load, added demand such as electric vehicle charging or heat pumps) at each candidate bus before a limit is broken, found by bisection on the size in MW.	hosting
cpf	Maximum loadability by stepping and bisection (ContinuationPowerFlow.MaxLoadability).	cpf
taps	Coordinated tap schedule (TapOptimizer.Flatten): one set of tap ratios across every OLTC that minimises the sum of squared bus-voltage deviations from --target, rounded to each OLTC's step grid.	taps
restore	Restoration (black-start) sequence check (RestorationSequencer.Evaluate).	restore
losses	Loss allocation on the solved base case, under a header naming the case (Loss allocation - <case> (N buses, M branches)): total P and Q losses, the real power drawn by bus shunt conductances (Bus shunt conductance, only when the...	losses
dist3ph	EXPERIMENTAL. The unbalanced three-phase distribution stack (GridSim.Core.Distribution) on a radial feeder read from a gridsim-dist3ph/1 JSON file, or (N339, October 2026) its JSON v2 form gridsim-dist3ph/2 (format in technical...	dist3ph
physics-check	Audit one solved state against the physical laws (energy balance, Ohm, Joule, KCL, complex power, and the rest of the registry) and print one row per law.	physics-check
conformance	Run the physics-law audit over the whole case registry (embedded classics plus every .m under data/matpower/) and write conformance.md, conformance.csv and run-metadata.json.	conformance
protection-check	Passive protection assessment of the solved state with generic relay settings: which elements would operate, with pickup, time and basis.	protection-check
grade	Inverse-time overcurrent grading (OvercurrentCoordination.GradeChain): a radial chain of relays, listed downstream first, graded pair by pair (primary then its backup) at each fault current.	grade
fault	Balanced three-phase fault at --bus through fault reactance --zf (pu, Zf = j--zf, printed Zf=j...; D-DOC-166: dist3ph fault --zf is a resistance instead): fault current (pu, and kA when the bus has a base kV), Thevenin...	fault
iec60909	IEC 60909 short-circuit duty at --bus (Iec60909): initial symmetrical current Ik'', peak ip with its factor kappa and the fault-loop R/X, breaking Ib, steady Ik, thermal-equivalent Ith over --tk with its factor m, the DC component...	iec60909
experimental	Opt-in experimental models, tagged unvalidated-at-scale and kept off the validated solve and estimate paths.	experimental
freq	NESO 1-second frequency statistics plus a GB limit-breach scan (RoCoF 0.125 Hz/s, operational 49.8 Hz, statutory 49.5 Hz, LFDD 48.8 Hz) and a 20 ms upsample demo.	freq
replay	Play a recorded frequency trace in the terminal (gauge and RoCoF), upsampled to 20 ms.	replay
transient	Headless demanding time-domain run: a simulated duration at a fine slice, integrating swing-equation frequency each slice.	transient
domains	Report the speed domains of the distributed-inertia model: per-domain machine count, GVA.s and GVAd stiffness, and whether a dominant domain exists (deltaGVA at least 10 %).	domains
stability	Classical multi-machine transient stability (constant E' behind X'd, Kron-reduced network, RK4 swing).	stability
modal	Small-signal (modal) stability of the linearised multi-machine swing: eigenvalues, frequency and damping ratio of every mode, the least-damped oscillatory mode, right-half-plane count, the dominant participating states per mode and an...	modal
fit-frequency	Fit the lumped swing model's nadir and recovery constants to one measured loss-of-infeed trace (R079, October 2026): load self-damping (DampingPctPerHz, % of demand per Hz), the responsive headroom fraction and the governor time...	fit-frequency
inertia-placement	The inertia placement study: with a network's synchronous inertia in better places, can it run on less of it?	inertia-placement
harmonics	Frequency-domain harmonic study on the study model (network, machine source impedance, loads as damping shunts): penetration (Y(h) V = I), the driving-point resonance scan, a fine frequency sweep for the true peak between integer...	harmonics
impedance-stability	Impedance-based (generalised Nyquist) inverter-grid stability screen: forms the loop gain of the grid impedance and the converter admittance over frequency (SISO: the positive- and negative-sequence loops in the converter's dq frame,...	impedance-stability
emt	Electromagnetic-transient time-domain solve: a Dommel nodal companion-model engine steps the instantaneous network at a fixed microsecond timestep.	emt
replay-event	The credibility gate: reproduce a recorded event's RoCoF and nadir with no device.	replay-event
scenario	The counterfactual sweep (inertia x device x corners) plus the inertia risk curve.	scenario
h0-study	The H=0 counterfactual: scale the real synchronous inertia toward zero while making a growing fraction of the converter fleet grid-forming, per asset (fleet-routed).	h0-study
fleet	Single-versus-fleet emergent behaviour: the same total device budget split across N staggered units.	fleet
evidence	The umbrella dossier (gridsim-evidence/1): recorded versus simulated versus counterfactual columns, risk curve, fleet comparison and avoided cost.	evidence
gda	Read the read-only GDA data lake and materialise a GridSim replica (data stays out of the repo).	gda
gda-replay	The historical state estimator: replay a demand time series through the validated solver, reconstructing grid state at each past timestamp (horizon-guarded, never nowcasting).	gda-replay
synth	Build the synthetic GB-at-scale case (no data held under a licence), solve it, and materialise it as a JSON case directory.	synth
export	Write a visualisation scene (buses, branches, animation frames) for external renderers.	export
convert	Convert a case between MATPOWER, PSS/E RAW, CGMES, a JSON case folder (v1) and a JSON v2 case.	convert
validate	Check GridSim JSON v2 documents with the Phase 1 validator, choosing the check by each document's "schema" tag: gridsim-case/2 against case.schema.json (and, when the manifest is valid, each network file it lists, read relative to...	validate
zonal	Show a PyPSA-GB zonal transport model: the bundled pypsa-gb-zonal (PyPSA-GB @ 8e084af, MIT, 20 zones and 37 links, under data/matpower/gb/pypsa-gb/zonal) or a folder holding the same two files, buses.csv (name,y,x,v_nom,carrier:...	zonal
pmu-ingest	EXPERIMENTAL. Decode a recorded IEEE C37.118.2 synchrophasor stream: the frames as sent, back to back, a CONFIG-1 or CONFIG-2 frame followed by DATA frames (technical ch. 33).	pmu-ingest
pmu-estimate	The linear PMU state estimate (1.95.245).	pmu-estimate
estimate	The measurement-based WLS state estimator.	estimate
estimate-noise-floor	The measurement noise-floor study.	estimate-noise-floor
crossval	An existing solve-export.json is diffed as it is: one written by another verb at the everyday 1e-8 pu carries that solve's own residual and will not agree to machine epsilon for that reason alone (the sidecar says so when its final...	crossval
serve	Run the real-time estimator as a resident stream over a directory of gridsim-measurements/1 files, taken in file-name order.	serve
interpose	The RTU/SCADA interposer: receive live protocol frames, validate and correct each frame, decode it to typed points, map the points through the crosswalk, and emit gridsim-measurements/1 windows.	interpose
bench	The solver x backend matrix over the whole case archive (embedded classics plus every .m under data/matpower/).	bench
bench --estimate	Times the WLS estimator per case per step backend (dense versus sparse, forced through the sparse threshold) on a fixed-seed synthetic set; sampling and the truth solve sit outside the timed region.	bench --estimate
bench --perf	The focused before/after yardstick for the performance programme: single-threaded, warmed once, median of N runs, with managed allocations per run on the measuring thread.	bench --perf
gpucheck	Fail-fast GPU preflight: reports CPU, ROCm, OpenCL and CUDA availability and runs one tiny case9 solve (dense and sparse) on each present backend, flushing every step so a crash names the failing call.	gpucheck
simdcheck	Report the CPU's vector capabilities and the active tier (Avx512, Avx256, Sse128 or Scalar, with the number of doubles per vector step) that the dense-LU, normal-equations and covariance kernels dispatch to at run time.	simdcheck
batchsolve	Solve N same-sized MxM dense systems in one batched dispatch on the selected backend (the GPU batched Gaussian-elimination kernel on a CUDA or OpenCL device, else a parallel CPU loop over the reference LU; ROCm uses the CPU loop),...	batchsolve
audit	Verify a tamper-evident audit log (gridsim-audit/1, technical ch. 31): recompute the hash chain line by line.	audit
compliance	Print this build's compliance attestation and exit 0 when the build is compliant, 1 when it is not.	compliance
ref	Electrical references: a number written as electrical words that can be read aloud and typed back, one word per byte from a fixed list of 256 (units, pioneers, materials, physics, signals and more; no switching, safety, phase, colour,...	ref