D.2 Matpower Functions

All of the functions listed in this section are found in <MATPOWER>/lib, unless noted otherwise.

Table D-2:Top-Level Simulation Functions

name

description

runpf

power flow

runcpf

AC continuation power flow

runopf

optimal power flow

runuopf

optimal power flow with unit-decommitment

rundcpf

DC power flow

rundcopf

DC optimal power flow

runduopf

DC optimal power flow with unit-decommitment

runopf_w_res

optimal power flow with fixed reserve requirements

most

MOST, Matpower Optimal Scheduling Tool §

Uses AC model by default. Simple wrapper function to set option to use DC model before calling the corresponding general function above. § MOST and its supporting files and functions in the most/ sub-directory are documented in the MOST User’s Manual and listed in its Appendix ??.

Table D-3:Input/Output Functions

name

description

cdf2mpc

converts power flow data from IEEE Common Data Format (CDF) to Matpower format

loadcase

loads data from a Matpower case file or struct into data matrices or a case struct

mpoption

sets and retrieves Matpower options

printpf

pretty prints power flow and OPF results

psse2mpc

converts power flow data from PSS/E RAW format to Matpower format

save2psse

exports Matpower case to PSS/E RAW format

savecase

saves case data to a Matpower case file

Table D-4:Data Conversion Functions

name

description

ext2int

converts case from external to internal indexing

e2i_data

converts arbitrary data from external to internal indexing

e2i_field

converts fields in mpc from external to internal indexing

int2ext

converts case from internal to external indexing

i2e_data

converts arbitrary data from internal to external indexing

i2e_field

converts fields in mpc from internal to external indexing

get_reorder

returns A  with one of its dimensions indexed

set_reorder

assigns B  to A  with one of the dimensions of A  indexed

Table D-5:Power Flow Functions

name

description

calc_v_i_sum

implementation of current summation power flow solver

calc_v_pq_sum

implementation of power summation power flow solver

calc_v_y_sum

implementation of admittance summation power flow solver

dcpf

implementation of DC power flow solver

fdpf

implementation of fast-decoupled power flow solver

gausspf

implementation of Gauss-Seidel power flow solver

make_vcorr

calculate voltage corrections for radial power flow

make_zpv

form loop impedance for PV bus handling in radial power flow

newtonpf

implementation of Newton-method power flow solver (power, polar)

newtonpf_I_cart

implementation of Newton-method power flow solver (current, cartesian)

newtonpf_I_polar

implementation of Newton-method power flow solver (current, polar)

newtonpf_S_cart

implementation of Newton-method power flow solver (power, cartesian)

order_radial

performs oriented ordering of buses and branches for radial power flow

pfsoln

computes branch flows, generator reactive power (and real power for slack bus), updates bus, gen, branch matrices with solved values

radial_pf

wrapper for backward/forward sweep power flow solvers

For radial networks only.

Table D-6:Continuation Power Flow Functions

name

description

cpf_corrector

computes Newton method corrector steps

cpf_current_mpc

construct Matpower case struct for current continuation step

cpf_default_callback

callback function that accumulates, and optionally plots, results from each iteration

cpf_detect_events

detects event intervals and zeros given previous and current event function values

cpf_flim_event_cb

callback function to handle 'FLIM' events

cpf_flim_event

event function for 'FLIM' events, to detect branch MVA flow limits

cpf_nose_event_cb

callback function to handle 'NOSE' events

cpf_nose_event

event function for 'NOSE' events, to detect nose point of continuation curve

cpf_p_jac

computes partial derivatives of parameterization function

cpf_p

computes value of parameterization function at current solution

cpf_plim_event_cb

callback function to handle 'PLIM' events

cpf_plim_event

event function for 'PLIM' events, to detect generator active power limits

cpf_predictor

computes the predicted solution from the current solution and tangent direction

cpf_qlim_event_cb

callback function to handle 'QLIM' events

cpf_qlim_event

