C Matpower Options

Beginning with version 4.2, Matpower uses 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:

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 Matpower options 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:

>> mpopt = mpoption('pf.alg', 'FDXB', 'verbose', 3);
>> runpf('case30', mpopt);

For backward compatibility, old-style option names/values can also be used.

>> mpopt = mpoption('PF_ALG', 2, 'VERBOSE', 3);

Another way to specify option overrides is via a struct. Using the example above, the code would be as follows.

>> overrides = struct('pf', struct('alg', 'FDXB'), 'verbose', 3);
>> mpopt = mpoption(overrides);

Finally, a string containing the name of a function that returns such a struct, can be passed to mpoption instead of the struct itself.

>> mpopt = mpoption('verbose_fast_decoupled_pf_opts');

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:

>> mpopt = mpoption(mpopt, 'pf.enforce_q_lims', 1, 'out.all', 0);
>> results = runpf('case30', mpopt);

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
'AC' use AC formulation and corresponding algs/options
'DC' use DC formulation and corresponding algs/options
pf see Table C-2 power flow options
cpf see Table C-3 continuation power flow options
opf see Tables C-4, C-5 optimal power flow options
verbose 1 amount of progress info 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 see Table C-6 pretty-printed output options
mips see Table C-7 MIPS options
clp see Table C-8 CLP options*
cplex see Table C-9 CPLEX options*
fmincon see Table C-10 fmincon options
glpk see Table C-11 GLPK options*
gurobi see Table C-12 Gurobi options*
ipopt see Table C-13 Ipopt options*
knitro see Table C-14 Artelys Knitro options*
minopf see Table C-15 MINOPF options*
mosek see Table C-16 MOSEK options*
pdipm see Table C-17 PDIPM options*
tralm see Table C-18 TRALM options*

* Requires the installation of an optional package. See Appendix G for 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 (formulation depends on values of pf.current_balance and pf.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 voltages for AC PF, 0 or 1

pf.tol   −8
10

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 Newton update 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 with approximate 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 power flow

0 – do not perform voltage correction
1 – perform voltage correction
pf.enforce_q_lims 0

enforce gen reactive power limits at expense of |Vm|

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  — stop upon reaching target λ  value λstop

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 Vm

 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 σ

cpf.step_min   −4
10

minimum allowed step size, σmin

cpf.step_max 0.2

maximum allowed step size, σmax

cpf.adapt_step 0

toggle adaptive step size feature

 0 — adaptive step size disabled

 1 — adaptive step size enabled

cpf.adapt_step_damping 0.7

damping factor βcpf  from (5.13) for adaptive step sizing

cpf.adapt_step_tol 10−3

tolerance 𝜖
 cpf  from (5.13) for adaptive step sizing

cpf.target_lam_tol 10−5

tolerance for target lambda detection

cpf.nose_tol 10−5

tolerance for nose point detection (p.u.)

cpf.p_lims_tol 10−2

tolerance for generator active power limit detection (MW)

cpf.q_lims_tol 10−2

tolerance for generator reactive power limit detection (MVAr)

cpf.v_lims_tol 10−4

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 callback functions

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, Matpower Interior Point Solver, primal/dual interior point method

'FMINCON'

Matlab Optimization Toolbox, fmincon

'IPOPT'

Ipopt*

'KNITRO'

Artelys Knitro*

'MINOPF'

MINOPF*,MINOS-based solver

'PDIPM'

PDIPM*,primal/dual interior point method

'SDPOPF'

SDPOPF*, solver based on semidefinite relaxation

'TRALM'

TRALM*, trust region based augmented Langrangian method

opf.dc.solver 'DEFAULT'

DC optimal power flow solver:

'DEFAULT'

choose default solver based on availability in the following order: 'GUROBI', 'CPLEX', 'MOSEK', 'OT', 'GLPK' (linear costs only), 'BPMPD', 'MIPS'

'MIPS'

MIPS, Matpower Interior 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'

Matlab Opt Toolbox, quadprog, linprog

* Requires the installation of an optional package. See Appendix G for 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 for AC OPF, 0 or 1

opf.v_cartesian 0

use cartesian, as opposed to polar, representation for voltages for AC OPF, 0 or 1

opf.violation 5× 10−6

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 bus by 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⋅VbasekV  )

