Home > matpower5.1 > gurobi_options.m

gurobi_options

PURPOSE ^

GUROBI_OPTIONS Sets options for GUROBI (version 5.x and greater).

SYNOPSIS ^

function opt = gurobi_options(overrides, mpopt)

DESCRIPTION ^

GUROBI_OPTIONS  Sets options for GUROBI (version 5.x and greater).

   OPT = GUROBI_OPTIONS
   OPT = GUROBI_OPTIONS(OVERRIDES)
   OPT = GUROBI_OPTIONS(OVERRIDES, FNAME)
   OPT = GUROBI_OPTIONS(OVERRIDES, MPOPT)

   Sets the values for the options struct normally passed to GUROBI.

   Inputs are all optional, second argument must be either a string
   (FNAME) or a struct (MPOPT):

       OVERRIDES - struct containing values to override the defaults
       FNAME - name of user-supplied function called after default
           options are set to modify them. Calling syntax is:
                   MODIFIED_OPT = FNAME(DEFAULT_OPT);
       MPOPT - MATPOWER options struct, uses the following fields:
           opf.violation    - used to set opt.FeasibilityTol
           verbose          - used to set opt.DisplayInterval,
                                 opt.OutputFlag, opt.LogToConsole
           gurobi.method    - used to set opt.Method
           gurobi.timelimit - used to set opt.TimeLimit (seconds)
           gurobi.threads   - used to set opt.Threads
           gurobi.opts      - struct containing values to use as OVERRIDES
           gurobi.opt_fname - name of user-supplied function used as FNAME,
               except with calling syntax:
                   MODIFIED_OPT = FNAME(DEFAULT_OPT, MPOPT);
           gurobi.opt       - numbered user option function, if and only if
               gurobi.opt_fname is empty and gurobi.opt is non-zero, the value
               of gurobi.opt_fname is generated by appending gurobi.opt to
               'gurobi_user_options_' (for backward compatibility with old
               MATPOWER option GRB_OPT).

   Output is a parameter struct to pass to GUROBI.

   There are multiple ways of providing values to override the default
   options. Their precedence and order of application are as follows:

   With inputs OVERRIDES and FNAME
       1. FNAME is called
       2. OVERRIDES are applied
   With inputs OVERRIDES and MPOPT
       1. FNAME (from gurobi.opt_fname or gurobi.opt) is called
       2. gurobi.opts (if not empty) are applied
       3. OVERRIDES are applied

   Example:

   If gurobi.opt = 3, then after setting the default GUROBI options,
   GUROBI_OPTIONS will execute the following user-defined function
   to allow option overrides:

       opt = gurobi_user_options_3(opt, mpopt);

   The contents of gurobi_user_options_3.m, could be something like:

       function opt = gurobi_user_options_3(opt, mpopt)
       opt.OptimalityTol   = 1e-9;
       opt.BarConvTol      = 1e-9;
       opt.IterationLimit  = 3000;
       opt.BarIterLimit    = 200;
       opt.Crossover       = 0;
       opt.Presolve        = 0;

   For details on the available options, see the "Parameters" section
   of the "Gurobi Optimizer Reference Manual" at:

       http://www.gurobi.com/documentation/5.6/reference-manual/parameters

   See also GUROBI, MPOPTION.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function opt = gurobi_options(overrides, mpopt)
