Home > matpower5.0 > mpoption.m

mpoption

PURPOSE ^

MPOPTION Used to set and retrieve a MATPOWER options struct.

SYNOPSIS ^

function opt = mpoption(varargin)

DESCRIPTION ^

MPOPTION  Used to set and retrieve a MATPOWER options struct.

   OPT = MPOPTION
       Returns the default options struct.

   OPT = MPOPTION(OVERRIDES)
       Returns the default options struct, with some fields overridden
       by values from OVERRIDES, which can be a struct or the name of
       a function that returns a struct.

   OPT = MPOPTION(NAME1, VALUE1, NAME2, VALUE2, ...)
       Same as previous, except override options are specified by NAME,
       VALUE pairs. This can be used to set any part of the options
       struct. The names can be individual fields or multi-level fields
       names with embedded periods. The values can be scalars or structs.

       For backward compatibility, the NAMES and VALUES may correspond
       to old-style MATPOWER option names (elements in the old-style
       options vector) as well.

   OPT = MPOPTION(OPT0)
       Converts an old-style options vector OPT0 into the corresponding
       options struct. If OPT0 is an options struct it does nothing.

   OPT = MPOPTION(OPT0, OVERRIDES)
       Applies overrides to an existing set of options, OPT0, which
       can be an old-style options vector or an options struct.

   OPT = MPOPTION(OPT0, NAME1, VALUE1, NAME2, VALUE2, ...)
       Same as above except it uses the old-style options vector OPT0
       as a base instead of the old default options vector.

   OPT_VECTOR = MPOPTION(OPT, [])
       Creates and returns an old-style options vector from an
       options struct OPT.

   Note: The use of old-style MATPOWER options vectors and their
         names and values has been deprecated and will be removed
         in a future version of MATPOWER. Until then, all uppercase
         option names are not permitted for new top-level options.

   Examples:
       mpopt = mpoption('pf.alg', 'FDXB', 'pf.tol', 1e-4);
       mpopt = mpoption(mpopt, 'opf.dc.solver', 'CPLEX', 'verbose', 2);

The currently defined options are as follows:

   name                    default     description [options]
----------------------    ---------   ----------------------------------
Model options:
   model                   'AC'        AC vs. DC power flow model
       [ 'AC' - use nonlinear AC model & corresponding algorithms/options  ]
       [ 'DC' - use linear DC model & corresponding algorithms/options     ]

