The Sphinx documentation describes the Python API.
The Doxygen documentation is automatically generated from the C++ code using Doxygen. It is helpful to understand the general structure of the C++ DPsim core components.
This is the multi-page printable view of this section. Click here to print.
Reference
Generated API documentation and lookup tables.
1 - Model Availability
Which simulation domain implements which model.
Which model exists in which domain. A tick means the domain has an implementation, a dash means it does not.
The table below is generated from the headers under dpsim-models/include/dpsim-models by
scripts/docs/generate_model_availability.py. Do not edit it by hand; run the script with --write
instead. A model class the script does not recognise makes it fail rather than silently drop the
model, so the table cannot fall behind the code. For the equations behind a model, see
models.
Passive elements and sources
| Model | SP::Ph1 | SP::Ph3 | DP::Ph1 | DP::Ph3 | EMT::Ph1 | EMT::Ph3 |
|---|---|---|---|---|---|---|
| Resistor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Inductor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Capacitor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| VoltageSource | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| CurrentSource | – | – | ✓ | ✓ | ✓ | ✓ |
| VoltageSourceNorton | – | – | ✓ | – | ✓ | ✓ |
| VoltageSourceRamp | – | – | ✓ | – | ✓ | – |
| ProfileVoltageSource | – | – | ✓ | – | – | – |
| ControlledVoltageSource | ✓ | – | ✓ | – | – | ✓ |
| ControlledCurrentSource | ✓ | – | ✓ | – | – | ✓ |
| NetworkInjection | ✓ | – | ✓ | ✓ | – | ✓ |
Branches
| Model | SP::Ph1 | SP::Ph3 | DP::Ph1 | DP::Ph3 | EMT::Ph1 | EMT::Ph3 |
|---|---|---|---|---|---|---|
| PiLine | ✓ | – | ✓ | ✓ | ✓ | ✓ |
| RxLine | – | ✓ | ✓ | – | – | ✓ |
| RXLine | ✓ | – | – | – | – | – |
| SeriesResistor | – | – | – | ✓ | – | ✓ |
| ResIndSeries | – | – | ✓ | – | – | – |
| Transformer | ✓ | – | ✓ | – | – | ✓ |
| SolidStateTransformer | ✓ | – | – | – | – | – |
Switches and loads
| Model | SP::Ph1 | SP::Ph3 | DP::Ph1 | DP::Ph3 | EMT::Ph1 | EMT::Ph3 |
|---|---|---|---|---|---|---|
| Switch | ✓ | – | ✓ | ✓ | ✓ | ✓ |
| SeriesSwitch | – | – | – | ✓ | – | ✓ |
| varResSwitch | ✓ | – | ✓ | – | – | – |
| RXLoad | – | – | ✓ | – | – | ✓ |
| RXLoadSwitch | – | – | ✓ | – | – | – |
| PQLoadCS | – | – | ✓ | – | – | – |
| Load | ✓ | – | – | – | – | – |
| Shunt | ✓ | – | ✓ | – | – | ✓ |
| SVC | – | – | ✓ | – | – | – |
Synchronous generators
| Model | SP::Ph1 | SP::Ph3 | DP::Ph1 | DP::Ph3 | EMT::Ph1 | EMT::Ph3 |
|---|---|---|---|---|---|---|
| SynchronGenerator | ✓ | – | – | – | – | – |
| SynchronGeneratorDQ | – | – | – | ✓ | – | ✓ |
| SynchronGeneratorDQODE | – | – | – | ✓ | – | ✓ |
| SynchronGeneratorDQTrapez | – | – | – | ✓ | – | ✓ |
| SynchronGeneratorVBR | – | – | – | – | – | ✓ |
| SynchronGenerator3OrderVBR | ✓ | – | ✓ | – | – | ✓ |
| SynchronGenerator4OrderVBR | ✓ | – | ✓ | – | – | ✓ |
| SynchronGenerator5OrderVBR | ✓ | – | ✓ | – | – | ✓ |
| SynchronGenerator6aOrderVBR | ✓ | – | ✓ | – | – | ✓ |
| SynchronGenerator6bOrderVBR | ✓ | – | ✓ | – | – | ✓ |
| SynchronGenerator4OrderPCM | – | – | ✓ | – | – | ✓ |
| SynchronGenerator6OrderPCM | – | – | ✓ | – | – | – |
| SynchronGenerator4OrderTPM | – | – | ✓ | – | – | – |
| SynchronGeneratorIdeal | – | – | ✓ | – | – | ✓ |
| SynchronGeneratorIter | – | – | ✓ | – | – | – |
| SynchronGeneratorTrStab | ✓ | – | ✓ | – | – | ✓ |
Power electronics
| Model | SP::Ph1 | SP::Ph3 | DP::Ph1 | DP::Ph3 | EMT::Ph1 | EMT::Ph3 |
|---|---|---|---|---|---|---|
| AvVoltageSourceInverterDQ | ✓ | – | ✓ | – | – | ✓ |
| AvVoltSourceInverterStateSpace | – | – | ✓ | ✓ | – | ✓ |
| Inverter | – | – | ✓ | – | – | – |
| VoltageSourceInverter | ✓ | – | – | – | – | – |
| VSIVoltageControlVCO | – | – | – | – | – | ✓ |
| SSN_GFM | – | – | – | – | – | ✓ |
State-space nodal components
| Model | SP::Ph1 | SP::Ph3 | DP::Ph1 | DP::Ph3 | EMT::Ph1 | EMT::Ph3 |
|---|---|---|---|---|---|---|
| SSN_Full_Serial_RLC | – | – | ✓ | ✓ | ✓ | ✓ |
| SSN_Variable_Serial_RLC | – | – | ✓ | – | – | – |
| SSN_Capacitor | – | – | – | – | – | ✓ |
| SSN_Inductor | – | – | – | – | – | ✓ |
| SSNTypeV2T | ✓ | – | – | – | ✓ | – |
| SSNTypeI2T | ✓ | – | – | – | ✓ | – |
| PiecewiseLinearInductor | – | – | – | – | – | ✓ |
| GenericTwoTerminalVTypeSSN | – | – | ✓ | ✓ | – | ✓ |
| GenericTwoTerminalITypeSSN | – | – | ✓ | ✓ | – | ✓ |
| GenericFourTerminalVTypeSSN | – | – | – | – | – | ✓ |
Excitation and stabilizers
ExciterDC1ExciterDC1SimpExciterST1SimpExciterStaticPSS1A
Turbines and governors
SteamTurbineSteamTurbineGovernorHydroTurbineHydroTurbineGovernorTurbineGovernorTurbineGovernorType1
Converter control
PowerControllerVSIVoltageControllerVSIPLLVCO
Signal sources and filters
SignalGeneratorSineWaveGeneratorCosineFMGeneratorDCGeneratorFrequencyRampGeneratorFIRFilterIntegrator
Decoupling components
These are network components: they connect to nodes and own their own sources. They are declared in the Signal namespace for historical reasons, which is why their domain appears in the class name rather than in the namespace.
| Model | SP::Ph1 | SP::Ph3 | DP::Ph1 | DP::Ph3 | EMT::Ph1 | EMT::Ph3 |
|---|---|---|---|---|---|---|
| DecouplingLine | – | – | ✓ | – | – | – |
| DecouplingLineEMT | – | – | – | – | ✓ | – |
| DecouplingLineEMT_Ph3 | – | – | – | – | – | ✓ |
| DecouplingIdealTransformer_SP_Ph1 | ✓ | – | – | – | – | – |
| DecouplingIdealTransformer_DP_Ph1 | – | – | ✓ | – | – | – |
| DecouplingIdealTransformer_EMT_Ph1 | – | – | – | – | ✓ | – |
| DecouplingIdealTransformer_EMT_Ph3 | – | – | – | – | – | ✓ |
2 - Signal Models
Controllers, regulators, generators and decoupling elements in the Signal namespace.
Signal models live in CPS::Signal and are domain independent: the same controller drives a
dynamic phasor or an electromagnetic transient machine model, because it operates on scalar
signals rather than on network quantities. The exception is the decoupling group, which exists
per domain since it inserts real components into the network.
Excitation systems
Regulate generator terminal voltage by acting on field voltage. Equations and block diagrams are on the regulators page.
| Model | Description |
|---|---|
ExciterDC1 | Standard IEEE type DC1 exciter |
ExciterDC1Simp | Simplified version of the IEEE type DC1 exciter |
ExciterST1Simp | Simplified static exciter |
ExciterStatic | Static exciter, with an anti-windup strategy for the integral component |
Power system stabiliser
| Model | Description |
|---|---|
PSS1A | Simplified IEEE PSS1A. Enhances damping of electromechanical oscillations, accepting rotor speed, active power and terminal voltage magnitude as optional inputs. Its output feeds the exciter |
Turbines and governors
Governors set mechanical power from speed deviation; turbine models convert that into the torque applied to the machine.
| Model | Description |
|---|---|
SteamTurbine | Steam turbine, used in series with its governor |
SteamTurbineGovernor | Governor for the steam turbine, instantiated separately from it |
HydroTurbine | Hydro turbine, used in series with its governor |
HydroTurbineGovernor | Governor for the hydro turbine, instantiated separately from it |
TurbineGovernorType1 | Turbine and governor combined in one component |
TurbineGovernor | Turbine and governor combined in one component |
Converter control
Control loops for the averaged inverter models. See power electronics for how these attach to the converter.
| Model | Description |
|---|---|
PowerControllerVSI | Power control loop used by the averaged grid-following inverter models |
VoltageControllerVSI | Voltage control loop used by the grid-forming inverter models |
PLL | Phase-locked loop |
VCO | Voltage-controlled oscillator |
Signal generators
Drive sources and setpoints from a prescribed waveform rather than a constant.
| Model | Description |
|---|---|
SignalGenerator | Base class for the generators below |
SineWaveGenerator | Sine wave |
CosineFMGenerator | Frequency-modulated cosine |
FrequencyRampGenerator | Frequency ramp |
DCGenerator | Constant value |
Filters and maths
| Model | Description |
|---|---|
FIRFilter | Finite impulse response filter |
Integrator | Integrator block used inside the control models |
Decoupling
Split a network into parts that can be solved separately, either across solvers or across simulators in a co-simulation. See co-simulation.
| Model | Domains |
|---|---|
DecouplingLine | DP::Ph1 |
DecouplingLineEMT | EMT::Ph1 |
DecouplingLineEMT_Ph3 | EMT::Ph3 |
DecouplingIdealTransformer | DP::Ph1, EMT::Ph1, EMT::Ph3, SP::Ph1 |
References
- IEEE Std 421.5-2016, “IEEE Recommended Practice for Excitation System Models for Power System Stability Studies”. https://doi.org/10.1109/IEEESTD.2016.7553421
- F. Milano, Power System Modelling and Scripting. London: Springer-Verlag, 2010. https://doi.org/10.1007/978-3-642-13669-6
- M. Eremia and M. Shahidehpour, Handbook of Electrical Power System Dynamics: Modeling, Stability, and Control. https://ieeexplore.ieee.org/book/6480471
3 - State-Space Extraction Support
Components that contribute states to the extracted state-space model.
For how extraction works and how to enable it, see state-space extraction.
State-space extraction is available for EMT Ph3 and DP Ph1 simulations using the direct MNA solver. For models containing switches, the extracted matrix represents the currently active switch configuration. The matrix is recomputed when the switch status changes.
EMT Ph3
Supported components with extraction states are:
EMT::Ph3::Inductor,EMT::Ph3::Capacitor,EMT::Ph3::TwoTerminalVTypeSSNComp,EMT::Ph3::TwoTerminalVTypeVariableSSNComp.
Supported algebraic components without extraction states are:
EMT::Ph3::Resistor,EMT::Ph3::Switch,EMT::Ph3::VoltageSource.
The following composite components are supported through their immediate MNA subcomponents:
EMT::Ph3::NetworkInjection,EMT::Ph3::PiLine,EMT::Ph3::RXLoad,EMT::Ph3::RxLine,EMT::Ph3::Shunt,EMT::Ph3::Transformer.
DP Ph1
Supported components with extraction states are:
DP::Ph1::Inductor,DP::Ph1::Capacitor,DP::Ph1::TwoTerminalVTypeSSNComp,DP::Ph1::MixedVTypeVariableSSNComp.
Supported algebraic components without extraction states are:
DP::Ph1::Resistor,DP::Ph1::Switch,DP::Ph1::VoltageSource.
The following composite components are supported through their immediate MNA subcomponents:
DP::Ph1::NetworkInjection,DP::Ph1::PiLine,DP::Ph1::RXLoad,DP::Ph1::RxLine,DP::Ph1::Shunt,DP::Ph1::Transformer.
Supported composite components are expanded by one level during contributor discovery. Their immediate MNA subcomponents provide the state-space contributions, while the composite parent remains part of the simulation and retains its normal MNA stamping. Nested composites are currently unsupported.
Other component types are rejected explicitly when state-space extraction is enabled.