From f7b2d0605ea5c8c2c617c4dd52eea2a9268dc6ac Mon Sep 17 00:00:00 2001 From: Leonardo Carreras Date: Tue, 7 Jul 2026 01:42:11 +0200 Subject: [PATCH 1/2] docs: expand scaling-conventions section with macros and power-formula info Signed-off-by: Leonardo Carreras --- docs/hugo/content/en/docs/Concepts/state-space-nodal.md | 7 +++++-- docs/hugo/content/en/docs/Development/guidelines.md | 4 ++++ 2 files changed, 9 insertions(+), 2 deletions(-) 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..6d7f27e4b6 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` apply neither, since the DP envelope already carries the complex amplitude directly. 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. From 500abc27a02e094624b78366cb4cf7af7f3d7f5f Mon Sep 17 00:00:00 2001 From: Leonardo Carreras Date: Tue, 7 Jul 2026 01:50:42 +0200 Subject: [PATCH 2/2] docs: mention SP::Ph1::VoltageSource in the scaling-conventions boundary note Signed-off-by: Leonardo Carreras --- docs/hugo/content/en/docs/Development/guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hugo/content/en/docs/Development/guidelines.md b/docs/hugo/content/en/docs/Development/guidelines.md index 6d7f27e4b6..22bc05938f 100644 --- a/docs/hugo/content/en/docs/Development/guidelines.md +++ b/docs/hugo/content/en/docs/Development/guidelines.md @@ -18,7 +18,7 @@ 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` apply neither, since the DP envelope already carries the complex amplitude directly. 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. +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.