event function for 'QLIM' events, to detect generator reactive power limits

cpf_register_callback

registers a CPF callback function to be called by runcpf

cpf_register_event

registers a CPF event function to be called by runcpf

cpf_tangent

computes the normalized tangent vector at the current solution

cpf_target_lam_event_cb

callback function to handle 'TARGET_LAM' events

cpf_target_lam_event

event function for 'TARGET_LAM' events, to detect end of continuation curve or other target λ  value

cpf_vlim_event_cb

callback function to handle 'VLIM' events

cpf_vlim_event

event function for 'VLIM' events, to detect bus voltage magnitude limits

Table D-7:OPF and Wrapper Functions

name

description

opf

the main OPF function, called by runopf

dcopf

calls opf with options set to solve DC OPF

fmincopf

calls opf with options set to use fmincon to solve AC OPF

mopf

calls opf with options set to use MINOPF to solve AC OPF§

uopf

implements unit-decommitment heuristic, called by runuopf

Can also be used as a top-level function, run directly from the command line. It provides more calling options than runopf, primarly for backward compatibility with previous versions of mopf from MINOPF, but does not offer the option to save the output or the solved case. Wrapper with same calling conventions as opf. § Requires the installation of an optional package. See Appendix G for details on the corresponding package.

Table D-8:OPF Model Objects
name

description

@opf_model/

OPF model object used to encapsulate OPF problem formulation

  display

called to display object when statement not ended with semicolon

  get_mpc

returns the Matpower case struct

  opf_model

constructor for the opf_model class

@opt_model/

optimization model object (@opf_model base class)

  add_legacy_cost

adds a named subset of legacy user-defined costs to the model

  add_lin_constraint

adds a named subset of linear constraints to the model

  add_named_set

adds a named subset of costs, constraints or variables to the model

  add_nln_constraint

adds a named subset of nonlinear constraints to the model

  add_nln_cost

adds a named subset of general nonlinear costs to the model

  add_quad_cost

adds a named subset of quadratic costs to the model

  add_var

adds a named subset of optimization variables to the model

  describe_idx

identifies variable, constraint or cost row indices

  display

called to display object when statement not ended with semicolon

  eval_legacy_cost

evaluates legacy user costs and derivatives

  eval_nln_constraint

returns full set of nonlinear equality or inequality constraints and their gradients

  eval_nln_constraint_hess

returns Hessian for full set of nonlinear equality or inequality constraints

  eval_nln_cost

evaluates general nonlinear costs and derivatives

  eval_quad_cost

evaluates quadratic costs and derivatives

  get_idx

returns the idx struct for vars, lin/nln constraints, costs

  get_userdata

returns values of user data stored in the model

  getN

returns the number of variables, constraints or cost rows

  get

returns the value of a field of the object

  init_indexed_name

initializes dimensions for indexed named set of costs, constraints or variables

  opt_model

constructor for the opt_model class

  params_lin_constraint

returns individual or full set of linear constraint parameters

  params_legacy_cost

returns individual or full set of legacy user cost coefficients

  params_nln_cost

returns individual general nonlinear cost parameters

  params_quad_cost

returns individual or full set of quadratic cost coefficients

  params_var

returns initial values, bounds and variable type for optimimization vector ˆx

  valid_named_set_type

returns label for given named set type if valid, empty otherwise

  varsets_cell2struct

converts variable set list from cell array to struct array

  varsets_idx

returns vector of indices into opt vector ˆx  for variable set list

  varsets_len

returns total number of optimization variables for variable set list

  varsets_x

assembles cell array of sub-vectors of opt vector ˆx  specified by variable set list

Private method for internal use only. For all, or alternatively, only for a named (and possibly indexed) subset.

Table D-9:Deprecated @opt_model Methods
name

description

@opt_model/

optimization model object (@opf_model base class)

  add_constraints

use add_lin_constraint or add_nln_constraint instead

  add_costs

