Running a harmonic study

This chapter covers the harmonics verb: point it at a case and a set of harmonic-source spectra, and it solves the network's response order by order - penetration, an impedance/resonance scan, the distortion indices, and a pass/fail against IEEE 519 and G5/5 - then prints a summary and, on request, writes a full export. Where the fundamental power flow asks "what is the 50 Hz operating point", this asks "what do the non-sinusoidal currents on this network do to its voltages". The math and design are in ../technical/19-harmonics.md; this is the task guide.

The harmonics verb

dotnet run --project src/GridSim.Cli harmonics <case> [--spectra <file.json> | --synth-sources] [--enableExport[=path]]

<case> is any case the rest of the CLI accepts - a built-in name, a .m path, --mpc <file>.m, or --dir <folder> (see 02-loading-networks.md). The verb loads the case, obtains a source set, runs the study, and exits.

You must tell it where the harmonic sources come from - this is the one input the network model cannot supply (see the input contract below):

A run with --synth-sources is a defensible engineering screen, not a measurement; every number it produces is stamped [VERIFY]. A run with --spectra pointed at metered data is grounded exactly to the extent its spectra are. You can mix them in one file - measured spectra where you have meters, placeholders elsewhere - and upgrade bus by bus as data arrives.

What one run does

1. Builds the frequency-dependent admittance Y(h) for each order in the source set (the fundamental YBus continued by the physics of frequency).
2. Runs linear penetration - solves Y(h) V(h) = I(h) per order - for the harmonic voltage at every bus.
3. Runs the impedance/frequency scan at the buses of interest and identifies the parallel resonances (order, magnitude, sharpness).
4. Computes the indices (THD and K-factor per bus, resonance damping-sharpness) and checks compliance against IEEE 519 and G5/5.
5. Prints a summary; with --enableExport, writes the full gridsim-harmonic-export/1 document.

Reading the summary

The console summary names, top to bottom: the case and source set (with the provenance mix - how many buses are Recorded vs CuratedPlaceholder); the orders solved; the worst-THD buses and their values, flagged against the IEEE 519 / G5/5 limit; the resonances the scan found, each as an order, peak |Z(h)| and sharpness, with the sharp near-characteristic-order peaks highlighted; the K-factor at the transformer buses; and a closing compliance verdict. A [VERIFY]-tagged run says so on every headline number.

The input contract: gridsim-harmonics/1

A source set is a versioned JSON document, schema string gridsim-harmonics/1, loaded by HarmonicSourceSet.Load. Each entry is the harmonic-current spectrum injected at one bus - the per-order magnitude and phase of the current that bus's connected equipment emits - carried with a ProvenanceTag (Recorded for metered, CuratedPlaceholder + a [VERIFY] note for assumed-typical, DerivedFromRecorded for a measured spectrum transformed to the operating point). The tag travels with the spectrum end to end and is echoed in every output, so an assumed run and a measured run are the same shape and a single bus upgrades in place.

The authoritative schema lives in GDA, at D:\Work\GDA\v1\NetworkModel\HarmonicDataSchema.json - source spectra per bus, provenance-tagged, with dated inputs. Any dated spectrum is guarded by the same 169-hour ForwardInferenceGuard the rest of the estate enforces: a source set stamped with a timestamp inside the forward-inference horizon is rejected on load, so a harmonic study cannot smuggle future data into the pipeline any more than a measurement set or event catalogue can (see ../technical/08-provenance-and-invariants.md). GDA's PQ-meter feed writes this document; a third party's power-quality meter data feeds it the same way, through the same schema and the same guard.

The output: gridsim-harmonic-export/1

--enableExport[=path] writes one gridsim-harmonic-export/1 JSON document (default exports/<case>-harmonics.json under the current directory, or the path you give). Like the solve and estimate exports it is the whole study in one auditable file, with these blocks:

The document is the input contract for downstream tooling and the file the desktop app's HARMONICS tab reads: it renders the impedance scan (the |Z(h)| curve with its resonant peaks), the per-bus THD bars against the limit line, the source spectra, and the compliance verdict, with the provenance of every source visible so a [VERIFY] placeholder is never mistaken for a measurement.

Worked example

# Quick screen from the device library - everything [VERIFY]
dotnet run --project src/GridSim.Cli harmonics case118 --synth-sources

# Grounded study from metered spectra, full export
dotnet run --project src/GridSim.Cli harmonics gb-full --spectra data/harmonics/gb-full-pq.json --enableExport

The first is the "what could resonate here" screen you run before you have any meters; the second is the grounded study once GDA's (or a third party's) PQ feed has produced a gridsim-harmonics/1 file. Both write the same export shape and drive the same dashboard tab; the only difference is how much of the provenance mix is Recorded.

Future extension: supraharmonics

The verb covers the classical harmonic range (integer orders up to the low tens). The supraharmonic band (2-150 kHz) - the switching-frequency emissions of modern converters - is a documented future extension; the input schema, export shape and dashboard tab are built to carry it without a new verb (see ../technical/19-harmonics.md).

See also

• ../technical/19-harmonics.md - the math and design: Y(h), the complex-solver seam, penetration, indices, coupled power flow and harmonic state estimation.
• 03-running-power-flows.md - the fundamental solve, --enableExport, and the backend switches.
• 02-loading-networks.md - case selection in full.
• 13-the-gda-bridge.md - how GDA products (including the PQ-meter feed) reach GridSim.
• 15-exports-and-formats.md - the export/run-directory conventions this study follows.
• 19-cli-reference.md - every verb and flag in one table.