DPsim – Documentation

Docs: Your First Simulation

Fri, 31 Jul 2026 00:00:00 +0000

This page goes from nothing to a plotted result. It assumes DPsim is installed and importable; if it is not, start with install or build.

The circuit is deliberately trivial, a voltage source feeding a resistor, so that nothing in it distracts from the shape of the script. Every real simulation has the same five parts in the same order.

The whole script

import dpsimpy
import villas.dataprocessing.readtools as rt
from villas.dataprocessing.timeseries import TimeSeries as ts

name = "first_simulation"

# 1. Nodes
gnd = dpsimpy.dp.SimNode.gnd
n1 = dpsimpy.dp.SimNode("n1")

# 2. Components
src = dpsimpy.dp.ph1.VoltageSource("src")
src.V_ref = complex(100, 0)

load = dpsimpy.dp.ph1.Resistor("load")
load.R = 10.0

# 3. Connections
src.connect([gnd, n1])
load.connect([n1, gnd])

# 4. Topology
system = dpsimpy.SystemTopology(50, [gnd, n1], [src, load])

# 5. Logging, then run
logger = dpsimpy.Logger(name)
logger.log_attribute("n1.v", "v", n1)
logger.log_attribute("load.i_intf", "i_intf", load)

sim = dpsimpy.Simulation(name)
sim.set_domain(dpsimpy.Domain.DP)
sim.set_system(system)
sim.set_time_step(1e-3)
sim.set_final_time(0.1)
sim.add_logger(logger)
sim.run()

Running it prints solver progress and writes logs/first_simulation.csv.

What each part is doing

Nodes come first because components connect to them, not to each other. SimNode.gnd is the reference node and is shared; every network needs it. Nodes are chosen from a domain namespace, dpsimpy.dp here, and a node from one domain cannot be connected to a component from another.

Components are created, then configured through their attributes. src.V_ref = complex(100, 0) sets the source reference as a complex phasor, because this is the dynamic phasor domain and a voltage is an envelope rather than an instantaneous value. In EMT the same field would carry a different meaning; see dynamic phasors.

Watch out: connection order sets the sign

Connection order defines polarity. src.connect([gnd, n1]) means terminal 0 at ground and terminal 1 at n1, so a positive current flows from terminal 0 to terminal 1 inside the component. Reversing the list reverses the sign of everything that component reports. Nothing checks this for you, and a sign error here produces a simulation that runs and is wrong.

Watch out: a component left out of the topology is ignored

The topology takes the system frequency first, then the nodes, then the components. Anything not in those two lists is not simulated, even if it was created and connected. This is the most common reason a component appears to have no effect.

Logging is opt-in, and takes three steps in order. Nothing is recorded unless a logger asks for it.

logger = dpsimpy.Logger(name) # 1. create it; the name becomes the file name
logger.log_attribute("n1.v", "v", n1) # 2. register each attribute you want
logger.log_attribute("load.i_intf", "i_intf", load)
sim.add_logger(logger) # 3. attach it to the simulation, before run()

log_attribute takes the column name you want, the name of the attribute on the object, and the object itself. "v" on a node is its voltage; "i_intf" on a component is the current through it. The first argument is yours to choose and is the key you will use when reading the file back; the second must be an attribute the object actually publishes, and print_attribute_list() on the object shows what that is.

Watch out: only attributes can be logged

A value a component computes internally but does not publish as an attribute cannot be recorded by any logger option. print_attribute_list() on an object shows what it publishes.

The order is what makes it work. A logger registers attributes before it is attached, and it must be attached before run(), because the column header is written from whatever is registered when the first row is written. A logger created but never passed to add_logger produces no file at all, which is the usual reason for a run that appears to have logged nothing.

Reading the results

results = rt.read_timeseries_dpsim("logs/" + name + ".csv")

print(sorted(results.keys()))
# ['load.i_intf', 'n1.v']

v = results["n1.v"]
print(v.time[1], abs(v.values[1]))
# 0.001 100.0

The keys are the column names given to log_attribute. Each value is a time series with time and values arrays; in a dynamic phasor simulation the values are complex, and abs() gives the envelope magnitude.

Note that the first sample is zero. The log is written before the first solve, so row zero is the state the simulation started from rather than a result. From t = 0.001 onwards this circuit sits at exactly 100 V and 10 A, which is what a 100 V source across 10 Ω should give.

Plotting

import villas.dataprocessing.plottools as pt

pt.plot_timeseries(1, results["n1.v"].abs())
pt.plot_timeseries(2, results["load.i_intf"].abs())

The first argument is a figure number, so repeated calls with the same number overlay curves on one axis. .abs() is needed for complex results; plotting a complex series directly is not meaningful.

Recovering the waveform from a dynamic phasor result

A dynamic phasor result is an envelope, not a waveform. To compare it against an instantaneous result, shift it back onto the carrier:

emt = ts.frequency_shift_list(results, 50)
print(sorted(emt.keys()))
# ['load.i_intf_shift', 'n1.v_shift']

Watch out: every key gains a _shift suffix

Every key gains a _shift suffix, which is easy to miss and produces a KeyError that reads as though the quantity were never logged. The result is a real waveform at the given carrier frequency, and can be plotted or compared against an EMT run directly.

The script

The complete script for this page is 01_first_simulation.py under examples/Python/Tutorials. The numbers quoted above are the numbers it prints, so if the two ever disagree the page is the one that is wrong.

This circuit has no dynamics at all: it is a source and a resistor, so it reaches its final value in one step and stays there. The next step is to add an element that stores energy, which is where the choice of time step starts to matter and where a result becomes worth plotting.

The examples work through larger networks, and the models used here are derived under sources and RLC elements.

Docs: Install

Fri, 31 Jul 2026 00:00:00 +0000

DPsim is a Python module and C++ library for dynamic power system simulation.

The quickest route to a result is the Python module: install it, then work through the tutorials, which build up one idea at a time from a source and a resistor. If you would rather read a finished study than build one, the example notebooks run complete scenarios and plot them.

Building from source is only needed for a platform without a published wheel, or to work on DPsim itself; see build.

Try it without installing

The example notebooks run in the browser with no local installation:

Python package

DPsim is published on PyPI and installs like any other Python package:

python3 -m venv venv
source venv/bin/activate
pip install dpsim

Requires Linux for the published wheels

Two limitations are worth knowing before you start. Only Linux wheels are currently published, for CPython 3.9 through 3.13, so on Windows and macOS you have to build from source for now. The package also contains only the simulation core; the example notebooks additionally need plotting and data handling packages, which are listed in the import section of each notebook.

If you prefer conda, the equivalent is:

conda create -n dpsim python=3.13
conda activate dpsim
pip install dpsim

Docker

You need Docker installed first. The prepared image on Docker Hub bundles the module together with a JupyterLab session:

docker run -p 8888:8888 sogno/dpsim

Then open http://localhost:8888/lab?token=3adaa57df44cea75e60c0169e1b2a98ae8f7de130481b5bc.

Note that the image pins that access token in its startup command, so it is the same for everyone who runs the image. Publish the port on localhost only, as above, and do not expose it to an untrusted network.

To build the image yourself rather than pulling it, see build.

Docs: The MNA Solver

Fri, 31 Jul 2026 00:00:00 +0000

MnaSolver<VarType> is the solver almost every simulation uses. The method it implements is derived under nodal analysis; what a component must provide to take part is under interfacing with the MNA solver. This page is the solver itself.

Note the spelling: the class is MnaSolver even though the file is MNASolver.h.

Setting up

initialize runs the sequence described under component and solver initialization: identify the topology objects, create sub-components, collect virtual nodes, assignMatrixNodeIndices, size the matrices, initialize the components, then assemble.

Which assembly function runs depends on the network:

initializeSystemWithPrecomputedMatrices when the switch combinations are few enough to enumerate. Every combination gets its own factorised matrix up front, so a switching event becomes a lookup rather than a refactorisation.
initializeSystemWithVariableMatrix when a component changes its own stamp continuously and enumeration is impossible.
initializeSystemWithParallelFrequencies for a harmonic study, where several frequencies are solved side by side.

resolveSystemMatrixRecomputationMode chooses between them when the mode is Auto; SystemMatrixRecomputationMode::Enabled and Disabled force it either way.

Stepping

solve does the same four things every step.

It zeroes the right-hand side and sums the stamps the components’ pre-step tasks produced, which is why a component that fails to declare its dependencies can find its contribution missing rather than wrong. It calls updateSwitchStatus, which produces an index into the precomputed matrices. It solves through the linear solver for that index. Then it hands the solution to the components' post-step tasks.

The switch index is the point of the precomputed strategy: with the factorisations already built, a switching event costs a different lookup rather than new numerical work. That is what makes a network with frequent switching affordable, and it is why the number of switches is bounded in practice, since the enumeration grows as two to the power of that number.

solveWithSystemMatrixRecomputation is the other path. It asks hasVariableComponentChanged each step and rebuilds and refactorises only when something reports a change, which is the expensive but general case used by variable components such as the SSN models.

Iterative components

After the solve, the solver checks whether any synchronous generator reports requiresIteration. If so it repeats the solve step until none does, which is how the predictor-corrector and two-stage machine models reach the implicit solution rather than its explicit approximation. Models that do not request iteration cost nothing here.

This loop is the reason a machine model can be iterative without the whole solver being iterative.

Linear backends

The solver does not implement its own factorisation; it selects an adapter through MnaSolverFactory. The choices and their tuning are described under alternative solvers, which also covers the ordering and partial-refactorisation options that matter most when the matrix changes every step.

Instrumentation

Solver::mLogSolveTimes records the wall-clock duration of each solve into mSolveTimes, which is the measurement to use when comparing backends or step sizes rather than timing the whole run.

Source

dpsim/src/MNASolver.cpp, dpsim/src/MNASolverDirect.cpp, and dpsim/include/dpsim/MNASolverFactory.h.

Docs: Reduced Order Machine Models

Fri, 31 Jul 2026 00:00:00 +0000

The full dq0 machine keeps every rotor winding as a state. Reduced order models keep the rotor flux linkages that matter on the timescale of interest and represent the rest algebraically, which removes the fastest states and lets the machine be stepped at the same rate as the network.

This page derives the equations. Nothing here depends on how they are arranged in software.

Per unit system and operational parameters

