Matpower Functions

Table D-2:Top-Level Simulation Functions

name	description
runpf	power ﬂow^†
runcpf	AC continuation power ﬂow
runopf	optimal power ﬂow^†
runuopf	optimal power ﬂow with unit-decommitment^†
rundcpf	DC power ﬂow^‡
rundcopf	DC optimal power ﬂow^‡
runduopf	DC optimal power ﬂow with unit-decommitment^‡
runopf_w_res	optimal power ﬂow with ﬁxed 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 ﬁles 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 ﬂow data from IEEE Common Data Format (CDF) to Matpower format
loadcase	loads data from a Matpower case ﬁle or struct into data matrices or a case struct
mpoption	sets and retrieves Matpower options
printpf	pretty prints power ﬂow and OPF results
psse2mpc	converts power ﬂow 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 ﬁle

Table D-5:Power Flow Functions

name	description
calc_v_i_sum	implementation of current summation power ﬂow solver^†
calc_v_pq_sum	implementation of power summation power ﬂow solver^†
calc_v_y_sum	implementation of admittance summation power ﬂow solver^†
dcpf	implementation of DC power ﬂow solver
fdpf	implementation of fast-decoupled power ﬂow solver
gausspf	implementation of Gauss-Seidel power ﬂow solver
make_vcorr	calculate voltage corrections for radial power ﬂow^†
make_zpv	form loop impedance for PV bus handling in radial power ﬂow^†
newtonpf	implementation of Newton-method power ﬂow solver (power, polar)
newtonpf_I_cart	implementation of Newton-method power ﬂow solver (current, cartesian)
newtonpf_I_polar	implementation of Newton-method power ﬂow solver (current, polar)
newtonpf_S_cart	implementation of Newton-method power ﬂow solver (power, cartesian)
order_radial	performs oriented ordering of buses and branches for radial power ﬂow^†
pfsoln	computes branch ﬂows, 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 ﬂow solvers^†

^† For radial networks only.

Table D-6:Continuation Power Flow Functions

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 oﬀer 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-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 diﬀerence 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 speciﬁed by an OPF model object
opf_branch_ang_fcn^†	evaluates AC branch angle diﬀerence limit constraints and gradients^‡
opf_branch_ang_hess^†	evaluates Hessian of AC branch angle diﬀerence limit constraints^‡
opf_branch_flow_fcn^†	evaluates AC branch ﬂow limit constraints and gradients
opf_branch_flow_hess^†	evaluates Hessian of AC branch ﬂow 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-deﬁned 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 ﬂow limits
toggle_reserves	enable/disable or check the status of the callbacks implementing ﬁxed reserve requirements
toggle_softlims	enable/disable or check the status of the callbacks implementing DC OPF branch ﬂow soft limits

If|t — Table D-13:Power Flow Derivative Functions

Table D-13:Power Flow Derivative 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.

′
B — Table D-15:Matrix Building Functions

′′
B — Table D-15:Matrix Building Functions

Table D-16:Utility Functions

name	description
apply_changes	modiﬁes an existing Matpower case by applying changes deﬁned 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 diﬀerences for branches
case_info	checks a Matpower case for connectivity and prints a system summary
compare_case	prints summary of diﬀerences between two Matpower cases
define_constants	convenience script deﬁnes 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	ﬁnds 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 deﬁnitions for branch matrix
idx_bus	named column index deﬁnitions for bus matrix
idx_cost	named column index deﬁnitions for gencost matrix
idx_ct	constant deﬁnitions for use with change tables and apply_changes
idx_dcline	named column index deﬁnitions for dcline matrix
idx_gen	named column index deﬁnitions for gen matrix
isload	checks if generators are actually dispatchable loads
load2disp	converts ﬁxed loads to dispatchable loads
loadshed	computes MW curtailments of dispatchable loads
mpver	prints version information for Matpower and optional packages
modcost	modiﬁes 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 ﬁle
scale_load	scales ﬁxed 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 ﬁle 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 ﬁle
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 ﬁle

name	description
ext2int	converts case from external to internal indexing
e2i_data	converts arbitrary data from external to internal indexing
e2i_field	converts ﬁelds 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 ﬁelds 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

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 ﬂow 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

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-deﬁned 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	identiﬁes 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 ﬁeld 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 coeﬃcients
params_nln_cost	returns individual general nonlinear cost parameters
params_quad_cost	returns individual or full set of quadratic cost coeﬃcients
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$ speciﬁed by variable set list

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 2^nd derivatives of $If\|t$ with respect to $V$
d2Sbr_dV2	evaluates the 2^nd derivatives of $Sf\|t$ with respect to $V$
d2Abr_dV2	evaluates the 2^nd derivatives of $2 \|Ff\|t\|$ with respect to $V$
d2AIbr_dV2^*	evaluates the 2^nd derivatives of $\|I \|2 f\|t$ with respect to $V$
d2ASbr_dV2^*	evaluates the 2^nd derivatives of $\|S \|2 f\|t$ with respect to $V$
d2Imis_dV2	evaluates the 2^nd derivatives of $I mis$ with respect to $V$
d2Imis_dVdSg	evaluates the 2^nd derivatives of $Imis$ with respect to $V$ and $Sg$ .
d2Sbus_dV2	evaluates the 2^nd derivatives of $Sbus$ with respect to $V$

name	description
makeB	forms the fast-decoupled power ﬂow matrices, $′ B$ and $′′ B$
makeBdc	forms the system matrices $Bbus$ and $Bf$ and vectors $Pf,shift$ and $Pbus,shift$ for the DC power ﬂow model
makeJac	forms the power ﬂow 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$

D.2 Matpower Functions