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 and mp.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 parameters

  • L - \(n_p n_k \times n_\Z\) matrix \(\LL\) of model parameters

  • M - \(n_p n_k \times n_n\) matrix \(\MM\) of model parameters

  • N - \(n_p n_k \times n_\Z\) matrix \(\NN\) of model parameters

  • i - \(n_p n_k \times 1\) vector \(\iv\) of model parameters

  • s - \(n_p n_k \times 1\) vector \(\sv\) of model parameters

  • params_ncols - specify number of columns for each parameter

  • inln - 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:

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'}.

See mp.form.model_params().

model_zvars()

Get cell array of names of non-voltage state variables, i.e. {'zr', 'zi'}.

See mp.form.model_zvars().

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. See mp.form_acc.port_inj_current_jac() and mp.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. See mp.form_acc.port_inj_current_hess_v() and mp.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. See mp.form_acc.port_inj_current_hess_vz() and mp.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. See mp.form_acc.port_inj_power_jac() and mp.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. See mp.form_acc.port_inj_power_hess_v() and mp.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. See mp.form_acc.port_inj_power_hess_vz() and mp.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 object

  • idx (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 object

  • idx (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 object

  • idx (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 object

  • idx (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() and port_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 object

  • idx (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() and port_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 object

  • idx (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() and port_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 object

  • idx (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() and port_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 object

  • idx (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() and mp.form_acp.aux_data_va_vm().