All quantities are in the reciprocal per unit system referred to the direct axis mutual inductance [Kundur1994]. With rated apparent power $S_n$ and rated line to line voltage $V_n$ as the stator base, the base peak phase voltage, base current and base impedance are

$$V_{base} = \frac{\sqrt{2}}{\sqrt{3}} V_n, \qquad I_{base} = \frac{S_n}{\frac{3}{2} V_{base}}, \qquad Z_{base} = \frac{V_n}{S_n / V_n}.$$

The machine is described by operational parameters rather than by winding data: the synchronous inductances $L_d$ and $L_q$, the transient inductances $L_d’$ and $L_q’$, the subtransient inductances $L_d’’$ and $L_q’’$, the corresponding open circuit time constants $T_{d0}’$, $T_{q0}’$, $T_{d0}’’$, $T_{q0}’’$, and the inertia constant $H$. A sixth parameter $T_{aa}$, the armature to field coupling time constant, distinguishes the two sixth order variants.

Which states each order retains

The state variables are the voltages behind the transient and subtransient reactances, $E_d’$, $E_q’$, $E_d’’$ and $E_q’’$, together with the two mechanical states. They are defined from the terminal quantities by

$$E_d' = V_d - L_q' I_q, \qquad E_q' = V_q + L_d' I_d,$$

and analogously for the subtransient pair with $L_d’’$ and $L_q’’$.

Order	Electrical states	Physical content
3	$E_q'$	Field winding only; the q axis rotor is neglected.
4	$E_d’$, $E_q'$	Field winding and one q axis damper.
5	$E_q’$, $E_d’’$, $E_q’'$	Adds both subtransient windings, no q axis transient state.
6a	$E_d’$, $E_q’$, $E_d’’$, $E_q’'$	Full transient and subtransient set, with $T_{aa} \neq 0$.
6b	$E_d’$, $E_q’$, $E_d’’$, $E_q’'$	Same states with $T_{aa} = 0$.

Every order carries the same two mechanical states, so the third order model has five states in total and the sixth order models have eight.

Voltage behind reactance form

Written directly, the stator equations couple the machine currents to the network currents, and the machine inductances appear in the axis frame while the network is solved in the phase frame. The voltage behind reactance form removes that coupling: the machine is expressed as an internal voltage in series with a reactance that is constant in the axis frame, so the only quantity that changes between steps is the internal voltage.

The internal voltage is not a free variable. Applying the trapezoidal rule to the rotor flux equations over one step $\Delta t$ gives it as a recursion in quantities already known at the start of the step. For the transient states,

$$E_{h,d} = A_d' \, I_q + B_d' \, E_d', \qquad E_{h,q} = A_q' \, I_d + B_q' \, E_q' + D_q' \left( E_{f}[k-1] + E_{f}[k] \right),$$

where $E_f$ is the field voltage supplied by the excitation system. The coefficients follow from the trapezoidal integration and depend only on the parameters and the step size:

$$A_d' = \frac{\Delta t \, Z_d'}{2 T_{q0}' + \Delta t}, \qquad B_d' = \frac{2 T_{q0}' - \Delta t}{2 T_{q0}' + \Delta t},$$

$$A_q' = \frac{-\Delta t \, Z_q'}{2 T_{d0}' + \Delta t}, \qquad B_q' = \frac{2 T_{d0}' - \Delta t}{2 T_{d0}' + \Delta t}, \qquad D_q' = \frac{\Delta t \left( 1 - T_f \right)}{2 T_{d0}' + \Delta t}.$$

The reactance differences are $Z_q’ = L_d - L_d’ - Y_d$ and $Z_d’ = L_q - L_q’ - Y_q$. For the orders without subtransient states $Y_d = Y_q = 0$ and $T_f = 0$. For the sixth order variant with armature coupling,

