Inspecting Models#
First of all, import andes and configure the logger to the WARNING level (30).
import andes
andes.config_logger(30)
Inspect Model Equations#
Create an empty andes.System object and call prepare(nomp=True) to generate equations and pretty print, where nomp disables multiprocessing so that equations can be properly returned. This operation may take a moment.
To only generate equations for a specific model, such as GENCLS, do:
ss = andes.System()
ss.GENCLS.prepare()
List all models#
print(ss.supported_models())
Supported Groups and Models
Group | Models
-------------------+----------------------------------------------------------
ACLine | Line
ACShort | Jumper
ACTopology | Bus
Calculation | ACE, ACEc, COI
Collection | Area
DCLink | Ground, R, L, C, RCp, RCs, RLs, RLCs, RLCp
DCTopology | Node
DG | PVD1, ESD1, EV1, EV2
DGProtection | DGPRCT1, DGPRCTExt
DynLoad | ZIP, FLoad
Exciter | EXDC2, IEEEX1, ESDC2A, EXST1, ESST3A, SEXS, IEEET1,
| EXAC1, EXAC4, ESST4B, AC8B, IEEET3, ESAC1A, ESST1A
FreqMeasurement | BusFreq, BusROCOF
Information | Summary
Motor | Motor3, Motor5
PLL | PLL1
PSS | IEEEST, ST2CUT
PhasorMeasurement | PMU
RenAerodynamics | WTARA1, WTARV1
RenExciter | REECA1, REECA1E, REECA1G
RenGen | REGCA1, REGCP1, REGCV1, REGCV2
RenGovernor | WTDTA1, WTDS
RenPitch | WTPTA1
RenPlant | REPCA1
RenTorque | WTTQA1
StaticACDC | VSCShunt
StaticGen | PV, Slack
StaticLoad | PQ
StaticShunt | Shunt, ShuntTD, ShuntSw
SynGen | GENCLS, GENROU, PLBVFU1, GENROUOS
TimedEvent | Toggle, Fault, Alter
TurbineGov | TG2, TGOV1, TGOV1DB, TGOV1N, TGOV1NDB, IEEEG1, IEESGO,
| GAST, HYGOV, HYGOVDB
Undefined | TimeSeries
VoltComp | IEEEVC
Check model documentation#
To check the documentation for the model, print the return of doc() for the model instance.
For example, the documentation for GENCLS can be printed with
print(ss.GENCLS.doc())
Model <GENCLS> in Group <SynGen>
Classical generator model.
Parameters
Name | Description | Default | Unit | Properties
--------+--------------------------+---------+------+-------------------------
idx | unique device idx | | |
u | connection status | 1 | bool |
name | device name | | |
bus | interface bus id | | | mandatory
gen | static generator index | | | mandatory
coi | center of inertia index | | |
coi2 | center of inertia index | | |
Sn | Power rating | 100 | MVA |
Vn | AC voltage rating | 110 | |
fn | rated frequency | 60 | |
D | Damping coefficient | 0 | | power
M | machine start up time | 6 | | non_zero,non_negative,po
| (2H) | | | wer
ra | armature resistance | 0 | | z
xl | leakage reactance | 0 | | z
xd1 | d-axis transient | 0.302 | | z
| reactance | | |
kp | active power feedback | 0 | |
| gain | | |
kw | speed feedback gain | 0 | |
S10 | first saturation factor | 0 | |
S12 | second saturation factor | 1 | |
gammap | P ratio of linked static | 1 | |
| gen | | |
gammaq | Q ratio of linked static | 1 | |
| gen | | |
subidx | Generator idx in plant; | 0 | |
| only used by PSS/E data | | |
Variables
Name | Type | Description | Unit | Properties
--------+----------+-----------------------------------+----------+-----------
delta | State | rotor angle | rad | v_str
omega | State | rotor speed | pu (Hz) | v_str
Id | Algeb | d-axis current | | v_str
Iq | Algeb | q-axis current | | v_str
vd | Algeb | d-axis voltage | | v_str
vq | Algeb | q-axis voltage | | v_str
tm | Algeb | mechanical torque | | v_str
te | Algeb | electric torque | | v_str
vf | Algeb | excitation voltage | pu | v_str
XadIfd | Algeb | d-axis armature excitation | p.u (kV) | v_str
| | current | |
Pe | Algeb | active power injection | | v_str
Qe | Algeb | reactive power injection | | v_str
psid | Algeb | d-axis flux | | v_str
psiq | Algeb | q-axis flux | | v_str
a | ExtAlgeb | Bus voltage phase angle | |
v | ExtAlgeb | Bus voltage magnitude | |
Initialization Equations
Name | Type | Initial Value
--------+----------+----------------------------
delta | State | delta0
omega | State | u
Id | Algeb | u * Id0
Iq | Algeb | u * Iq0
vd | Algeb | u * vd0
vq | Algeb | u * vq0
tm | Algeb | tm0
te | Algeb | u * tm0
vf | Algeb | u * vf0
XadIfd | Algeb | u * vf0
Pe | Algeb | u * (vd0 * Id0 + vq0 * Iq0)
Qe | Algeb | u * (vq0 * Id0 - vd0 * Iq0)
psid | Algeb | u * psid0
psiq | Algeb | u * psiq0
a | ExtAlgeb |
v | ExtAlgeb |
Differential Equations
Name | Type | RHS of Equation "T x' = f(x, y)" | T (LHS)
-------+-------+----------------------------------+--------
delta | State | u * (2 * pi * fn) * (omega - 1) |
omega | State | u * (tm - te - D * (omega - 1)) | M
Algebraic Equations
Name | Type | RHS of Equation "0 = g(x, y)"
--------+----------+---------------------------------
Id | Algeb | + xq * Id - vf+ psid
Iq | Algeb | + xq * Iq+ psiq
vd | Algeb | u * v * sin(delta - a) - vd
vq | Algeb | u * v * cos(delta - a) - vq
tm | Algeb | tm0 - tm
te | Algeb | u * (psid * Iq - psiq * Id) - te
vf | Algeb | u * vf0 - vf
XadIfd | Algeb | u * vf0 - XadIfd
Pe | Algeb | u * (vd * Id + vq * Iq) - Pe
Qe | Algeb | u * (vq * Id - vd * Iq) - Qe
psid | Algeb | u * (ra*Iq + vq) - psid
psiq | Algeb | u * (ra*Id + vd) + psiq
a | ExtAlgeb | -u * (vd * Id + vq * Iq)
v | ExtAlgeb | -u * (vq * Id - vd * Iq)
Services
Name | Equation | Type
---------+------------------------------------------------------+-------------
p0 | p0s * gammap | ConstService
q0 | q0s * gammaq | ConstService
_V | v * exp(1j * a) | ConstService
_S | p0 - 1j * q0 | ConstService
_I | _S / conj(_V) | ConstService
_E | _V + _I * (ra + 1j * xq) | ConstService
_deltac | log(_E / abs(_E)) | ConstService
delta0 | u * im(_deltac) | ConstService
vdq | u * (_V * exp(1j * 0.5 * pi - _deltac)) | ConstService
Idq | u * (_I * exp(1j * 0.5 * pi - _deltac)) | ConstService
Id0 | re(Idq) | ConstService
Iq0 | im(Idq) | ConstService
vd0 | re(vdq) | ConstService
vq0 | im(vdq) | ConstService
tm0 | u * ((vq0 + ra * Iq0) * Iq0 + (vd0 + ra * Id0) * | ConstService
| Id0) |
psid0 | u * (ra * Iq0) + vq0 | ConstService
psiq0 | -u * (ra * Id0) - vd0 | ConstService
vf0 | (vq0 + ra * Iq0) + xq * Id0 | ConstService
Config Fields in [GENCLS]
Option | Value | Info | Acceptable values
--------------+-------+------------------------------------+------------------
allow_adjust | 1 | allow adjusting upper or lower | (0, 1)
| | limits |
adjust_lower | 0 | adjust lower limit | (0, 1)
adjust_upper | 1 | adjust upper limit | (0, 1)
vf_lower | 1 | lower limit for vf warning |
vf_upper | 5 | upper limit for vf warning |
Pretty print of variables#
All symbols are stored in the attributes of Model.syms. For example,
ss.GENCLS.syms.xy
\[\begin{split}\displaystyle \left[\begin{matrix}\delta\\\omega\\I_{d}\\I_{q}\\V_{d}\\V_{q}\\\tau_{m}\\\tau_{e}\\v_{f}\\X_{ad}I_{fd}\\P_{e}\\Q_{e}\\\psi_{d}\\\psi_{q}\\\theta\\V\end{matrix}\right]\end{split}\]
Differential variables comes before algebraic variables.
ss.GENCLS.states
OrderedDict([('delta', State: GENCLS.delta, []),
('omega', State: GENCLS.omega, [])])
ss.GENCLS.algebs
OrderedDict([('Id', Algeb: GENCLS.Id, []),
('Iq', Algeb: GENCLS.Iq, []),
('vd', Algeb: GENCLS.vd, []),
('vq', Algeb: GENCLS.vq, []),
('tm', Algeb: GENCLS.tm, []),
('te', Algeb: GENCLS.te, []),
('vf', Algeb: GENCLS.vf, []),
('XadIfd', Algeb: GENCLS.XadIfd, []),
('Pe', Algeb: GENCLS.Pe, []),
('Qe', Algeb: GENCLS.Qe, []),
('psid', Algeb: GENCLS.psid, []),
('psiq', Algeb: GENCLS.psiq, [])])
Pretty print of equations#
Formatted equations are stored in each model. The following attributes of Model.syms are available for equation printing.
f: differential equations
g: algebraic equations
df: df/dxy
dg: dg/dxy
ss.GENCLS.syms.f
\[\begin{split}\displaystyle \left[\begin{matrix}2 \pi f u \left(\omega - 1\right)\\u \left(- D \left(\omega - 1\right) - \tau_{e} + \tau_{m}\right)\end{matrix}\right]\end{split}\]
ss.GENCLS.syms.g
\[\begin{split}\displaystyle \left[\begin{matrix}I_{d} xq + \psi_{d} - v_{f}\\I_{q} xq + \psi_{q}\\V u \sin{\left(\delta - \theta \right)} - V_{d}\\V u \cos{\left(\delta - \theta \right)} - V_{q}\\- \tau_{m} + \tau_{m0}\\- \tau_{e} + u \left(- I_{d} \psi_{q} + I_{q} \psi_{d}\right)\\u v_{f0} - v_{f}\\- X_{ad}I_{fd} + u v_{f0}\\- P_{e} + u \left(I_{d} V_{d} + I_{q} V_{q}\right)\\- Q_{e} + u \left(I_{d} V_{q} - I_{q} V_{d}\right)\\- \psi_{d} + u \left(I_{q} r_{a} + V_{q}\right)\\\psi_{q} + u \left(I_{d} r_{a} + V_{d}\right)\\- u \left(I_{d} V_{d} + I_{q} V_{q}\right)\\- u \left(I_{d} V_{q} - I_{q} V_{d}\right)\end{matrix}\right]\end{split}\]
ss.GENCLS.syms.df
\[\begin{split}\displaystyle \left[\begin{array}{cccccccccccccccc}0 & 2 \pi f u & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0\\0 & - D u & 0 & 0 & 0 & 0 & u & - u & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0\end{array}\right]\end{split}\]
ss.GENCLS.syms.dg
\[\begin{split}\displaystyle \left[\begin{array}{cccccccccccccccc}0 & 0 & xq & 0 & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 1 & 0 & 0 & 0\\0 & 0 & 0 & xq & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0\\V u \cos{\left(\delta - \theta \right)} & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & - V u \cos{\left(\delta - \theta \right)} & u \sin{\left(\delta - \theta \right)}\\- V u \sin{\left(\delta - \theta \right)} & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & V u \sin{\left(\delta - \theta \right)} & u \cos{\left(\delta - \theta \right)}\\0 & 0 & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0\\0 & 0 & - \psi_{q} u & \psi_{d} u & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0 & I_{q} u & - I_{d} u & 0 & 0\\0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0 & 0 & 0 & 0\\0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0 & 0 & 0\\0 & 0 & V_{d} u & V_{q} u & I_{d} u & I_{q} u & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0 & 0\\0 & 0 & V_{q} u & - V_{d} u & - I_{q} u & I_{d} u & 0 & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0 & 0\\0 & 0 & 0 & r_{a} u & 0 & u & 0 & 0 & 0 & 0 & 0 & 0 & -1 & 0 & 0 & 0\\0 & 0 & r_{a} u & 0 & u & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0\\0 & 0 & - V_{d} u & - V_{q} u & - I_{d} u & - I_{q} u & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0\\0 & 0 & - V_{q} u & V_{d} u & I_{q} u & - I_{d} u & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0\end{array}\right]\end{split}\]
Pretty print of services#
The list of services is in services.
ss.GENCLS.services
OrderedDict([('p0', ConstService: GENCLS.p0, v=0.0),
('q0', ConstService: GENCLS.q0, v=0.0),
('_V', ConstService: GENCLS._V, v=0.0),
('_S', ConstService: GENCLS._S, v=0.0),
('_I', ConstService: GENCLS._I, v=0.0),
('_E', ConstService: GENCLS._E, v=0.0),
('_deltac', ConstService: GENCLS._deltac, v=0.0),
('delta0', ConstService: GENCLS.delta0, v=0.0),
('vdq', ConstService: GENCLS.vdq, v=0.0),
('Idq', ConstService: GENCLS.Idq, v=0.0),
('Id0', ConstService: GENCLS.Id0, v=0.0),
('Iq0', ConstService: GENCLS.Iq0, v=0.0),
('vd0', ConstService: GENCLS.vd0, v=0.0),
('vq0', ConstService: GENCLS.vq0, v=0.0),
('tm0', ConstService: GENCLS.tm0, v=0.0),
('psid0', ConstService: GENCLS.psid0, v=0.0),
('psiq0', ConstService: GENCLS.psiq0, v=0.0),
('vf0', ConstService: GENCLS.vf0, v=0.0)])
Service equations are in Model.syms.s For example, services of GENCLS is in
ss.GENCLS.syms.s
[P_{0s}*\gamma_P,
Q_{0s}*\gamma_Q,
V*exp(I*\theta),
P_0 - I*Q_0,
S/conj(V_c),
I_c*(r_a + I*xq) + V_c,
log(E/Abs(E)),
u*im(\delta_c),
V_c*u*exp(-\delta_c + 0.5*I*pi),
I_c*u*exp(-\delta_c + 0.5*I*pi),
re(I_{dq}),
im(I_{dq}),
re(V_{dq}),
im(V_{dq}),
u*(I_{d0}*(I_{d0}*r_a + V_{d0}) + I_{q0}*(I_{q0}*r_a + V_{q0})),
I_{q0}*r_a*u + V_{q0},
-I_{d0}*r_a*u - V_{d0},
I_{d0}*xq + I_{q0}*r_a + V_{q0}]