use add_legacy_cost, add_nln_cost or add_quad_cost instead

  add_vars

use add_var instead

  build_cost_params

no longer needed

  compute_cost

use eval_legacy_cost instead

  get_cost_params

use params_legacy_cost instead

  getv

use params_var instead

  linear_constraints

use params_lin_constraint instead

Or init_indexed_name if simply initializing the dimensions for an indexed named set.

Table D-10:OPF Solver Functions
name description
dcopf_solver sets up and solves DC OPF problem
fmincopf_solver sets up and solves OPF problem using fmincon, Matlab Opt Toolbox
ipoptopf_solver sets up and solves OPF problem using Ipopt
ktropf_solver sets up and solves OPF problem using Artelys Knitro
mipsopf_solver sets up and solves OPF problem using MIPS
mopf_solver sets up and solves OPF problem using MINOPF
tspopf_solver sets up and solves OPF problem using PDIPM, SC-PDIPM or TRALM

Requires the installation of an optional package. See Appendix G for details on the corresponding package.

Table D-11:Other OPF Functions
name

description

margcost

computes the marginal cost of generation as a function of generator output

makeAang

forms linear constraints for branch angle difference limits

makeApq

forms linear constraints for generator PQ capability curves

makeAvl

forms linear constraints for dispatchable load constant power factor

makeAy

forms linear constraints for piecewise linear generator costs (CCV)

opf_args

input argument handling for opf

opf_setup

constructs an OPF model object from a Matpower case

opf_execute

executes the OPF specified by an OPF model object

opf_branch_ang_fcn

evaluates AC branch angle difference limit constraints and gradients

opf_branch_ang_hess

evaluates Hessian of AC branch angle difference limit constraints

opf_branch_flow_fcn

evaluates AC branch flow limit constraints and gradients

opf_branch_flow_hess

evaluates Hessian of AC branch flow limit constraints

opf_consfcn

evaluates function and gradients for AC OPF nonlinear constraints

opf_costfcn

evaluates function, gradients and Hessian for AC OPF objective function

opf_current_balance_fcn

evaluates AC current balance constraints and gradients

opf_current_balance_hess

evaluates Hessian of AC current balance constraints

opf_gen_cost_fcn

evaluates polynomial generator costs and derivatives

opf_hessfcn

evaluates the Hessian of the Lagrangian for AC OPF

opf_legacy_user_cost_fcn

evaluates legacy user-defined costs and derivatives

opf_power_balance_fcn

evaluates AC power balance constraints and gradients

opf_power_balance_hess

evaluates Hessian of AC power balance constraints

opf_veq_fcn

evaluates voltage magnitude equality constraints and gradients

opf_veq_hess

evaluates Hessian of voltage magnitude equality constraints

opf_vlim_fcn

evaluates voltage magnitude limit constraints and gradients

opf_vlim_hess

evaluates Hessian of voltage magnitude limit constraints

opf_vref_fcn

evaluates reference voltage angle equality constraints and gradients

opf_vref_hess

evaluates Hessian of reference voltage angle equality constraints

totcost

computes the total cost of generation as a function of generator output

update_mupq

updates generator limit prices based on the shadow prices on capability curve constraints

Used by fmincon, MIPS, Ipopt and Artelys Knitro for AC OPF. Used with cartesian coordinate voltage representation only. I.e. opf.v_cartesian option set to 1.

Table D-12:OPF User Callback Functions

name

description

add_userfcn

appends a user callback function to the list of those to be called for a given case

remove_userfcn

removes a user callback function from the list

run_userfcn

executes the user callback functions for a given stage

toggle_dcline

enable/disable or check the status of the callbacks implementing DC lines

toggle_iflims

enable/disable or check the status of the callbacks implementing interface flow limits

toggle_reserves

enable/disable or check the status of the callbacks implementing fixed reserve requirements

toggle_softlims

enable/disable or check the status of the callbacks implementing DC OPF branch flow soft limits