Power Flow options:
   pf.alg                  'NR'        AC power flow algorithm
       [ 'NR'   - Newton's method                                          ]
       [ 'FDXB' - Fast-Decoupled (XB version)                              ]
       [ 'FDBX' - Fast-Decoupled (BX version)                              ]
       [ 'GS'   - Gauss-Seidel                                             ]
   pf.tol                  1e-8        termination tolerance on per unit
                                       P & Q mismatch
   pf.nr.max_it            10          maximum number of iterations for
                                       Newton's method
   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.enforce_q_lims       0           enforce gen reactive power limits at
                                       expense of |V|
       [  0 - do NOT enforce limits                                        ]
       [  1 - enforce limits, simultaneous bus type conversion             ]
       [  2 - enforce limits, one-at-a-time bus type conversion            ]

Continuation Power Flow options:
   cpf.parameterization    3           choice of parameterization
       [  1 - natural                                                      ]
       [  2 - arc length                                                   ]
       [  3 - pseudo arc length                                            ]
   cpf.stop_at             'NOSE'      determins stopping criterion
       [ 'NOSE'     - stop when nose point is reached                      ]
       [ 'FULL'     - trace full nose curve                                ]
       [ <lam_stop> - stop upon reaching specified target lambda value     ]
   cpf.step                0.05        continuation power flow step size
   cpf.adapt_step          0           toggle adaptive step size feature
       [  0 - adaptive step size disabled                                  ]
       [  1 - adaptive step size enabled                                   ]
   cpf.error_tol           1e-3        tolerance for adaptive step control
   cpf.step_min            1e-4        minimum allowed step size
   cpf.step_max            0.2         maximum allowed step size
   cpf.plot.level          0           control plotting of noze 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'
   cpf.user_callback_args  <empty>     struct passed to user-defined
                                       callback functions

Optimal Power Flow options:
   opf.ac.solver           'DEFAULT'   AC optimal power flow solver
       [ 'DEFAULT' - choose solver based on availability in the following  ]
       [             order: 'PDIPM', 'MIPS'                                ]
       [ 'MIPS'    - MIPS, Matlab Interior Point Solver, primal/dual       ]
       [             interior point method (pure Matlab)                   ]
       [ 'FMINCON' - MATLAB Optimization Toolbox, FMINCON                  ]
       [ 'IPOPT'   - IPOPT, requires MEX interface to IPOPT solver         ]
       [             available from: https://projects.coin-or.org/Ipopt/   ]
       [ 'KNITRO'  - KNITRO, requires MATLAB Optimization Toolbox and      ]
       [             KNITRO libraries available from: http://www.ziena.com/]
       [ 'MINOPF'  - MINOPF, MINOS-based solver, requires optional         ]
       [             MEX-based MINOPF package, available from:             ]
       [                   http://www.pserc.cornell.edu/minopf/            ]
       [ 'PDIPM'   - PDIPM, primal/dual interior point method, requires    ]
       [             optional MEX-based TSPOPF package, available from:    ]
       [                   http://www.pserc.cornell.edu/tspopf/            ]
       [ 'SDPOPF'  - SDPOPF, solver based on semidefinite relaxation of    ]
       [             OPF problem, requires optional packages:              ]
       [               SDP_PF, available in extras/sdp_pf                  ]
       [               YALMIP, available from:                             ]
       [                   http://users.isy.liu.se/johanl/yalmip/          ]
       [               SDP solver such as SeDuMi, available from:          ]
       [                   http://sedumi.ie.lehigh.edu/                    ]
       [ 'TRALM'   - TRALM, trust region based augmented Langrangian       ]
       [             method, requires TSPOPF (see 'PDIPM')                 ]
   opf.dc.solver           'DEFAULT'   DC optimal power flow solver
       [ 'DEFAULT' - choose solver based on availability in the following  ]
       [             order: 'CPLEX', 'GUROBI', 'MOSEK','BPMPD','OT',       ]
       [             'GLPK' (linear costs only), 'MIPS'                    ]
       [ 'MIPS'    - MIPS, Matlab Interior Point Solver, primal/dual       ]
       [             interior point method (pure Matlab)                   ]
       [ 'BPMPD'   - BPMPD, requires optional MEX-based BPMPD_MEX package  ]
       [             available from: http://www.pserc.cornell.edu/bpmpd/   ]
       [ 'CPLEX'   - CPLEX, requires Matlab interface to CPLEX solver      ]
       [ 'GLPK'    - GLPK, requires interface to GLPK solver               ]
       [             available from: http://www.gnu.org/software/glpk/     ]
       [             (GLPK does not work with quadratic cost functions)    ]
       [ 'GUROBI'  - GUROBI, requires Gurobi optimizer (v. 5+)             ]
       [             available from: http://www.gurobi.com/                ]
       [ 'IPOPT'   - IPOPT, requires MEX interface to IPOPT solver         ]
       [             available from: https://projects.coin-or.org/Ipopt/   ]
       [ 'MOSEK'   - MOSEK, requires Matlab interface to MOSEK solver      ]
       [             available from: http://www.mosek.com/                 ]
       [ 'OT'      - MATLAB Optimization Toolbox, QUADPROG, LINPROG        ]
   opf.violation           5e-6        constraint violation tolerance
   opf.flow_lim            'S'         quantity limited by 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)          ]
   opf.ignore_angle_lim    0           angle diff limits for branches
       [ 0 - include angle difference limits, if specified                 ]
       [ 1 - ignore angle difference limits even if specified              ]
   opf.init_from_mpc       -1          specify whether to use current state
                                       in MATPOWER case to initialize OPF
                                       (currently supported only for Ipopt,
                                        Knitro and MIPS solvers)
       [  -1 - MATPOWER decides, based on solver/algorithm                 ]
       [   0 - ignore current state when initializing OPF                  ]
       [   1 - use current state to initialize OPF                         ]
   opf.return_raw_der      0           for AC OPF, return constraint and
                                       derivative info in results.raw
                                       (in fields g, dg, df, d2f) [ 0 or 1 ]

Output 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.all                 -1          controls pretty-printing of results
       [  -1 - individual flags control what prints                        ]
       [   0 - do not print anything (overrides individual flags, ignored  ]
       [       for files specified as FNAME arg to runpf(), runopf(), etc.)]
       [   1 - print everything (overrides individual flags)               ]
   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           [ 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 constraint info prints        ]
       [   0 - no constraint info (overrides individual flags)             ]
       [   1 - binding constraint info (overrides individual flags)        ]
       [   2 - all constraint info (overrides individual flags)            ]
   out.lim.v               1           control voltage limit info
       [   0 - do not print                                                ]
       [   1 - print binding constraints only                              ]
       [   2 - print all constraints                                       ]
       [   (same options for OUT_LINE_LIM, OUT_PG_LIM, OUT_QG_LIM)         ]
   out.lim.line            1           control line flow limit info
   out.lim.pg              1           control gen active power limit info
   out.lim.qg              1           control gen reactive pwr 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           ]
       [       (overrides individual flags, but not out.all = 1)           ]

Solver specific options:
       name                    default     description [options]
   -----------------------    ---------   ----------------------------------
   MIPS:
       mips.feastol            0           feasibility (equality) tolerance
                                           (set to opf.violation by default)
       mips.gradtol            1e-6        gradient tolerance
       mips.comptol            1e-6        complementary condition
                                           (inequality) tolerance
       mips.costtol            1e-6        optimality tolerance
       mips.max_it             150         maximum number of iterations
       mips.step_control       0           enable step-size cntrl [ 0 or 1 ]
       mips.sc.red_it          20          maximum number of reductions per
                                           iteration with step control
       mips.xi                 0.99995     constant used in alpha updates*
       mips.sigma              0.1         centering parameter*
       mips.z0                 1           used to initialize slack variables*
       mips.alpha_min          1e-8        returns "Numerically Failed" if
                                           either alpha parameter becomes
                                           smaller than this value*
       mips.rho_min            0.95        lower bound on rho_t*
       mips.rho_max            1.05        upper bound on rho_t*
       mips.mu_threshold       1e-5        KT multipliers smaller than this
                                           value for non-binding constraints
                                           are forced to zero
       mips.max_stepsize       1e10        returns "Numerically Failed" if the
                                           2-norm of the reduced Newton step
                                           exceeds this value*
           * See the corresponding Appendix in the manual for details.

   CPLEX:
       cplex.lpmethod          0           solution algorithm 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           solution algorithm for QP problems
           [   0 - automatic: let CPLEX choose                             ]
           [   1 - primal simplex optimizer                                ]
           [   2 - dual simplex optimizer                                  ]
           [   3 - network optimizer                                       ]
           [   4 - barrier optimizer                                       ]
       cplex.opts              <empty>     see CPLEX_OPTIONS for details
       cplex.opt_fname         <empty>     see CPLEX_OPTIONS for details
       cplex.opt               0           see CPLEX_OPTIONS for details

   FMINCON:
       fmincon.alg             4           algorithm used by fmincon() for OPF
                                           for Opt Toolbox 4 and later
            [  1 - active-set (not suitable for large problems)            ]
            [  2 - interior-point, w/default 'bfgs' Hessian approx         ]
            [  3 - interior-point, w/ 'lbfgs' Hessian approx               ]
            [  4 - interior-point, w/exact user-supplied Hessian           ]
            [  5 - interior-point, w/Hessian via finite differences        ]
            [  6 - sqp (not suitable for large problems)                   ]
       fmincon.tol_x           1e-4        termination tol on x
       fmincon.tol_f           1e-4        termination tol on f
       fmincon.max_it          0           maximum number of iterations
                                                           [  0 => default ]

   GUROBI:
       gurobi.method           0           solution algorithm (Method)
           [  -1 - automatic, let Gurobi decide                            ]
           [   0 - primal simplex                                          ]
           [   1 - dual simplex                                            ]
           [   2 - barrier                                                 ]
           [   3 - concurrent (LP only)                                    ]
           [   4 - deterministic concurrent (LP only)                      ]
       gurobi.timelimit        Inf         maximum time allowed (TimeLimit)
       gurobi.threads          0           max number of threads (Threads)
       gurobi.opts             <empty>     see GUROBI_OPTIONS for details
       gurobi.opt_fname        <empty>     see GUROBI_OPTIONS for details
       gurobi.opt              0           see GUROBI_OPTIONS for details

   IPOPT:
       ipopt.opts              <empty>     see IPOPT_OPTIONS for details
       ipopt.opt_fname         <empty>     see IPOPT_OPTIONS for details
       ipopt.opt               0           see IPOPT_OPTIONS for details

   KNITRO:
       knitro.tol_x            1e-4        termination tol on x
       knitro.tol_f            1e-4        termination tol on f
       knitro.opt_fname        <empty>     name of user-supplied native
                                           KNITRO options file that overrides
                                           all other options
       knitro.opt              0           if knitro.opt_fname is empty and
                                           knitro.opt is a non-zero integer N
                                           then knitro.opt_fname is auto-
                                           generated as:
                                           'knitro_user_options_N.txt'

   LINPROG:
       linprog                 <empty>     LINPROG options passed to
                                           OPTIMOPTIONS or OPTIMSET.
                                           see LINPROG in the Optimization
                                           Toolbox for details

   MINOPF:
       minopf.feastol          0 (1e-3)    primal feasibility tolerance
                                           (set to opf.violation by default)
       minopf.rowtol           0 (1e-3)    row tolerance
       minopf.xtol             0 (1e-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)    iterations limit
       minopf.verbosity        -1          amount of progress info printed
           [  -1 - controlled by 'verbose' option                          ]
           [   0 - print nothing                                           ]
           [   1 - print only termination status message                   ]
           [   2 - print termination status and screen progress            ]
           [   3 - print screen progress, report file (usually fort.9)     ]
       minopf.core             0 (1200*nb + 2*(nb+ng)^2) memory allocation
       minopf.supbasic_lim     0 (2*nb + 2*ng) superbasics limit
       minopf.mult_price       0 (30)      multiple price

   MOSEK:
       mosek.lp_alg            0           solution algorithm for LP problems
                                               (MSK_IPAR_OPTIMIZER)
           [   0 - automatic: let MOSEK choose                             ]
           [   1 - interior point                                          ]
           [   4 - primal simplex                                          ]
           [   5 - dual simplex                                            ]
           [   6 - primal dual simplex                                     ]
           [   7 - automatic simplex (MOSEK chooses which simplex method)  ]
           [   10 - concurrent                                             ]
       mosek.max_it            0 (400)     interior point max iterations
                                               (MSK_IPAR_INTPNT_MAX_ITERATIONS)
       mosek.gap_tol           0 (1e-8)    interior point relative gap tol
                                               (MSK_DPAR_INTPNT_TOL_REL_GAP)
       mosek.max_time          0 (-1)      maximum time allowed
                                               (MSK_DPAR_OPTIMIZER_MAX_TIME)
       mosek.num_threads       0 (1)       max number of threads
                                               (MSK_IPAR_INTPNT_NUM_THREADS)
       mosek.opts              <empty>     see MOSEK_OPTIONS for details
       mosek.opt_fname         <empty>     see MOSEK_OPTIONS for details
       mosek.opt               0           see MOSEK_OPTIONS for details

   QUADPROG:
       quadprog                <empty>     QUADPROG options passed to
                                           OPTIMOPTIONS or OPTIMSET.
                                           see QUADPROG in the Optimization
                                           Toolbox for details

   TSPOPF:
       pdipm.feastol           0           feasibility (equality) tolerance
                                           (set to opf.violation by default)
       pdipm.gradtol           1e-6        gradient tolerance
       pdipm.comptol           1e-6        complementary condition
                                           (inequality) tolerance
       pdipm.costtol           1e-6        optimality tolerance
       pdipm.max_it            150         maximum number of iterations
       pdipm.step_control      0           enable step-size cntrl [ 0 or 1 ]
       pdipm.sc.red_it         20          maximum number of reductions per
                                           iteration with step control
       pdipm.sc.smooth_ratio   0.04        piecewise linear curve smoothing
                                           ratio

       tralm.feastol           0           feasibility tolerance
                                           (set to opf.violation by default)
       tralm.primaltol         5e-4        primal variable tolerance
       tralm.dualtol           5e-4        dual variable tolerance
       tralm.costtol           1e-5        optimality tolerance
       tralm.major_it          40          maximum number of major iterations
       tralm.minor_it          40          maximum number of minor iterations
       tralm.smooth_ratio      0.04        piecewise linear curve smoothing
                                           ratio

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function opt = mpoption(varargin)
0002 %MPOPTION  Used to set and retrieve a MATPOWER options struct.
0003 %
0004 %   OPT = MPOPTION
0005 %       Returns the default options struct.
0006 %
0007 %   OPT = MPOPTION(OVERRIDES)
0008 %       Returns the default options struct, with some fields overridden
0009 %       by values from OVERRIDES, which can be a struct or the name of
0010 %       a function that returns a struct.
0011 %
0012 %   OPT = MPOPTION(NAME1, VALUE1, NAME2, VALUE2, ...)
0013 %       Same as previous, except override options are specified by NAME,
0014 %       VALUE pairs. This can be used to set any part of the options
0015 %       struct. The names can be individual fields or multi-level fields
0016 %       names with embedded periods. The values can be scalars or structs.
0017 %
0018 %       For backward compatibility, the NAMES and VALUES may correspond
0019 %       to old-style MATPOWER option names (elements in the old-style
0020 %       options vector) as well.
0021 %
0022 %   OPT = MPOPTION(OPT0)
0023 %       Converts an old-style options vector OPT0 into the corresponding
0024 %       options struct. If OPT0 is an options struct it does nothing.
0025 %
0026 %   OPT = MPOPTION(OPT0, OVERRIDES)
0027 %       Applies overrides to an existing set of options, OPT0, which
0028 %       can be an old-style options vector or an options struct.
0029 %
0030 %   OPT = MPOPTION(OPT0, NAME1, VALUE1, NAME2, VALUE2, ...)
0031 %       Same as above except it uses the old-style options vector OPT0
0032 %       as a base instead of the old default options vector.
0033 %
0034 %   OPT_VECTOR = MPOPTION(OPT, [])
0035 %       Creates and returns an old-style options vector from an
0036 %       options struct OPT.
0037 %
0038 %   Note: The use of old-style MATPOWER options vectors and their
0039 %         names and values has been deprecated and will be removed
0040 %         in a future version of MATPOWER. Until then, all uppercase
0041 %         option names are not permitted for new top-level options.
0042 %
0043 %   Examples:
0044 %       mpopt = mpoption('pf.alg', 'FDXB', 'pf.tol', 1e-4);
0045 %       mpopt = mpoption(mpopt, 'opf.dc.solver', 'CPLEX', 'verbose', 2);
0046 %
0047 %The currently defined options are as follows:
0048 %
0049 %   name                    default     description [options]
0050 %----------------------    ---------   ----------------------------------
0051 %Model options:
0052 %   model                   'AC'        AC vs. DC power flow model
0053 %       [ 'AC' - use nonlinear AC model & corresponding algorithms/options  ]
0054 %       [ 'DC' - use linear DC model & corresponding algorithms/options     ]
0055 %
0056 %Power Flow options:
0057 %   pf.alg                  'NR'        AC power flow algorithm
0058 %       [ 'NR'   - Newton's method                                          ]
0059 %       [ 'FDXB' - Fast-Decoupled (XB version)                              ]
0060 %       [ 'FDBX' - Fast-Decoupled (BX version)                              ]
0061 %       [ 'GS'   - Gauss-Seidel                                             ]
0062 %   pf.tol                  1e-8        termination tolerance on per unit
0063 %                                       P & Q mismatch
0064 %   pf.nr.max_it            10          maximum number of iterations for
0065 %                                       Newton's method
0066 %   pf.fd.max_it            30          maximum number of iterations for
0067 %                                       fast decoupled method
0068 %   pf.gs.max_it            1000        maximum number of iterations for
0069 %                                       Gauss-Seidel method
0070 %   pf.enforce_q_lims       0           enforce gen reactive power limits at
0071 %                                       expense of |V|
0072 %       [  0 - do NOT enforce limits                                        ]
0073 %       [  1 - enforce limits, simultaneous bus type conversion             ]
0074 %       [  2 - enforce limits, one-at-a-time bus type conversion            ]
0075 %
0076 %Continuation Power Flow options:
0077 %   cpf.parameterization    3           choice of parameterization
0078 %       [  1 - natural                                                      ]
0079 %       [  2 - arc length                                                   ]
0080 %       [  3 - pseudo arc length                                            ]
0081 %   cpf.stop_at             'NOSE'      determins stopping criterion
0082 %       [ 'NOSE'     - stop when nose point is reached                      ]
0083 %       [ 'FULL'     - trace full nose curve                                ]
0084 %       [ <lam_stop> - stop upon reaching specified target lambda value     ]
0085 %   cpf.step                0.05        continuation power flow step size
0086 %   cpf.adapt_step          0           toggle adaptive step size feature
0087 %       [  0 - adaptive step size disabled                                  ]
0088 %       [  1 - adaptive step size enabled                                   ]
0089 %   cpf.error_tol           1e-3        tolerance for adaptive step control
0090 %   cpf.step_min            1e-4        minimum allowed step size
0091 %   cpf.step_max            0.2         maximum allowed step size
0092 %   cpf.plot.level          0           control plotting of noze curve
0093 %       [  0 - do not plot nose curve                                       ]
0094 %       [  1 - plot when completed                                          ]
0095 %       [  2 - plot incrementally at each iteration                         ]
0096 %       [  3 - same as 2, with 'pause' at each iteration                    ]
0097 %   cpf.plot.bus            <empty>     index of bus whose voltage is to be
0098 %                                       plotted
0099 %   cpf.user_callback       <empty>     string or cell array of strings
0100 %                                       with names of user callback functions
0101 %                                       see 'help cpf_default_callback'
0102 %   cpf.user_callback_args  <empty>     struct passed to user-defined
0103 %                                       callback functions
0104 %
0105 %Optimal Power Flow options:
0106 %   opf.ac.solver           'DEFAULT'   AC optimal power flow solver
0107 %       [ 'DEFAULT' - choose solver based on availability in the following  ]
0108 %       [             order: 'PDIPM', 'MIPS'                                ]
0109 %       [ 'MIPS'    - MIPS, Matlab Interior Point Solver, primal/dual       ]
0110 %       [             interior point method (pure Matlab)                   ]
0111 %       [ 'FMINCON' - MATLAB Optimization Toolbox, FMINCON                  ]
0112 %       [ 'IPOPT'   - IPOPT, requires MEX interface to IPOPT solver         ]
0113 %       [             available from: https://projects.coin-or.org/Ipopt/   ]
0114 %       [ 'KNITRO'  - KNITRO, requires MATLAB Optimization Toolbox and      ]
0115 %       [             KNITRO libraries available from: http://www.ziena.com/]
0116 %       [ 'MINOPF'  - MINOPF, MINOS-based solver, requires optional         ]
0117 %       [             MEX-based MINOPF package, available from:             ]
0118 %       [                   http://www.pserc.cornell.edu/minopf/            ]
0119 %       [ 'PDIPM'   - PDIPM, primal/dual interior point method, requires    ]
0120 %       [             optional MEX-based TSPOPF package, available from:    ]
0121 %       [                   http://www.pserc.cornell.edu/tspopf/            ]
0122 %       [ 'SDPOPF'  - SDPOPF, solver based on semidefinite relaxation of    ]
0123 %       [             OPF problem, requires optional packages:              ]
0124 %       [               SDP_PF, available in extras/sdp_pf                  ]
0125 %       [               YALMIP, available from:                             ]
0126 %       [                   http://users.isy.liu.se/johanl/yalmip/          ]
0127 %       [               SDP solver such as SeDuMi, available from:          ]
0128 %       [                   http://sedumi.ie.lehigh.edu/                    ]
0129 %       [ 'TRALM'   - TRALM, trust region based augmented Langrangian       ]
0130 %       [             method, requires TSPOPF (see 'PDIPM')                 ]
0131 %   opf.dc.solver           'DEFAULT'   DC optimal power flow solver
0132 %       [ 'DEFAULT' - choose solver based on availability in the following  ]
0133 %       [             order: 'CPLEX', 'GUROBI', 'MOSEK','BPMPD','OT',       ]
0134 %       [             'GLPK' (linear costs only), 'MIPS'                    ]
0135 %       [ 'MIPS'    - MIPS, Matlab Interior Point Solver, primal/dual       ]
0136 %       [             interior point method (pure Matlab)                   ]
0137 %       [ 'BPMPD'   - BPMPD, requires optional MEX-based BPMPD_MEX package  ]
0138 %       [             available from: http://www.pserc.cornell.edu/bpmpd/   ]
0139 %       [ 'CPLEX'   - CPLEX, requires Matlab interface to CPLEX solver      ]
0140 %       [ 'GLPK'    - GLPK, requires interface to GLPK solver               ]
0141 %       [             available from: http://www.gnu.org/software/glpk/     ]
0142 %       [             (GLPK does not work with quadratic cost functions)    ]
0143 %       [ 'GUROBI'  - GUROBI, requires Gurobi optimizer (v. 5+)             ]
0144 %       [             available from: http://www.gurobi.com/                ]
0145 %       [ 'IPOPT'   - IPOPT, requires MEX interface to IPOPT solver         ]
0146 %       [             available from: https://projects.coin-or.org/Ipopt/   ]
0147 %       [ 'MOSEK'   - MOSEK, requires Matlab interface to MOSEK solver      ]
0148 %       [             available from: http://www.mosek.com/                 ]
0149 %       [ 'OT'      - MATLAB Optimization Toolbox, QUADPROG, LINPROG        ]
0150 %   opf.violation           5e-6        constraint violation tolerance
0151 %   opf.flow_lim            'S'         quantity limited by branch flow
0152 %                                       constraints
0153 %       [ 'S' - apparent power flow (limit in MVA)                          ]
0154 %       [ 'P' - active power flow (limit in MW)                             ]
0155 %       [ 'I' - current magnitude (limit in MVA at 1 p.u. voltage)          ]
0156 %   opf.ignore_angle_lim    0           angle diff limits for branches
0157 %       [ 0 - include angle difference limits, if specified                 ]
0158 %       [ 1 - ignore angle difference limits even if specified              ]
0159 %   opf.init_from_mpc       -1          specify whether to use current state
0160 %                                       in MATPOWER case to initialize OPF
0161 %                                       (currently supported only for Ipopt,
0162 %                                        Knitro and MIPS solvers)
0163 %       [  -1 - MATPOWER decides, based on solver/algorithm                 ]
0164 %       [   0 - ignore current state when initializing OPF                  ]
0165 %       [   1 - use current state to initialize OPF                         ]
0166 %   opf.return_raw_der      0           for AC OPF, return constraint and
0167 %                                       derivative info in results.raw
0168 %                                       (in fields g, dg, df, d2f) [ 0 or 1 ]
0169 %
0170 %Output options:
0171 %   verbose                 1           amount of progress info printed
0172 %       [   0 - print no progress info                                      ]
0173 %       [   1 - print a little progress info                                ]
0174 %       [   2 - print a lot of progress info                                ]
0175 %       [   3 - print all progress info                                     ]
0176 %   out.all                 -1          controls pretty-printing of results
0177 %       [  -1 - individual flags control what prints                        ]
0178 %       [   0 - do not print anything (overrides individual flags, ignored  ]
0179 %       [       for files specified as FNAME arg to runpf(), runopf(), etc.)]
0180 %       [   1 - print everything (overrides individual flags)               ]
0181 %   out.sys_sum             1           print system summary       [ 0 or 1 ]
0182 %   out.area_sum            0           print area summaries       [ 0 or 1 ]
0183 %   out.bus                 1           print bus detail           [ 0 or 1 ]
0184 %   out.branch              1           print branch detail        [ 0 or 1 ]
0185 %   out.gen                 0           print generator detail     [ 0 or 1 ]
0186 %   out.lim.all             -1          controls constraint info output
0187 %       [  -1 - individual flags control what constraint info prints        ]
0188 %       [   0 - no constraint info (overrides individual flags)             ]
0189 %       [   1 - binding constraint info (overrides individual flags)        ]
0190 %       [   2 - all constraint info (overrides individual flags)            ]
0191 %   out.lim.v               1           control voltage limit info
0192 %       [   0 - do not print                                                ]
0193 %       [   1 - print binding constraints only                              ]
0194 %       [   2 - print all constraints                                       ]
0195 %       [   (same options for OUT_LINE_LIM, OUT_PG_LIM, OUT_QG_LIM)         ]
0196 %   out.lim.line            1           control line flow limit info
0197 %   out.lim.pg              1           control gen active power limit info
0198 %   out.lim.qg              1           control gen reactive pwr limit info
0199 %   out.force               0           print results even if success
0200 %                                       flag = 0                   [ 0 or 1 ]
0201 %   out.suppress_detail     -1          suppress all output but system summary
0202 %       [  -1 - suppress details for large systems (> 500 buses)            ]
0203 %       [   0 - do not suppress any output specified by other flags         ]
0204 %       [   1 - suppress all output except system summary section           ]
0205 %       [       (overrides individual flags, but not out.all = 1)           ]
0206 %
0207 %Solver specific options:
0208 %       name                    default     description [options]
0209 %   -----------------------    ---------   ----------------------------------
0210 %   MIPS:
0211 %       mips.feastol            0           feasibility (equality) tolerance
0212 %                                           (set to opf.violation by default)
0213 %       mips.gradtol            1e-6        gradient tolerance
0214 %       mips.comptol            1e-6        complementary condition
0215 %                                           (inequality) tolerance
0216 %       mips.costtol            1e-6        optimality tolerance
0217 %       mips.max_it             150         maximum number of iterations
0218 %       mips.step_control       0           enable step-size cntrl [ 0 or 1 ]
0219 %       mips.sc.red_it          20          maximum number of reductions per
0220 %                                           iteration with step control
0221 %       mips.xi                 0.99995     constant used in alpha updates*
0222 %       mips.sigma              0.1         centering parameter*
0223 %       mips.z0                 1           used to initialize slack variables*
0224 %       mips.alpha_min          1e-8        returns "Numerically Failed" if
0225 %                                           either alpha parameter becomes
0226 %                                           smaller than this value*
0227 %       mips.rho_min            0.95        lower bound on rho_t*
0228 %       mips.rho_max            1.05        upper bound on rho_t*
0229 %       mips.mu_threshold       1e-5        KT multipliers smaller than this
0230 %                                           value for non-binding constraints
0231 %                                           are forced to zero
0232 %       mips.max_stepsize       1e10        returns "Numerically Failed" if the
0233 %                                           2-norm of the reduced Newton step
0234 %                                           exceeds this value*
0235 %           * See the corresponding Appendix in the manual for details.
0236 %
0237 %   CPLEX:
0238 %       cplex.lpmethod          0           solution algorithm for LP problems
0239 %           [   0 - automatic: let CPLEX choose                             ]
0240 %           [   1 - primal simplex                                          ]
0241 %           [   2 - dual simplex                                            ]
0242 %           [   3 - network simplex                                         ]
0243 %           [   4 - barrier                                                 ]
0244 %           [   5 - sifting                                                 ]
0245 %           [   6 - concurrent (dual, barrier, and primal)                  ]
0246 %       cplex.qpmethod          0           solution algorithm for QP problems
0247 %           [   0 - automatic: let CPLEX choose                             ]
0248 %           [   1 - primal simplex optimizer                                ]
0249 %           [   2 - dual simplex optimizer                                  ]
0250 %           [   3 - network optimizer                                       ]
0251 %           [   4 - barrier optimizer                                       ]
0252 %       cplex.opts              <empty>     see CPLEX_OPTIONS for details
0253 %       cplex.opt_fname         <empty>     see CPLEX_OPTIONS for details
0254 %       cplex.opt               0           see CPLEX_OPTIONS for details
0255 %
0256 %   FMINCON:
0257 %       fmincon.alg             4           algorithm used by fmincon() for OPF
0258 %                                           for Opt Toolbox 4 and later
0259 %            [  1 - active-set (not suitable for large problems)            ]
0260 %            [  2 - interior-point, w/default 'bfgs' Hessian approx         ]
0261 %            [  3 - interior-point, w/ 'lbfgs' Hessian approx               ]
0262 %            [  4 - interior-point, w/exact user-supplied Hessian           ]
0263 %            [  5 - interior-point, w/Hessian via finite differences        ]
0264 %            [  6 - sqp (not suitable for large problems)                   ]
0265 %       fmincon.tol_x           1e-4        termination tol on x
0266 %       fmincon.tol_f           1e-4        termination tol on f
0267 %       fmincon.max_it          0           maximum number of iterations
0268 %                                                           [  0 => default ]
0269 %
0270 %   GUROBI:
0271 %       gurobi.method           0           solution algorithm (Method)
0272 %           [  -1 - automatic, let Gurobi decide                            ]
0273 %           [   0 - primal simplex                                          ]
0274 %           [   1 - dual simplex                                            ]
0275 %           [   2 - barrier                                                 ]
0276 %           [   3 - concurrent (LP only)                                    ]
0277 %           [   4 - deterministic concurrent (LP only)                      ]
0278 %       gurobi.timelimit        Inf         maximum time allowed (TimeLimit)
0279 %       gurobi.threads          0           max number of threads (Threads)
0280 %       gurobi.opts             <empty>     see GUROBI_OPTIONS for details
0281 %       gurobi.opt_fname        <empty>     see GUROBI_OPTIONS for details
0282 %       gurobi.opt              0           see GUROBI_OPTIONS for details
0283 %
0284 %   IPOPT:
0285 %       ipopt.opts              <empty>     see IPOPT_OPTIONS for details
0286 %       ipopt.opt_fname         <empty>     see IPOPT_OPTIONS for details
0287 %       ipopt.opt               0           see IPOPT_OPTIONS for details
0288 %
0289 %   KNITRO:
0290 %       knitro.tol_x            1e-4        termination tol on x
0291 %       knitro.tol_f            1e-4        termination tol on f
0292 %       knitro.opt_fname        <empty>     name of user-supplied native
0293 %                                           KNITRO options file that overrides
0294 %                                           all other options
0295 %       knitro.opt              0           if knitro.opt_fname is empty and
0296 %                                           knitro.opt is a non-zero integer N
0297 %                                           then knitro.opt_fname is auto-
0298 %                                           generated as:
0299 %                                           'knitro_user_options_N.txt'
0300 %
0301 %   LINPROG:
0302 %       linprog                 <empty>     LINPROG options passed to
0303 %                                           OPTIMOPTIONS or OPTIMSET.
0304 %                                           see LINPROG in the Optimization
0305 %                                           Toolbox for details
0306 %
0307 %   MINOPF:
0308 %       minopf.feastol          0 (1e-3)    primal feasibility tolerance
0309 %                                           (set to opf.violation by default)
0310 %       minopf.rowtol           0 (1e-3)    row tolerance
0311 %       minopf.xtol             0 (1e-4)    x tolerance
0312 %       minopf.majdamp          0 (0.5)     major damping parameter
0313 %       minopf.mindamp          0 (2.0)     minor damping parameter
0314 %       minopf.penalty          0 (1.0)     penalty parameter
0315 %       minopf.major_it         0 (200)     major iterations
0316 %       minopf.minor_it         0 (2500)    minor iterations
0317 %       minopf.max_it           0 (2500)    iterations limit
0318 %       minopf.verbosity        -1          amount of progress info printed
0319 %           [  -1 - controlled by 'verbose' option                          ]
0320 %           [   0 - print nothing                                           ]
0321 %           [   1 - print only termination status message                   ]
0322 %           [   2 - print termination status and screen progress            ]
0323 %           [   3 - print screen progress, report file (usually fort.9)     ]
0324 %       minopf.core             0 (1200*nb + 2*(nb+ng)^2) memory allocation
0325 %       minopf.supbasic_lim     0 (2*nb + 2*ng) superbasics limit
0326 %       minopf.mult_price       0 (30)      multiple price
0327 %
0328 %   MOSEK:
0329 %       mosek.lp_alg            0           solution algorithm for LP problems
0330 %                                               (MSK_IPAR_OPTIMIZER)
0331 %           [   0 - automatic: let MOSEK choose                             ]
0332 %           [   1 - interior point                                          ]
0333 %           [   4 - primal simplex                                          ]
0334 %           [   5 - dual simplex                                            ]
0335 %           [   6 - primal dual simplex                                     ]
0336 %           [   7 - automatic simplex (MOSEK chooses which simplex method)  ]
0337 %           [   10 - concurrent                                             ]
0338 %       mosek.max_it            0 (400)     interior point max iterations
0339 %                                               (MSK_IPAR_INTPNT_MAX_ITERATIONS)
0340 %       mosek.gap_tol           0 (1e-8)    interior point relative gap tol
0341 %                                               (MSK_DPAR_INTPNT_TOL_REL_GAP)
0342 %       mosek.max_time          0 (-1)      maximum time allowed
0343 %                                               (MSK_DPAR_OPTIMIZER_MAX_TIME)
0344 %       mosek.num_threads       0 (1)       max number of threads
0345 %                                               (MSK_IPAR_INTPNT_NUM_THREADS)
0346 %       mosek.opts              <empty>     see MOSEK_OPTIONS for details
0347 %       mosek.opt_fname         <empty>     see MOSEK_OPTIONS for details
0348 %       mosek.opt               0           see MOSEK_OPTIONS for details
0349 %
0350 %   QUADPROG:
0351 %       quadprog                <empty>     QUADPROG options passed to
0352 %                                           OPTIMOPTIONS or OPTIMSET.
0353 %                                           see QUADPROG in the Optimization
0354 %                                           Toolbox for details
0355 %
0356 %   TSPOPF:
0357 %       pdipm.feastol           0           feasibility (equality) tolerance
0358 %                                           (set to opf.violation by default)
0359 %       pdipm.gradtol           1e-6        gradient tolerance
0360 %       pdipm.comptol           1e-6        complementary condition
0361 %                                           (inequality) tolerance
0362 %       pdipm.costtol           1e-6        optimality tolerance
0363 %       pdipm.max_it            150         maximum number of iterations
0364 %       pdipm.step_control      0           enable step-size cntrl [ 0 or 1 ]
0365 %       pdipm.sc.red_it         20          maximum number of reductions per
0366 %                                           iteration with step control
0367 %       pdipm.sc.smooth_ratio   0.04        piecewise linear curve smoothing
0368 %                                           ratio
0369 %
0370 %       tralm.feastol           0           feasibility tolerance
0371 %                                           (set to opf.violation by default)
0372 %       tralm.primaltol         5e-4        primal variable tolerance
0373 %       tralm.dualtol           5e-4        dual variable tolerance
0374 %       tralm.costtol           1e-5        optimality tolerance
0375 %       tralm.major_it          40          maximum number of major iterations
0376 %       tralm.minor_it          40          maximum number of minor iterations
0377 %       tralm.smooth_ratio      0.04        piecewise linear curve smoothing
0378 %                                           ratio
0379 
0380 %   MATPOWER
0381 %   $Id: mpoption.m 2466 2014-12-12 21:01:55Z ray $
0382 %   by Ray Zimmerman, PSERC Cornell
0383 %   Copyright (c) 2013 by Power System Engineering Research Center (PSERC)
0384 %
0385 %   This file is part of MATPOWER.
0386 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0387 %
0388 %   MATPOWER is free software: you can redistribute it and/or modify
0389 %   it under the terms of the GNU General Public License as published
0390 %   by the Free Software Foundation, either version 3 of the License,
0391 %   or (at your option) any later version.
0392 %
0393 %   MATPOWER is distributed in the hope that it will be useful,
0394 %   but WITHOUT ANY WARRANTY; without even the implied warranty of
0395 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0396 %   GNU General Public License for more details.
0397 %
0398 %   You should have received a copy of the GNU General Public License
0399 %   along with MATPOWER. If not, see <http://www.gnu.org/licenses/>.
0400 %
0401 %   Additional permission under GNU GPL version 3 section 7
0402 %
0403 %   If you modify MATPOWER, or any covered work, to interface with
0404 %   other modules (such as MATLAB code and MEX-files) available in a
0405 %   MATLAB(R) or comparable environment containing parts covered
0406 %   under other licensing terms, the licensors of MATPOWER grant
0407 %   you additional permission to convey the resulting work.
0408 
0409 %% some constants
0410 N = 124;                %% number of options in old-style vector
0411 v = mpoption_version;   %% version number of MATPOWER options struct
0412 
0413 %% initialize flags and arg counter
0414 have_opt0 = 0;          %% existing options struct or vector provided?
0415 have_old_style_ov = 0;  %% override options using old-style names?
0416 return_old_style = 0;   %% return value as old-style vector?
0417 k = 1;
0418 if nargin > 0
0419     opt0 = varargin{k};
0420     if (isstruct(opt0) && isfield(opt0, 'v')) || ...
0421         (isnumeric(opt0) && size(opt0, 1) == N && size(opt0, 2) == 1)
0422         have_opt0 = 1;
0423         k = k + 1;
0424     end
0425 end
0426 
0427 %% create base options vector to which overrides are made
0428 if have_opt0
0429     if isstruct(opt0)               %% it's already a valid options struct
0430         if DEBUG, fprintf('OPT0 is a valid options struct\n'); end
0431         if opt0.v < v
0432             %% convert older version to current version
0433 %             switch v
0434 %                 case 1
0435 %                     %% convert version 1 to current
0436 %             end
0437         end
0438         opt = opt0;
0439     else                            %% convert from old-style options vector
0440         if DEBUG, fprintf('OPT0 is a old-style options vector\n'); end
0441         opt = mpoption_v2s(opt0);
0442     end
0443 else                                %% use default options struct as base
0444     if DEBUG, fprintf('no OPT0, starting with default options struct\n'); end
0445     opt = mpoption_default();
0446 end
0447 
0448 
0449 %% do we have OVERRIDES or NAME/VALUE pairs
0450 ov = [];
0451 if nargin - k == 0          %% looking at last arg, must be OVERRIDES
0452     if isstruct(varargin{k})        %% OVERRIDES provided as struct
0453         if DEBUG, fprintf('OVERRIDES struct\n'); end
0454         ov = varargin{k};
0455     elseif ischar(varargin{k})      %% OVERRIDES provided as file/function name
0456         if DEBUG, fprintf('OVERRIDES file/function name\n'); end
0457         try
0458             ov = feval(varargin{k});
0459         catch
0460             error('mpoption: Unable to load MATPOWER options from ''%s''', varargin{k});
0461         end
0462         if ~isstruct(ov)
0463             error('mpoption: calling ''%s'' did not return a struct', varargin{k});
0464         end
0465     elseif isempty(varargin{k})
0466         return_old_style = 1;
0467     else
0468         error('mpoption: OVERRIDES must be a struct or the name of a function that returns a struct');
0469     end
0470 elseif nargin - k > 0 && mod(nargin-k, 2)   %% even number of remaining args
0471     if DEBUG, fprintf('NAME/VALUE pairs override defaults\n'); end
0472     %% process NAME/VALUE pairs
0473     if (have_opt0 && isnumeric(opt0)) ...   %% modifying an old-style options vector
0474             || strcmp(varargin{k}, upper(varargin{k}))
0475             %% this code implies that top-level option fields
0476             %% cannot be all uppercase
0477         if have_opt0
0478             have_old_style_ov = 1;
0479             %% convert pairs to struct
0480             while k < nargin
0481                 name = varargin{k};
0482                 val  = varargin{k+1};
0483                 k = k + 2;
0484                 ov.(name) = val;
0485             end
0486         else
0487             opt_v = mpoption_old(varargin{:});  %% create modified vector ...
0488             opt = mpoption_v2s(opt_v);          %% ... then convert
0489         end
0490     else                                    %% modifying options struct
0491         %% convert pairs to struct
0492         while k < nargin
0493             name = varargin{k};
0494             val  = varargin{k+1};
0495             k = k + 2;
0496             if have_fcn('octave')
0497                 c = strsplit(name, '.');
0498             else
0499                 [c, matches] = regexp(name, '\.', 'split', 'match');
0500                 if isempty(c) && ~isempty(name) %% workaround for bug in Matlab 7.3 (R2006b)
0501                     c{1} = name;
0502                 end
0503             end
0504             s = struct();
0505             for i = 1:length(c)
0506                 s(i).type = '.';
0507                 s(i).subs = c{i};
0508             end
0509             ov = subsasgn(ov, s, val);
0510         end
0511     end
0512 elseif nargin == 0 || nargin == 1
0513     if DEBUG, fprintf('no OVERRIDES, return default options struct or converted OPT0 vector\n'); end
0514 else
0515     error('mpoption: invalid calling syntax, see ''help mpoption'' to double-check the valid options');
0516 end
0517 
0518 %% apply overrides
0519 if ~isempty(ov)
0520     if have_old_style_ov
0521         opt = apply_old_mpoption_overrides(opt, ov);
0522     else
0523         vf = nested_struct_copy(mpoption_default(), mpoption_info_mips('V'));
0524         vf = nested_struct_copy(vf, mpoption_optional_fields());
0525         ex = struct(...
0526             'name', {...
0527                 'cpf.user_callback_args' ...
0528             }, ...
0529             'check', {...
0530                 0 ...
0531             }, ...
0532             'copy_mode', {...
0533                 '' ...
0534             } ...
0535         );
0536         %% add exceptions for optional packages
0537         opt_pkgs = mpoption_optional_pkgs();
0538         n = length(ex);
0539         for k = 1:length(opt_pkgs)
0540             fname = ['mpoption_info_' opt_pkgs{k}];
0541             if exist(fname, 'file') == 2
0542                 opt_ex = feval(fname, 'E');
0543                 nex = length(opt_ex);
0544                 if ~isempty(opt_ex)
0545                     for j = 1:nex
0546                         ex(n+j).name = opt_ex(j).name;
0547                     end
0548                     if isfield(opt_ex, 'check')
0549                         for j = 1:nex
0550                             ex(n+j).check = opt_ex(j).check;
0551                         end
0552                     end
0553                     if isfield(opt_ex, 'copy_mode')
0554                         for j = 1:nex
0555                             ex(n+j).copy_mode = opt_ex(j).copy_mode;
0556                         end
0557                     end
0558                     if isfield(opt_ex, 'valid_fields')
0559                         for j = 1:nex
0560                             ex(n+j).valid_fields = opt_ex(j).valid_fields;
0561                         end
0562                     end
0563                     n = n + nex;
0564                 end
0565             end
0566         end
0567         nsc_opt = struct('check', 1, 'valid_fields', vf, 'exceptions', ex);
0568 %         if have_fcn('catchme')
0569 %             try
0570 %                 opt = nested_struct_copy(opt, ov, nsc_opt);
0571 %             catch me
0572 %                 str = strrep(me.message, 'field', 'option');
0573 %                 str = strrep(str, 'nested_struct_copy', 'mpoption');
0574 %                 error(str);
0575 %             end
0576 %         else
0577             try
0578                 opt = nested_struct_copy(opt, ov, nsc_opt);
0579             catch
0580                 me = lasterr;
0581                 str = strrep(me, 'field', 'option');
0582                 str = strrep(str, 'nested_struct_copy', 'mpoption');
0583                 error(str);
0584             end
0585 %         end
0586     end
0587 end
0588 if return_old_style
0589     opt = mpoption_s2v(opt);
0590 end
0591 
0592 
0593 %%-------------------------------------------------------------------
0594 function opt = apply_old_mpoption_overrides(opt0, ov)
0595 %
0596 %   OPT0 is assumed to already have all of the fields and sub-fields found
0597 %   in the default options struct.
0598 
0599 %% initialize output
0600 opt = opt0;
0601 
0602 errstr = 'mpoption: %g is not a valid value for the old-style ''%s'' option';
0603 fields = fieldnames(ov);
0604 for f = 1:length(fields)
0605     ff = fields{f};
0606     switch ff
0607         case 'PF_ALG'
0608             switch ov.(ff)
0609                 case 1
0610                     opt.pf.alg = 'NR';      %% Newton's method
0611                 case 2
0612                     opt.pf.alg = 'FDXB';    %% fast-decoupled (XB version)
0613                 case 3
0614                     opt.pf.alg = 'FDBX';    %% fast-decoupled (BX version)
0615                 case 4
0616                     opt.pf.alg = 'GS';      %% Gauss-Seidel
0617                 otherwise
0618                     error(errstr, ov.(ff), ff);
0619             end
0620         case 'PF_TOL'
0621             opt.pf.tol = ov.(ff);
0622         case 'PF_MAX_IT'
0623             opt.pf.nr.max_it = ov.(ff);
0624         case 'PF_MAX_IT_FD'
0625             opt.pf.fd.max_it = ov.(ff);
0626         case 'PF_MAX_IT_GS'
0627             opt.pf.gs.max_it = ov.(ff);
0628         case 'ENFORCE_Q_LIMS'
0629             opt.pf.enforce_q_lims = ov.(ff);
0630         case 'PF_DC'
0631             switch ov.(ff)
0632                 case 0
0633                     opt.model = 'AC';
0634                 case 1
0635                     opt.model = 'DC';
0636                 otherwise
0637                     error(errstr, ov.(ff), ff);
0638             end
0639         case 'OPF_ALG'
0640             switch ov.(ff)
0641                 case 0
0642                     opt.opf.ac.solver = 'DEFAULT';
0643                 case 500
0644                     opt.opf.ac.solver = 'MINOPF';
0645                 case 520
0646                     opt.opf.ac.solver = 'FMINCON';
0647                 case {540, 545}
0648                     opt.opf.ac.solver = 'PDIPM';
0649                     if ov.(ff) == 545
0650                         opt.pdipm.step_control = 1;
0651                     else
0652                         opt.pdipm.step_control = 0;
0653                     end
0654                 case 550
0655                     opt.opf.ac.solver = 'TRALM';
0656                 case {560, 565}
0657                     opt.opf.ac.solver = 'MIPS';
0658                     if ov.(ff) == 565
0659                         opt.mips.step_control = 1;
0660                     else
0661                         opt.mips.step_control = 0;
0662                     end
0663                 case 580
0664                     opt.opf.ac.solver = 'IPOPT';
0665                 case 600
0666                     opt.opf.ac.solver = 'KNITRO';
0667                 otherwise
0668                     error(errstr, ov.(ff), ff);
0669             end
0670         case 'OPF_VIOLATION'
0671             opt.opf.violation = ov.(ff);
0672         case 'CONSTR_TOL_X'
0673             opt.fmincon.tol_x = ov.(ff);
0674             opt.knitro.tol_x = ov.(ff);
0675         case 'CONSTR_TOL_F'
0676             opt.fmincon.tol_f = ov.(ff);
0677             opt.knitro.tol_f = ov.(ff);
0678         case 'CONSTR_MAX_IT'
0679             opt.fmincon.max_it = ov.(ff);
0680         case 'OPF_FLOW_LIM'
0681             switch ov.(ff)
0682                 case 0
0683                     opt.opf.flow_lim = 'S';   %% apparent power (MVA)
0684                 case 1
0685                     opt.opf.flow_lim = 'P';   %% real power (MW)
0686                 case 2
0687                     opt.opf.flow_lim = 'I';   %% current magnitude (MVA @ 1 p.u. voltage)
0688                 otherwise
0689                     error(errstr, ov.(ff), ff);
0690             end
0691         case 'OPF_IGNORE_ANG_LIM'
0692             opt.opf.ignore_angle_lim = ov.(ff);
0693         case 'OPF_ALG_DC'
0694             switch ov.(ff)
0695                 case 0
0696                     opt.opf.dc.solver = 'DEFAULT';
0697                 case 100
0698                     opt.opf.dc.solver = 'BPMPD';
0699                 case {200, 250}
0700                     opt.opf.dc.solver = 'MIPS';
0701                     if ov.(ff) == 250
0702                         opt.mips.step_control = 1;
0703                     else
0704                         opt.mips.step_control = 0;
0705                     end
0706                 case 300
0707                     opt.opf.dc.solver = 'OT';     %% QUADPROG, LINPROG
0708                 case 400
0709                     opt.opf.dc.solver = 'IPOPT';
0710                 case 500
0711                     opt.opf.dc.solver = 'CPLEX';
0712                 case 600
0713                     opt.opf.dc.solver = 'MOSEK';
0714                 case 700
0715                     opt.opf.dc.solver = 'GUROBI';
0716                 otherwise
0717                     error(errstr, ov.(ff), ff);
0718             end
0719         case 'VERBOSE'
0720             opt.verbose = ov.(ff);
0721         case 'OUT_ALL'
0722             opt.out.all = ov.(ff);
0723         case 'OUT_SYS_SUM'
0724             opt.out.sys_sum = ov.(ff);
0725         case 'OUT_AREA_SUM'
0726             opt.out.area_sum = ov.(ff);
0727         case 'OUT_BUS'
0728             opt.out.bus = ov.(ff);
0729         case 'OUT_BRANCH'
0730             opt.out.branch = ov.(ff);
0731         case 'OUT_GEN'
0732             opt.out.gen = ov.(ff);
0733         case 'OUT_ALL_LIM'
0734             opt.out.lim.all = ov.(ff);
0735         case 'OUT_V_LIM'
0736             opt.out.lim.v = ov.(ff);
0737         case 'OUT_LINE_LIM'
0738             opt.out.lim.line = ov.(ff);
0739         case 'OUT_PG_LIM'
0740             opt.out.lim.pg = ov.(ff);
0741         case 'OUT_QG_LIM'
0742             opt.out.lim.qg = ov.(ff);
0743         case 'OUT_FORCE'
0744             opt.out.force = ov.(ff);
0745         case 'RETURN_RAW_DER'
0746             opt.opf.return_raw_der = ov.(ff);
0747         case 'FMC_ALG'
0748             opt.fmincon.alg = ov.(ff);
0749         case 'KNITRO_OPT'
0750             opt.knitro.opt = ov.(ff);
0751         case 'IPOPT_OPT'
0752             opt.ipopt.opt = ov.(ff);
0753         case 'MNS_FEASTOL'
0754             opt.minopf.feastol = ov.(ff);
0755         case 'MNS_ROWTOL'
0756             opt.minopf.rowtol = ov.(ff);
0757         case 'MNS_XTOL'
0758             opt.minopf.xtol = ov.(ff);
0759         case 'MNS_MAJDAMP'
0760             opt.minopf.majdamp = ov.(ff);
0761         case 'MNS_MINDAMP'
0762             opt.minopf.mindamp = ov.(ff);
0763         case 'MNS_PENALTY_PARM'
0764             opt.minopf.penalty = ov.(ff);
0765         case 'MNS_MAJOR_IT'
0766             opt.minopf.major_it = ov.(ff);
0767         case 'MNS_MINOR_IT'
0768             opt.minopf.minor_it = ov.(ff);
0769         case 'MNS_MAX_IT'
0770             opt.minopf.max_it = ov.(ff);
0771         case 'MNS_VERBOSITY'
0772             opt.minopf.verbosity = ov.(ff);
0773         case 'MNS_CORE'
0774             opt.minopf.core = ov.(ff);
0775         case 'MNS_SUPBASIC_LIM'
0776             opt.minopf.supbasic_lim = ov.(ff);
0777         case 'MNS_MULT_PRICE'
0778             opt.minopf.mult_price = ov.(ff);
0779         case 'FORCE_PC_EQ_P0'
0780             opt.sopf.force_Pc_eq_P0 = ov.(ff);
0781         case 'PDIPM_FEASTOL'
0782             opt.mips.feastol = ov.(ff);
0783             opt.pdipm.feastol = ov.(ff);
0784         case 'PDIPM_GRADTOL'
0785             opt.mips.gradtol = ov.(ff);
0786             opt.pdipm.gradtol = ov.(ff);
0787         case 'PDIPM_COMPTOL'
0788             opt.mips.comptol = ov.(ff);
0789             opt.pdipm.comptol = ov.(ff);
0790         case 'PDIPM_COSTTOL'
0791             opt.mips.costtol = ov.(ff);
0792             opt.pdipm.costtol = ov.(ff);
0793         case 'PDIPM_MAX_IT'
0794             opt.mips.max_it = ov.(ff);
0795             opt.pdipm.max_it = ov.(ff);
0796         case 'SCPDIPM_RED_IT'
0797             opt.mips.sc.red_it = ov.(ff);
0798             opt.pdipm.sc.red_it = ov.(ff);
0799         case 'TRALM_FEASTOL'
0800             opt.tralm.feastol = ov.(ff);
0801         case 'TRALM_PRIMETOL'
0802             opt.tralm.primaltol = ov.(ff);
0803         case 'TRALM_DUALTOL'
0804             opt.tralm.dualtol = ov.(ff);
0805         case 'TRALM_COSTTOL'
0806             opt.tralm.costtol = ov.(ff);
0807         case 'TRALM_MAJOR_IT'
0808             opt.tralm.major_it = ov.(ff);
0809         case 'TRALM_MINOR_IT'
0810             opt.tralm.minor_it = ov.(ff);
0811         case 'SMOOTHING_RATIO'
0812             opt.pdipm.sc.smooth_ratio = ov.(ff);
0813             opt.tralm.smooth_ratio = ov.(ff);
0814         case 'CPLEX_LPMETHOD'
0815             opt.cplex.lpmethod = ov.(ff);
0816         case 'CPLEX_QPMETHOD'
0817             opt.cplex.qpmethod = ov.(ff);
0818         case 'CPLEX_OPT'
0819             opt.cplex.opt = ov.(ff);
0820         case 'MOSEK_LP_ALG'
0821             opt.mosek.lp_alg = ov.(ff);
0822         case 'MOSEK_MAX_IT'
0823             opt.mosek.max_it = ov.(ff);
0824         case 'MOSEK_GAP_TOL'
0825             opt.mosek.gap_tol = ov.(ff);
0826         case 'MOSEK_MAX_TIME'
0827             opt.mosek.max_time = ov.(ff);
0828         case 'MOSEK_NUM_THREADS'
0829             opt.mosek.num_threads = ov.(ff);
0830         case 'MOSEK_OPT'
0831             opt.mosek.opt = ov.(ff);
0832         case 'GRB_METHOD'
0833             opt.gurobi.method = ov.(ff);
0834         case 'GRB_TIMELIMIT'
0835             opt.gurobi.timelimit = ov.(ff);
0836         case 'GRB_THREADS'
0837             opt.gurobi.threads = ov.(ff);
0838         case 'GRB_OPT'
0839             opt.gurobi.opt = ov.(ff);
0840         otherwise
0841             error('mpoption: ''%s'' is not a valid old-style option name', ff);
0842     end
0843 end
0844 % ov
0845 
0846 
0847 %%-------------------------------------------------------------------
0848 function opt_s = mpoption_v2s(opt_v)
0849 if DEBUG, fprintf('mpoption_v2s()\n'); end
0850 opt_s = mpoption_default();
0851 errstr = 'mpoption: %g is not a valid value for the old-style ''%s'' option';
0852 switch opt_v(1)                                 %% PF_ALG
0853     case 1
0854         opt_s.pf.alg = 'NR';        %% Newton's method
0855     case 2
0856         opt_s.pf.alg = 'FDXB';      %% fast-decoupled (XB version)
0857     case 3
0858         opt_s.pf.alg = 'FDBX';      %% fast-decoupled (BX version)
0859     case 4
0860         opt_s.pf.alg = 'GS';        %% Gauss-Seidel
0861     otherwise
0862         error(errstr, opt_v(1), 'PF_ALG');
0863 end
0864 opt_s.pf.tol                = opt_v(2);         %% PF_TOL
0865 opt_s.pf.nr.max_it          = opt_v(3);         %% PF_MAX_IT
0866 opt_s.pf.fd.max_it          = opt_v(4);         %% PF_MAX_IT_FD
0867 opt_s.pf.gs.max_it          = opt_v(5);         %% PF_MAX_IT_GS
0868 opt_s.pf.enforce_q_lims     = opt_v(6);         %% ENFORCE_Q_LIMS
0869 switch opt_v(10)                                %% PF_DC
0870     case 0
0871         opt_s.model = 'AC';
0872     case 1
0873         opt_s.model = 'DC';
0874     otherwise
0875         error(errstr, opt_v(10), 'PF_DC');
0876 end
0877 switch opt_v(11)                                %% OPF_ALG
0878     case 0
0879         opt_s.opf.ac.solver = 'DEFAULT';
0880     case 500
0881         opt_s.opf.ac.solver = 'MINOPF';
0882     case 520
0883         opt_s.opf.ac.solver = 'FMINCON';
0884     case {540, 545}
0885         opt_s.opf.ac.solver = 'PDIPM';
0886     case 550
0887         opt_s.opf.ac.solver = 'TRALM';
0888     case {560, 565}
0889         opt_s.opf.ac.solver = 'MIPS';
0890     case 580
0891         opt_s.opf.ac.solver = 'IPOPT';
0892     case 600
0893         opt_s.opf.ac.solver = 'KNITRO';
0894     otherwise
0895         error(errstr, opt_v(11), 'OPF_ALG');
0896 end
0897 opt_s.opf.violation         = opt_v(16);        %% OPF_VIOLATION
0898 
0899 opt_s.fmincon.tol_x         = opt_v(17);        %% CONSTR_TOL_X
0900 opt_s.fmincon.tol_f         = opt_v(18);        %% CONSTR_TOL_F
0901 opt_s.fmincon.max_it        = opt_v(19);        %% CONSTR_MAX_IT
0902 
0903 opt_s.knitro.tol_x          = opt_v(17);        %% CONSTR_TOL_X
0904 opt_s.knitro.tol_f          = opt_v(18);        %% CONSTR_TOL_F
0905 
0906 switch opt_v(24)                                %% OPF_FLOW_LIM
0907     case 0
0908         opt_s.opf.flow_lim = 'S';   %% apparent power (MVA)
0909     case 1
0910         opt_s.opf.flow_lim = 'P';   %% real power (MW)
0911     case 2
0912         opt_s.opf.flow_lim = 'I';   %% current magnitude (MVA @ 1 p.u. voltage)
0913     otherwise
0914         error(errstr, opt_v(10), 'PF_DC');
0915 end
0916 
0917 opt_s.opf.ignore_angle_lim  = opt_v(25);        %% OPF_IGNORE_ANG_LIM
0918 
0919 switch opt_v(26)                                %% OPF_ALG_DC
0920     case 0
0921         opt_s.opf.dc.solver = 'DEFAULT';
0922     case 100
0923         opt_s.opf.dc.solver = 'BPMPD';
0924     case {200, 250}
0925         opt_s.opf.dc.solver = 'MIPS';
0926     case 300
0927         opt_s.opf.dc.solver = 'OT';     %% QUADPROG, LINPROG
0928     case 400
0929         opt_s.opf.dc.solver = 'IPOPT';
0930     case 500
0931         opt_s.opf.dc.solver = 'CPLEX';
0932     case 600
0933         opt_s.opf.dc.solver = 'MOSEK';
0934     case 700
0935         opt_s.opf.dc.solver = 'GUROBI';
0936     otherwise
0937         error(errstr, opt_v(26), 'OPF_ALG_DC');
0938 end
0939 
0940 opt_s.verbose               = opt_v(31);        %% VERBOSE
0941 opt_s.out.all               = opt_v(32);        %% OUT_ALL
0942 opt_s.out.sys_sum           = opt_v(33);        %% OUT_SYS_SUM
0943 opt_s.out.area_sum          = opt_v(34);        %% OUT_AREA_SUM
0944 opt_s.out.bus               = opt_v(35);        %% OUT_BUS
0945 opt_s.out.branch            = opt_v(36);        %% OUT_BRANCH
0946 opt_s.out.gen               = opt_v(37);        %% OUT_GEN
0947 opt_s.out.lim.all           = opt_v(38);        %% OUT_ALL_LIM
0948 opt_s.out.lim.v             = opt_v(39);        %% OUT_V_LIM
0949 opt_s.out.lim.line          = opt_v(40);        %% OUT_LINE_LIM
0950 opt_s.out.lim.pg            = opt_v(41);        %% OUT_PG_LIM
0951 opt_s.out.lim.qg            = opt_v(42);        %% OUT_QG_LIM
0952 opt_s.out.force             = opt_v(44);        %% OUT_FORCE
0953 
0954 opt_s.opf.return_raw_der    = opt_v(52);        %% RETURN_RAW_DER
0955 
0956 opt_s.fmincon.alg           = opt_v(55);        %% FMC_ALG
0957 opt_s.knitro.opt            = opt_v(58);        %% KNITRO_OPT
0958 opt_s.ipopt.opt             = opt_v(60);        %% IPOPT_OPT
0959 
0960 opt_s.minopf.feastol        = opt_v(61);        %% MNS_FEASTOL
0961 opt_s.minopf.rowtol         = opt_v(62);        %% MNS_ROWTOL
0962 opt_s.minopf.xtol           = opt_v(63);        %% MNS_XTOL
0963 opt_s.minopf.majdamp        = opt_v(64);        %% MNS_MAJDAMP
0964 opt_s.minopf.mindamp        = opt_v(65);        %% MNS_MINDAMP
0965 opt_s.minopf.penalty        = opt_v(66);        %% MNS_PENALTY_PARM
0966 opt_s.minopf.major_it       = opt_v(67);        %% MNS_MAJOR_IT
0967 opt_s.minopf.minor_it       = opt_v(68);        %% MNS_MINOR_IT
0968 opt_s.minopf.max_it         = opt_v(69);        %% MNS_MAX_IT
0969 opt_s.minopf.verbosity      = opt_v(70);        %% MNS_VERBOSITY
0970 opt_s.minopf.core           = opt_v(71);        %% MNS_CORE
0971 opt_s.minopf.supbasic_lim   = opt_v(72);        %% MNS_SUPBASIC_LIM
0972 opt_s.minopf.mult_price     = opt_v(73);        %% MNS_MULT_PRICE
0973 
0974 opt_s.sopf.force_Pc_eq_P0   = opt_v(80);        %% FORCE_PC_EQ_P0, for c3sopf
0975 
0976 if (opt_v(11) == 565 && opt_v(10) == 0) || (opt_v(26) == 250 && opt_v(10) == 1)
0977     opt_s.mips.step_control = 1;
0978 end
0979 opt_s.mips.feastol          = opt_v(81);        %% PDIPM_FEASTOL
0980 opt_s.mips.gradtol          = opt_v(82);        %% PDIPM_GRADTOL
0981 opt_s.mips.comptol          = opt_v(83);        %% PDIPM_COMPTOL
0982 opt_s.mips.costtol          = opt_v(84);        %% PDIPM_COSTTOL
0983 opt_s.mips.max_it           = opt_v(85);        %% PDIPM_MAX_IT
0984 opt_s.mips.sc.red_it        = opt_v(86);        %% SCPDIPM_RED_IT
0985 
0986 opt_s.pdipm.feastol         = opt_v(81);        %% PDIPM_FEASTOL
0987 opt_s.pdipm.gradtol         = opt_v(82);        %% PDIPM_GRADTOL
0988 opt_s.pdipm.comptol         = opt_v(83);        %% PDIPM_COMPTOL
0989 opt_s.pdipm.costtol         = opt_v(84);        %% PDIPM_COSTTOL
0990 opt_s.pdipm.max_it          = opt_v(85);        %% PDIPM_MAX_IT
0991 opt_s.pdipm.sc.red_it       = opt_v(86);        %% SCPDIPM_RED_IT
0992 opt_s.pdipm.sc.smooth_ratio = opt_v(93);        %% SMOOTHING_RATIO
0993 if opt_v(11) == 545 && opt_v(10) == 0
0994     opt_s.pdipm.step_control = 1;
0995 end
0996 
0997 opt_s.tralm.feastol         = opt_v(87);        %% TRALM_FEASTOL
0998 opt_s.tralm.primaltol       = opt_v(88);        %% TRALM_PRIMETOL
0999 opt_s.tralm.dualtol         = opt_v(89);        %% TRALM_DUALTOL
1000 opt_s.tralm.costtol         = opt_v(90);        %% TRALM_COSTTOL
1001 opt_s.tralm.major_it        = opt_v(91);        %% TRALM_MAJOR_IT
1002 opt_s.tralm.minor_it        = opt_v(92);        %% TRALM_MINOR_IT
1003 opt_s.tralm.smooth_ratio    = opt_v(93);        %% SMOOTHING_RATIO
1004 
1005 opt_s.cplex.lpmethod        = opt_v(95);        %% CPLEX_LPMETHOD
1006 opt_s.cplex.qpmethod        = opt_v(96);        %% CPLEX_QPMETHOD
1007 opt_s.cplex.opt             = opt_v(97);        %% CPLEX_OPT
1008 
1009 opt_s.mosek.lp_alg          = opt_v(111);       %% MOSEK_LP_ALG
1010 opt_s.mosek.max_it          = opt_v(112);       %% MOSEK_MAX_IT
1011 opt_s.mosek.gap_tol         = opt_v(113);       %% MOSEK_GAP_TOL
1012 opt_s.mosek.max_time        = opt_v(114);       %% MOSEK_MAX_TIME
1013 opt_s.mosek.num_threads     = opt_v(115);       %% MOSEK_NUM_THREADS
1014 opt_s.mosek.opt             = opt_v(116);       %% MOSEK_OPT
1015 
1016 opt_s.gurobi.method         = opt_v(121);       %% GRB_METHOD
1017 opt_s.gurobi.timelimit      = opt_v(122);       %% GRB_TIMELIMIT
1018 opt_s.gurobi.threads        = opt_v(123);       %% GRB_THREADS
1019 opt_s.gurobi.opt            = opt_v(124);       %% GRB_OPT
1020 
1021 
1022 %%-------------------------------------------------------------------
1023 function opt_v = mpoption_s2v(opt_s)
1024 if DEBUG, fprintf('mpoption_s2v()\n'); end
1025 %% PF_ALG
1026 old = mpoption_old;
1027 switch upper(opt_s.pf.alg)
1028     case 'NR'
1029         PF_ALG = 1;
1030     case 'FDXB'
1031         PF_ALG = 2;
1032     case 'FDBX'
1033         PF_ALG = 3;
1034     case 'GS'
1035         PF_ALG = 4;
1036 end
1037 
1038 %% PF_DC
1039 if strcmp(upper(opt_s.model), 'DC')
1040     PF_DC = 1;
1041 else
1042     PF_DC = 0;
1043 end
1044 
1045 %% OPF_ALG
1046 switch upper(opt_s.opf.ac.solver)
1047     case 'DEFAULT'
1048         OPF_ALG = 0;
1049     case 'MINOPF'
1050         OPF_ALG = 500;
1051     case 'FMINCON'
1052         OPF_ALG = 520;
1053     case 'PDIPM'
1054         if isfield(opt_s, 'pdipm') && opt_s.pdipm.step_control
1055             OPF_ALG = 545;
1056         else
1057             OPF_ALG = 540;
1058         end
1059     case 'TRALM'
1060         OPF_ALG = 550;
1061     case 'MIPS'
1062         if opt_s.mips.step_control
1063             OPF_ALG = 565;
1064         else
1065             OPF_ALG = 560;
1066         end
1067     case 'IPOPT'
1068         OPF_ALG = 580;
1069     case 'KNITRO'
1070         OPF_ALG = 600;
1071 end
1072 
1073 %% FMINCON, Knitro tol_x, tol_f, max_it
1074 if strcmp(upper(opt_s.opf.ac.solver), 'KNITRO') && isfield(opt_s, 'knitro')
1075     CONSTR_TOL_X = opt_s.knitro.tol_x;
1076     CONSTR_TOL_F = opt_s.knitro.tol_f;
1077 elseif isfield(opt_s, 'fmincon')
1078     CONSTR_TOL_X  = opt_s.fmincon.tol_x;
1079     CONSTR_TOL_F  = opt_s.fmincon.tol_f;
1080 else
1081     CONSTR_TOL_X = old(17);
1082     CONSTR_TOL_F = old(18);
1083 end
1084 if isfield(opt_s, 'fmincon')
1085     CONSTR_MAX_IT   = opt_s.fmincon.max_it;
1086     FMC_ALG         = opt_s.fmincon.alg;
1087 else
1088     CONSTR_MAX_IT   = old(19);
1089     FMC_ALG         = old(55);
1090 end
1091 
1092 %% OPF_FLOW_LIM
1093 switch upper(opt_s.opf.flow_lim)
1094     case 'S'
1095         OPF_FLOW_LIM = 0;
1096     case 'P'
1097         OPF_FLOW_LIM = 1;
1098     case 'I'
1099         OPF_FLOW_LIM = 2;
1100 end
1101 
1102 %% OPF_ALG_DC
1103 switch upper(opt_s.opf.dc.solver)
1104     case 'DEFAULT'
1105         OPF_ALG_DC = 0;
1106     case 'BPMPD'
1107         OPF_ALG_DC = 100;
1108     case 'MIPS'
1109         if opt_s.mips.step_control
1110             OPF_ALG_DC = 250;
1111         else
1112             OPF_ALG_DC = 200;
1113         end
1114     case 'OT'
1115         OPF_ALG_DC = 300;
1116     case 'IPOPT'
1117         OPF_ALG_DC = 400;
1118     case 'CPLEX'
1119         OPF_ALG_DC = 500;
1120     case 'MOSEK'
1121         OPF_ALG_DC = 600;
1122     case 'GUROBI'
1123         OPF_ALG_DC = 700;
1124 end
1125 
1126 %% KNITRO_OPT
1127 if isfield(opt_s, 'knitro')
1128     KNITRO_OPT  = opt_s.knitro.opt;
1129 else
1130     KNITRO_OPT  = old(58);
1131 end
1132 
1133 %% IPOPT_OPT
1134 if isfield(opt_s, 'ipopt')
1135     IPOPT_OPT  = opt_s.ipopt.opt;
1136 else
1137     IPOPT_OPT  = old(58);
1138 end
1139 
1140 %% MINOPF options
1141 if isfield(opt_s, 'minopf')
1142     MINOPF_OPTS = [
1143         opt_s.minopf.feastol;   %% 61 - MNS_FEASTOL
1144         opt_s.minopf.rowtol;    %% 62 - MNS_ROWTOL
1145         opt_s.minopf.xtol;      %% 63 - MNS_XTOL
1146         opt_s.minopf.majdamp;   %% 64 - MNS_MAJDAMP
1147         opt_s.minopf.mindamp;   %% 65 - MNS_MINDAMP
1148         opt_s.minopf.penalty;   %% 66 - MNS_PENALTY_PARM
1149         opt_s.minopf.major_it;  %% 67 - MNS_MAJOR_IT
1150         opt_s.minopf.minor_it;  %% 68 - MNS_MINOR_IT
1151         opt_s.minopf.max_it;    %% 69 - MNS_MAX_IT
1152         opt_s.minopf.verbosity; %% 70 - MNS_VERBOSITY
1153         opt_s.minopf.core;      %% 71 - MNS_CORE
1154         opt_s.minopf.supbasic_lim;  %% 72 - MNS_SUPBASIC_LIM
1155         opt_s.minopf.mult_price;%% 73 - MNS_MULT_PRICE
1156     ];
1157 else
1158     MINOPF_OPTS = old(61:73);
1159 end
1160 
1161 %% FORCE_PC_EQ_P0
1162 if isfield(opt_s, 'sopf') && isfield(opt_s.sopf, 'force_Pc_eq_P0')
1163     FORCE_PC_EQ_P0 = opt_s.sopf.force_Pc_eq_P0;
1164 else
1165     FORCE_PC_EQ_P0 = 0;
1166 end
1167 
1168 %% PDIPM options
1169 if isfield(opt_s, 'pdipm')
1170     PDIPM_OPTS = [
1171         opt_s.pdipm.feastol;    %% 81 - PDIPM_FEASTOL
1172         opt_s.pdipm.gradtol;    %% 82 - PDIPM_GRADTOL
1173         opt_s.pdipm.comptol;    %% 83 - PDIPM_COMPTOL
1174         opt_s.pdipm.costtol;    %% 84 - PDIPM_COSTTOL
1175         opt_s.pdipm.max_it;     %% 85 - PDIPM_MAX_IT
1176         opt_s.pdipm.sc.red_it;  %% 86 - SCPDIPM_RED_IT
1177     ];
1178 else
1179     PDIPM_OPTS = old(81:86);
1180 end
1181 
1182 %% TRALM options
1183 if isfield(opt_s, 'tralm')
1184     TRALM_OPTS = [
1185         opt_s.tralm.feastol;    %% 87 - TRALM_FEASTOL
1186         opt_s.tralm.primaltol;  %% 88 - TRALM_PRIMETOL
1187         opt_s.tralm.dualtol;    %% 89 - TRALM_DUALTOL
1188         opt_s.tralm.costtol;    %% 90 - TRALM_COSTTOL
1189         opt_s.tralm.major_it;   %% 91 - TRALM_MAJOR_IT
1190         opt_s.tralm.minor_it;   %% 92 - TRALM_MINOR_IT
1191     ];
1192 else
1193     TRALM_OPTS = old(87:92);
1194 end
1195 
1196 %% SMOOTHING_RATIO
1197 if strcmp(upper(opt_s.opf.ac.solver), 'TRALM') && isfield(opt_s, 'tralm')
1198     SMOOTHING_RATIO = opt_s.tralm.smooth_ratio;
1199 elseif isfield(opt_s, 'pdipm')
1200     SMOOTHING_RATIO = opt_s.pdipm.sc.smooth_ratio;
1201 else
1202     SMOOTHING_RATIO = old(93);
1203 end
1204 
1205 %% CPLEX options
1206 if isfield(opt_s, 'cplex')
1207     CPLEX_OPTS = [
1208         opt_s.cplex.lpmethod;   %% 95 - CPLEX_LPMETHOD
1209         opt_s.cplex.qpmethod;   %% 96 - CPLEX_QPMETHOD
1210         opt_s.cplex.opt;        %% 97 - CPLEX_OPT
1211     ];
1212 else
1213     CPLEX_OPTS = old(95:97);
1214 end
1215 
1216 %% MOSEK options
1217 if isfield(opt_s, 'mosek')
1218     MOSEK_OPTS = [
1219         opt_s.mosek.lp_alg;     %% 111 - MOSEK_LP_ALG
1220         opt_s.mosek.max_it;     %% 112 - MOSEK_MAX_IT
1221         opt_s.mosek.gap_tol;    %% 113 - MOSEK_GAP_TOL
1222         opt_s.mosek.max_time;   %% 114 - MOSEK_MAX_TIME
1223         opt_s.mosek.num_threads;%% 115 - MOSEK_NUM_THREADS
1224         opt_s.mosek.opt;        %% 116 - MOSEK_OPT
1225     ];
1226 else
1227     MOSEK_OPTS = old(111:116);
1228 end
1229 
1230 %% Gurobi options
1231 if isfield(opt_s, 'gurobi')
1232     GUROBI_OPTS = [
1233         opt_s.gurobi.method;    %% 121 - GRB_METHOD
1234         opt_s.gurobi.timelimit; %% 122 - GRB_TIMELIMIT
1235         opt_s.gurobi.threads;   %% 123 - GRB_THREADS
1236         opt_s.gurobi.opt;       %% 124 - GRB_OPT
1237     ];
1238 else
1239     GUROBI_OPTS = old(121:124);
1240 end
1241 
1242 opt_v = [
1243         %% power flow options
1244         PF_ALG;                 %% 1  - PF_ALG
1245         opt_s.pf.tol;           %% 2  - PF_TOL
1246         opt_s.pf.nr.max_it;     %% 3  - PF_MAX_IT
1247         opt_s.pf.fd.max_it;     %% 4  - PF_MAX_IT_FD
1248         opt_s.pf.gs.max_it;     %% 5  - PF_MAX_IT_GS
1249         opt_s.pf.enforce_q_lims;%% 6  - ENFORCE_Q_LIMS
1250         0;                      %% 7  - RESERVED7
1251         0;                      %% 8  - RESERVED8
1252         0;                      %% 9  - RESERVED9
1253         PF_DC;                  %% 10 - PF_DC
1254         
1255         %% OPF options
1256         OPF_ALG;                %% 11 - OPF_ALG
1257         0;                      %% 12 - RESERVED12 (was OPF_ALG_POLY = 100)
1258         0;                      %% 13 - RESERVED13 (was OPF_ALG_PWL = 200)
1259         0;                      %% 14 - RESERVED14 (was OPF_POLY2PWL_PTS = 10)
1260         0;                      %% 15 - OPF_NEQ (removed)
1261         opt_s.opf.violation;    %% 16 - OPF_VIOLATION
1262         CONSTR_TOL_X;           %% 17 - CONSTR_TOL_X
1263         CONSTR_TOL_F;           %% 18 - CONSTR_TOL_F
1264         CONSTR_MAX_IT;          %% 19 - CONSTR_MAX_IT
1265         old(20);                %% 20 - LPC_TOL_GRAD (removed)
1266         old(21);                %% 21 - LPC_TOL_X (removed)
1267         old(22);                %% 22 - LPC_MAX_IT (removed)
1268         old(23);                %% 23 - LPC_MAX_RESTART (removed)
1269         OPF_FLOW_LIM;           %% 24 - OPF_FLOW_LIM
1270         opt_s.opf.ignore_angle_lim; %% 25 - OPF_IGNORE_ANG_LIM
1271         OPF_ALG_DC;             %% 26 - OPF_ALG_DC
1272         0;                      %% 27 - RESERVED27
1273         0;                      %% 28 - RESERVED28
1274         0;                      %% 29 - RESERVED29
1275         0;                      %% 30 - RESERVED30
1276         
1277         %% output options
1278         opt_s.verbose;          %% 31 - VERBOSE
1279         opt_s.out.all;          %% 32 - OUT_ALL
1280         opt_s.out.sys_sum;      %% 33 - OUT_SYS_SUM
1281         opt_s.out.area_sum;     %% 34 - OUT_AREA_SUM
1282         opt_s.out.bus;          %% 35 - OUT_BUS
1283         opt_s.out.branch;       %% 36 - OUT_BRANCH
1284         opt_s.out.gen;          %% 37 - OUT_GEN
1285         opt_s.out.lim.all;      %% 38 - OUT_ALL_LIM
1286         opt_s.out.lim.v;        %% 39 - OUT_V_LIM
1287         opt_s.out.lim.line;     %% 40 - OUT_LINE_LIM
1288         opt_s.out.lim.pg;       %% 41 - OUT_PG_LIM
1289         opt_s.out.lim.qg;       %% 42 - OUT_QG_LIM
1290         0;                      %% 43 - RESERVED43 (was OUT_RAW)
1291         opt_s.out.force;        %% 44 - OUT_FORCE
1292         0;                      %% 45 - RESERVED45
1293         0;                      %% 46 - RESERVED46
1294         0;                      %% 47 - RESERVED47
1295         0;                      %% 48 - RESERVED48
1296         0;                      %% 49 - RESERVED49
1297         0;                      %% 50 - RESERVED50
1298         
1299         %% other options
1300         old(51);                %% 51 - SPARSE_QP (removed)
1301         opt_s.opf.return_raw_der;   %% 52 - RETURN_RAW_DER
1302         0;                      %% 53 - RESERVED53
1303         0;                      %% 54 - RESERVED54
1304         FMC_ALG;                %% 55 - FMC_ALG
1305         0;                      %% 56 - RESERVED56
1306         0;                      %% 57 - RESERVED57
1307         KNITRO_OPT;             %% 58 - KNITRO_OPT
1308         0;                      %% 59 - RESERVED59
1309         IPOPT_OPT;              %% 60 - IPOPT_OPT
1310         
1311         %% MINOPF options
1312         MINOPF_OPTS;            %% 61-73 - MNS_FEASTOL-MNS_MULT_PRICE
1313         0;                      %% 74 - RESERVED74
1314         0;                      %% 75 - RESERVED75
1315         0;                      %% 76 - RESERVED76
1316         0;                      %% 77 - RESERVED77
1317         0;                      %% 78 - RESERVED78
1318         0;                      %% 79 - RESERVED79
1319         FORCE_PC_EQ_P0;         %% 80 - FORCE_PC_EQ_P0, for c3sopf
1320         
1321         %% MIPS, PDIPM, SC-PDIPM, and TRALM options
1322         PDIPM_OPTS;             %% 81-86 - PDIPM_FEASTOL-SCPDIPM_RED_IT
1323         TRALM_OPTS;             %% 87-92 - TRALM_FEASTOL-TRALM_MINOR_IT
1324         SMOOTHING_RATIO;        %% 93 - SMOOTHING_RATIO
1325         0;                      %% 94 - RESERVED94
1326         
1327         %% CPLEX options
1328         CPLEX_OPTS;             %% 95-97 - CPLEX_LPMETHOD-CPLEX_OPT
1329         0;                      %% 98 - RESERVED98
1330         0;                      %% 99 - RESERVED99
1331         0;                      %% 100 - RESERVED100
1332         0;                      %% 101 - RESERVED101
1333         0;                      %% 102 - RESERVED102
1334         0;                      %% 103 - RESERVED103
1335         0;                      %% 104 - RESERVED104
1336         0;                      %% 105 - RESERVED105
1337         0;                      %% 106 - RESERVED106
1338         0;                      %% 107 - RESERVED107
1339         0;                      %% 108 - RESERVED108
1340         0;                      %% 109 - RESERVED109
1341         0;                      %% 110 - RESERVED110
1342 
1343         %% MOSEK options
1344         MOSEK_OPTS;             %% 111-116 - MOSEK_LP_ALG-MOSEK_OPT
1345         0;                      %% 117 - RESERVED117
1346         0;                      %% 118 - RESERVED118
1347         0;                      %% 119 - RESERVED119
1348         0;                      %% 120 - RESERVED120
1349 
1350         %% Gurobi options
1351         GUROBI_OPTS;            %% 121-124 - GRB_METHOD-GRB_OPT
1352     ];
1353 
1354 
1355 %%-------------------------------------------------------------------
1356 function opt = mpoption_default()
1357 if DEBUG, fprintf('mpoption_default()\n'); end
1358 opt = struct(...
1359     'v',                    mpoption_version, ...   %% version
1360     'model',                'AC', ...
1361     'pf',                   struct(...
1362         'alg',                  'NR', ...
1363         'tol',                  1e-8, ...
1364         'nr',                   struct(...
1365             'max_it',               10  ), ...
1366         'fd',                   struct(...
1367             'max_it',               30  ), ...
1368         'gs',                   struct(...
1369             'max_it',               1000  ), ...
1370         'enforce_q_lims',       0   ), ...
1371     'cpf',                  struct(...
1372         'parameterization',     3, ...
1373         'stop_at',              'NOSE', ...     %% 'NOSE', <lam val>, 'FULL'
1374         'step',                 0.05, ...
1375         'adapt_step',           0, ...
1376         'error_tol',            1e-3, ...
1377         'step_min',             1e-4, ...
1378         'step_max',             0.2, ...
1379         'plot',                 struct(...
1380             'level',                0, ...
1381             'bus',                  []  ), ...
1382         'user_callback',        '', ...
1383         'user_callback_args',   struct()    ), ...
1384     'opf',                  struct(...
1385         'ac',                   struct(...
1386             'solver',               'DEFAULT'   ), ...
1387         'dc',                   struct(...
1388             'solver',               'DEFAULT'   ), ...
1389         'violation',            5e-6, ...
1390         'flow_lim',             'S', ...
1391         'ignore_angle_lim',     0, ...
1392         'init_from_mpc',        -1, ...
1393         'return_raw_der',       0   ), ...
1394     'verbose',              1, ...
1395     'out',                  struct(...
1396         'all',                  -1, ...
1397         'sys_sum',              1, ...
1398         'area_sum',             0, ...
1399         'bus',                  1, ...
1400         'branch',               1, ...
1401         'gen',                  0, ...
1402         'lim',                  struct(...
1403             'all',                  -1, ...
1404             'v',                    1, ...
1405             'line',                 1, ...
1406             'pg',                   1, ...
1407             'qg',                   1   ), ...
1408         'force',                0, ...
1409         'suppress_detail',      -1  ), ...
1410     'mips',                 struct(...  %% see mpoption_info_mips() for optional fields
1411         'step_control',         0, ...
1412         'feastol',              0, ...
1413         'gradtol',              1e-6, ...
1414         'comptol',              1e-6, ...
1415         'costtol',              1e-6, ...
1416         'max_it',               150, ...
1417         'sc',                   struct(...
1418             'red_it',               20  )) ...
1419 );
1420 opt_pkgs = mpoption_optional_pkgs();
1421 for k = 1:length(opt_pkgs)
1422     fname = ['mpoption_info_' opt_pkgs{k}];
1423     if exist(fname, 'file') == 2
1424         opt = nested_struct_copy(opt, feval(fname, 'D'));
1425     end
1426 end
1427 
1428 %%-------------------------------------------------------------------
1429 function opt = mpoption_optional_fields()
1430 if DEBUG, fprintf('mpoption_optional_fields()\n'); end
1431 opt_pkgs = mpoption_optional_pkgs();
1432 opt = struct;
1433 for k = 1:length(opt_pkgs)
1434     fname = ['mpoption_info_' opt_pkgs{k}];
1435     if exist(fname, 'file') == 2
1436         opt = nested_struct_copy(opt, feval(fname, 'V'));
1437     end
1438 end
1439 
1440 %% globals
1441 %%-------------------------------------------------------------------
1442 function v = mpoption_version
1443 v = 2;      %% version number of MATPOWER options struct
1444             %% (must be incremented every time structure is updated)
1445 
1446 %%-------------------------------------------------------------------
1447 function db_level = DEBUG
1448 db_level = 0;
1449 
1450 %%-------------------------------------------------------------------
1451 function pkgs = mpoption_optional_pkgs()
1452 pkgs = {...
1453     'cplex', 'fmincon', 'gurobi', 'glpk', 'ipopt', 'knitro', 'linprog', ...
1454     'minopf', 'mosek', 'quadprog', 'sdp_pf', 'sopf', 'tspopf', 'yalmip' ...
1455 };

Generated on Mon 26-Jan-2015 15:21:31 by m2html © 2005