Induction Machine (3-phase)

Three-phase squirrel-cage induction machine (motor or generator) modeled in the synchronously-rotating dq reference frame. The rotor carries one or two short-circuited cage windings per axis (single-cage, or a double-cage / deep-bar rotor for accurate starting and transient torque); there is no field winding, so the rotor is driven entirely by induced (slip-frequency) currents. The rotor flux linkages are integrated with the slip-speed coupling retained, the internal voltage behind the (sub)transient reactance is reconstructed each step, and the machine couples to the network by the EMTDC-style voltage-behind-reactance method as a mutually-coupled three-phase stator companion (positive/negative sequence Z1 = Rs + jX'', a distinct zero sequence Z0 = R0 + jX0, plus a per-step Norton injection of the internal EMF and trapezoidal history). The star point is internal (no exposed neutral): the grounding mode selects ungrounded, solidly grounded, or grounded through Rn + jXn so unbalanced / zero-sequence studies behave correctly. Equivalent-circuit parameters (stator Rs / Xls, magnetizing Xm, cage Rr1 / Xlr1, and Rr2 / Xlr2 for a double cage) are entered directly in pu on the machine base (or in ohms). Magnetic saturation optionally derates the magnetizing reactance Xm with the shared exponential open-circuit curve. The shaft is either a single lumped inertia (swing equation) or a multi-mass torsional chain for sub-synchronous / torsional studies. Mechanical drive is a wired torque input with a constant fallback, plus an optional built-in speed-dependent load curve T = T0 (A + B w + C w^2) for fans / pumps (single-mass). The run starts from a user initial-slip parameter, seeding the rotor flux to the steady state at that slip and the rated terminal voltage. Rotor speed, slip and the developed electromagnetic torque are wired control outputs; the three stator currents, slip, speed, torque, and filtered P / Q are optional observables. For power flow the machine contributes a constant-PQ load row (enter the consumed P and Q on the Power Flow tab). Sign convention: generator convention internally (positive Te = generating with the rotor above synchronous speed, slip < 0; negative Te = motoring, slip > 0). Standalone machine — wire an external transformer, breaker, or supply on the canvas.

Category: Three-Phase / Machines

Overview

The Induction Machine models a three-phase squirrel-cage induction motor or generator — the most common machine in industry. The stator carries the three armature windings; the rotor carries one or two short-circuited cage windings per axis. Unlike the synchronous machine there is no field winding and no excitation: the rotor is energised entirely by currents induced across the air gap, which only flow when the rotor turns at a speed different from the rotating stator field. That speed difference is the slip, and it is what produces torque.

The model works in the synchronously-rotating $dq$ reference frame (the grid reference, ${\theta }_s={\omega }_{0}t$ — no rotor angle is needed because the cage rotor is magnetically round). The rotor flux linkages are integrated with the slip-speed coupling retained and the stator transients kept, so the model is faithful for switching and fault studies, not only slow electromechanical swings.

The same component runs as a motor (rotor below synchronous speed, slip $>0$, absorbing real power) or as a generator (rotor driven above synchronous speed by a prime mover, slip $<0$, injecting real power) — the $dq$ equations are sign-symmetric, so no mode switch is needed.

Single-cage vs. double-cage rotor

Two rotor constructions are offered through the Rotor type parameter:

• Single-cage carries one short-circuited winding per axis ($R_{r1}$, $X_{lr1}$). This is the standard model and is accurate near rated slip.
• Double-cage (or deep-bar) adds a second, deeper cage per axis ($R_{r2}$, $X_{lr2}$). Because of the skin effect, the higher-resistance outer cage dominates at large slip (starting) while the lower-resistance inner cage dominates near rated slip. This reproduces the characteristic high starting torque and steep current-vs-slip behaviour of a real deep-bar machine — it is the induction analogue of the synchronous machine's round-vs-salient choice.

The synchronously-rotating $dq$ frame and slip

The three stator phase quantities are projected onto a reference frame rotating at the synchronous speed ${\omega }_0=2\pi f$. In this frame the machine inductances are constant and the steady operating point is a DC point, which is what makes the model tractable. The per-unit slip is

$$s=1-{\omega }_r,$$

where ${\omega }_r$ is the per-unit rotor speed (1.0 = synchronous). The short-circuited cage obeys, per axis, the rotor voltage equation in the synchronous frame (per unit, with $\psi$ the cage flux linkage, $R_r$ the cage resistance and ${\omega }_0$ the base electrical speed):

$$\frac{\mathrm{d}{\psi }_{dr}}{\mathrm{d}t}={\omega }_0(-R_r{i}_{dr}+s{\psi }_{qr}),\frac{\mathrm{d}{\psi }_{qr}}{\mathrm{d}t}={\omega }_0(-R_r{i}_{qr}-s{\psi }_{dr}),$$