Table D-13:Power Flow Derivative Functions

name

description

dIbr_dV

evaluates the partial derivatives of If|t  with respect to V

dSbr_dV

evaluates the partial derivatives of Sf|t  with respect to V

dAbr_dV

evaluates the partial derivatives of |Ff |t|2  with respect to V

dImis_dV

evaluates the partial derivatives of Imis  with respect to V

dSbus_dV

evaluates the partial derivatives of Sbus  with respect to V

d2Ibr_dV2

evaluates the 2nd derivatives of If|t  with respect to V

d2Sbr_dV2

evaluates the 2nd derivatives of Sf|t  with respect to V

d2Abr_dV2

evaluates the 2nd derivatives of     2
|Ff|t|  with respect to V

d2AIbr_dV2*

evaluates the 2nd derivatives of |I  |2
 f|t  with respect to V

d2ASbr_dV2*

evaluates the 2nd derivatives of |S  |2
 f|t  with respect to V

d2Imis_dV2

evaluates the 2nd derivatives of I
mis  with respect to V

d2Imis_dVdSg

evaluates the 2nd derivatives of Imis  with respect to V  and Sg  .

d2Sbus_dV2

evaluates the 2nd derivatives of Sbus  with respect to V

* Deprecated. Please use d2Abr_dV2 instead. V  represents complex bus voltages, Sg  the complex generator power injections, If|t  complex branch current injections, Sf|t  complex branch power injections, Imis  complex bus current injections, Sbus  complex bus power injections and Ff|t  refers to branch flows, either If|t  or Sf|t  , depending on the inputs. The second derivatives are all actually partial derivatives of the product of a first derivative matrix and a vector λ  . Please see Matpower Technical Note 2 [38], Matpower Technical Note 3 [39] and Matpower Technical Note 4 [40] for the detailed derivations of the formulas implemented by these functions.

Table D-14:NLP, LP & QP Solver Functions

name

description

clp_options

default options for CLP solver

cplex_options

default options for CPLEX solver

glpk_options

default options for GLPK solver

gurobi_options

default options for Gurobi solver

gurobiver

prints version information for Gurobi/Gurobi_MEX

ipopt_options

default options for Ipopt solver

mips

Matpower Interior Point Solver – primal/dual interior point solver for NLP

mipsver

prints version information for MIPS

miqps_matpower

Mixed-Integer Quadratic Program Solver for Matpower, wrapper function

provides a common MIQP solver interface for various MIQP/MILP solvers

miqps_cplex

common MIQP/MILP solver interface to CPLEX (cplexmiqp and cplexmilp)

miqps_glpk

common MILP solver interface to GLPK

miqps_gurobi

common MIQP/MILP solver interface to Gurobi

miqps_mosek

common MIQP/MILP solver interface to MOSEK (mosekopt)

miqps_ot

common QP/MILP solver interface to Matlab Opt Toolbox’s intlinprog, quadprog, linprog

mosek_options

default options for MOSEK solver

mosek_symbcon

symbolic constants to use for MOSEK solver options

mplinsolve

common linear system solver interface, used by MIPS

mpopt2qpopt

create mi/qps_matpower options struct from Matpower options struct

qps_matpower

Quadratic Program Solver for Matpower, wrapper function

provides a common QP solver interface for various QP/LP solvers

qps_bpmpd

common QP/LP solver interface to BPMPD_MEX

qps_clp

common QP/LP solver interface to CLP

qps_cplex

common QP/LP solver interface to CPLEX (cplexqp and cplexlp)

qps_glpk

common QP/LP solver interface to GLPK

qps_gurobi

common QP/LP solver interface to Gurobi

qps_ipopt

common QP/LP solver interface to Ipopt-based solver

qps_mips

common QP/LP solver interface to MIPS-based solver

qps_mosek

common QP/LP solver interface to MOSEK (mosekopt)

qps_ot

