Beginning with version 4.2, Matpoweruses an options struct to control the many
options available. Earlier versions used an options vector with named elements.
Matpower’s options are used to control things such as:
power flow algorithm
power flow termination criterion
power flow options (e.g. enforcing of reactive power generation limits)
continuation power flow options
OPF algorithm
OPF termination criterion
OPF options (e.g. active vs. apparent power vs. current for line limits)
verbose level
printing of results
solver specific options
As with the old-style options vector, the options struct should always be created and
modified using the mpoption function to ensure compatibility across different versions of
Matpower. The default Matpoweroptions struct is obtained by calling mpoption with
no arguments.
>> mpopt = mpoption;
Individual options can be overridden from their default values by calling mpoption with a set
of name/value pairs as input arguments. For example, the following runs a fast-decoupled
power flow of case30 with very verbose progress output:
where the function verbose_fast_decoupled_pf_opts is defined as follows:
function ov = verbose_fast_decoupled_pf_opts() ov = struct('pf', struct('alg', 'FDXB'), 'verbose', 3);
To make changes to an existing options struct (as opposed to the default options
struct), simply include it as the first argument. For example, to modify the previous run to
enforce reactive power limts, suppress the pretty-printing of the output and save the
results to a struct instead:
This works when specifying the overrides as a struct or function name as well. For backward
compatibility, the first argument can be an old-style options vector, followed by old-style
option name/value pairs.
The available options and their default values are summarized in the following tables
and can also be accessed via the command help mpoption. Some of the options
require separately installed optional packages available from the Matpower
website.
Table C-1:Top-Level Options
name
default
description
model
'AC'
AC vs. DC modeling for power flow and OPF formulation
*Requires the installation of an optional package. See AppendixGfor details on the corresponding package.†Requires Matlab’s Optimization Toolbox, available from The MathWorks, Inc (https://www.mathworks.com/).
Table C-2:Power Flow Options
name
default
description
pf.alg
'NR'
AC power flow algorithm:
'NR' –
Newtons’s method (formulationdepends on values of pf.current_balance andpf.v_cartesian options)
'NR-SC' –
Newtons’s method (power mismatch, cartesian)†
'NR-IP' –
Newtons’s method (current mismatch, polar)†
'NR-IC' –
Newtons’s method (current mismatch, cartesian)†
'FDXB' –
Fast-Decoupled (XB version)
'FDBX' –
Fast-Decouple (BX version)
'GS' –
Gauss-Seidel
'PQSUM' –
Power Summation (radial networks only)
'ISUM' –
Current Summation (radial networks only)
'YSUM' –
Admittance Summation (radial networks only)
–
pf.current_balance‡
0
use current, as opposed to power, balance for AC PF, 0 or 1
pf.v_cartesian‡
0
use cartesian, as opposed to polar, representation for voltagesfor AC PF, 0 or 1
pf.tol
termination tolerance on per unit P and Q dispatch
pf.nr.max_it
10
maximum number of iterations for Newton’s method
pf.nr.lin_solver
''
linear solver option for mplinsolve for computing Newtonupdate step
(see mplinsolve for complete list of all options)
'' –
default to '∖' for small systems, 'LU3' for larger ones
'∖' –
built-in backslash operator
'LU' –
explicit default LU decomposition and back substitution
'LU3' –
3 output arg form of lu, Gilbert-Peierls algorithm withapproximate minimum degree (AMD) reordering
'LU4' –
4 output arg form of lu, UMFPACK solver (same as'LU')
'LU5' –
5 output arg form of lu, UMFPACK solver w/row scaling
–
pf.fd.max_it
30
maximum number of iterations for fast-decoupled method
pf.gs.max_it
1000
maximum number of iterations for Gauss-Seidel method
pf.radial.max_it
20
maximum number of iterations for radial power flow methods
pf.radial.vcorr
0
perform voltage correction procedure in distribution powerflow
0 –
do not perform voltage correction
1 –
perform voltage correction
–
pf.enforce_q_lims
0
enforce gen reactive power limits at expense of
0 –
do not enforce limits
1 –
enforce limits, simultaneous bus type conversion
2 –
enforce limits, one-at-a-time bus type conversion
–
†Automatically sets/overrides pf.current_balance and pf.v_cartesian options with corresponding values.‡Only relevant for Newton power flow solver.
Table C-3:Continuation Power Flow Options
name
default
description
cpf.parameterization
3
choice of parameterization
1 — natural
2 — arc length
3 — pseudo arc length
cpf.stop_at
'NOSE'
determines stopping criterion
'NOSE' — stop when nose point is reached
'FULL' — trace full nose curve
— stop upon reaching targetvalue
cpf.enforce_p_lims
0
enforce gen active power limits
0 — do not enforce limits
1 — enforce limits
cpf.enforce_q_lims
0
enforce gen reactive power limits at expense of
0 — do not enforce limits
1 — enforce limits
cpf.enforce_v_lims
0
enforce bus voltage magnitude limits
0 — do not enforce limits
1 — enforce limits
cpf.enforce_flow_lims
0
enforce branch MVA flow limits
0 — do not enforce limits
1 — enforce limits
cpf.step
0.05
default value for continuation power flow step size
tolerance for generator active power limit detection(MW)
cpf.q_lims_tol
tolerance for generator reactive power limit detection(MVAr)
cpf.v_lims_tol
tolerance for bus voltage magnitude limit detection (p.u)
cpf.flow_lims_tol
0.01
tolerance for branch flow limit detection (MVA)
cpf.plot.level
0
control plotting of nose curve
0 — do not plot nose curve
1 — plot when completed
2 — plot incrementally at each iteration
3 — same as 2, with pause at each iteration
cpf.plot.bus
empty
index of bus whose voltage is to be plotted
cpf.user_callback
empty
string or cell array of strings with names of user callbackfunctions†
†See help cpf_default_callback for details.
Table C-4:OPF Solver Options
name
default
description
opf.ac.solver
'DEFAULT'
AC optimal power flow solver:
'DEFAULT' –
choose default solver, i.e. 'MIPS'
'MIPS' –
MIPS, MatpowerInterior Point Solver,primal/dual interior point method†
'FMINCON' –
MatlabOptimization Toolbox, fmincon
'IPOPT' –
Ipopt*
'KNITRO' –
Artelys Knitro*
'MINOPF' –
MINOPF*,MINOS-based solver
'PDIPM' –
PDIPM*,primal/dual interior point method‡
'SDPOPF' –
SDPOPF*, solver based on semidefiniterelaxation
'TRALM' –
TRALM*, trust region based augmentedLangrangian method
–
opf.dc.solver
'DEFAULT'
DC optimal power flow solver:
'DEFAULT' –
choose default solver based on availabilityin the following order: 'GUROBI', 'CPLEX','MOSEK', 'OT', 'GLPK' (linear costs only),'BPMPD', 'MIPS'
'MIPS' –
MIPS, MatpowerInterior Point Solver,primal/dual interior point method†
'BPMPD' –
BPMPD*
'CLP' –
CLP*
'CPLEX' –
CPLEX*
'GLPK' –
GLPK*(no quadratic costs)
'GUROBI' –
Gurobi*
'IPOPT' –
Ipopt*
'MOSEK' –
MOSEK*
'OT' –
MatlabOpt Toolbox, quadprog, linprog
–
*Requires the installation of an optional package. See AppendixGfor details on the corresponding package.†For MIPS-sc, the step-controlled version of this solver, the mips.step_control option must be set to 1.‡For SC-PDIPM, the step-controlled version of this solver, the pdipm.step_control option must be set to 1.
Table C-5:General OPF Options
name
default
description
opf.current_balance‡
0
use current, as opposed to power, balance formulation forAC OPF, 0 or 1
opf.v_cartesian‡
0
use cartesian, as opposed to polar, representation forvoltages for AC OPF, 0 or 1
opf.violation
constraint violation tolerance
opf.use_vg
0
respect generator voltage setpoint, 0 or 1†
0 –
use voltage magnitude limits specified in bus,ignore VG in gen
1 –
replace voltage magnitude limits specified in busby VG in corresponding gen
–
opf.flow_lim
'S'
quantity to limit for branch flow constraints
'S' –
apparent power flow (limit in MVA)
'P' –
active power flow (limit in MW)
'I' –
current magnitude (limit in MVA at 1 p.u.voltage, i.e kA)
'2' –
same as 'P', but implemented using squareof active flow, rather than simple max
–
opf.ignore_angle_lim
0
ignore angle difference limits for branches
0 –
include angle difference limits, if specified
1 –
ignore angle difference limits even if specified
–
opf.softlims.default
1
default behavior of implicit soft limits, where parametersare not explicitly provided
0 –
do not include softlims if not explicitly specified
1 –
include softlims with default values if notexplicitly specified
–
opf.init_from_mpc*
-1
specify whether to use the current state in Matpowercase to initialize OPF
-1 –
Matpowerdecides based on solver/algorithm
0 –
ignore current state in Matpowercase‡
1 –
use current state in Matpowercase
–
opf.start
0
strategy for initializing OPF starting point
0 –
default, Matpowerdecides based on solver,(currently identical to 1)
1 –
ignore current state in Matpowercase‡
2 –
use current state in Matpowercase
3 –
solve power flow and use resulting state
–
opf.return_raw_der
0
for AC OPF, return constraint and derivative info inresults.raw (in fields g, dg, df, d2f)
*Deprecated. Use opf.start instead.†Using a value between 0 and 1 results in the limits being determined by the corresponding weighted average of the 2 options.‡Only applies to fmincon, Ipopt, Artelys Knitro and MIPS solvers, which use an interior point estimate; others use currentstate in Matpowercase, as with opf.start = 2.
Table C-6:Power Flow and OPF Output Options
name
default
description
verbose
1
amount of progress info to be printed
0 –
print no progress info
1 –
print a little progress info
2 –
print a lot of progress info
3 –
print all progress info
–
out.all
-1
controls pretty-printing of results
-1 –
individual flags control what is printed
0 –
do not print anything†*
1 –
print everything†
–
out.sys_sum
1
print system summary (0 or 1)
out.area_sum
0
print area summaries (0 or 1)
out.bus
1
print bus detail, includes per bus gen info (0 or 1)
out.branch
1
print branch detail (0 or 1)
out.gen
0
print generator detail (0 or 1)
out.lim.all
-1
controls constraint info output
-1 –
individual flags control what is printed
0 –
do not print any constraint info†
1 –
print only binding constraint info†
2 –
print all constraint info†
–
out.lim.v
1
control output of voltage limit info
0 –
do not print
1 –
print binding constraints only
2 –
print all constraints
–
out.lim.line
1
control output of line flow limit info‡
out.lim.pg
1
control output of gen active power limit info‡
out.lim.qg
1
control output of gen reactive power limit info‡
out.force
0
print results even if success flag = 0 (0 or 1)
out.suppress_detail
-1
suppress all output but system summary
-1 –
suppress details for large systems ( 500 buses)
0 –
do not suppress any output specified by other flags
1 –
suppress all output except system summary section†
–
*This setting is ignored for pretty-printed output to files specified as FNAME argument in calls to runpf, runopf, etc.†Overrides individual flags, but (in the case of out.suppress_detail) not out.all = 1.‡Takes values of 0, 1 or 2 as for out.lim.v.
Table C-7:OPF Options for MIPS
name
default
description
mips.linsolver
''
linear system solver for update step
'' or '∖' –
built-in backslash ∖ operator
'PARDISO' –
PARDISO solver†
–
mips.feastol
0
feasibiliy (equality) tolerance
set to value of opf.violation by default
mips.gradtol
gradient tolerance
mips.comptol
complementarity condition (inequality) tolerance
mips.costtol
optimality tolerance
mips.max_it
150
maximum number of iterations
mips.step_control
0
set to 1 to enable step-size control
mips.sc.red_it‡
20
maximum number of step size reductions per iteration
†Requires installation of the optional PARDISO package. See AppendixG.11for details.‡Only relevant when mips.step_control is on.
Table C-8:OPF Options for CLP†
name
default§
description
clp.opts
empty
struct of native CLP options passed to clp_options to overridedefaults, applied after overrides from clp.opt_fname‡
clp.opt_fname
empty
name of user-supplied function passed as FNAME argument toclp_options to override defaults‡
†For opf.dc.solver option set to 'CLP' only. Requires the installation of the optional CLP package. See AppendixG.2for details.‡For details, see help clp_options or help clp.
Table C-9:OPF Options for CPLEX†
name
default
description
cplex.lpmethod
0
algorithm used by CPLEX for LP problems
0 –
automatic; let CPLEX choose
1 –
primal simplex
2 –
dual simplex
3 –
network simplex
4 –
barrier
5 –
sifting
6 –
concurrent (dual, barrier, and primal)
–
cplex.qpmethod
0
algorithm used by CPLEX for QP problems
0 –
automatic; let CPLEX choose
1 –
primal simplex
2 –
dual simplex
3 –
network simplex
4 –
barrier
–
cplex.opts
empty
struct of native CPLEX options (for cplexoptimset) passed tocplex_options to override defaults, applied after overrides fromcplex.opt_fname‡
cplex.opt_fname
empty
name of user-supplied function passed as FNAME argument tocplex_options to override defaults‡
cplex.opt
0
if cplex.opt_fname is empty and cplex.opt is non-zero, thevalue of cplex.opt_fname is generated by appending cplex.optto 'cplex_user_options_' (for backward compatibility withold Matpoweroption CPLEX_OPT)
†For opf.dc.solver option set to 'CPLEX' only. Requires the installation of the optional CPLEX package. SeeAppendixG.3for details.‡For details, see help cplex_options and the “Parameters of CPLEX” section of the CPLEX documentation athttp://www.ibm.com/support/knowledgecenter/SSSA5P.
†Requires Matlab’s Optimization Toolbox, available from The MathWorks, Inc (https://www.mathworks.com/).‡Does not use sparse matrices, so not applicable for large-scale systems.*Display is set by verbose, TolCon by opf.violation, TolX by fmincon.tol_x, TolFun by fmincon.tol_f, andMaxIter and MaxFunEvals by fmincon.max_it.
Table C-11:OPF Options for GLPK†
name
default§
description
glpk.opts
empty
struct of native GLPK options passed to glpk_options tooverride defaults, applied after overrides from glpk.opt_fname‡
glpk.opt_fname
empty
name of user-supplied function passed as FNAME argument toglpk_options to override defaults‡
struct of native Gurobioptions passed to gurobi_options to override defaults, appliedafter overrides from gurobi.opt_fname‡
gurobi.opt_fname
empty
name of user-supplied function passed as FNAME argument togurobi_options to override defaults‡
gurobi.opt
0
if gurobi.opt_fname is empty and gurobi.opt is non-zero, thevalueof gurobi.opt_fname is generated by appending gurobi.opt to'gurobi_user_options_' (for backward compatibility with oldMatpoweroption GRB_OPT)
†For opf.dc.solver option set to 'GUROBI' only. Requires the installation of the optional Gurobi package. See AppendixG.5for details.§Default values in parenthesis refer to defaults assigned by Gurobi if called with option equal to 0.‡For details, see help gurobi_options and the “Parameters” section of the “Gurobi Optimizer Reference Manual” athttps://www.gurobi.com/documentation/.
Table C-13:OPF Options for Ipopt†
name
default
description
ipopt.opts
empty
struct of native Ipoptoptions (options.ipopt for ipopt)passed to ipopt_options to override defaults, applied afteroverrides from ipopt.opt_fname‡
ipopt.opt_fname
empty
name of user-supplied function passed as FNAME argument toipopt_options to override defaults‡
ipopt.opt
0
if ipopt.opt_fname is empty and ipopt.opt is non-zero, thevalue of ipopt.opt_fname is generated by appending ipopt.optto 'ipopt_user_options_' (for backward compatibility withold Matpoweroption IPOPT_OPT)
†For opf.ac.solver or opf.dc.solver option set to 'IPOPT' only. Requires the installation of the optional Ipoptpackage[51]. See AppendixG.6for details.‡For details, see help ipopt_options and the options reference section of the Ipoptdocumentation athttp://www.coin-or.org/Ipopt/documentation/.
Table C-14:OPF Options for Artelys Knitro†
name
default
description
knitro.tol_x
termination tolerance on
knitro.tol_f
termination tolerance on
knitro.maxit
0
maximum number of iterations
use solver’s default value
knitro.opt_fname
empty
name of user-supplied native Knitro options file that overridesother options‡
knitro.opt
0
if knitro.opt_fname is empty and knitro.opt is a positiveinteger, the value of knitro.opt_fname is generated as'knitro_user_options_.txt' (for backward compatibilitywith old Matpoweroption KNITRO_OPT)
†For opf.ac.solver option set to 'KNITRO' only. Requires the installation of the optional Artelys Knitro package[34].See AppendixG.7for details.‡Note that Artelys Knitro uses the opt_fname option slightly differently from other optional solvers. Specifically, it is thename of a text file processed directly by Artelys Knitro, not a Matlabfunction that returns an options struct passed tothe solver.
†For opf.ac.solver option set to 'MINOPF' only. Requires the installation of the optional MINOPF package[32]. See AppendixG.8for details.‡Default values in parenthesis refer to defaults assigned in MEX file if called with option equal to 0.
Table C-16:OPF Options for MOSEK†
name
default§
description
mosek.lp_alg
0
solution algorithm used by MOSEK for continuous LP problems
(MSK_IPAR_OPTIMIZER)*
0 –
automatic; let MOSEK choose
1 –
interior point
3 –
primal simplex
4 –
dual simplex
5 –
primal dual simplex
6 –
automatic simplex (MOSEK chooses which simplex)
7 –
network primal simplex
10 –
concurrent
–
mosek.max_it
0 (400)
interior point maximum iterations
(MSK_IPAR_INTPNT_MAX_ITERATIONS)
mosek.gap_tol
0 ()
interior point relative gap tolerance
(MSK_DPAR_INTPNT_TOL_REL_GAP)
mosek.max_time
0 (-1)
maximum time allowed for solver (negative means)
(MSK_DPAR_OPTIMIZER_MAX_TIME)
mosek.num_threads
0 (1)
maximum number of threads to use
(MSK_IPAR_INTPNT_NUM_THREADS)
mosek.opts
empty
struct of native MOSEK options (param struct normally passedto mosekopt) passed to mosek_options to override defaults,applied after overrides from mosek.opt_fname‡
mosek.opt_fname
empty
name of user-supplied function passed as FNAME argument tomosek_options to override defaults‡
mosek.opt
0
if mosek.opt_fname is empty and mosek.opt is non-zero, thevalue of mosek.opt_fname is generated by appending mosek.optto 'mosek_user_options_' (for backward compatibility withold Matpoweroption MOSEK_OPT)
†For opf.dc.solver option set to 'MOSEK' only. Requires the installation of the optional MOSEK package. See AppendixG.9for details.§Default values in parenthesis refer to defaults assigned by MOSEK if called with option equal to 0.*The values listed here correspond to those used by MOSEK version 7.x. Version 6.x was different. It is probably safer to writeyour code using the symbolic constants defined by mosek_symbcon rather than using explicit numerical values.‡For details, see help mosek_options and the “Parameters” reference in “The MOSEK optimization toolbox for MATLABmanual” at http://docs.mosek.com/7.1/toolbox/Parameters.html.
Table C-17:OPF Options for PDIPM†
name
default
description
pdipm.feastol
0
feasibiliy (equality) tolerance
set to value of opf.violation by default
pdipm.gradtol
gradient tolerance
pdipm.comptol
complementarity condition (inequality) tolerance
pdipm.costtol
optimality tolerance
pdipm.max_it
150
maximum number of iterations
pdipm.step_control
0
set to 1 to enable step-size control
pdipm.sc.red_it‡
20
maximum number of step size reductions per iteration
pdipm.sc.smooth_ratio‡
0.04
piecewise linear curve smoothing ratio
†Requires installation of the optional TSPOPF package[28]. See AppendixG.13for details.‡Only relevant when pdipm.step_control is on.
Table C-18:OPF Options for TRALM†
name
default
description
tralm.feastol
0
feasibiliy tolerance
set to value of opf.violation by default
tralm.primaltol
primal variable tolerance
tralm.dualtol
dual variable tolerance
tralm.costtol
optimality tolerance
tralm.major_it
40
maximum number of major iterations
tralm.minor_it
100
maximum number of minor iterations
tralm.smooth_ratio
0.04
piecewise linear curve smoothing ratio
†Requires installation of the optional TSPOPF package[28]. See AppendixG.13for details.