'2'

same as 'P', but implemented using square of 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 parameters are not explicitly provided

0 –

do not include softlims if not explicitly specified

1 –

include softlims with default values if not explicitly specified

opf.init_from_mpc* -1

specify whether to use the current state in Matpower case to initialize OPF

-1 – Matpower decides based on solver/algorithm
0 – ignore current state in Matpower case
1 – use current state in Matpower case
opf.start 0

strategy for initializing OPF starting point

0 –

default, Matpower decides based on solver, (currently identical to 1)

1 –

ignore current state in Matpower case

2 –

use current state in Matpower case

3 –

solve power flow and use resulting state

opf.return_raw_der 0

for AC OPF, return constraint and derivative info in results.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 current state in Matpower case, 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 10−6  gradient tolerance
mips.comptol 10−6  complementarity condition (inequality) tolerance
mips.costtol 10−6  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 Appendix G.11 for 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 override defaults, applied after overrides from clp.opt_fname

clp.opt_fname empty

name of user-supplied function passed as FNAME argument to clp_options to override defaults

For opf.dc.solver option set to 'CLP' only. Requires the installation of the optional CLP package. See Appendix G.2 for 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 to cplex_options to override defaults, applied after overrides from cplex.opt_fname

cplex.opt_fname empty

name of user-supplied function passed as FNAME argument to cplex_options to override defaults

cplex.opt 0

if cplex.opt_fname is empty and cplex.opt is non-zero, the value of cplex.opt_fname is generated by appending cplex.opt to 'cplex_user_options_' (for backward compatibility with old Matpower option CPLEX_OPT)

For opf.dc.solver option set to 'CPLEX' only. Requires the installation of the optional CPLEX package. See Appendix G.3 for details. For details, see help cplex_options and the “Parameters of CPLEX” section of the CPLEX documentation at http://www.ibm.com/support/knowledgecenter/SSSA5P.

Table C-10:OPF Options for fmincon
name default

description

fmincon.alg 4

algorithm used by fmincon in Matlab Opt Toolbox ≥ 4

1 – active-set
2 – interior-point, default “bfgs” Hessian approximation
3 – interior-point, “lbfgs” Hessian approximation
4 – interior-point, exact user-supplied Hessian
5 – interior-point, Hessian via finite-differences
6 – sqp, sequential quadratic programming
fmincon.tol_x   −4
10

termination tolerance on x  *

fmincon.tol_f 10−4

termination tolerance on f  *

fmincon.max_it 0

maximum number of iterations*

  0 ⇒ use solver’s default value

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, and MaxIter 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 to override defaults, applied after overrides from glpk.opt_fname

glpk.opt_fname empty

name of user-supplied function passed as FNAME argument to glpk_options to override defaults

For opf.dc.solver option set to 'GLPK' only. Requires the installation of the optional GLPK package. See Appendix G.4 for details. For details, see help glpk_options or the “param” section of the GLPK documentation at https://www.gnu.org/software/octave/doc/interpreter/Linear-Programming.html.

Table C-12:OPF Options for Gurobi
name default§

description

gurobi.method 0

algorithm used by Gurobi for LP/QP problems

0 – primal simplex
1 – dual simplex
2 – barrier
3 – concurrent (LP only)
4 – deterministic concurrent (LP only)
gurobi.timelimit ∞

maximum time allowed for solver (secs)

gurobi.threads 0 (auto)

maximum number of threads to use

gurobi.opts empty

struct of native Gurobi options passed to gurobi_options to override defaults, applied after overrides from gurobi.opt_fname

gurobi.opt_fname empty

name of user-supplied function passed as FNAME argument to gurobi_options to override defaults

gurobi.opt 0

if gurobi.opt_fname is empty and gurobi.opt is non-zero, the value of gurobi.opt_fname is generated by appending gurobi.opt to 'gurobi_user_options_' (for backward compatibility with old Matpower option GRB_OPT)