$$Y_d = \frac{T_{d0}''}{T_{d0}'} \frac{L_d''}{L_d'} \left( L_d - L_d' \right), \qquad Y_q = \frac{T_{q0}''}{T_{q0}'} \frac{L_q''}{L_q'} \left( L_q - L_q' \right), \qquad T_f = \frac{T_{aa}}{T_{d0}'}.$$

The subtransient states obey a recursion of the same shape with $T_{d0}’’$ and $T_{q0}’’$ in place of the transient time constants, and with the transient history entering as a forcing term.

Two properties of this form matter. The coefficients are computed once for a fixed step size, since they contain no state. And because $B_d’$ and $B_q’$ are the trapezoidal amplification factors $(2T - \Delta t)/(2T + \Delta t)$, they lie strictly inside the unit interval for any positive time constant, so the flux recursion is unconditionally stable regardless of step size.

Mechanical equations

The rotor obeys the swing equation in per unit,

$$2H \frac{d \omega_r}{dt} = T_m - T_e, \qquad \frac{d \theta}{dt} = \omega_{base} \, \omega_r,$$

with the electrical torque taken from the axis frame quantities as $T_e = V_d I_d + V_q I_q$. The load angle follows from the initial operating point as the phase of $V + j L_q I$, which is the standard construction of the q axis position from terminal conditions.

Solution schemes

The recursion above evaluates the internal voltage from quantities at the previous step, so the machine and the network are solved once per step in sequence. Two refinements exist for cases where that single pass is not accurate enough.

The predictor corrector method takes the single pass result as a prediction, re-evaluates the flux recursion using the corrected terminal quantities, and repeats until the change between successive passes falls below a tolerance. It converges to the solution of the implicit trapezoidal step rather than to its explicit approximation, at the cost of repeated network solutions.

The two stage predictor method splits the step differently: it advances the machine state on a predicted terminal voltage, then applies a single correction derived from the network solution, without iterating to convergence. It costs one extra network solve per step and removes most of the one step delay error.

Both are schemes for solving the same equations. They do not change the model order or the retained states.

Validity

The reduced order models assume the stator transients are fast enough to be neglected, so the stator is treated as algebraic. This is the assumption that makes the model valid for electromechanical studies and invalid where stator dynamics matter, such as during the first cycles of a close-in fault or for subsynchronous interaction. Neglecting the q axis rotor entirely, as the third order model does, additionally removes damping that is physically present, so a third order machine oscillates more than the same machine represented at fourth order.

References

[Kundur1994] P. Kundur, Power System Stability and Control. New York: McGraw-Hill, 1994. Source of the reciprocal per unit system and of the operational parameter definitions used throughout this page.

Docs: Architecture

Wed, 25 Mar 2020 00:00:00 +0000

Modules and Dependencies

The figure below shows the main components of the DPsim library and their dependencies on other software projects. All functionality is implemented in the C++ core, which can be used standalone or together with the Python interface. The Python interface is a thin wrapper of the C++ core. Jupyter notebooks can either use the DPsim Python interface to run simulations or call executables implemented in C++. The data analysis and plotting is always done in Python using common libraries like Matplotlib. To collect the simulation results from within Python, one can use the villas-dataprocessing Python package.

Another approach to get data in or out of DPsim is the VILLASnode interface, which does not depend on Python at all. The main purpose of the VILLASnode interface is to exchange data during the simulation runtime, for example, in real-time simulation experiments. The data could be send to other simulators, hardware or other software components like databases. Storing the data in databases can be another way of managing (also offline) simulation results if the Python CSV method is not desireable.

The CIM reader is based on the CIM++ library and provides a comfortable alternative to defining the grid manually in C++ or Python. In principle, it calls the same functions to create elements, which are also used in the C++ defined example scenarios, but automatically. DPsim also provides a way to visualize the defined networks before simulation.

The main solver of DPsim is currently the MNA solver because it enables a rather deterministic computation time per simulation time step, which is necessary for real-time simulation. Apart from that, it is also well established in offline circuit simulation. The only dependency of the MNA solver is the linear algebra library Eigen. For some component models, it is possible to use the Sundials ODE solver in combination with the MNA solver. In that case, the component is solved by the ODE solver whereas the network is still handled by the MNA solver. A DAE solver is currently under development. Its main purpose will be offline simulation, for example, to provide reference results where simulation runtime and real-time execution are not relevant.

The component models depend mostly on the Eigen library. Even if components are used in combination with Sundials ODE / DAE solvers, we try to keep the specific functions required by these solvers independent of the Sundials package.

Class Hierarchy

The Simulation class holds references to instances of Interface, Solver, Logger and SystemTopology. For a simulation scenario, the minimum description would include a SystemTopology and a solver type. The Solver instance is then created by the Simulation.

An important function of the Simulation is to collect all tasks, which have to be executed during the simulation. These tasks include computation steps of the individual power system component models as well as read and write tasks of the interfaces and logging variables etc. Before the scheduling is done, Simulation calls getTasks() to retrieve the tasks from three of these classes: Solver, Interface and Logger. The power system component and signal-model tasks are collected by the Solver instances and relayed to the Simulation, while interfaces and loggers contribute their own tasks directly.

All power system element classes inherit from the IdentifiedObject class. This class corresponds with the IdentifiedObject of the IEC61970 CIM and has a uid and name attribute as well.

The next layer of specialization includes information on the topological connection between network elements. An electrical bus and network nodes in general are represented by the TopologiclaNode class. The connection of electrical components, TopologicalPowerComp, is managed via terminals of type TopologicalTerminal. These three types describe the electrical connections of the network, which are bidirectional and include voltages and currents. The signal type elements, TopologicalSignalComp, can only have unidirectional components, which are not expressed using node and terminals. Instead, the attribute system is used to define signal type connections.

Docs: Nodal Analysis

Wed, 18 Mar 2020 00:00:00 +0000

A circuit with $b$ branches has $2b$ unknowns since there are $b$ voltages and $b$ currents. Hence, $2b$ linear independent equations are required to solve the circuit. If the circuit has $n$ nodes and $b$ branches, it has

Kirchoff’s current law (KCL) equations
Kirchoff’s voltage law (KVL) equations
Characteristic equations (Ohm’s Law)

There are only $n-1$ KCLs since the nth equation is a linear combination of the remaining $n-1$. At the same time, it can be demonstrated that if we can imagine a very high number of closed paths in the network, only $b-n+1$ are able to provide independent KVLs. Finally there are $b$ characteristic equations, describing the behavior of the branch, making a total of $2b$ linear independent equations.

The nodal analysis method reduces the number of equations that need to be solved simultaneously. $n-1$ voltage variables are defined and solved, writing $n-1$ KCL based equations. A circuit can be solved using Nodal Analysis as follows

Select a reference node (mathematical ground) and number the remaining $n-1$ nodes, that are the independent voltage variables
Represent every branch current $i$ as a function of node voltage variables $v$ with the general expression $i = g(v)$
Write $n-1$ KCL based equations in terms of node voltage variable.

The resulting equations can be written in matrix form and have to be solved for $v$.

$$\boldsymbol{Y} \boldsymbol{v} = \boldsymbol{i}$$

Assembling the System by Stamping

The matrix $\boldsymbol{Y}$ and the right hand side $\boldsymbol{i}$ are never written out by inspecting the whole circuit at once. Each element contributes its own fixed pattern of entries, and the system is formed by adding those contributions together. A conductance $G$ between nodes $k$ and $l$ adds $G$ to the diagonal entries $Y_{kk}$ and $Y_{ll}$ and subtracts it from the off-diagonal entries $Y_{kl}$ and $Y_{lk}$; if one terminal is the reference node, only the single diagonal entry appears. A current source injecting $I$ into node $k$ from node $l$ adds $I$ to $i_k$ and subtracts it from $i_l$.

This additive assembly is what makes the method practical. An element needs to know only the indices of the nodes it is attached to, never anything about the rest of the network, and the same element contributes the same pattern regardless of what it is connected to. It also explains the structure of the result: each row corresponds to one node and holds a non-zero entry only for nodes reachable through a single element, so $\boldsymbol{Y}$ is symmetric for networks of passive elements and sparse for any network of realistic size.

Dynamic Elements and the Companion Model

The formulation above assumes every branch current can be written as a function of node voltages alone. Inductors and capacitors do not satisfy this, since their currents depend on derivatives. They are brought into the same form by discretising the differential relation over one time step. Applying the trapezoidal rule to a capacitor between the instants $t - \Delta t$ and $t$ gives

$$i(t) = \frac{2C}{\Delta t} v(t) - \left( \frac{2C}{\Delta t} v(t - \Delta t) + i(t - \Delta t) \right),$$

and the same treatment of an inductor gives

$$i(t) = \frac{\Delta t}{2L} v(t) + \left( \frac{\Delta t}{2L} v(t - \Delta t) + i(t - \Delta t) \right).$$

Both have the form of a conductance in parallel with a current source. The conductance depends only on the element value and the time step, so it is a constant contribution to $\boldsymbol{Y}$; the current source depends only on quantities from the previous step, which are known when the current step begins, so it is a contribution to $\boldsymbol{i}$. This pair is called the companion model of the element, and the current source term is called its history term. Once every dynamic element has been replaced by its companion model, the network at each instant is a purely resistive one and the nodal formulation applies unchanged.

Extending the Formulation for Voltage Sources

An ideal voltage source cannot be stamped as a conductance, because its current is not determined by the voltage across it. The formulation is extended by admitting the source current as an additional unknown and adding the equation that constrains its terminal voltage. The system becomes

$$\begin{bmatrix} \boldsymbol{Y} & \boldsymbol{A} \\ \boldsymbol{A}^{\mathsf{T}} & \boldsymbol{0} \end{bmatrix} \begin{bmatrix} \boldsymbol{v} \\ \boldsymbol{j} \end{bmatrix} = \begin{bmatrix} \boldsymbol{i} \\ \boldsymbol{u} \end{bmatrix},$$

where $\boldsymbol{j}$ collects the unknown source currents, $\boldsymbol{u}$ the prescribed source voltages, and $\boldsymbol{A}$ has a single $+1$ and $-1$ per source marking its terminals. This extension is known as modified nodal analysis, and it is the form actually solved. The augmented matrix is no longer positive definite and carries zeros on part of its diagonal, which is why the solver has to be one that tolerates that rather than one specialised to the passive case.

Solving Over Time

Within a simulation the same system is solved once per time step. The left hand side depends only on the element values, the topology and the time step, none of which change from one step to the next in the ordinary case, so the matrix is factorised once and each step reuses that factorisation with a new right hand side. The cost of a step is then a forward and backward substitution rather than a full solve, which is what makes the method viable for large networks and for real time.

Two situations invalidate the factorisation. A switching event changes the topology and therefore the matrix, so the affected configuration has to be factorised again; simulations that switch frequently often pre-compute a factorisation for each configuration instead. A non-linear element makes the entries themselves depend on the solution, which requires iterating within the step until the node voltages and the element operating points agree.

Docs: RLC-Elements

Wed, 18 Mar 2020 00:00:00 +0000

EMT Equations and Modified Nodal Analysis

Inductance

An inductance is described by

$$v_j(t) - v_k(t) = v_L(t) = L \frac{\mathrm{d} i_L(t)}{\mathrm{d}t}$$

Integration results in an equation to compute the current at time $t$ from a previous state at $t - \Delta t$.

$$i_L(t) = i_L(t - \Delta t) + \frac{1}{L} \ \int_{t - \Delta t}^{t} v_L(\tau) \ \mathrm{d} \tau$$

There are various methods to discretize this equation in order to solve it numerically. The trapezoidal rule, an implicit second-order method, is commonly applied for circuit simulation:

$$\int_{t - \Delta t}^{t} f(\tau) \ \mathrm{d} \tau \approx \frac{\Delta t}{2}(f(t) + f(t - \Delta t))$$

Applying the trapezoidal rule to leads to

$$i_L(t) = i_L(t - \Delta t) + \frac{\Delta t}{2L}(v_L(t) + v_L(t - \Delta t))$$

This can be rewritten in terms of an equivalent conductance and current source and the number of time steps $k$ with size $\Delta t$.

$$i_L(k) = g_L v_L(k) + i_{L,equiv}(k-1)$$

$$i_{L,equiv}(k-1) = i_L(k-1) + \frac{\Delta t}{2L} v_L(k-1)$$

$$g_L = \frac{\Delta t}{2L}$$

Hence, components described by differential equations are transformed into a DC equivalent circuit as depicted in the figure below.

Capacitance

The same procedure can be applied to a capacitance. Integration on both side yields

$$i_C(t) = C \frac{\mathrm{d}}{\mathrm{d}t} \ v_C(t)$$

$$v_C(t) = v_C(t - \Delta t) + \frac{1}{C} \int_{t - \Delta t}^t i_C(\tau) \mathrm{d} \tau$$

Finally, the equivalent circuit is described by a current source and a conductance.

$$i_{C}(k) = g_{C} v_C(k) + i_{C,equiv}(k-1)$$

$$i_{C,equiv}(k-1) = -i_{C}(k-1) - g_C v_C(k-1)$$

$$g_{C} = \frac{2C}{\Delta t}$$

This equation set is visualized in the figure below.

Hence, the vector of unknowns $\boldsymbol{x}$ and the source vector $\boldsymbol{b}$ become time dependent and this leads to the system description:

$$\boldsymbol{A} \boldsymbol{x}(t) = \boldsymbol{b}(t)$$

To simulate the transient behavior of circuits, this linear equation has to be solved repeatedly. As long as the system topology and the time step is fixed, the system matrix is constant.

Extension with Dynamic Phasors

The dynamic phasor concept can be integrated with nodal analysis. The overall procedure does not change but the system equations are rewritten using complex numbers and all variables need to be expressed in terms of dynamic phasors. Therefore, the resistive companion representations of inductances and capacitances have to be adapted as well.

Inductance

In dynamic phasors the integration of the inductance equation yields

$$\begin{align} \langle v_L \rangle(t) &= \Big \langle L \frac{\mathrm{d} i_L}{\mathrm{d}t} \Big \rangle(t) \nonumber \\ &= L \frac{\mathrm{d}}{dt} \langle i_L \rangle(t) + j \omega L \ \langle i_L \rangle(t) \end{align}$$

$$\langle i_L \rangle(t) = \langle i_L \rangle(t - \Delta t) + \int_{t - \Delta t}^t \frac{1}{L} \langle v_L \rangle(\tau) - j \omega \ \langle i_L \rangle(\tau) \mathrm{d} \tau$$

Applying the trapezoidal method leads to the finite difference equation:

$$\begin{aligned} \langle i_L \rangle(k) = \langle i_L \rangle(k-1) + \frac{\Delta t}{2} \bigg[ \frac{1}{L} (\langle v_L \rangle(k) + \langle v_L \rangle(k-1)) - j \omega (\langle i_L \rangle(t) + \langle i_L \rangle(k-1) \bigg] \end{aligned}$$

Solving this for $\langle i_L \rangle(k)$ results in the \ac{DP} equivalent circuit model:

$$\langle i_L \rangle(k) = \frac{a - jab}{1 + b^2} \langle v_L \rangle(k) + \langle i_{L,equiv} \rangle(k-1)$$

with

$$a = \frac{\Delta t}{2L}, \qquad b = \frac{\Delta t \omega}{2}$$

$$\langle i_{L,equiv} \rangle(k-1) = \frac{1 - b^2 - j2b}{1 + b^2} \langle i_L \rangle(k-1) + \frac{a - jab}{1 + b^2} \langle v_L \rangle(k-1)$$

Capacitance

Similarly, a capacitance is described by as follows

$$\langle i_C \rangle(k) = C \ \frac{\mathrm{d} \langle v_C \rangle}{\mathrm{d} t} + j \omega C \ \langle v_C \rangle(t)$$

$$v_C(t) = v_C(t- \Delta t) + \int_{t- \Delta t}^{t} \frac{1}{C} \ i_C(\tau) -j \omega \ v_C(\tau) \ \mathrm{d} \tau$$

Applying the trapezoidal rule for the capacitance equation leads to the finite difference equation:

$$\begin{aligned} \langle v_C \rangle(k) = \langle v_C \rangle(k-1) + \frac{\Delta t}{2} \bigg[ \frac{1}{C} \ \langle i_C \rangle(k) - j \omega \ \langle v_C \rangle(k) \\ + \frac{1}{C} \ \langle i_C \rangle(k-1) - j \omega \ \langle v_C \rangle(k-1) \bigg] \end{aligned}$$

The DP model for the capacitance is defined by

$$\langle i_C \rangle(k) = \frac{1+jb}{a} \ \langle v_C \rangle(k) + \langle i_{C,equiv} \rangle(k-1)$$

with

$$a = \frac{\Delta t}{2C}, \qquad b = \frac{\Delta t \omega}{2}$$

$$\langle i_{C,equiv} \rangle(k-1) = - \frac{1-jb}{a} \ \langle v_C \rangle(k-1) - \langle i_C \rangle(k-1)$$

RL-series element

In dynamic phasors the integration of the inductance equation yields

$$\langle v \rangle(t) = L \frac{\mathrm{d}}{dt} \langle i \rangle(t) + j \omega L \ \langle i \rangle(t) + R \ \langle i \rangle(t)$$

$$\langle i \rangle(t) = \langle i \rangle(t - \Delta t) + \int_{t - \Delta t}^t \frac{1}{L} \langle v \rangle(\tau) - j \omega \ \langle i \rangle(\tau) - \frac{R}{L} \ \langle i \rangle(\tau) \mathrm{d} \tau$$

Applying the trapezoidal method leads to the finite difference equation:

$$\begin{aligned} \langle i \rangle(k) = \langle i \rangle(k-1) + \frac{\Delta t}{2} \bigg[ \frac{1}{L} (\langle v \rangle(k) + \langle v \rangle(k-1)) - \left( j \omega + \frac{R}{L} \right) (\langle i \rangle(k) + \langle i \rangle(k-1)) \bigg] \end{aligned}$$

Solving this for $\langle i \rangle(k)$ results in the \ac{DP} equivalent circuit model:

$$\langle i \rangle(k) = \frac{a + Ra^2 - jab}{(1+Ra)^2 + b^2} \langle v \rangle(k) + \langle i_{equiv} \rangle(k-1)$$

with

$$a = \frac{\Delta t}{2L}, \qquad b = \frac{\Delta t \omega}{2}$$

$$\langle i_{equiv} \rangle(k-1) = \frac{1 - b^2 - j2b + 2Ra + (Ra)^2 - j2Rab}{(1+Ra^2) + b^2} \langle i \rangle(k-1) + \frac{a + Ra^2 - jab}{(1+Ra)^2 + b^2} \langle v \rangle(k-1)$$

Docs: EMT Ph3 Averaged Voltage Source Inverter

Mon, 01 Jan 0001 00:00:00 +0000

This model represents a grid-following averaged voltage source inverter in the EMT domain. Because its state-space form is recomputed as the operating point moves, it is solved simultaneously with the network rather than through a delayed injection. The model includes a PLL, filtered active/reactive power measurement, outer power control, inner current control, and an LC filter with coupling resistance to the grid node.

The terminal input is the PCC voltage vector

$$\mathbf{u} = \begin{bmatrix} u_a & u_b & u_c \end{bmatrix}^\top ,$$

and the state vector is

$$\mathbf{x} = \begin{bmatrix} \theta_{\mathrm{PLL}} & \phi_{\mathrm{PLL}} & P & Q & \phi_d & \phi_q & \gamma_d & \gamma_q & v_{c,a} & v_{c,b} & v_{c,c} & i_{f,a} & i_{f,b} & i_{f,c} \end{bmatrix}^\top .$$

The model output is the interface current injected into the MNA system,

$$\mathbf{y} = \frac{\mathbf{u} - \mathbf{v}_c}{R_c}.$$

Model equations

The controller uses the opposite current direction, i.e. positive current denotes inverter injection into the grid,

$$\mathbf{i}_{rc} = \frac{\mathbf{v}_c - \mathbf{u}}{R_c}.$$

The Park transformation with PLL angle $\theta_{\mathrm{PLL}}$ is used to obtain dq quantities,

$$\begin{bmatrix} v_{c,d} \\ v_{c,q} \end{bmatrix} = \mathbf{T}(\theta_{\mathrm{PLL}})\mathbf{v}_c, \qquad \begin{bmatrix} i_{rc,d} \\ i_{rc,q} \end{bmatrix} = \mathbf{T}(\theta_{\mathrm{PLL}})\mathbf{i}_{rc}.$$

The instantaneous active and reactive powers are calculated as

$$p = v_{c,d} i_{rc,d} + v_{c,q} i_{rc,q},$$

$$q = -v_{c,d} i_{rc,q} + v_{c,q} i_{rc,d}.$$

The PLL and power-filter dynamics are

$$\dot{\theta}_{\mathrm{PLL}} = \omega_n + K_{p,\mathrm{PLL}} v_{c,q} + K_{i,\mathrm{PLL}} \phi_{\mathrm{PLL}},$$

$$\dot{\phi}_{\mathrm{PLL}} = v_{c,q},$$

$$\dot{P} = \omega_c(p - P), \qquad \dot{Q} = \omega_c(q - Q).$$

The outer power-control integrators and current references are

$$\dot{\phi}_d = P_{\mathrm{ref}} - P, \qquad \dot{\phi}_q = Q - Q_{\mathrm{ref}},$$

$$i_{d,\mathrm{ref}} = K_{p,P}(P_{\mathrm{ref}} - P) + K_{i,P}\phi_d,$$

$$i_{q,\mathrm{ref}} = K_{p,P}(Q - Q_{\mathrm{ref}}) + K_{i,P}\phi_q.$$

The inner current-control integrators and voltage references are

$$\dot{\gamma}_d = i_{d,\mathrm{ref}} - i_{rc,d}, \qquad \dot{\gamma}_q = i_{q,\mathrm{ref}} - i_{rc,q},$$

$$v_{d,\mathrm{ref}} = K_{p,I}(i_{d,\mathrm{ref}} - i_{rc,d}) + K_{i,I}\gamma_d,$$

$$v_{q,\mathrm{ref}} = K_{p,I}(i_{q,\mathrm{ref}} - i_{rc,q}) + K_{i,I}\gamma_q.$$

The reference voltage is transformed back to abc coordinates,

$$\mathbf{v}_{\mathrm{ref}} = \mathbf{T}^{-1}(\theta_{\mathrm{PLL}}) \begin{bmatrix} v_{d,\mathrm{ref}} \\ v_{q,\mathrm{ref}} \end{bmatrix}.$$

The LC filter dynamics are

$$\dot{\mathbf{v}}_c = \frac{1}{C_f}\mathbf{i}_f + \frac{1}{C_f R_c}(\mathbf{u} - \mathbf{v}_c),$$

$$\dot{\mathbf{i}}_f = \frac{1}{L_f} \left( \mathbf{v}_{\mathrm{ref}} - \mathbf{v}_c - R_f \mathbf{i}_f \right).$$

At each simulation step, the nonlinear model is locally linearized into the affine state-space form

$$\dot{\mathbf{x}} \approx \mathbf{A}\mathbf{x} + \mathbf{B}\mathbf{u} + \mathbf{E},$$

$$\mathbf{y} \approx \mathbf{C}\mathbf{x} + \mathbf{D}\mathbf{u} + \mathbf{F},$$

which is then discretized and stamped into the EMT MNA system.

How this is arranged in code, together with the source and the runnable examples, is covered under EMT Ph3 averaged VSI implementation.

Docs: Exciters and Power System Stabiliser

Mon, 01 Jan 0001 00:00:00 +0000

DC1 type model is the standard IEEE type DC1 exciter, whereas the other model is a simplified version of the IEEE DC1 type model. The inputs of the exciters are the magnitude of the terminal voltage of the generator connected to the exciter $v_h$ and the voltage reference $v_{ref}$, which is defined as a variable since other devices such as over-excitation limiters or power system stabilizers (PSS) modify such reference with additional signals. At the moment, no over-excitation limiters have been implemented in DPSim so that the reference voltage is given by: $$ v_{ref}(t) = v_{ref,0} + v_{pss}(t) $$ where $v_{ref,0}$ is initialized after the power flow computations and $v_{pss}(t)$ is the output of the (optional) PSS connected to the exciter. The output of the exciter systems is the induced emf by the field current at $t=k + \Delta t$: $v_{ef}(k + \Delta t)$ (sometimes the alternative notation $e_{fd}(k + \Delta t)$ is used).

IEEE Type DC1 exciter model

Fig. 1: Control diagram of the IEEE Type DC1 exciter
Adapted from: Milano, Frequency Variations in Power Systems

This model is used to represent field controlled dc commutator exciters with continuously acting voltage regulators (especially the direct-acting rheostatic, rotating amplifier, and magnetic amplifier types). The control diagram of this exciter is depicted in Fig. 1 and it is described by the following set of differential equations:

$$ T_{R} \frac{d}{dt} v_{R}(t) = v_{h}(t) - v_{R}(t) $$

$$ T_{b} \frac{d}{dt} v_{b}(t) = v_{ref} - v_{R}(t) - v_{f}(t) - v_{b}(t), $$ $$ T_{a} \frac{d}{dt} v_{a}(t) = K_{a} v_{in}(t) - v_{a}(t), $$ $$ T_{f} \frac{d}{dt} v_{f}(t) - K_{f} \frac{d}{dt} v_{ef}(t) = -v_{f}(t), $$ $$ T_{ef} \frac{d}{dt} v_{ef}(t) = v_{a}(t) - (K_{ef} + sat(t)) v_{ef}(t), $$ where $v_h$ is the module of the machine’s terminal voltage, and $v_{in}$ is the amplifier input signal, which for the IEEE Type DC1 is given by: $$ v_{in}(t) = T_{c} \frac{d}{dt} v_b(t) + v_b(t). $$

The ceiling function approximates the saturation of the excitation winding: $$ sat(t) = A_{ef} e^{(B_{ef} | v_{ef}(t) | )} $$

The set of differential equations are discretized using forward euler in order to solve it numerically, which leads to the following set of algebraic equations: $$ v_R(k + \Delta t) = v_R(k) + \frac{\Delta t}{T_R} ( v_h(k) - v_R(k) ), $$ $$ v_b(k + \Delta t) = v_b(k)(1 - \frac{\Delta t}{T_b}) + \frac{\Delta t}{T_b} ( v_{ref}(k) - v_R(k) - v_f(k)), $$ $$ v_{in}(k + \Delta t) = \Delta t \cdot \frac{T_c}{T_b} (v_{ref}(k) - v_R(k) - v_{f}(k) - v_b(k)) + v_b(k+1), $$ $$ v_a(k + \Delta t) = v_a(k) + \frac{\Delta t}{T_a} ( v_{in}(k) K_a - v_a(k) ), $$ $$ v_f(k + \Delta t) = (1 - \frac{\Delta t}{T_f}) v_f(k) + \frac{\Delta t K_f}{T_f T_{ef}} ( v_{a}(k) - (K_{ef} + sat(k)) v_{ef}(k) ), $$ $$ v_{ef}(k + \Delta t) = v_{ef}(k) + \frac{\Delta t}{T_{ef}} ( v_{a}(k) - (sat(k) + K_{ef}) v_{ef}(k)), $$ $$ sat(k) = A_{ef} e^{(B_{ef} | v_{ef}(k) | )} $$

Since the values of all variables for $t=k$ are known, $v_{ef}(k+1)$ can be easily calculated using the discretised equations, which is carried out in the preStep function of the generator connected to each exciter.

The initial values of all variables, which are used in the first simulation step, are calculated assuming that the simulation starts in the steady. This is equivalent to assume that all derivative are equal to zero, which leads to: $$ v_R(k=0) = v_h(k=0), $$ $$ v_f(k=0) = 0 $$ $$ v_a(k=0) = K_{ef} v_{ef}(k=0) + A_{ef} e^{B_{ef} |v_{ef} (k=0)|} v_{ef}(k=0), $$ $$ v_{in}(k=0) = \frac{v_a(k=0)}{K_a}, $$ $$ v_b(k=0) = v_{in}(k=0), $$ $$ v_{ref}(t=0) = v_{in}(t=0) + v_b(t=0), $$ where $v_h(k=0)$, $v_{ef}(k=0)$ are calculated after the power flow analysis and after the initialization of synchronous machines (see section initialization of SG).

Simplified IEEE Type DC1 exciter model (DC1Simp)

Fig. 2: Control diagram of the IEEE Type DC1 exciter
Adapted from: Milano, Power System Modelling and Scripting

Because the time constants $T_b$ and $T_c$ of the IEEE Type DC1 exciter model are frequently small enough to be neglected, in DPSim a simplified model of this exciter which neglect these time constants is also implemented. The control diagram of this exciter is depicted in Fig. 2 and it is described by the following set of differential equations: $$ T_R \frac{d}{dt} v_R(t) = v_h(t) - v_R(t) $$ $$ T_a \frac{d}{dt} v_a(t) = - v_a(t) + K_a v_{in}(t) $$ $$ T_f \frac{d}{dt} v_f(t) - K_f \frac{d}{dt} v_{ef}(t) = -v_f(t), $$ $$ T_e \frac{d}{dt} v_{ef}(t) = v_a(t) - v_{ef}(t) (sat(t) + K_{ef}) $$ where $v_h$ is the module of the machine’s terminal voltage, and $v_{in}$ is the amplifier input signal, which is given by: $$ v_{in}(t) = v_{ref} (t) - v_R(t) - v_f(t) $$ The set of differential equations are discretized using forward euler in order to solve it numerically, which leads to the following set of algebraic equations: $$ v_R(k + \Delta t) = v_R(k) + \frac{\Delta t}{T_R} ( v_h(k) - v_R(k) ), $$ $$ v_{in}(k) = v_{ref}(k) - v_R(k) - v_f(k), $$ $$ v_a(k + \Delta t) = v_a(k) + \frac{\Delta t}{T_a} ( v_{in}(k) K_a - v_a(k) ), $$ $$ v_f(k + \Delta t) = (1 - \frac{\Delta t}{T_f}) v_f(k) + \frac{\Delta t K_f}{T_f T_{ef}} ( v_{a}(k) - (K_{ef} + sat(k)) v_{ef}(k) ), $$ $$ v_{ef}(k + \Delta t) = v_{ef}(k) + \frac{\Delta t}{T_{ef}} ( v_{a}(k) - (sat(k) + K_{ef}) v_{ef}(k)), $$ $$ sat(k) = A_{ef} e^{(B_{ef} | v_{ef}(k) | )} $$

The initial values of all variables, which are used in the first simulation step, are calculated assuming that the simulation starts in the steady. This is equivalent to assume that all derivative are equal to zero, which leads to: $$ v_R(k=0) = v_h(k=0), $$ $$ v_f(k=0) = 0, $$ $$ v_a(k=0) = K_{ef} v_{ef}(k=0) + A_{ef} e^{B_{ef} |v_{ef} (k=0)|} v_{ef}(k=0), $$ $$ v_{in}(k=0) = \frac{v_a(k=0)}{K_a}, $$ $$ v_{ref}(t=0) = v_R(t=0) + v_{in}(t=0), $$ where $v_h(k=0)$, $v_{ef}(k=0)$ are calculated using the power flow analysis and after the initialization of synchronous machines (see section initialization of SG).

Static Exciter

Fig. 3: Control diagram of the Static Exciter
Adapted from [6]

The control diagram of this is depicted in Fig. 3. It can be observed as a simplified version of the DC1 type exciter which is composed only by the regulator, the amplifier and an optional transducer. To discretize the lead-lag compensator using forward euler it is better to split this block into two parallel blocks as depicted in Fig. 4.

Fig. 4: Control diagram of the Static Exciter

where:

$$ C_{a} = \frac{T_{a}}{T_{b}}, \quad C_{b} = \frac{T_{b}-T_{a}}{T_{b}}. $$ and it is described by the following set of differential equations: $$ T_{R} \frac{d}{dt} v_{r}(t) = v_{h}(t) - v_{r}(t) $$ $$ T_{b} \frac{d}{dt} x_{b}(t) = v_{in}(t) - x_{b}(t) $$ $$ T_{e} \frac{d}{dt} e_{fd}(t) = K_{a} v_{e}(t) - e_{fd}(t), $$

Then, the set of differential equations are discretized using forward euler in order to solve it numerically, which leads to the following set of algebraic equations:

$$ v_r(k + \Delta t) = v_r(k) + \frac{\Delta t}{T_R} ( v_h(k) - v_r(k) ), $$ $$ v_{in}(k) = v_{ref}(k) - v_{r}(k), $$ $$ X_b(k + \Delta t) = \frac{\Delta t}{T_{b}} (v_{in}(k) - x_{b}(k)) + x_{b}(k), $$ $$ v_e(k) = K_{a} (C_{b} x_{b}(k) + C_{a} v_{in} (k)) , $$ $$ e_{fd}(k + \Delta t) = \frac{\Delta t}{T_{e}}(v_{e}(k) - e_{fd}(k)) + e_{fd}(k). $$

To consider the saturation of $e_{fd}$ there are two different implementations, which is automatically selected depending of value of the parameter $K_{bc}$:

Standard ($K_{bc}=0$):

$$ e^{}{fd} = e{fd, max} \quad \quad if \quad \quad e^{}{fd} > e{fd, max} \ e^{}{fd} = e{fd, min} \quad \quad if \quad \quad e^{}{fd} < e{fd, min}, $$

where $e^{*}_{fd}$ represents the output of the exciter.

Anti-windup ($K_{bc}>0$): for controllers with an integral component, i.e. also for PID controllers, the so-called “windup effect” can occur when using the standard saturation function. A strategy for limiting the anti-windup effect is shown in Fig. 5.

Fig. 5: Control diagram of the Static Exciter with anti windup strategy

which means that the input of the differential equation describing $e_{fd}$, $v_{e}$, takes now the following form:

$$ v_{e} = C_{a} v_{in} + C_{b} x_{b} - K_{bc} (e_{fd} - e_{fd}^{*}) $$

$$ v_{r}(t=0) = v_{h}(t=0), $$

$$ v_{e}(t=0) = \frac{e_{fd}(t=0)}{K_{a}}, $$

$$ v_{in}(t=0) = \frac{v_{e}(t=0)}{C_{a}+C_{b}}, $$

$$ x_{b}(t=0) = v_{in}(t=0), $$

$$ v_{ref}(t=0) = v_{in}(t=0) + v_{r}(t=0) $$

Power System Stabilizer (PSS)

PSS is a controller of synchronous generators used to enhance damping of electromechanical oscillations. The PSS1A implemented in DPSim accepts three optional input signals: rotor speed $\omega$, active power $P$, and terminal voltage magnitude $V_h$. The combined input signal is: $$ s(t) = K_w \omega(t) + K_p P(t) + K_v V_h(t) $$ Setting $K_p = K_v = 0$ recovers the speed-only special case. The PSS output $v_{pss}$ at time $t=k$ is a signal used as the input of the AVR to calculate the field voltage at $t=k+\Delta t$, $v_{fd}(k+\Delta t)$. At present, only one PSS is implemented in DPSim which is a simplified version of the IEEE PSS1A type model.

IEEE PSS1A type PSS

Fig. 6: Control diagram of the PSS Type 1 (speed input only;
the implementation also accepts active power $K_p P$ and terminal voltage $K_v V_h$).
Adapted from: Milano, Power System Modelling and Scripting

The control diagram of this PSS is depicted in Fig. 6. It includes a washout filter and two lead-lag blocks and is described by the following set of differential equations: $$ T_w \frac{d}{dt} v_1(t) = -(s(t) + v_1(t)), $$ $$ T_2 \frac{d}{dt} v_2(t) = (1 - \frac{T_1}{T_2})(s(t) + v_1(t)) - v_2(t), $$ $$ T_4 \frac{d}{dt} v_3(t) = (1 - \frac{T_3}{T_4})\left(v_2(t) + \frac{T_1}{T_2}(s(t) + v_1(t))\right) - v_3(t), $$ $$ v_{pss}(t) = v_3(t) + \frac{T_3}{T_4}\left(v_2(t) + \frac{T_1}{T_2}(s(t) + v_1(t))\right), $$

where $s(t) = K_w \omega(t) + K_p P(t) + K_v V_h(t)$ is the combined input signal and $v_{pss}(t)$ is the output signal used to modify the reference voltage of the AVR.

The set of differential equations are discretized using forward euler in order to solve it numerically, which leads to the following set of algebraic equations: $$ v_1(k + \Delta t) = v_1(k) - \frac{\Delta t}{T_w} (s(k) + v_1(k)), $$ $$ v_2(k + \Delta t) = v_2(k) + \frac{\Delta t}{T_2} \left((1-\frac{T_1}{T_2})(s(k) + v_1(k)) - v_2(k)\right), $$ $$ v_3(k + \Delta t) = v_3(k) + \frac{\Delta t}{T_4} \left((1-\frac{T_3}{T_4})\left(v_2(k) + \frac{T_1}{T_2}(s(k) + v_1(k))\right) - v_3(k)\right), $$ $$ v_{pss}(k) = v_3(k) + \frac{T_3}{T_4} \left(v_2(k) + \frac{T_1}{T_2} (s(k) + v_1(k))\right) $$

Since the values of all variables for $t=k$ are known, $v_{pss}(k)$ can be easily calculated using the discretised equations, which is carried out in the preStep function of the generator connected to each exciter. Then, $v_{pss}(k)$ is used as input of the AVR to calculate the field voltage at time $k+1$. The values $v_1(k+1)$, $v_2(k+1)$, $v_3(k+1)$ are stored and used to calculate the PSS output of the next time step.

The initial values of all variables, which are used in the first simulation step, are calculated assuming that the simulation starts in steady state. This is equivalent to assuming that all derivatives are equal to zero, which leads to: $$ v_1(k=0) = -s(k=0), $$ $$ v_2(k=0) = (1 - \frac{T_1}{T_2})(s(k=0) + v_1(k=0)), $$ $$ v_3(k=0) = (1 - \frac{T_3}{T_4})\left(v_2(k=0) + \frac{T_1}{T_2}(s(k=0) + v_1(k=0))\right), $$ $$ v_{pss}(k=0) = v_3(k=0) + \frac{T_3}{T_4}\left(v_2(k=0) + \frac{T_1}{T_2}(s(k=0) + v_1(k=0))\right), $$

where $s(k=0) = K_w \omega(k=0) + K_p P(k=0) + K_v V_h(k=0)$ is evaluated after the power flow analysis and initialization of synchronous machines (see section initialization of SG). In steady state $\omega(k=0) = 1.0$ (pu), and if $K_p = K_v = 0$ then $v_2 = v_3 = v_{pss} = 0$.

Turbine Governor Models

In DPsim there are two types of Turbine Governor implementations. The Turbine Governor Type 1 implements both the turbine and the governor in one component. In contrast, Steam Turbine and Steam Turbine Governor are implemented as two separate classes and their objects are created independently. Steam/Hydro Turbine and Steam/Hydro Turbine Governor are two blocks that must be connected in series.

The input of the turbine governor models is the mechanical omega at time $t=k-\Delta t$ and the output is the mechanical power at time $t=k$. This variable is then used by the SG to predict the mechanical omega at time $t=k+\Delta t$.

Turbine Governor Type 1

Fig. 7: Control diagram of the turbine governor type 1
Source: Milano, Power System Modelling and Scripting

This model includes a governor, a servo and a reheat block. The control diagram of this governor is depicted in Fig. 7 and it is described by the following set of differential equations: $$ p_{in}(t) = p_{ref} + \frac{1}{R} (\omega_{ref} - \omega(t)), $$ $$ T_s \frac{d}{dt} x_{g1}(t) = p_{in}(t) - x_{g1}(t), $$ $$ T_c \frac{d}{dt} x_{g2}(t) = \left(1 - \frac{T_3}{T_c}\right) x_{g1}(t) - x_{g2}(t), $$ $$ T_5 \frac{d}{dt} x_{g3}(t) = \left(1 - \frac{T_4}{T_5}\right) \left(x_{g2}(t) + \frac{T_3}{T_c} x_{g1}(t)\right) - x_{g3}(t), $$ $$ \tau_m(t) = x_{g3}(t) + \frac{T_4}{T_5} \left(x_{g2}(t) + \frac{T_3}{T_c} x_{g1}(t)\right), $$ where $\omega(t)$ is the input signal and $\tau_m(t)$ is the output signal of the governor.

The differential equations are discretized using the forward Euler method, which leads to the following set of algebraic equations: $$ p_{in}(k-\Delta t) = p_{ref} + \frac{1}{R} (\omega_{ref} - \omega(k-\Delta t)), $$ $$ x_{g1}(k) = x_{g1}(k-\Delta t) + \frac{\Delta t}{T_s} \left(p_{in}(k-\Delta t) - x_{g1}(k-\Delta t)\right), $$ $$ x_{g2}(k) = x_{g2}(k-\Delta t) + \frac{\Delta t}{T_c} \left(\left(1 - \frac{T_3}{T_c}\right) x_{g1}(k-\Delta t) - x_{g2}(k-\Delta t)\right), $$ $$ x_{g3}(k) = x_{g3}(k-\Delta t) + \frac{\Delta t}{T_5} \left(\left(1 - \frac{T_4}{T_5}\right) \left(x_{g2}(k-\Delta t) + \frac{T_3}{T_c} x_{g1}(k-\Delta t)\right) - x_{g3}(k-\Delta t)\right), $$ $$ \tau_m(k) = x_{g3}(k) + \frac{T_4}{T_5} \left(x_{g2}(k) + \frac{T_3}{T_c} x_{g1}(k)\right). $$ Since all variables at $t=k-\Delta t$ are known, $\tau_m(k)$ is computed in the preStep of the generator and used to approximate the mechanical equations at time $k+\Delta t$.

Docs: Adding Dynamics

Fri, 31 Jul 2026 00:00:00 +0000

The circuit in your first simulation reaches its final value in a single step. A resistor is a purely algebraic element: it stores no energy, so the circuit has no state variable and its response to a change is instantaneous.

An inductor stores energy in its magnetic field, and its current cannot change instantaneously. That current becomes a state variable, the circuit becomes first order, and it acquires a transient worth looking at and a reason to care about the time step.

The circuit

A source, a resistor and an inductor in series. Only the inductor is new; everything else is the same shape as before.

import dpsimpy
import villas.dataprocessing.readtools as rt

name = "rl_circuit"

gnd = dpsimpy.dp.SimNode.gnd
n1 = dpsimpy.dp.SimNode("n1")
n2 = dpsimpy.dp.SimNode("n2")

src = dpsimpy.dp.ph1.VoltageSource("src")
src.V_ref = complex(100, 0)

r = dpsimpy.dp.ph1.Resistor("r")
r.R = 10.0

l = dpsimpy.dp.ph1.Inductor("l")
l.L = 0.05

src.connect([gnd, n1])
r.connect([n1, n2])
l.connect([n2, gnd])

system = dpsimpy.SystemTopology(50, [gnd, n1, n2], [src, r, l])

logger = dpsimpy.Logger(name)
logger.log_attribute("i_l", "i_intf", l)

sim = dpsimpy.Simulation(name)
sim.set_domain(dpsimpy.Domain.DP)
sim.set_system(system)
sim.set_time_step(1e-4)
sim.set_final_time(0.05)
sim.add_logger(logger)
sim.run()

current = rt.read_timeseries_dpsim("logs/" + name + ".csv")["i_l"]

A second node appears because the resistor and the inductor meet somewhere, and that junction is a node like any other. Components connect to nodes, never directly to each other, so a series chain of two elements always needs the node between them.

What to expect before running it

Two numbers are worth working out first, because they are what the result should be checked against.

The steady-state current follows from the impedance at the system frequency,

$$|I| = \frac{|V|}{\sqrt{R^2 + (\omega L)^2}} = \frac{100}{\sqrt{10^2 + (2\pi \cdot 50 \cdot 0.05)^2}} = \frac{100}{18.62} = 5.37 \ \mathrm{A},$$

and the transient decays with the time constant $\tau = L/R = 5$ ms, so the circuit settles after roughly five of those, about 25 ms. The simulation runs for 50 ms, comfortably past that.

Getting 5.37 A at the end is the check that the circuit was built as intended. A wrong connection order or a missing component usually shows up here rather than as an error.

Why the time step matters now

Run the same circuit twice, once at 0.1 ms and once at 5 ms, and compare the inductor current:

Time	0.1 ms step	5 ms step
5 ms	5.699 A	2.953 A
10 ms	6.105 A	6.256 A
20 ms	5.271 A	5.276 A
50 ms	5.371 A	5.366 A

At 5 ms the two disagree by nearly a factor of two. By 20 ms they agree to better than a tenth of a percent, and both end at the right steady-state value.

Watch out: a bad step size hides in the final value

That pattern is the whole point. The coarse run is not uniformly wrong; it is wrong during the transient and right afterwards. A step size equal to the time constant cannot resolve a change that happens over one time constant, but it has no trouble with a value that is no longer changing. Checking a simulation only at its final value will therefore not detect a step size that is far too large.

The rule that follows: choose the step against the fastest thing you need to see, not against the duration of the run or the value you expect at the end. Here the fastest thing is $\tau = 5$ ms, and 0.1 ms resolves it with room to spare.

What the values mean in this domain

The current is complex, and abs() gives the magnitude of the envelope rather than an instantaneous current. In this domain the 50 Hz oscillation is not in the numbers at all: it has been moved into the carrier and handled analytically, which is why a 0.1 ms step is generous here and would be merely adequate for the same circuit solved as a waveform.

That difference is the subject of a later step. For now it is enough to know that a flat line in a dynamic phasor result means a steady sinusoid, not a constant.

The script

The complete script for this page is 02_adding_dynamics.py under examples/Python/Tutorials. The numbers quoted above are the numbers it prints, so if the two ever disagree the page is the one that is wrong.

The circuit still has one source and one branch. Next is a network with a line between two buses, where the state the simulation starts from stops being obvious.

The elements used here are derived under RLC elements, and the trapezoidal companion models behind them under nodal analysis.

Docs: Branches

Fri, 31 Jul 2026 00:00:00 +0000

Both line models below are composite components: they do not stamp the system matrix directly but are built from resistor, inductor and capacitor subcomponents, each of which contributes its own stamp. See subcomponents for how that composition works, and RLC elements for the stamps of the individual elements.

The transformer is documented separately under transformer.

RX-Line

The RX line represents a line by its series resistance and series inductance only, ignoring the shunt admittance. It is the appropriate choice for short lines, where the charging current is negligible, and it is what the CIM reader produces for an ACLineSegment when no shunt data is present.

The model is composed of a series resistor and a series inductor between the two terminals:

$$\underline{Z} = R + j \omega L$$

An additional resistor from the inductor terminal to ground is present to make initialisation well posed. It is not part of the physical model.

RxLine exists in DP::Ph1, EMT::Ph3, SP::Ph1 and SP::Ph3.

PI-Line

The PI line adds the shunt admittance of the line, split evenly between the two terminals, which matters once the line is long enough for the charging current to affect the result. The name comes from the shape of the equivalent circuit: a series branch with one shunt branch at each end.

The series branch carries the resistance and inductance as above. Each terminal additionally carries half of the total shunt capacitance and half of the total shunt conductance:

$$\underline{Y}_{shunt} = \frac{G + j \omega C}{2}$$

The shunt capacitance and conductance are specified as totals for the line, and the halving between the two ends is part of the model rather than something the user does.

Decoupling Line

The decoupling line is a distributed parameter line based on the Bergeron travelling wave method. Unlike the two models above it is not primarily a fidelity improvement: its purpose is to remove the direct coupling between the two terminals so that the network on either side can be solved as an independent system, which is what makes splitting a network across solvers or across simulators possible.

The method rests on the behaviour of a lossless line. For a line with distributed inductance and capacitance, the quantity $v + Z_c, i$ observed at one end reappears unchanged at the other end one travel time later, and likewise in the opposite direction. Nothing propagates faster than that travel time, so the two ends cannot influence each other within it. The surge impedance and the travel time follow from the line’s total inductance and capacitance,

$$Z_c = \sqrt{\frac{L}{C}}, \qquad \tau = \sqrt{L C}.$$

Each terminal is then represented by a resistance to ground in parallel with a current source. The resistance is $Z_c + R/4$, and the current source carries the history term, whose value depends on the voltage and current recorded at the other terminal one travel time ago. Because that value is already known when the step begins, it enters the system as a constant injection rather than as a coupling into the admittance matrix, and the matrix separates into two blocks that can be factorised and solved independently.

The series resistance is not distributed along the line. It is lumped, with $R/4$ placed at each end and the remainder in the middle of the equivalent, which is why the terminating resistance and the history coefficients carry $R/4$ terms rather than the full $R$.

The travel time is not required to be a whole number of time steps. The recorded quantities are held in a buffer of $\lceil \tau / \Delta t \rceil$ samples and the value one travel time ago is recovered by linear interpolation between the two nearest entries. The one hard requirement is that the travel time exceed the time step; a line whose $\tau$ is shorter than $\Delta t$ cannot decouple anything, and setting one up is rejected rather than silently approximated.

In the dynamic phasor domain the history terms carry an additional rotation $e^{-j \omega_s \tau}$. This is a direct consequence of working with envelopes: a delay of $\tau$ applied to an instantaneous waveform becomes, for the envelope, the same delay together with a phase rotation of the carrier over that interval, as described under dynamic phasors. Note that this rotation is currently evaluated at a fixed 50 Hz rather than at the system frequency in use.

The decoupling is exact for the lossless travelling wave line it is derived from. The error introduced in practice comes from the lumped treatment of the series resistance and from the interpolation of the delayed quantities, and it grows as the time step approaches the travel time.

Choosing between them

Use the RX line when the shunt admittance can be neglected and you want the smaller system matrix, since the PI line introduces additional nodes for its shunt branches. Use the PI line when the line is long enough that its charging current matters, or when you are comparing against a reference tool that models the shunt branch.

Both are lumped parameter models and therefore do not reproduce travelling wave behaviour. Use the decoupling line when you need that behaviour, or when the reason for reaching for a line model is to split the network in the first place. For the domains each model is available in, see model availability.

Docs: Build

Fri, 31 Jul 2026 00:00:00 +0000

All builds start from a checkout of the repository. To build and read the code, cloning over HTTPS needs no account:

git clone https://github.com/sogno-platform/dpsim.git
cd dpsim

If you intend to contribute, clone your own fork over SSH instead, since contributions are accepted from forks only and pushing needs an authenticated remote:

git clone git@github.com:<your-user>/dpsim.git
cd dpsim
git remote add upstream https://github.com/sogno-platform/dpsim.git

The container route below is the most reproducible, because the image already carries every dependency at the version CI uses. The native routes need those dependencies installed by hand.

Container based

The commands below use docker, but the images are ordinary OCI images, so podman works as a drop-in replacement throughout. On Fedora and Rocky, podman is usually the one already installed. Substitute podman for docker in every command if you prefer it.

The repository ships a development image with all required dependencies:

docker build -t sogno/dpsim:dev -f packaging/Docker/Dockerfile.dev .

Alternatively, pull the prebuilt image instead of building it:

docker pull sogno/dpsim:dev

Then start an interactive session with the working copy mounted into the container:

docker run -it -p 8888:8888 -v $(pwd):/dpsim --privileged sogno/dpsim:dev bash

The -p option maps port 8888 so a JupyterLab instance inside the container is reachable from the host. The --privileged option is required for debug builds. On Windows, the current directory is spelled differently:

docker run -it -p 8888:8888 -v ${pwd}:/dpsim --privileged sogno/dpsim:dev bash

Inside the container, the C++ and Python libraries build as follows:

cd /dpsim
mkdir build && cd build
cmake ..
cmake --build . --target dpsimpy

Targets that are not built by default have to be named explicitly, for example:

cmake --build . --target dpsimpy dpsimpyvillas

To build everything:

cmake --build .

Optional features are enabled through the CMake options defined in the CMakeLists.txt files, for example:

cmake .. -DWITH_GSL=ON

To use the freshly built Python package without installing it, put both the compiled extension and the pure Python package on the path:

cd /dpsim/build
export PYTHONPATH=$(pwd):$(pwd)/../python/src

This is the setup most contributors work with, since it picks up a rebuild immediately without any reinstall step.

Do not use pip install -e . for this. An editable install only links the pure Python sources; dpsimpy is a compiled extension, so edits to the C++ are not picked up and you keep running whatever binary was built at install time. The failure is silent, since the import still succeeds and simply gives you stale behaviour. Either rebuild and rely on PYTHONPATH as above, or reinstall the package after every C++ change.

To summarise the three ways to get DPsim, in increasing order of involvement: pip install dpsim for a released Linux wheel, a native build plus PYTHONPATH for development, and make install to place a build system wide.

If you develop inside a conda environment, the equivalent is to register the same two directories from within the active environment. This needs conda-build installed:

cd /dpsim/build
conda develop $(pwd) && conda develop $(pwd)/../python/src

Note that this writes into the environment, so it becomes specific to your setup.

To run JupyterLab against it:

cd /dpsim
jupyter lab --ip="0.0.0.0" --allow-root --no-browser

To install DPsim system wide instead:

cd /dpsim/build
sudo make install

CMake for Linux

The authoritative dependency list is whatever the Dockerfiles install, since that is what CI builds against. See packaging/Docker/Dockerfile.dev for the Fedora set, and install-fedora-deps.sh or install-ubuntu-deps.sh for scripts that install them.

Both libcimpp and villas-node are optional. Neither needs to be built from source, though the images do not yet take the same route for both.

libcimpp publishes prebuilt .deb and .rpm packages per CIM version as release assets. The Fedora and Debian images install those directly, while the Rocky image still builds it from source:

# Pick the package matching your distribution and the CIM version you need.
wget https://github.com/sogno-platform/libcimpp/releases/download/release%2Fv2.2.0/libcimpp_CGMES_2.4.15_16FEB2016-2.2.0-Linux.deb
sudo apt-get install -y ./libcimpp_CGMES_2.4.15_16FEB2016-2.2.0-Linux.deb
sudo ldconfig

VILLASnode is served from the package repositories at https://packages.fein-aachen.org, which carry both debian/ and redhat/. Note that the images currently still build it from source, pinned to a specific commit, so the packaged version is the more convenient route for a local build but is not what CI exercises.

Building either from source remains supported, and the deps scripts above do that, which is what you want when you need a specific commit rather than a release.

Sundials is only needed for the DAE solver. If your distribution does not package it, the version CI uses is:

git clone --branch v3.2.1 --recurse-submodules --depth 1 https://github.com/LLNL/sundials.git
mkdir -p sundials/build && cd sundials/build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc) install

Cloning, building and installing then work exactly as in the container section above.

CMake for Windows

Windows is built in CI on windows-latest, so the recipe below mirrors what .github/workflows/build_test_windows.yaml runs. You need Visual Studio with the C++ desktop development workload, CMake and Git for Windows. For Python support, install Python 3 and add it to your PATH. Let CMake pick the default generator rather than naming a Visual Studio version, so the build follows whichever Visual Studio you have.

For the C++ libraries only:

mkdir build
cd build
cmake -DWITH_PYBIND=OFF ..
cmake --build . --target dpsim --target dpsim-models --parallel

For the Python bindings, install pybind11 first:

pip install pybind11[global]
mkdir build
cd build
cmake -DWITH_PYBIND=ON ..
cmake --build . --target dpsimpy --parallel

If CMake rejects the spdlog dependency because of its minimum policy version, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5, which is what CI currently does as a workaround.

The dpsim-villas library is not available on Windows, since it requires VILLASnode, which does not build there. WITH_VILLAS therefore stays off and the dpsimpyvillas target does not exist, so co-simulation examples cannot be built on Windows. The CIM reader is likewise not part of the CI Windows build, as libcimpp is not installed there.

CMake for macOS

macOS is not covered by CI, so treat this as a starting point rather than a supported path. Install the dependencies with Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install gcc git cmake graphviz python3 gsl eigen spdlog

Then build as in the container section. Building on Apple Silicon is known to fail while building libcimpp, see issue #609. Configure with -DWITH_CIM=OFF if you do not need the CIM reader.

Python package

Wheels are produced by cibuildwheel in the publish_to_pypi workflow, currently for manylinux x86_64 and CPython 3.9 through 3.13. To build a source distribution locally:

python3 -m build --sdist

Nix

DPsim can be built using Nix, a declarative package manager for reproducible builds. The following steps require a working single-user or multi-user installation of Nix, but not necessarily NixOS.

DPsim uses the Flakes feature, which has to be enabled:

echo "experimental-features=nix-command flakes" > ~/.config/nix/nix.conf

Building DPsim, including all its dependencies:

nix build github:sogno-platform/dpsim

The result is placed in the result folder of the current directory. For development, a local environment can be set up with:

nix develop github:sogno-platform/dpsim

The Flake reference above can be replaced by a local path such as . when the repository is already checked out.

Documentation

The Python and C++ references are generated by separate CMake targets. Both are also built and published by the documentation workflow on every push to master.

Python

Install Sphinx or use the Docker image, then:

mkdir -p build && cd build
cmake ..
make docs

The result is generated in build/docs/sphinx/html/. Note that this target requires the Python bindings, so it is only available when configured with -DWITH_PYBIND=ON.

C++

Install Doxygen or use the Docker image, then:

mkdir -p build && cd build
cmake ..
make docs_cxx

The result is generated in build/docs/doxygen/html/.

Website

The surrounding website is a Hugo site under docs/hugo. It needs the Hugo version pinned in the documentation workflow, since the theme does not build with arbitrary versions:

cd docs/hugo
npm ci
hugo --minify

Docs: Dynamic Phasors

Wed, 18 Mar 2020 00:00:00 +0000

In the power systems community, dynamic phasors were initially introduced for power electronics analysis Sanders1991 as a more general approach than state-space averaging. They were used to construct efficient models for the dynamics of switching gate phenomena with a high level of detail as shown in Mattavelli1999. A few years later, dynamic phasors were also employed for power system simulation as described in Demiray2008. In Strunz2006 the authors combine the dynamic phasor approach with the Electromagnetic Transients Program (EMTP) simulator concept which includes Modified Nodal Analysis (MNA). Further research topics include fault and stability analysis under unbalanced conditions as presented in Stankovic2000 and also rotating machine models have been developed in dynamic phasors Zhang 2007.

Bandpass Signals and Baseband Representation

Although here, dynamic phasors are presented as a power system modelling tool, it should be noted that the concept is also known in other domains, for example, microwave and communications engineering Maas2003, Suarez2009, Haykin2009, Proakis2001. In these domains, the approach is often denoted as base band representation or complex envelope. Another common term coming from power electrical engineering is shifted frequency analysis (SFA). In the following, the general approach of dynamic phasors for power system simulation is explained starting from the idea of bandpass signals. This is because the 50 Hz or 60 Hz fundamental and small deviations from it can be seen as such a bandpass signal. Futhermore, higher frequencies, for example, generated by power electronics can be modelled in a similar way.

Two Derivations of the Same Transform

The literature reaches the envelope description along two different routes. One starts from the analytic signal and shifts the spectrum; the other averages a sliding Fourier series. They are usually presented independently, under different names, and it is not always stated that they arrive at the same differential operator. The two routes are set out below so that the equivalence is visible.

Route A: shifting the spectrum

A bandpass signal is one whose spectrum is concentrated in a band around some carrier frequency $\omega_s$, narrow compared with $\omega_s$ itself. The network voltages and currents of a power system are of this kind: energy sits around the 50 Hz or 60 Hz fundamental and spreads only a little either side of it during a transient.

Such a signal can be written exactly as

$$x(t) = \operatorname{Re}\{\, X(t)\, e^{j \omega_s t} \,\},$$

where the complex quantity $X(t)$ is the envelope. It is obtained from the analytic signal $x_a(t) = x(t) + j,\mathcal{H}{x}(t)$, with $\mathcal{H}$ the Hilbert transform, by

$$X(t) = x_a(t)\, e^{-j \omega_s t}.$$

Multiplication by $e^{-j\omega_s t}$ translates the spectrum down by $\omega_s$, so the band that sat around the carrier now sits around zero. That translation is what the name shifted frequency analysis refers to. No information is lost, and nothing is approximated: the operation is invertible and $x(t)$ can be recovered from $X(t)$ at any instant.

The consequence that matters for simulation is what happens to the derivative. Differentiating the expression above gives

$$\frac{dx}{dt} = \operatorname{Re}\left\{ \left( \frac{dX}{dt} + j \omega_s X \right) e^{j \omega_s t} \right\},$$

so in envelope coordinates the time derivative becomes

$$\frac{d}{dt} \;\longrightarrow\; \frac{d}{dt} + j \omega_s .$$

An inductor $v = L,\frac{di}{dt}$ therefore satisfies $V = L,\frac{dI}{dt} + j \omega_s L, I$. Two limiting cases are worth noting. When the envelope is constant, the first term vanishes and what remains is $V = j\omega_s L, I$, the classical steady-state phasor relation. When $\omega_s = 0$, the second term vanishes and the envelope is the instantaneous signal itself, which is the electromagnetic transient description. Both the phasor and the instantaneous representation are special cases of the same expression.

Route B: averaging a Fourier series

The dynamic phasor derivation starts elsewhere. Over a window of length $T = 2\pi/\omega_s$ ending at time $t$, the waveform is expanded in a Fourier series

$$x(t + s) = \sum_{k} X_k(t)\, e^{j k \omega_s s}, \qquad s \in (-T, 0],$$

whose coefficients are themselves functions of time,

$$X_k(t) = \frac{1}{T} \int_{t-T}^{t} x(\tau)\, e^{-j k \omega_s \tau} \, d\tau .$$

These sliding-window coefficients are the dynamic phasors. Each one is constant whenever the waveform is periodic and varies only as the waveform’s shape changes, which is why they are also called generalized averages. Integrating by parts gives the property the method is built on,

$$\frac{dX_k}{dt} = \left\langle \frac{dx}{dt} \right\rangle_k - j k \omega_s X_k ,$$

that is, the same shift as Route A, applied to the $k$-th coefficient.

Where the routes meet

Retaining only $k = 1$ makes Route B’s relation identical to Route A’s: the first coefficient obeys $\frac{d}{dt} + j\omega_s$ and the network equations that follow are the same. The two derivations produce one model.

The difference is emphasis rather than substance. Route A treats a single carrier and is exact for any signal, so the accuracy question is only whether the signal is genuinely bandpass around the carrier that was chosen. Route B offers a whole family of coefficients, so it can carry a DC component in $X_0$, the fundamental in $X_1$ and switching harmonics in higher $X_k$ simultaneously, at the cost of one complex state per coefficient retained. Truncating that series is where the approximation enters: energy at frequencies that were not given a coefficient is discarded, and the sliding window acts as a low-pass filter on what remains, so envelope components varying as fast as $\omega_s$ itself are attenuated.

This explains the split in usage. Work concerned with converter switching, harmonic interaction or unbalanced and fault conditions keeps several coefficients and speaks of dynamic phasors. Work concerned with transient simulation of the fundamental keeps one and speaks of shifted frequency analysis, emphasising the enlarged time step rather than the series. The communications and microwave literature calls the same object the complex envelope or the lowpass equivalent. The three names describe one transform, and the choice between them says more about a paper’s lineage than about its mathematics.

Relationship to Electromagnetic Transient Models

An electromagnetic transient (EMT) model solves for the instantaneous quantities directly. Because the waveform it integrates oscillates at the carrier, the step size has to resolve that oscillation, and the accuracy of the result is bounded by how finely the fundamental period is sampled. A shifted frequency model integrates the envelope instead. In sinusoidal steady state the envelope is constant, so the step size is dictated by the bandwidth of the transient rather than by the carrier, and it can be substantially larger for the same accuracy. This is the reason the approach is attractive for transient stability studies and for real-time simulation of large networks.

The saving is not free, and it is worth being precise about where it comes from. It is not that the envelope model is a coarser description of the same system; for a single carrier the transform is exact. It is that the carrier oscillation has been removed from the quantity being integrated and folded into the coefficient $j\omega_s$, which the model handles analytically rather than numerically. What the envelope model cannot represent is content the retained coefficients do not cover, which for a single-coefficient model means anything outside the band around $\omega_s$.

Because $x(t) = \operatorname{Re}{X(t) e^{j\omega_s t}}$ holds at every instant, converting between the two descriptions is an algebraic operation at a given point in time, not a filtering or a fitting problem. That is what makes mixed-domain and co-simulation setups possible: part of a network can be solved in envelope form and part in instantaneous form, with the interface performing the multiplication in one direction and the extraction of the envelope in the other. Two conditions have to be respected at such an interface. The envelope is defined relative to a chosen $\omega_s$ and a chosen time origin, so both sides must agree on the carrier frequency and share a phase reference; and the extraction direction needs the analytic signal, which for a general instantaneous waveform cannot be formed from a single sample. Any delay introduced between the two sides appears as a phase error on the carrier, and that error grows with $\omega_s$ rather than with the envelope’s own rate of change.

The state-space form of the shift, and how the resulting complex system is solved as a real one, are covered in State-Space Nodal.

Docs: DP Ph1 Averaged Voltage Source Inverter

Mon, 01 Jan 0001 00:00:00 +0000

This model ports the same grid-following averaged inverter into the dynamic-phasor (DP) domain, as a single positive-sequence complex envelope rather than three abc waveforms. The PLL, power filter, outer power control, and inner current control are baseband and stay real; only the LC filter’s two states are genuine carrier-band envelopes and carry the $-j\omega_n$ shift described in State-Space Nodal.

The terminal input is the PCC voltage envelope

$$u = U ,$$

and the state vector is the mixed real/complex-envelope form

$$\mathbf{x} = \begin{bmatrix} \psi & \phi_{\mathrm{PLL}} & P & Q & \phi_d & \phi_q & \gamma_d & \gamma_q & \operatorname{Re}\{V_c\} & \operatorname{Im}\{V_c\} & \operatorname{Re}\{I_f\} & \operatorname{Im}\{I_f\} \end{bmatrix}^\top ,$$

where $\psi := \theta_{\mathrm{PLL}} - \omega_n t$ is the PLL angle’s deviation from the nominal carrier phase, tracked instead of the raw, unboundedly growing $\theta_{\mathrm{PLL}}$ for relinearization accuracy, and $V_c$, $I_f$ are complex envelopes replacing EMT’s six abc filter states.

The model output is the interface current injected into the MNA system,

$$y = \frac{U - V_c}{R_c}.$$

Model equations

The controller uses the opposite current direction, i.e. positive current denotes inverter injection into the grid,

$$I_{rc} = \frac{V_c - U}{R_c}.$$

Because the DP envelope already demodulates the carrier, the dq quantities are obtained by rotating the envelope by $\psi$ alone, not by the full absolute angle $\theta_{\mathrm{PLL}}$,

$$V_{c,dq} = V_c\, e^{-j\psi}, \qquad I_{rc,dq} = I_{rc}\, e^{-j\psi},$$

with $v_{c,d} = \operatorname{Re}{V_{c,dq}}$, $v_{c,q} = \operatorname{Im}{V_{c,dq}}$, and likewise for $i_{rc,d}$, $i_{rc,q}$.

The instantaneous active and reactive powers are calculated as

$$p = v_{c,d} i_{rc,d} + v_{c,q} i_{rc,q},$$

$$q = -v_{c,d} i_{rc,q} + v_{c,q} i_{rc,d},$$

identical in form to EMT’s; DP::Ph1’s own voltage/current scale already represents total power directly, with no three-phase multiplier.

The PLL and power-filter dynamics are

$$\dot{\psi} = K_{p,\mathrm{PLL}} v_{c,q} + K_{i,\mathrm{PLL}} \phi_{\mathrm{PLL}},$$