common QP/LP solver interface to Matlab Opt Toolbox’s quadprog, linprog

Requires the installation of an optional package. See Appendix G for details on the corresponding package.

Table D-15:Matrix Building Functions

name

description

makeB

forms the fast-decoupled power flow matrices,   ′
B and   ′′
B

makeBdc

forms the system matrices Bbus  and Bf  and vectors Pf,shift  and Pbus,shift  for the DC power flow model

makeJac

forms the power flow Jacobian matrix

makeLODF

forms the line outage distribution factor matrix

makePTDF

forms the DC PTDF matrix for a given choice of slack

makeSbus

forms the vector of complex bus power injections

makeSdzip

forms a struct w/vectors of nominal values for each component of ZIP load

makeYbus

forms the complex bus and branch admittance matrices Ybus  , Yf  and Yt

Table D-16:Utility Functions

name

description

apply_changes

modifies an existing Matpower case by applying changes defined in a change table

bustypes

creates vectors of bus indices for reference bus, PV buses, PQ buses

calc_branch_angle

calcultes a vector of voltage angle differences for branches

case_info

checks a Matpower case for connectivity and prints a system summary

compare_case

prints summary of differences between two Matpower cases

define_constants

convenience script defines constants for named column indices to data matrices (calls idx_bus, idx_brch, idx_gen and idx_cost)

extract_islands

extracts islands in a network into their own Matpower case struct

feval_w_path

same as Matlab’s feval function, except the function being evaluated need not be in the Matlab path

find_islands

finds islands and isolated buses in a network

genfuels

list of standard values for generator fuel types, for mpc.genfuel

gentypes

list of standard values for generator unit types, for mpc.gentype

get_losses

compute branch losses (and derivatives) as functions of bus voltage

hasPQcap

checks for generator P-Q capability curve constraints

have_fcn

checks for availability of optional functionality

idx_brch

named column index definitions for branch matrix

idx_bus

named column index definitions for bus matrix

idx_cost

named column index definitions for gencost matrix

idx_ct

constant definitions for use with change tables and apply_changes

idx_dcline

named column index definitions for dcline matrix

idx_gen

named column index definitions for gen matrix

isload

checks if generators are actually dispatchable loads

load2disp

converts fixed loads to dispatchable loads

loadshed

computes MW curtailments of dispatchable loads

mpver

prints version information for Matpower and optional packages

modcost

modifies gencost by horizontal or vertical scaling or shifting

nested_struct_copy

copies the contents of nested structs

poly2pwl

creates piecewise linear approximation to polynomial cost function

polycost

evaluates polynomial generator cost and its derivatives

pqcost

splits gencost into real and reactive power costs

savechgtab

saves a change table, such as used by apply_changes, to a file

scale_load

scales fixed and/or dispatchable loads by load zone

total_load

returns vector of total load in each load zone

Table D-17:Other Functions

name

description

connected_components

returns the connected components of a graph

mpoption_info_clp

option information for CLP

mpoption_info_cplex

option information for CPLEX

mpoption_info_fmincon

option information for FMINCON

mpoption_info_glpk

option information for GLPK

mpoption_info_gurobi

option information for Gurobi

mpoption_info_intlinprog

option information for INTLINPROG

mpoption_info_ipopt

option information for Ipopt

mpoption_info_knitro

option information for Artelys Knitro

mpoption_info_linprog

option information for LINPROG

mpoption_info_mips

option information for MIPS

mpoption_info_mosek

option information for MOSEK

mpoption_info_quadprog

option information for QUADPROG

psse_convert

converts data read from PSS/E RAW file to Matpower format

psse_convert_hvdc

called by psse_convert to handle HVDC data

psse_convert_xfmr

called by psse_convert to handle transformer data

psse_parse

parses data from a PSS/E RAW data file

psse_parse_line

called by psse_parse to parse a single line

psse_parse_section

called by psse_parse to parse an entire section

psse_read

reads data from a PSS/E RAW data file