mp.form_ac
- class mp.form_ac
Bases:
mp.form
mp.form_ac
- Abstract base class for MATPOWER AC formulations.Used as a mix-in class for all network model element classes with an AC network model formulation. That is, each concrete network model element class with an AC formulation must inherit, at least indirectly, from both
mp.nm_element
andmp.form_ac
.mp.form_ac
defines the complex port injections as functions of the state variables \(\X\), that is, the complex voltages \(\V\) and non-voltage states \(\Z\). They are defined in terms of 3 components, the linear current injection and linear power injection components,(3.2)\[\begin{split}\Ilin(\X) &= \left[\begin{array}{cc}\YY & \LL\end{array}\right] \X + \iv \\ &= \YY \V + \LL \Z + \iv\end{split}\](3.3)\[\begin{split}\Slin(\X) &= \left[\begin{array}{cc}\MM & \NN\end{array}\right] \X + \sv \\ &= \MM \V + \NN \Z + \sv,\end{split}\]and an arbitrary nonlinear injection component represented by \(\Snln(\X)\) or \(\Inln(\X)\). The full complex power and current port injection functions implemented by
mp.form_ac
, are respectively(3.4)\[\begin{split}\GS(\X) &= \dV \conj{\left( \Ilin(\X) \right)} + \Slin(\X) + \Snln(\X) \\ &= \dV \conj{\left( \YY \V + \LL \Z + \iv \right)} + \MM \V + \NN \Z + \sv + \Snln(\X)\end{split}\](3.5)\[\begin{split}\GI(\X) &= \Ilin(\X) + \cdiag{\Slin(\X)} \inVc + \Inln(\X) \\ &= \YY \V + \LL \Z + \iv + \cdiag{\MM \V + \NN \Z + \sv} \inVc + \Inln(\X)\end{split}\]where \(\YY\), \(\LL\), \(\MM\), \(\NN\), \(\iv\), and \(\sv\), along with \(\Snln(\X)\) or \(\Inln(\X)\), are the model parameters.
For more details, see the AC Formulations section in the MATPOWER Developer’s Manual and the derivations in MATPOWER Technical Note 5.
- mp.form_dc Properties:
Y
- \(n_p n_k \times n_n\) matrix \(\YY\) of model parametersL
- \(n_p n_k \times n_\Z\) matrix \(\LL\) of model parametersM
- \(n_p n_k \times n_n\) matrix \(\MM\) of model parametersN
- \(n_p n_k \times n_\Z\) matrix \(\NN\) of model parametersi
- \(n_p n_k \times 1\) vector \(\iv\) of model parameterss
- \(n_p n_k \times 1\) vector \(\sv\) of model parametersparams_ncols
- specify number of columns for each parameterinln
- function to compute \(\Inln(\X)\)snln
- function to compute \(\Snln(\X)\)inln_hess
- function to compute Hessian of \(\Inln(\X)\)snln_hess
- function to compute Hessian of \(\Snln(\X)\)
- mp.form_dc Methods:
model_params()
- get network model element parameters ({'Y', 'L', 'M', 'N', 'i', 's'}
)model_zvars()
- get cell array of names of non-voltage state variables ({'zr', 'zi'}
)port_inj_current()
- compute port current injections from network stateport_inj_power()
- compute port power injections from network stateport_inj_current_hess()
- compute Hessian of port current injectionsport_inj_power_hess()
- compute Hessian of port power injectionsport_inj_current_jac()
- abstract method to compute voltage-related Jacobian termsport_inj_current_hess_v()
- abstract method to compute voltage-related Hessian termsport_inj_current_hess_vz()
- abstract method to compute voltage-related Hessian termsport_inj_power_jac()
- abstract method to compute voltage-related Jacobian termsport_inj_power_hess_v()
- abstract method to compute voltage-related Hessian termsport_inj_power_hess_vz()
- abstract method to compute voltage-related Hessian termsport_apparent_power_lim_fcn()
- compute port squared apparent power injection constraintsport_active_power_lim_fcn()
- compute port active power injection constraintsport_active_power2_lim_fcn()
- compute port squared active power injection constraintsport_current_lim_fcn()
- compute port squared current injection constraintsport_apparent_power_lim_hess()
- compute port squared apparent power injection Hessianport_active_power_lim_hess()
- compute port active power injection Hessianport_active_power2_lim_hess()
- compute port squared active power injection Hessianport_current_lim_hess()
- compute port squared current injection Hessianaux_data_va_vm()
- abstract method to return voltage angles/magnitudes from auxiliary data
See also
mp.form
,mp.form_acc
,mp.form_acp
,mp.form_dc
,mp.nm_element
.- Property Summary
- Y = []
(double) \(n_p n_k \times n_n\) matrix \(\YY\) of model parameter coefficients for \(\V\)
- L = []
(double) \(n_p n_k \times n_\Z\) matrix \(\LL\) of model parameter coefficients for \(\Z\)
- M = []
(double) \(n_p n_k \times n_n\) matrix \(\MM\) of model parameter coefficients for \(\V\)
- N = []
(double) \(n_p n_k \times n_\Z\) matrix \(\NN\) of model parameter coefficients for \(\Z\)
- i = []
(double) \(n_p n_k \times 1\) vector \(\iv\) of model parameters
- s = []
(double) \(n_p n_k \times 1\) vector \(\sv\) of model parameters
- param_ncols = struct('Y',2,'L',3,'M',2,'N',3,'i',1,'s',1)
(struct) specify number of columns for each parameter, where
1 => single column (i.e. a vector)
2 => \(n_p\) columns
3 => \(n_\Z\) columns
- inln = ''
(function handle) function to compute \(\Inln(\X)\)
- snln = ''
(function handle) function to compute \(\Snln(\X)\)
- inln_hess = ''
(function handle) function to compute Hessian of \(\Inln(\X)\)
- snln_hess = ''
(function handle) function to compute Hessian of \(\Snln(\X)\)
- Method Summary
- model_params()
Get cell array of names of model parameters, i.e.
{'Y', 'L', 'M', 'N', 'i', 's'}
.
- model_zvars()
Get cell array of names of non-voltage state variables, i.e.
{'zr', 'zi'}
.
- port_inj_current(x_, sysx, idx)
Compute port complex current injections from network state.
I = nme.port_inj_current(x_, sysx) I = nme.port_inj_current(x_, sysx, idx) [I, Iv1, Iv2] = nme.port_inj_current(...) [I, Iv1, Iv2, Izr, Izi] = nme.port_inj_current(...)
Compute the complex current injections for all or a selected subset of ports and, optionally, the components of the Jacobian, that is, the sparse matrices of partial derivatives with respect to each real component of the state. The voltage portion, which depends on the formulation (polar vs cartesian), is delegated to the
port_inj_current_jac()
method implemented by the appropriate subclass.The state can be provided as a stacked aggregate of the state variables (port voltages and non-voltage states) for the full collection of network model elements of this type, or as the combined state for the entire network.
- Inputs:
x_ (complex double) – state vector \(\X\)
sysx (0 or 1) – which state is provided in
x_
0 – class aggregate state
1 – (default) full system state
idx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Outputs:
I (complex double) – vector of port complex current injections, \(\GI(\X)\)
Iv1 (complex double) – Jacobian of port complex current injections w.r.t 1st voltage component, \(\GI_\Va\) (polar) or \(\GI_\Vr\) (cartesian)
Iv2 (complex double) – Jacobian of port complex current injections w.r.t 2nd voltage component, \(\GI_\Vm\) (polar) or \(\GI_\Vi\) (cartesian)
Izr (complex double) – Jacobian of port complex current injections w.r.t real part of non-voltage state, \(\GI_\Zr\)
Izi (complex double) – Jacobian of port complex current injections w.r.t imaginary part of non-voltage state, \(\GI_\Zi\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
.
- port_inj_power(x_, sysx, idx)
Compute port complex power injections from network state.
S = nme.port_inj_power(x_, sysx) S = nme.port_inj_power(x_, sysx, idx) [S, Sv1, Sv2] = nme.port_inj_power(...) [S, Sv1, Sv2, Szr, Szi] = nme.port_inj_power(...)
Compute the complex power injections for all or a selected subset of ports and, optionally, the components of the Jacobian, that is, the sparse matrices of partial derivatives with respect to each real component of the state. The voltage portion, which depends on the formulation (polar vs cartesian), is delegated to the
port_inj_power_jac()
method implemented by the appropriate subclass.The state can be provided as a stacked aggregate of the state variables (port voltages and non-voltage states) for the full collection of network model elements of this type, or as the combined state for the entire network.
- Inputs:
x_ (complex double) – state vector \(\X\)
sysx (0 or 1) – which state is provided in
x_
0 – class aggregate state
1 – (default) full system state
idx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Outputs:
S (complex double) – vector of port complex power injections, \(\GS(\X)\)
Sv1 (complex double) – Jacobian of port complex power injections w.r.t 1st voltage component, \(\GS_\Va\) (polar) or \(\GS_\Vr\) (cartesian)
Sv2 (complex double) – Jacobian of port complex power injections w.r.t 2nd voltage component, \(\GS_\Vm\) (polar) or \(\GS_\Vi\) (cartesian)
Szr (complex double) – Jacobian of port complex power injections w.r.t real part of non-voltage state, \(\GS_\Zr\)
Szi (complex double) – Jacobian of port complex power injections w.r.t imaginary part of non-voltage state, \(\GS_\Zi\).
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_current()
.
- port_inj_current_hess(x_, lam, sysx, idx)
Compute Hessian of port current injections from network state.
H = nme.port_inj_current_hess(x_, lam) H = nme.port_inj_current_hess(x_, lam, sysx) H = nme.port_inj_current_hess(x_, lam, sysx, idx)
Compute a sparse Hessian matrix for all or a selected subset of ports. Rather than a full, 3-dimensional Hessian, it computes the Jacobian of the vector obtained by muliplying the transpose of the port current injection Jacobian by a vector \(\lam\).
- Inputs:
x_ (complex double) – state vector \(\X\)
lam (double) – vector \(\lam\) of multipliers, one for each port
sysx (0 or 1) – which state is provided in
x_
0 – class aggregate state
1 – (default) full system state
idx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Outputs:
H (complex double) – sparse Hessian matrix of port complex current injections corresponding to specified \(\lam\), namely \(\GI_{\X\X}(\lam)\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_current()
.
- port_inj_power_hess(x_, lam, sysx, idx)
Compute Hessian of port power injections from network state.
H = nme.port_inj_power_hess(x_, lam) H = nme.port_inj_power_hess(x_, lam, sysx) H = nme.port_inj_power_hess(x_, lam, sysx, idx)
Compute a sparse Hessian matrix for all or a selected subset of ports. Rather than a full, 3-dimensional Hessian, it computes the Jacobian of the vector obtained by muliplying the transpose of the port power injection Jacobian by a vector \(\lam\).
- Inputs:
x_ (complex double) – state vector \(\X\)
lam (double) – vector \(\lam\) of multipliers, one for each port
sysx (0 or 1) – which state is provided in
x_
0 – class aggregate state
1 – (default) full system state
idx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Outputs:
H (complex double) – sparse Hessian matrix of port complex power injections corresponding to specified \(\lam\), namely \(\GS_{\X\X}(\lam)\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
.
- port_inj_current_jac(n, v_, Y, M, invdiagvic, diagSlincJ)
Abstract method to compute voltage-related Jacobian terms.
Called by
port_inj_current()
to compute voltage-related Jacobian terms. Seemp.form_acc.port_inj_current_jac()
andmp.form_acp.port_inj_current_jac()
for details.
- port_inj_current_hess_v(x_, lam, v_, z_, diaginvic, Y, M, diagSlincJ, dlamJ)
Abstract method to compute voltage-related Hessian terms.
Called by
port_inj_current_hess()
to compute voltage-related Hessian terms. Seemp.form_acc.port_inj_current_hess_v()
andmp.form_acp.port_inj_current_hess_v()
for details.
- port_inj_current_hess_vz(x_, lam, v_, z_, diaginvic, N, dlamJ)
Abstract method to compute voltage-related Hessian terms.
Called by
port_inj_current_hess()
to compute voltage/non-voltage-related Hessian terms. Seemp.form_acc.port_inj_current_hess_vz()
andmp.form_acp.port_inj_current_hess_vz()
for details.
- port_inj_power_jac(n, v_, Y, M, diagv, diagvi, diagIlincJ)
Abstract method to compute voltage-related Jacobian terms.
Called by
port_inj_power()
to compute voltage-related Jacobian terms. Seemp.form_acc.port_inj_power_jac()
andmp.form_acp.port_inj_power_jac()
for details.
- port_inj_power_hess_v(x_, lam, v_, z_, diagvi, Y, M, diagIlincJ, dlamJ)
Abstract method to compute voltage-related Hessian terms.
Called by
port_inj_power_hess()
to compute voltage-related Hessian terms. Seemp.form_acc.port_inj_power_hess_v()
andmp.form_acp.port_inj_power_hess_v()
for details.
- port_inj_power_hess_vz(x_, lam, v_, z_, diagvi, L, dlamJ)
Abstract method to compute voltage-related Hessian terms.
Called by
port_inj_power_hess()
to compute voltage/non-voltage-related Hessian terms. Seemp.form_acc.port_inj_power_hess_vz()
andmp.form_acp.port_inj_power_hess_vz()
for details.
- port_apparent_power_lim_fcn(x_, nm, idx, hmax)
Compute port squared apparent power injection constraints.
h = nme.port_apparent_power_lim_fcn(x_, nm, idx, hmax) [h, dh] = nme.port_apparent_power_lim_fcn(x_, nm, idx, hmax)
Compute constraint function and optionally the Jacobian for the limit on port squared apparent power injections based on complex outputs of
port_inj_power()
.- Inputs:
x_ (complex double) – state vector \(\X\)
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
hmax (double) – vector of squared apparent power limits
- Outputs:
h (double) – constraint function, \(\h^\mathrm{flow}(\x)\)
dh (double) – constraint Jacobian, \(\h_\x^\mathrm{flow}\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
.
- port_active_power_lim_fcn(x_, nm, idx, hmax)
Compute port active power injection constraints.
h = nme.port_active_power_lim_fcn(x_, nm, idx, hmax) [h, dh] = nme.port_active_power_lim_fcn(x_, nm, idx, hmax)
Compute constraint function and optionally the Jacobian for the limit on port active power injections based on complex outputs of
port_inj_power()
.- Inputs:
x_ (complex double) – state vector \(\X\)
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
hmax (double) – vector of active power limits
- Outputs:
h (double) – constraint function, \(\h^\mathrm{flow}(\x)\)
dh (double) – constraint Jacobian, \(\h_\x^\mathrm{flow}\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
.
- port_active_power2_lim_fcn(x_, nm, idx, hmax)
Compute port squared active power injection constraints.
h = nme.port_active_power2_lim_fcn(x_, nm, idx, hmax) [h, dh] = nme.port_active_power2_lim_fcn(x_, nm, idx, hmax)
Compute constraint function and optionally the Jacobian for the limit on port squared active power injections based on complex outputs of
port_inj_power()
.- Inputs:
x_ (complex double) – state vector \(\X\)
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
hmax (double) – vector of squared active power limits
- Outputs:
h (double) – constraint function, \(\h^\mathrm{flow}(\x)\)
dh (double) – constraint Jacobian, \(\h_\x^\mathrm{flow}\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
.
- port_current_lim_fcn(x_, nm, idx, hmax)
Compute port squared current injection constraints.
h = nme.port_current_lim_fcn(x_, nm, idx, hmax) [h, dh] = nme.port_current_lim_fcn(x_, nm, idx, hmax)
Compute constraint function and optionally the Jacobian for the limit on port squared current injections based on complex outputs of
port_inj_current()
.- Inputs:
x_ (complex double) – state vector \(\X\)
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
hmax (double) – vector of squared current limits
- Outputs:
h (double) – constraint function, \(\h^\mathrm{flow}(\x)\)
dh (double) – constraint Jacobian, \(\h_\x^\mathrm{flow}\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_current()
.
- port_apparent_power_lim_hess(x_, lam, nm, idx)
Compute port squared apparent power injection Hessian.
d2H = nme.port_apparent_power_lim_hess(x_, lam, nm, idx)
Compute a sparse Hessian matrix for all or a selected subset of ports. Rather than a full, 3-dimensional Hessian, it computes the Jacobian of the vector obtained by muliplying the transpose of the constraint Jacobian by a vector \(\muv\). Results are based on the complex outputs of
port_inj_power()
andport_inj_power_hess()
.- Inputs:
x_ (complex double) – state vector \(\X\)
lam (double) – vector \(\muv\) of multipliers, one for each port
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Output:
d2H (double) – sparse constraint Hessian matrix, \(\h_{\x\x}^\mathrm{flow}(\muv)\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
,port_inj_power_hess()
.
- port_active_power_lim_hess(x_, lam, nm, idx)
Compute port active power injection Hessian.
d2H = nme.port_active_power_lim_hess(x_, lam, nm, idx)
Compute a sparse Hessian matrix for all or a selected subset of ports. Rather than a full, 3-dimensional Hessian, it computes the Jacobian of the vector obtained by muliplying the transpose of the constraint Jacobian by a vector \(\muv\). Results are based on the complex outputs of
port_inj_power()
andport_inj_power_hess()
.- Inputs:
x_ (complex double) – state vector \(\X\)
lam (double) – vector \(\muv\) of multipliers, one for each port
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Output:
d2H (double) – sparse constraint Hessian matrix, \(\h_{\x\x}^\mathrm{flow}(\muv)\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
,port_inj_power_hess()
.
- port_active_power2_lim_hess(x_, lam, nm, idx)
Compute port squared active power injection Hessian.
d2H = nme.port_active_power2_lim_hess(x_, lam, nm, idx)
Compute a sparse Hessian matrix for all or a selected subset of ports. Rather than a full, 3-dimensional Hessian, it computes the Jacobian of the vector obtained by muliplying the transpose of the constraint Jacobian by a vector \(\muv\). Results are based on the complex outputs of
port_inj_power()
andport_inj_power_hess()
.- Inputs:
x_ (complex double) – state vector \(\X\)
lam (double) – vector \(\muv\) of multipliers, one for each port
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Output:
d2H (double) – sparse constraint Hessian matrix, \(\h_{\x\x}^\mathrm{flow}(\muv)\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_power()
,port_inj_power_hess()
.
- port_current_lim_hess(x_, lam, nm, idx)
Compute port squared current injection Hessian.
d2H = nme.port_current_lim_hess(x_, lam, nm, idx)
Compute a sparse Hessian matrix for all or a selected subset of ports. Rather than a full, 3-dimensional Hessian, it computes the Jacobian of the vector obtained by muliplying the transpose of the constraint Jacobian by a vector \(\muv\). Results are based on the complex outputs of
port_inj_current()
andport_inj_current_hess()
.- Inputs:
x_ (complex double) – state vector \(\X\)
lam (double) – vector \(\muv\) of multipliers, one for each port
nm (
mp.net_model
) – network model objectidx (integer) – (optional) vector of indices of ports of interest, if empty or missing, returns results corresponding to all ports
- Output:
d2H (double) – sparse constraint Hessian matrix, \(\h_{\x\x}^\mathrm{flow}(\muv)\)
For details on the derivations of the formulas used, see MATPOWER Technical Note 5.
See also
port_inj_current()
,port_inj_current_hess()
.
- aux_data_va_vm(ad)
Abstract method to return voltage angles/magnitudes from auxiliary data.
[va, vm] = nme.aux_data_va_vm(ad)
- Input:
ad (struct) – struct of auxiliary data
- Outputs:
va (double) – vector of voltage angles corresponding to voltage information stored in auxiliary data
vm (double) – vector of voltage magnitudes corresponding to voltage information stored in auxiliary data
Implemented by
mp.form_acc.aux_data_va_vm()
andmp.form_acp.aux_data_va_vm()
.