diff --git a/docs/hugo/content/en/docs/Concepts/state-space-nodal.md b/docs/hugo/content/en/docs/Concepts/state-space-nodal.md index d59b5ea4fe..121c9be5a2 100644 --- a/docs/hugo/content/en/docs/Concepts/state-space-nodal.md +++ b/docs/hugo/content/en/docs/Concepts/state-space-nodal.md @@ -101,8 +101,11 @@ dynamic-phasor stamping exactly, and the reconstructed time-domain waveform matches the EMT and EMT-SSN results within discretisation error once corrected for the RMS-to-peak scaling that `EMT::Ph3` sources apply and `DP::Ph3` sources do not, since the DP envelope already carries the complex -amplitude directly. The notebooks below only exercise the symmetrical, -diagonal case; coupling between phases is not covered by existing tests. +amplitude directly (see the +[scaling conventions]({{< ref "../Development/guidelines.md" >}}) for the +exact factors and where they apply). The notebooks below only exercise the +symmetrical, diagonal case; coupling between phases is not covered by +existing tests. # Variable Components diff --git a/docs/hugo/content/en/docs/Development/guidelines.md b/docs/hugo/content/en/docs/Development/guidelines.md index 5cd74875a6..22bc05938f 100644 --- a/docs/hugo/content/en/docs/Development/guidelines.md +++ b/docs/hugo/content/en/docs/Development/guidelines.md @@ -18,6 +18,10 @@ Current quantities are expressed either as `RMS` or as `PEAK` values: - Simulation quantities in both `SP` and `DP` domain (e.g. `mIntfCurrent` of `DP::Ph1::PiLine`) as `RMS` values - Simulation quantities in the `EMT` domain (e.g. `mIntfCurrent` of `EMT::Ph3::Transformer`) as `PEAK` values +The conversion factors are defined in `dpsim-models/include/dpsim-models/Definitions.h`: `RMS3PH_TO_PEAK1PH` (`sqrt(2/3)`) for voltages and `RMS_TO_PEAK` (`sqrt(2)`) for currents, with inverses `PEAK1PH_TO_RMS3PH` and `PEAK_TO_RMS` for the return trip. `EMT::Ph3::VoltageSource::updateVoltage` and `EMT::Ph3::CurrentSource::updateCurrent` apply these at the reference-to-interface-quantity boundary; `DP::Ph3::VoltageSource`/`CurrentSource` and `SP::Ph1::VoltageSource` apply neither, since DP and SP already carry the complex phasor amplitude directly (SP has no `CurrentSource`). The same boundary applies wherever a component reads a power-flow-solved node voltage, for example the SSN `buildInitialInputFromNodes()`: the `EMT::Ph3` variant scales by `RMS3PH_TO_PEAK1PH`, the `DP::Ph1`/`DP::Ph3` variant does not. + +This scaling is independent of a second, easily conflated convention: how a component computes power from its own native `V`, `I`. `DP::Ph1`/`SP::Ph1` treat their native `RMS3PH`/`RMS` values as already representing the full three-phase quantity, so total power is plain `P + jQ = V * conj(I)` (e.g. `DP::Ph1::AvVoltageSourceInverterDQ`, or `SP::Ph1::Load`'s `R = V_nom^2 / P`). `EMT::Ph3` works with per-phase peak quantities, so total three-phase power needs an explicit `1.5` factor (e.g. `EMT::Ph3::AvVoltSourceInverterStateSpace`). When porting a component between domains, do not copy an EMT power-formula constant into a DP/SP component or vice versa; each domain's native scale already determines whether that factor is needed. + # Logging Debug or trace should be the default log level for information that might be nice to have but not necessary for every simulation case.