with one such pair for the single cage and a second pair (in $R_{r2}$, $X_{lr2}$) added for a double-cage rotor. The $s\psi$ terms are the slip-frequency speed EMFs that drive the induced rotor currents; the $\mathrm{d}\psi /\mathrm{d}t$ terms are the transformer EMFs the model keeps. At synchronous speed ($s=0$) the cage carries no net induced current and the machine produces no torque — the defining property of an induction machine.

Equivalent circuit

The machine is entered directly by its equivalent-circuit parameters (there is no datasheet-reactance conversion as on the synchronous machine):

• stator resistance $R_s$ and leakage reactance $X_{ls}$,
• magnetizing reactance $X_m$,
• cage-1 resistance $R_{r1}$ and leakage reactance $X_{lr1}$,
• cage-2 resistance $R_{r2}$ and leakage reactance $X_{lr2}$ (double-cage rotor only).

These combine into the interface reactance behind which the internal EMF is reconstructed each step:

$$X^{\prime }=X_{ls}+(X_m\parallel X_{lr1})\text{(single cage)},X^{″}=X_{ls}+(X_m\parallel X_{lr1}\parallel X_{lr2})\text{(double cage)},$$

where $\parallel$ denotes the parallel (reciprocal-sum) combination. The rotor flux states are integrated and the internal voltage behind $X^{\prime }$ (single) or $X^{″}$ (double) is reconstructed, so the machine presents the correct sub-transient impedance to the network during fast transients.

Every reactance / resistance can be typed in per-unit on the machine base or in ohms; the value is converted internally so the simulation always sees a consistent set of pu parameters regardless of how it was entered.

Torque and rotor dynamics

The air-gap electromagnetic torque is

$$T_e={\psi }_d{i}_q-{\psi }_q{i}_d(\text{pu}),$$

with the stator flux linkages ${\psi }_d=-X^{″}{i}_d+{\psi }_d^{″}$ and ${\psi }_q=-X^{″}{i}_q+{\psi }_q^{″}$ formed from the reconstructed internal flux. The rotor accelerates per the swing equation (per unit, inertia constant $H$ in seconds, damping $D$):

$$2H\frac{\mathrm{d}{\omega }_r}{\mathrm{d}t}=T_m-T_e-D({\omega }_r-1),s=1-{\omega }_r.$$

The model uses the generator convention consistently with the synchronous machine: a positive $T_e$ is generating torque (rotor above synchronous, $s<0$) and a negative $T_e$ is motoring torque (rotor below synchronous, $s>0$). At steady state $T_e=T_m$:

• drive the shaft ($T_m>0$) and the rotor settles above synchronous speed, $s<0$, injecting real power — an induction generator;
• load the shaft ($T_m<0$) and the rotor settles below synchronous speed, $s>0$, absorbing real power — an induction motor.

In either case the machine always draws reactive power from the network to magnetize, so $Q$ at the terminals is negative (absorbed) even when generating real power — the reason a stand-alone induction generator needs an external VAr source (capacitors or the grid).

This single lumped inertia is the right choice for ordinary motor / generator studies. For torsional / sub-synchronous studies, switch the Shaft model to Multi-mass (below).

Mechanical drive: wired torque and the load curve

The mechanical torque $T_m$ is a wired control input (with a constant fallback $t_{m0}$ used when the pin is unwired), in the generator convention: positive drives the rotor (generating), negative loads it (motoring). The rotor speed ${\omega }_r$, the slip $s$ and the developed torque $T_e$ are wired control outputs, so the machine connects naturally to a turbine / governor or a mechanical-load model on the canvas.

For driven loads with a known speed dependence (fans, pumps, compressors), enabling the built-in load curve adds a speed-dependent mechanical load torque that opposes rotation, on top of the wired drive:

$$T_{\text{load}}=T_0(A+B{\omega }_r+C{\omega }_r^2),T_m^{\text{eff}}=T_{m,\text{wired}}-T_{\text{load}}.$$

A constant load uses $A$ only; a fan or centrifugal pump uses the quadratic $C$ term. The load curve is available in single-mass mode only.

Multi-mass shaft (torsional model)

Selecting Multi-mass on the Shaft tab replaces the single lumped inertia with a spring-coupled chain of rotor masses, for torsional / sub-synchronous studies. The chain is built around the machine rotor: 1 to 4 driven masses, the rotor itself, and an optional extra undriven mass (up to six masses in all). Each mass carries its own inertia $H$ and self-damping $D$; adjacent masses are joined by a torsional spring of stiffness $K$ (pu torque per electrical radian of twist) and a mutual damping $D_m$. Every mass obeys its own swing equation, coupled to its neighbours through the shaft springs:

$$2H_i\frac{\mathrm{d}{\omega }_i}{\mathrm{d}t}=T_{m,i}-[i=\text{rotor}]T_e-D_i({\omega }_i-1)-\sum _{j\in \text{neighbours}}[K_{ij}({\delta }_i-{\delta }_j)+D_{m,ij}({\omega }_i-{\omega }_j)],\frac{\mathrm{d}{\delta }_i}{\mathrm{d}t}={\omega }_0({\omega }_i-1).$$