0002 %GUROBI_OPTIONS  Sets options for GUROBI (version 5.x and greater).
0003 %
0004 %   OPT = GUROBI_OPTIONS
0005 %   OPT = GUROBI_OPTIONS(OVERRIDES)
0006 %   OPT = GUROBI_OPTIONS(OVERRIDES, FNAME)
0007 %   OPT = GUROBI_OPTIONS(OVERRIDES, MPOPT)
0008 %
0009 %   Sets the values for the options struct normally passed to GUROBI.
0010 %
0011 %   Inputs are all optional, second argument must be either a string
0012 %   (FNAME) or a struct (MPOPT):
0013 %
0014 %       OVERRIDES - struct containing values to override the defaults
0015 %       FNAME - name of user-supplied function called after default
0016 %           options are set to modify them. Calling syntax is:
0017 %                   MODIFIED_OPT = FNAME(DEFAULT_OPT);
0018 %       MPOPT - MATPOWER options struct, uses the following fields:
0019 %           opf.violation    - used to set opt.FeasibilityTol
0020 %           verbose          - used to set opt.DisplayInterval,
0021 %                                 opt.OutputFlag, opt.LogToConsole
0022 %           gurobi.method    - used to set opt.Method
0023 %           gurobi.timelimit - used to set opt.TimeLimit (seconds)
0024 %           gurobi.threads   - used to set opt.Threads
0025 %           gurobi.opts      - struct containing values to use as OVERRIDES
0026 %           gurobi.opt_fname - name of user-supplied function used as FNAME,
0027 %               except with calling syntax:
0028 %                   MODIFIED_OPT = FNAME(DEFAULT_OPT, MPOPT);
0029 %           gurobi.opt       - numbered user option function, if and only if
0030 %               gurobi.opt_fname is empty and gurobi.opt is non-zero, the value
0031 %               of gurobi.opt_fname is generated by appending gurobi.opt to
0032 %               'gurobi_user_options_' (for backward compatibility with old
0033 %               MATPOWER option GRB_OPT).
0034 %
0035 %   Output is a parameter struct to pass to GUROBI.
0036 %
0037 %   There are multiple ways of providing values to override the default
0038 %   options. Their precedence and order of application are as follows:
0039 %
0040 %   With inputs OVERRIDES and FNAME
0041 %       1. FNAME is called
0042 %       2. OVERRIDES are applied
0043 %   With inputs OVERRIDES and MPOPT
0044 %       1. FNAME (from gurobi.opt_fname or gurobi.opt) is called
0045 %       2. gurobi.opts (if not empty) are applied
0046 %       3. OVERRIDES are applied
0047 %
0048 %   Example:
0049 %
0050 %   If gurobi.opt = 3, then after setting the default GUROBI options,
0051 %   GUROBI_OPTIONS will execute the following user-defined function
0052 %   to allow option overrides:
0053 %
0054 %       opt = gurobi_user_options_3(opt, mpopt);
0055 %
0056 %   The contents of gurobi_user_options_3.m, could be something like:
0057 %
0058 %       function opt = gurobi_user_options_3(opt, mpopt)
0059 %       opt.OptimalityTol   = 1e-9;
0060 %       opt.BarConvTol      = 1e-9;
0061 %       opt.IterationLimit  = 3000;
0062 %       opt.BarIterLimit    = 200;
0063 %       opt.Crossover       = 0;
0064 %       opt.Presolve        = 0;
0065 %
0066 %   For details on the available options, see the "Parameters" section
0067 %   of the "Gurobi Optimizer Reference Manual" at:
0068 %
0069 %       http://www.gurobi.com/documentation/5.6/reference-manual/parameters
0070 %
0071 %   See also GUROBI, MPOPTION.
0072 
0073 %   MATPOWER
0074 %   Copyright (c) 2010-2015 by Power System Engineering Research Center (PSERC)
0075 %   by Ray Zimmerman, PSERC Cornell
0076 %
0077 %   $Id: gurobi_options.m 2644 2015-03-11 19:34:22Z ray $
0078 %
0079 %   This file is part of MATPOWER.
0080 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0081 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0082 
0083 %%-----  initialization and arg handling  -----
0084 %% defaults
0085 verbose = 1;
0086 fname   = '';
0087 
0088 %% second argument
0089 if nargin > 1 && ~isempty(mpopt)
0090     if ischar(mpopt)        %% 2nd arg is FNAME (string)
0091         fname = mpopt;
0092         have_mpopt = 0;
0093     else                    %% 2nd arg is MPOPT (MATPOWER options struct)
0094         have_mpopt = 1;
0095         verbose = mpopt.verbose;
0096         if isfield(mpopt.gurobi, 'opt_fname') && ~isempty(mpopt.gurobi.opt_fname)
0097             fname = mpopt.gurobi.opt_fname;
0098         elseif mpopt.gurobi.opt
0099             fname = sprintf('gurobi_user_options_%d', mpopt.gurobi.opt);
0100         end
0101     end
0102 else
0103     have_mpopt = 0;
0104 end
0105 
0106 %%-----  set default options for Gurobi  -----
0107 % opt.OptimalityTol = 1e-6;
0108 % opt.Presolve = -1;              %% -1 - auto, 0 - no, 1 - conserv, 2 - aggressive=
0109 % opt.LogFile = 'qps_gurobi.log';
0110 if have_mpopt
0111     %% (make default opf.violation correspond to default FeasibilityTol)
0112     opt.FeasibilityTol  = mpopt.opf.violation/5;
0113     opt.Method          = mpopt.gurobi.method;
0114     opt.TimeLimit       = mpopt.gurobi.timelimit;
0115     opt.Threads         = mpopt.gurobi.threads;
0116 else
0117     opt.Method          = -1;           %% automatic
0118 end
0119 if verbose > 1
0120     opt.LogToConsole = 1;
0121     opt.OutputFlag = 1;
0122     if verbose > 2
0123         opt.DisplayInterval = 1;
0124     else
0125         opt.DisplayInterval = 100;
0126     end
0127 else
0128     opt.LogToConsole = 0;
0129     opt.OutputFlag = 0;
0130 end
0131 
0132 %%-----  call user function to modify defaults  -----
0133 if ~isempty(fname)
0134     if have_mpopt
0135         opt = feval(fname, opt, mpopt);
0136     else
0137         opt = feval(fname, opt);
0138     end
0139 end
0140 
0141 %%-----  apply overrides  -----
0142 if have_mpopt && isfield(mpopt.gurobi, 'opts') && ~isempty(mpopt.gurobi.opts)
0143     opt = nested_struct_copy(opt, mpopt.gurobi.opts);
0144 end
0145 if nargin > 0 && ~isempty(overrides)
0146     opt = nested_struct_copy(opt, overrides);
0147 end

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