Home > matpower7.1 > mp-opt-model > lib > 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:

       https://www.gurobi.com/documentation/

   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 %       https://www.gurobi.com/documentation/
0070 %
0071 %   See also GUROBI, MPOPTION.
0072 
0073 %   MP-Opt-Model
0074 %   Copyright (c) 2010-2020, Power Systems Engineering Research Center (PSERC)
0075 %   by Ray Zimmerman, PSERC Cornell
0076 %
0077 %   This file is part of MP-Opt-Model.
0078 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0079 %   See https://github.com/MATPOWER/mp-opt-model for more info.
0080 
0081 %%-----  initialization and arg handling  -----
0082 %% defaults
0083 verbose = 1;
0084 fname   = '';
0085 
0086 %% second argument
0087 if nargin > 1 && ~isempty(mpopt)
0088     if ischar(mpopt)        %% 2nd arg is FNAME (string)
0089         fname = mpopt;
0090         have_mpopt = 0;
0091     else                    %% 2nd arg is MPOPT (MATPOWER options struct)
0092         have_mpopt = 1;
0093         verbose = mpopt.verbose;
0094         if isfield(mpopt.gurobi, 'opt_fname') && ~isempty(mpopt.gurobi.opt_fname)
0095             fname = mpopt.gurobi.opt_fname;
0096         elseif mpopt.gurobi.opt
0097             fname = sprintf('gurobi_user_options_%d', mpopt.gurobi.opt);
0098         end
0099     end
0100 else
0101     have_mpopt = 0;
0102 end
0103 
0104 %%-----  set default options for Gurobi  -----
0105 % opt.OptimalityTol = 1e-6;
0106 % opt.Presolve = -1;              %% -1 - auto, 0 - no, 1 - conserv, 2 - aggressive=
0107 % opt.LogFile = 'qps_gurobi.log';
0108 if have_mpopt
0109     %% (make default opf.violation correspond to default FeasibilityTol)
0110     opt.FeasibilityTol  = mpopt.opf.violation/5;
0111     opt.Method          = mpopt.gurobi.method;
0112     opt.TimeLimit       = mpopt.gurobi.timelimit;
0113     opt.Threads         = mpopt.gurobi.threads;
0114 else
0115     opt.Method          = -1;           %% automatic
0116 end
0117 if verbose > 1
0118     opt.LogToConsole = 1;
0119     opt.OutputFlag = 1;
0120     if verbose > 2
0121         opt.DisplayInterval = 1;
0122     else
0123         opt.DisplayInterval = 100;
0124     end
0125 else
0126     opt.LogToConsole = 0;
0127     opt.OutputFlag = 0;
0128 end
0129 
0130 %%-----  call user function to modify defaults  -----
0131 if ~isempty(fname)
0132     if have_mpopt
0133         opt = feval(fname, opt, mpopt);
0134     else
0135         opt = feval(fname, opt);
0136     end
0137 end
0138 
0139 %%-----  apply overrides  -----
0140 if have_mpopt && isfield(mpopt.gurobi, 'opts') && ~isempty(mpopt.gurobi.opts)
0141     opt = nested_struct_copy(opt, mpopt.gurobi.opts);
0142 end
0143 if nargin > 0 && ~isempty(overrides)
0144     opt = nested_struct_copy(opt, overrides);
0145 end

Generated on Fri 09-Oct-2020 11:21:31 by m2html © 2005