For opf.dc.solver option set to 'GUROBI' only. Requires the installation of the optional Gurobi package. See Appendix G.5 for 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” at https://www.gurobi.com/documentation/.

Table C-13:OPF Options for Ipopt
name default

description

ipopt.opts empty

struct of native Ipopt options (options.ipopt for ipopt) passed to ipopt_options to override defaults, applied after overrides from ipopt.opt_fname

ipopt.opt_fname empty

name of user-supplied function passed as FNAME argument to ipopt_options to override defaults

ipopt.opt 0

if ipopt.opt_fname is empty and ipopt.opt is non-zero, the value of ipopt.opt_fname is generated by appending ipopt.opt to 'ipopt_user_options_' (for backward compatibility with old Matpower option IPOPT_OPT)

For opf.ac.solver or opf.dc.solver option set to 'IPOPT' only. Requires the installation of the optional Ipopt package [51]. See Appendix G.6 for details. For details, see help ipopt_options and the options reference section of the Ipopt documentation at http://www.coin-or.org/Ipopt/documentation/.

Table C-14:OPF Options for Artelys Knitro
name default

description

knitro.tol_x   −4
10

termination tolerance on x

knitro.tol_f 10−4

termination tolerance on f

knitro.maxit 0

maximum number of iterations

  0 ⇒ use solver’s default value

knitro.opt_fname empty

name of user-supplied native Knitro options file that overrides other options

knitro.opt 0

if knitro.opt_fname is empty and knitro.opt is a positive integer n  , the value of knitro.opt_fname is generated as 'knitro_user_options_n   .txt' (for backward compatibility with old Matpower option KNITRO_OPT)

For opf.ac.solver option set to 'KNITRO' only. Requires the installation of the optional Artelys Knitro package [34]. See Appendix G.7 for details. Note that Artelys Knitro uses the opt_fname option slightly differently from other optional solvers. Specifically, it is the name of a text file processed directly by Artelys Knitro, not a Matlab function that returns an options struct passed to the solver.

Table C-15:OPF Options for MINOPF
name default description
minopf.feastol 0 (  −3
10  ) primal feasibility tolerance
  set to value of opf.violation by default
minopf.rowtol 0 (10−3  ) row tolerance
  set to value of opf.violation by default
minopf.xtol 0 (10−4  ) x  tolerance
minopf.majdamp 0 (0.5) major damping parameter
minopf.mindamp 0 (2.0) minor damping parameter
minopf.penalty 0 (1.0) penalty parameter
minopf.major_it 0 (200) major iterations
minopf.minor_it 0 (2500) minor iterations
minopf.max_it 0 (2500) iteration limit
minopf.verbosity -1 amount of progress output printed by MEX file
-1 – controlled by verbose option
0 – do not print anything
1 – print only only termination status message
2 – print termination status & screen progress
3 – print screen progress, report file (usually fort.9)
minopf.core 0 memory allocation
  defaults to                 2
1200nb + 2(nb + ng)
minopf.supbasic_lim 0 superbasics limit, defaults to 2n + 2n
  b    g
minopf.mult_price 0 (30) multiple price

For opf.ac.solver option set to 'MINOPF' only. Requires the installation of the optional MINOPF package [32]. See Appendix G.8 for 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 (10−8  )

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 passed to 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 to mosek_options to override defaults

mosek.opt 0

if mosek.opt_fname is empty and mosek.opt is non-zero, the value of mosek.opt_fname is generated by appending mosek.opt to 'mosek_user_options_' (for backward compatibility with old Matpower option MOSEK_OPT)

For opf.dc.solver option set to 'MOSEK' only. Requires the installation of the optional MOSEK package. See Appendix G.9 for 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 write your 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 MATLAB manual” 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 10−6  gradient tolerance
pdipm.comptol 10−6  complementarity condition (inequality) tolerance
pdipm.costtol 10−6  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 Appendix G.13 for 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 5× 10−4  primal variable tolerance
tralm.dualtol 5× 10−4  dual variable tolerance
tralm.costtol   −5
10  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 Appendix G.13 for details.

 C.1 Mapping of Old-Style Options to New-Style Options