Only the rotor mass exchanges the air-gap torque $T_e$ with the electrical model, and its speed sets the slip. The driven masses (numbered outward from the rotor) each get their own mechanical-torque input pin — the connection point for a separate load / prime-mover model — and any pin left unwired falls back to that mass's constant fallback torque. Enabling Measure shaft (per-mass) publishes each mass's speed and angle as observables so the torsional oscillations (and the twist between any two masses) can be plotted directly.

The single-mass model is exactly the one-mass special case of this chain.

Magnetic saturation

Saturation derates the magnetizing reactance $X_m$ as a function of the air-gap (mutual) flux ${\psi }_{at}=\sqrt{{\psi }_{ad}^2+{\psi }_{aq}^2}$ using the standard exponential open-circuit curve:

$$S({\psi }_{at})=\{\begin{array}{ll}{A}_{\text{sat}}\exp (B_{\text{sat}}({\psi }_{at}-{\psi }_{T1}))& {\psi }_{at}>{\psi }_{T1},\\ 0& {\psi }_{at}\le {\psi }_{T1},\end{array}{X}_m=\frac{X_{mu}}{1+S({\psi }_{at})},$$

where $X_{mu}$ is the unsaturated magnetizing reactance. The curve can be entered two equivalent ways (selected by the Definition field on the Saturation tab): the exponential coefficients $A_{\text{sat}}$, $B_{\text{sat}}$ directly, or the two datasheet saturation factors $S_E(1.0)$ and $S_E(1.2)$, from which the exponential is fit. This is the same saturation convention shared across the machine models.

Network interface and grounding

The machine couples to the network by the EMTDC-style voltage-behind-(sub)transient-reactance method, realised as a mutually-coupled three-phase stator companion. Decomposed into symmetric sequences:

• the positive / negative sequence sees the interface impedance $Z_1=Z_2=R_s+j{X}^{″}$ (or $j{X}^{\prime }$ for a single cage);
• the zero sequence sees the machine's own impedance $Z_0=R_0+j{X}_0$ (entered on the Zero Sequence tab), with no rotor coupling — the cage carries no zero-sequence flux.

A per-step Norton current source carries the internal EMF (reconstructed from the rotor fluxes) plus the trapezoidal history.

There is no exposed neutral terminal. The star (neutral) point is internal, and the Neutral grounding mode selects how it ties to ground:

Mode	Terminal zero-sequence impedance
Ungrounded	open — no zero-sequence current path
Solidly grounded	$Z_0$
Grounded via impedance	$Z_0+3(R_n+j{X}_n)$

The factor of 3 is the standard symmetric-component result for a neutral impedance carrying $3I_0$, so single-line-to-ground faults and other zero-sequence studies reproduce the textbook behaviour.

Initial-slip start

An EMT run needs the rotor fluxes initialised. Rather than re-deriving the operating point from the load flow, the machine starts from a user Initial slip parameter: it solves the steady-state equivalent circuit at that slip and the rated terminal voltage ($V=1\mathrm{\angle }0$ pu), converts the resulting stator and cage phasor currents to $dq$ flux linkages, and seeds the rotor state and the rotor speed ${\omega }_r(0)=1-s_0$ accordingly.

Set the initial slip near the expected operating slip for a clean start with minimal pull-in transient; set it to 0 to start from synchronous speed (open cage, magnetizing current only) and let the rotor pull in to its loaded operating point under the applied torque. There is no automatic back-calculation of slip from the load-flow solution.

Power-flow (load-flow) behaviour

For power flow the machine contributes a constant-PQ load row at its bus: it draws the real power $P$ and reactive power $Q$ you enter on the Power Flow tab (positive $Q$ = absorbed, the usual inductive case for an induction machine). The power-flow draw is independent of the EMT initial-slip start — there is no auto-initialisation linking the two — so enter the operating-point $P$ and $Q$ (or power factor) directly.

Display label

The Name parameter (Config tab) is a display-only tag (e.g. M-1). It is drawn beneath the icon, on the line above the machine's rated power, and has no effect on the simulation.

When to use something else

• A synchronous generator / motor (field winding, excitation / AVR, governor, sustained voltage support): use the Synchronous Machine instead.
• A stiff/ideal source behind a fixed impedance (no rotor dynamics needed): use the 3-Phase Voltage Source, which is far cheaper.
• A machine on a different MVA / kV base wired to the grid: add an external Transformer (3-phase) rather than re-basing the machine by hand.

Ports

Name	Direction	Value type	Notes
terminals	electrical_3ph	double
Tmech	input	double	Visible when shaft_model == 0
Tmech1	input	double	Visible when shaft_model == 1 && num_turbines >= 1
Tmech2	input	double	Visible when shaft_model == 1 && num_turbines >= 2
Tmech3	input	double	Visible when shaft_model == 1 && num_turbines >= 3
Tmech4	input	double	Visible when shaft_model == 1 && num_turbines >= 4
speed	output	double
slip	output	double
Te	output	double

Parameters

Config

Name	Label	Type	Default	Units	Description
name	Name	string	(empty)	—	Display-only label for this machine (e.g. a tag like `M-1`). Drawn under the icon above the rated power. Has no effect on the simulation.
rotor_type	Rotor type	enum (Single-cage (Rr1, Xlr1) / Double-cage (Rr1/Xlr1 + Rr2/Xlr2))	0	—	Rotor cage structure. `Single-cage` carries one short-circuited winding per axis (Rr1, Xlr1) — the standard model, accurate near rated slip. `Double-cage` adds a second, deeper cage per axis (Rr2, Xlr2) that models the deep-bar / double-cage effect: the higher-resistance outer cage dominates at large slip (starting), giving an accurate starting torque and current, while the inner cage dominates near rated slip.
shaft_model	Shaft model	enum (Single-mass (lumped) / Multi-mass (torsional))	0	—	Mechanical rotor representation. `Single-mass` lumps the whole rotor + driven train into one inertia governed by the scalar swing equation 2Hdw/dt = Tm - Te - D(w-1) — the right choice for ordinary motor / generator studies, and the only mode that offers the built-in speed-dependent load curve. `Multi-mass` replaces it with a chain of spring-coupled rotor masses for torsional / sub-synchronous studies; configure the masses, shaft stiffnesses and per-stage mechanical-torque inputs on the Shaft tab.
s_rated	S rated	double	1	MVA (VA, kVA, MVA)	Machine rated apparent power. Also the per-unit power base for the reactances/resistances and the basis for the pu electrical torque Te.
v_rated	V rated (LL rms)	double	0.48	kV (V, kV)	Machine rated line-to-line RMS terminal voltage. Per-unit voltage base; the internal air-gap EMF for 1 pu flux is V_rated*sqrt(2/3) peak line-to-neutral.
f_rated	f rated	double	60	—	Rated electrical (supply) frequency (Hz). Sets the synchronous speed and base angular speed w0 = 2pif and the pu<->SI reactance/inductance conversion.
H	H (MWs/MVA)	double	1	—	Inertia constant in seconds (stored kinetic energy of the rotor + driven load at synchronous speed / rated MVA). Larger H = slower speed changes. Used by the single-mass swing equation 2Hdw/dt = Tm - Te - D(w-1). Single-mass shaft only — in multi-mass mode each rotor mass carries its own H on the Shaft tab.
D	D (pu)	double	0	—	Per-unit mechanical damping torque coefficient (damping torque = D*(w-1) in pu). 0 disables. Single-mass shaft only — in multi-mass mode each rotor mass carries its own self-damping on the Shaft tab.
load_curve	Built-in load curve	enum (Off / On)	0	—	Add a built-in speed-dependent mechanical LOAD torque T_load = T0*(A + Bw + Cw^2) (pu) that opposes rotation, on top of the wired Tmech drive / its fallback. A constant load uses A only; a fan / pump / compressor uses the quadratic C term. Configure T0 / A / B / C on the Mechanical tab. Single-mass shaft only.
grounding_mode	Neutral grounding	enum (Ungrounded / Solidly grounded / Grounded via impedance)	0	—	How the machine's internal star point is tied to ground (there is no exposed neutral terminal). `Ungrounded`: the star point floats — no zero-sequence current path (the usual case for a delta or ungrounded-wye motor). `Solid`: star point bonded to ground (terminal zero-sequence impedance = the machine Z0 = R0 + jX0). `Impedance`: star point grounded through Rn + jXn, so the terminal zero-sequence impedance is Z0 + 3*(Rn + jXn). Set the machine Z0 on the Zero Sequence tab.
saturation	Magnetic saturation	enum (Off (linear) / On)	0	—	Enable the exponential open-circuit saturation curve acting on the magnetizing reactance Xm (both axes scaled by the same factor). Define the curve directly (Asat/Bsat) or via the SE(1.0)/SE(1.2) datasheet points on the Saturation tab.
measure_current	Measure stator current	enum (Off / On)	0	—	Emit the three stator phase currents as observables. Names/units on the Signal Names tab.
measure_speed	Measure speed / slip	enum (Off / On)	0	—	Emit the rotor speed (pu) and slip (pu) as observables. Names on the Signal Names tab. (Rotor speed, slip and torque are also always available as wired control outputs.)
measure_te	Measure elec. torque	enum (Off / On)	0	—	Emit the developed (air-gap) electrical torque Te as an observable. Name/unit on the Signal Names tab. Generator convention: positive = generating, negative = motoring.
measure_shaft	Measure shaft (per-mass)	enum (Off / On)	0	—	Emit each rotor mass's speed and angle as observables (multi-mass shaft only). Use the per-mass speeds and the angle twist between adjacent masses to study torsional / sub-synchronous oscillations. Names on the Shaft Signals tab.
monitor_pq	Monitor P/Q	enum (Off / On)	0	—	Emit real (P) and reactive (Q) power at the terminals as observables. Instantaneous Akagi form, low-pass filtered with pq_time_constant to reject 2w ripple. Generator convention: positive P = injected into the network (generating); a motor draws P < 0. Names/units on the Signal Names tab.
pq_time_constant	P/Q filter tau (sec)	double	0.02	—	Low-pass filter time constant for P/Q (and the Te report). Smaller tracks transients; larger gives a cleaner steady state.

Equivalent Circuit

Name	Label	Type	Default	Units	Description
Rs	Rs (stator)	double	0.03	pu (pu, Ω)	Stator (armature) resistance per phase. Also sets the positive- and zero-sequence interface resistance. Enter in pu on the machine base or in ohms.
Xls	Xls (stator leakage)	double	0.1	pu (pu, Ω)	Stator (armature) leakage reactance. With Xm sets the stator self-reactance Xs = Xls + Xm and the (sub)transient reactance that interfaces the machine to the network. Enter in pu on the machine base or in ohms.
Xm	Xm (magnetizing)	double	3	pu (pu, Ω)	Magnetizing (mutual) reactance — the shunt air-gap branch shared by the stator and rotor windings. Sets the no-load magnetizing current (~1/Xm pu) and, with saturation enabled, is the reactance the saturation curve derates. Enter in pu on the machine base or in ohms.
Rr1	Rr1 (rotor)	double	0.025	pu (pu, Ω)	Rotor cage 1 resistance, referred to the stator. With Xlr1 sets the rotor transient open-circuit time constant T'o = (Xlr1 + Xm)/(w0*Rr1) and dominates the rated-slip torque. On a double-cage rotor this is typically the higher-resistance (outer / starting) cage. Enter in pu on the machine base or in ohms.
Xlr1	Xlr1 (rotor leakage)	double	0.1	pu (pu, Ω)	Rotor cage 1 leakage reactance, referred to the stator. With Xm and Xls sets the transient reactance X' = Xls + Xm*Xlr1/(Xm+Xlr1). Enter in pu on the machine base or in ohms.
Rr2	Rr2 (rotor cage 2)	double	0.018	pu (pu, Ω)	Rotor cage 2 resistance, referred to the stator (double-cage rotor only). Typically the lower-resistance (inner / running) cage that dominates near rated slip. Enter in pu on the machine base or in ohms.
Xlr2	Xlr2 (rotor cage 2 leakage)	double	0.14	pu (pu, Ω)	Rotor cage 2 leakage reactance, referred to the stator (double-cage rotor only). With Xm, Xls and cage 1 sets the sub-transient reactance X'' = Xls + Xm || Xlr1 || Xlr2. Enter in pu on the machine base or in ohms.

Mechanical

Name	Label	Type	Default	Units	Description
tm0	Tm (fallback, pu)	double	0	—	Constant per-unit mechanical DRIVE torque used when the Tmech control input is left unwired (generator convention: positive drives the rotor as a generator). Leave at 0 for a motor whose load is set by the built-in load curve, or set negative to apply a constant load torque.
t0	Load T0 (pu)	double	1	—	Built-in load-curve magnitude (pu): the mechanical LOAD torque is T_load = T0*(A + Bw + Cw^2), opposing rotation. T0 is the rated load torque. Active only when Built-in load curve is On.
load_a	Load A (constant)	double	0	—	Constant (speed-independent) term of the load curve T_load = T0*(A + Bw + Cw^2). Coulomb / dry-friction loads use A; conveyors and hoists are nearly pure A.
load_b	Load B (linear)	double	0	—	Linear-in-speed term of the load curve (proportional to w). Viscous-friction loads use B.
load_c	Load C (quadratic)	double	1	—	Quadratic-in-speed term of the load curve (proportional to w^2). Centrifugal fans, pumps and compressors are dominated by C.

Saturation

Name	Label	Type	Default	Units	Description
sat_definition	Definition	enum (Exponential (Asat/Bsat) / SE points (SE1.0/SE1.2))	0	—	How the saturation curve is specified. `Exponential` enters the coefficients Asat / Bsat directly. `SE points` enters the two datasheet saturation factors SE(1.0) and SE(1.2); the exponential is fit through them. Both end up as the same Ssat(psi) = Asatexp(Bsat(psi - psiT1)) curve internally.
Asat	Asat	double	0.03	—	Exponential saturation coefficient A: the saturation function is Ssat(psi_at) = Asatexp(Bsat(psi_at - psiT1)) for air-gap flux psi_at above the threshold psiT1, else 0. The saturated magnetizing reactance is Xm = Xm_unsat / (1 + Ssat). 0 disables saturation.
Bsat	Bsat	double	7	—	Exponential saturation coefficient B (1/pu-flux): controls how sharply saturation increases with air-gap flux above psiT1.
SE10	SE(1.0)	double	0.1	—	Open-circuit saturation factor at Vt = 1.0 pu: SE(1.0) = dI(1.0)/1.0, the fractional extra magnetizing current (vs. the air-gap line) needed to reach 1.0 pu terminal voltage. Typical 0.05-0.15.
SE12	SE(1.2)	double	0.3	—	Open-circuit saturation factor at Vt = 1.2 pu: SE(1.2) = dI(1.2)/1.2. Must exceed SE(1.0). Typical 0.2-0.5. With SE(1.0) it fixes Bsat = ln(SE12/SE10)/0.2 and Asat = SE10/exp(Bsat*(1.0 - psiT1)).
psiT1	psiT1 (pu)	double	0.8	—	Air-gap flux threshold (pu) below which the iron is unsaturated (Ssat = 0).

Zero Sequence

Name	Label	Type	Default	Units	Description
X0	X0	double	0.05	pu (pu, Ω)	Machine zero-sequence reactance. Sets the zero-sequence stator impedance Z0 = R0 + jX0 (carried by a true mutually-coupled stator companion). For an induction machine the cage produces no zero-sequence coupling, so X0 is essentially the stator leakage Xls. Leave at/near 0 to default to the average (sub)transient reactance. Enter in pu on the machine base or in ohms.
R0	R0	double	0	pu (pu, Ω)	Machine zero-sequence resistance. Defaults to the stator resistance Rs when left at 0. Enter in pu on the machine base or in ohms.

Grounding

Name	Label	Type	Default	Units	Description
Rn	Rn (neutral)	double	0	pu (pu, Ω)	Neutral grounding resistance, between the internal star point and ground. Adds 3*Rn to the terminal zero-sequence impedance. Enter in pu on the machine base or in ohms.
Xn	Xn (neutral)	double	0	pu (pu, Ω)	Neutral grounding reactance, between the internal star point and ground. Adds 3*Xn to the terminal zero-sequence impedance. Enter in pu on the machine base or in ohms.

Initialization

Name	Label	Type	Default	Units	Description
init_slip	Initial slip (pu)	double	0	—	Slip s = (w_sync - w_rotor)/w_sync at t = 0 (pu). The rotor flux is seeded to the steady state at this slip and the rated terminal voltage, so the machine starts near its operating point with a short transient. 0 starts at synchronous speed with only the magnetizing flux established (a smooth no-load start); a small positive value (e.g. 0.02) starts a motor near full-load slip; a negative value starts a generator above synchronous speed.

Shaft

Name	Label	Type	Default	Units	Description
num_turbines	Number of masses	enum (1 / 2 / 3 / 4)	1	—	How many external mechanical masses are on the shaft (1 to 4). Each is a spring-coupled rotor mass with its own mechanical-torque input pin; Mass 1 sits next to the machine rotor and higher-numbered masses extend outward. With the rotor (and optional extra mass) this gives a 2- to 6-mass torsional chain. For a motor these represent the driven load train; for a generator, the prime-mover stages.
model_exciter	Model extra mass	enum (Off / On)	0	—	Add a separate undriven rotor mass on the far side of the machine rotor from the load masses, coupled to the rotor by its own shaft section (e.g. a shaft-mounted exciter or a flywheel). It has no torque-input pin; its small steady torque is set by its fallback below. Off lumps it into the rotor mass.
H_gen	Rotor: H (MWs/MVA)	double	1	—	Inertia constant of the machine rotor mass — the electrical rotor that exchanges the air-gap torque Te with the network and whose speed sets the slip.
D_gen	Rotor: D (pu)	double	0	—	Self (absolute) damping torque coefficient of the rotor mass (damping torque = D*(w-1), pu). Models windage/load damping against the stationary frame. 0 disables.
K_t1_gen	Mass 1 - Rotor: K (pu torque/rad)	double	30	—	Torsional stiffness of the shaft section between Mass 1 and the machine rotor (per-unit torque per electrical radian of twist). Larger K = stiffer shaft, higher torsional natural frequency.
Dmut_t1_gen	Mass 1 - Rotor: Dmut (pu)	double	0	—	Mutual (relative) damping of the Mass 1 - rotor shaft section (damping torque = Dmut*(w1-w_rotor), pu). Damps the torsional mode. 0 disables.
H_turb1	Mass 1: H (MWs/MVA)	double	1	—	Inertia constant of Mass 1 (the mechanical mass adjacent to the machine rotor).
D_turb1	Mass 1: D (pu)	double	0	—	Self (absolute) damping torque coefficient of Mass 1. 0 disables.
tm_turb1_fb	Mass 1: Tm (fallback, pu)	double	0	—	Constant per-unit mechanical torque applied to Mass 1 when its Tmech1 input is left unwired (generator convention: positive drives the shaft, negative is a load).
K_t1_t2	Mass 1 - Mass 2: K (pu torque/rad)	double	30	—	Torsional stiffness of the shaft section between Mass 1 and Mass 2 (pu torque per electrical radian).
Dmut_t1_t2	Mass 1 - Mass 2: Dmut (pu)	double	0	—	Mutual damping of the Mass 1 - Mass 2 shaft section (pu). 0 disables.
H_turb2	Mass 2: H (MWs/MVA)	double	1	—	Inertia constant of Mass 2.
D_turb2	Mass 2: D (pu)	double	0	—	Self (absolute) damping torque coefficient of Mass 2. 0 disables.
tm_turb2_fb	Mass 2: Tm (fallback, pu)	double	0	—	Constant per-unit mechanical torque applied to Mass 2 when its Tmech2 input is left unwired.
K_t2_t3	Mass 2 - Mass 3: K (pu torque/rad)	double	30	—	Torsional stiffness of the shaft section between Mass 2 and Mass 3 (pu torque per electrical radian).
Dmut_t2_t3	Mass 2 - Mass 3: Dmut (pu)	double	0	—	Mutual damping of the Mass 2 - Mass 3 shaft section (pu). 0 disables.
H_turb3	Mass 3: H (MWs/MVA)	double	1	—	Inertia constant of Mass 3.
D_turb3	Mass 3: D (pu)	double	0	—	Self (absolute) damping torque coefficient of Mass 3. 0 disables.
tm_turb3_fb	Mass 3: Tm (fallback, pu)	double	0	—	Constant per-unit mechanical torque applied to Mass 3 when its Tmech3 input is left unwired.
K_t3_t4	Mass 3 - Mass 4: K (pu torque/rad)	double	30	—	Torsional stiffness of the shaft section between Mass 3 and Mass 4 (pu torque per electrical radian).
Dmut_t3_t4	Mass 3 - Mass 4: Dmut (pu)	double	0	—	Mutual damping of the Mass 3 - Mass 4 shaft section (pu). 0 disables.
H_turb4	Mass 4: H (MWs/MVA)	double	1	—	Inertia constant of Mass 4 (the outermost mass).
D_turb4	Mass 4: D (pu)	double	0	—	Self (absolute) damping torque coefficient of Mass 4. 0 disables.
tm_turb4_fb	Mass 4: Tm (fallback, pu)	double	0	—	Constant per-unit mechanical torque applied to Mass 4 when its Tmech4 input is left unwired.
K_gen_exc	Rotor - Extra: K (pu torque/rad)	double	30	—	Torsional stiffness of the shaft section between the rotor and the extra mass (pu torque per electrical radian).
Dmut_gen_exc	Rotor - Extra: Dmut (pu)	double	0	—	Mutual damping of the rotor - extra-mass shaft section (pu). 0 disables.
H_exc	Extra mass: H (MWs/MVA)	double	0.1	—	Inertia constant of the extra rotor mass.
D_exc	Extra mass: D (pu)	double	0	—	Self (absolute) damping torque coefficient of the extra mass. 0 disables.
tm_exc_fb	Extra mass: Tm (fallback, pu)	double	0	—	Constant per-unit mechanical torque applied to the extra mass. It has no torque-input pin, so this fallback is always in effect (normally 0 - the extra mass is undriven).

Signal Names

Name	Label	Type	Default	Units	Description
current_name_a	Phase A current name	string	Ia	A (A, kA)	Signal name for the Phase A stator current. Blank = skip. Value scaled to the chosen unit.
current_name_b	Phase B current name	string	Ib	A (A, kA)	Signal name for the Phase B stator current. Blank = skip. Value scaled to the chosen unit.
current_name_c	Phase C current name	string	Ic	A (A, kA)	Signal name for the Phase C stator current. Blank = skip. Value scaled to the chosen unit.
speed_name	Speed name	string	w	—	Signal name for the rotor speed (pu of synchronous). Blank = skip.
slip_name	Slip name	string	slip	—	Signal name for the slip s = 1 - w (pu). Positive = subsynchronous (motoring), negative = supersynchronous (generating). Blank = skip.
te_name	Elec. torque name	string	Te	pu (pu, N·m)	Signal name for the developed electrical torque Te. Generator convention (positive = generating). Blank = skip. Value scaled to the chosen unit.
p_signal_name	P signal name	string	P	MW (W, kW, MW)	Signal name for filtered real-power output P (generator convention: positive = injected). Blank = skip. Value scaled to the chosen unit.
q_signal_name	Q signal name	string	Q	MVAr (VAr, kVAr, MVAr)	Signal name for filtered reactive-power output Q (generator convention: positive = injected). Blank = skip. Value scaled to the chosen unit.

Shaft Signals

Name	Label	Type	Default	Units	Description
gen_speed_name	Rotor speed name	string	w_rotor	—	Signal name for the machine rotor mass speed (pu). Blank = skip.
gen_angle_name	Rotor angle name	string	(empty)	—	Signal name for the machine rotor mass angle (electrical radians, relative to the synchronous reference). Blank = skip.
turb1_speed_name	Mass 1 speed name	string	w_m1	—	Signal name for the Mass 1 speed (pu). Blank = skip.
turb1_angle_name	Mass 1 angle name	string	(empty)	—	Signal name for the Mass 1 angle (electrical radians). Blank = skip.
turb2_speed_name	Mass 2 speed name	string	(empty)	—	Signal name for the Mass 2 speed (pu). Blank = skip.
turb2_angle_name	Mass 2 angle name	string	(empty)	—	Signal name for the Mass 2 angle (electrical radians). Blank = skip.
turb3_speed_name	Mass 3 speed name	string	(empty)	—	Signal name for the Mass 3 speed (pu). Blank = skip.
turb3_angle_name	Mass 3 angle name	string	(empty)	—	Signal name for the Mass 3 angle (electrical radians). Blank = skip.
turb4_speed_name	Mass 4 speed name	string	(empty)	—	Signal name for the Mass 4 speed (pu). Blank = skip.
turb4_angle_name	Mass 4 angle name	string	(empty)	—	Signal name for the Mass 4 angle (electrical radians). Blank = skip.
exc_speed_name	Extra mass speed name	string	(empty)	—	Signal name for the extra mass speed (pu). Blank = skip.
exc_angle_name	Extra mass angle name	string	(empty)	—	Signal name for the extra mass angle (electrical radians). Blank = skip.

Power Flow

Name	Label	Type	Default	Units	Description
pf_p_mw	P (MW)	double	0	—	Scheduled real-power demand (MW) contributed to power flow as a constant-PQ load (PSSE LOAD PL column). Positive = consumed from the bus (motor). Power-flow only - separate from the EMT settings.
pf_q_mvar	Q (MVAr)	double	0	—	Scheduled reactive-power demand (MVAr) contributed to power flow as a constant-PQ load (PSSE LOAD QL column). Positive = consumed (inductive) - an induction machine always draws magnetizing vars. Power-flow only.

Observables

Signal	Type	Default name	Enable	Description
branchCurrent_a	signal	from current_name_a	measure_current	Phase A stator current (out of the machine into the network; negative for a motor drawing current), scaled to the chosen current unit (A / kA).
branchCurrent_b	signal	from current_name_b	measure_current	Phase B stator current (out of the machine into the network), scaled to the chosen current unit (A / kA).
branchCurrent_c	signal	from current_name_c	measure_current	Phase C stator current (out of the machine into the network), scaled to the chosen current unit (A / kA).
speed_meas	signal	from speed_name	measure_speed	Rotor speed (pu of synchronous speed). 1.0 = synchronous; below 1 motoring, above 1 generating.
slip_meas	signal	from slip_name	measure_speed	Slip s = 1 - w (pu). Positive = subsynchronous (motoring), negative = supersynchronous (generating).
te	signal	from te_name	measure_te	Developed (air-gap) electrical torque Te, generator convention (positive = generating, negative = motoring), scaled to the chosen unit (pu / N·m).
p_elec	signal	from p_signal_name	monitor_pq	Filtered real-power output P at the terminals (generator convention: positive = injected into the network; a motor draws P < 0), scaled to the chosen unit (W / kW / MW).
q_elec	signal	from q_signal_name	monitor_pq	Filtered reactive-power output Q at the terminals (generator convention; an induction machine always draws magnetizing vars, so Q < 0), scaled to the chosen unit (VAr / kVAr / MVAr).
speed_gen	signal	from gen_speed_name	measure_shaft	Multi-mass shaft: speed of the machine rotor mass (pu).
angle_gen	signal	from gen_angle_name	measure_shaft	Multi-mass shaft: angle of the machine rotor mass (electrical radians, relative to the synchronous reference).
speed_turb1	signal	from turb1_speed_name	measure_shaft	Multi-mass shaft: speed of Mass 1 (pu).
angle_turb1	signal	from turb1_angle_name	measure_shaft	Multi-mass shaft: angle of Mass 1 (electrical radians, relative to the synchronous reference).
speed_turb2	signal	from turb2_speed_name	measure_shaft	Multi-mass shaft: speed of Mass 2 (pu).
angle_turb2	signal	from turb2_angle_name	measure_shaft	Multi-mass shaft: angle of Mass 2 (electrical radians, relative to the synchronous reference).
speed_turb3	signal	from turb3_speed_name	measure_shaft	Multi-mass shaft: speed of Mass 3 (pu).
angle_turb3	signal	from turb3_angle_name	measure_shaft	Multi-mass shaft: angle of Mass 3 (electrical radians, relative to the synchronous reference).
speed_turb4	signal	from turb4_speed_name	measure_shaft	Multi-mass shaft: speed of Mass 4 (pu).
angle_turb4	signal	from turb4_angle_name	measure_shaft	Multi-mass shaft: angle of Mass 4 (electrical radians, relative to the synchronous reference).
speed_exc	signal	from exc_speed_name	measure_shaft	Multi-mass shaft: speed of the extra rotor mass (pu).
angle_exc	signal	from exc_angle_name	measure_shaft	Multi-mass shaft: angle of the extra rotor mass (electrical radians, relative to the synchronous reference).