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

Generated on Fri 20-Mar-2015 18:23:34 by m2html © 2005