Home > matpower7.0 > extras > syngrid > lib > sg_options.m

sg_options

PURPOSE ^

SG_OPTIONS Create a SynGrid options struct with default options + overrides.

SYNOPSIS ^

function sgopt = sg_options(varargin)

DESCRIPTION ^

SG_OPTIONS  Create a SynGrid options struct with default options + overrides.
   SGOPT = SG_OPTIONS()
   SGOPT = SG_OPTIONS(OVERRIDES)
   SGOPT = SG_OPTIONS(SGOPT0, OVERRIDES)
   SGOPT = SG_OPTIONS(NAME1, VAL1, ...)
   SGOPT = SG_OPTIONS(SGOPT0, NAME1, VAL1, ...)

   Create a SynGrid options struct with default values for all options,
   then optionally apply values specified in the OVERRIDES struct.
   Alternatively, the options struct can be initialized with an existing
   SynGrid options struct SGOPT0 and/or the overrides can be specified
   as a set of name value pairs (e.g. NAME1, VAL1, ...). Note that the
   name in the name value pairs can be a string containing '.', such as
   'ea.parallel.numcores'.

   The SynGrid options are as follows, with the default values in parenthesis:

       general options:
           verbose (0) - controls level of progress output displayed
               0 : print no progress info
               1 : print a little progress info
               2 : print a lot of progress info
               3 : print all progress info
           debug (0) - debug mode switch
               0 : run in normal mode
               1 : run in debug mode (not currently used)
           mpopt (see MPOPTION) - MATPOWER options struct, default is
               given by MPOPTION() with the following two exceptions:
               (1) 'out.all' and 'verbose' are set to 0, unless
                   'mpoptprint' is set to 1
               (2) if IPOPT is available, 'opf.ac.solver' is set to 'IPOPT'
                   and several 'ipopt.opts.*' are set explicitly, as follows:
                       'file_print_level', 5
                       'print_user_options', 'yes'
                       'tol', 1e-6
                       'dual_inf_tol', 1e-5
                       'max_iter', 500
                       'print_timing_statistics', 'yes'
                       'constr_viol_tol', 1e-6
                       'acceptable_tol', 1e-6
           mpoptprint (0) - determine whether mpopt controls MATPOWER output
               0 : turn off all MATPOWER screen output
               1 : use values in 'mpopt' to control MATPOWER screen output

       base mode options:
           bm.loading ('D') - loading level
               'D' : default - depends on system size
                               (based on stats from realistic grids)
               'L' : low     - total load = 30%-40% of generation capacity
               'M' : medium  - total load = 50%-60% of generation capacity
               'H' : high    - total load = 70%-80% of generation capacity
           bm.br2b_ratio (1.5) - ratio of number of branches to number of buses
                              valid range (1.25 - 2.5)
           bm.br_overload (0) - overloaded branches
               0 : without overloaded branches
               1 : with same percentage of overloaded branches as
                   realistic grids
           bm.bta_method (0) - bus type assignment method
               0 : "W0" method - simpler & faster
               1 : "W1" method - more accurate & slower
           bm.cost_model (2) - generation cost model
               1 : linear cost function
               2 : quadratic cost function

       variations mode options:
           vm.opflogpath ('') - path to log files if IPOPT used
           vm.ea.generations (5) - number of iterations in variations mode
           vm.ea.inds (4) - # of unique cases active in each iteration
           vm.ea.select (5) - # of cases returned upon termination
           vm.ea.randnew (0) - # of new cases via the initialization method
           vm.ea.initfill (0) - handling when fewer individuals than vm.ea.inds
               0 : do not initialize new individuals
               1 : initialize new individuals
           vm.parallel.use (0) - controls whether PARFOR loops are used
               0 : do not use parallelization
               1 : use parallelization
           vm.parallel.numcores (0) - # of cores for parallelization
           vm.branchperm.niter (1) - # of branch permutation iterations
               per generation
           vm.branchperm.verbose (0) - print progress for branch permutation
               0 : no progress info
               1 : some progress info
           vm.branchperm.overload_frac_factor (0.95) - scaling factor in
               [0, 1] used to update what is considered overload.
               E.g., if x0=1 initially is the overload factor, in the next
               branch permutation x1=0.95
           vm.nodeperm.niter (1) - # of node permutation iterations per
               generation
           vm.nodeperm.verbose (0) - print progress for node permutation
               0 : no progress info
               1 : some progress info
               2 : even more progress info
               3 : all progress info including from LP solver
           vm.nodeperm.nox (1) - handling of impact of V on P and theta
               on Q in sgvm_calc_injection_delta()
               0 : include impact
               1 : exclude impact
           vm.nodeperm.usedv (0) - INITIAL handling of voltage change
               constraints in sgvm_calc_injection_delta()
               0 : ignore constraints initially
               1 : include constraints initially
           vm.nodeperm.scale_s (1) - initial scaling factor for determining
               overloaded lines in node permutation
           vm.nodeperm.scale_s_factor (0.95) - factor for decreasing 
               'vm.nodeperm.scale_s'
           vm.shunts (see SGVM_SHUNTSOPTS) - options for adding reactive
               shunts
           vm.smpl (see SGVM_SMPLOPTS) - sampling options for creating a
               seed MATPOWER case

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function sgopt = sg_options(varargin)
0002 %SG_OPTIONS  Create a SynGrid options struct with default options + overrides.
0003 %   SGOPT = SG_OPTIONS()
0004 %   SGOPT = SG_OPTIONS(OVERRIDES)
0005 %   SGOPT = SG_OPTIONS(SGOPT0, OVERRIDES)
0006 %   SGOPT = SG_OPTIONS(NAME1, VAL1, ...)
0007 %   SGOPT = SG_OPTIONS(SGOPT0, NAME1, VAL1, ...)
0008 %
0009 %   Create a SynGrid options struct with default values for all options,
0010 %   then optionally apply values specified in the OVERRIDES struct.
0011 %   Alternatively, the options struct can be initialized with an existing
0012 %   SynGrid options struct SGOPT0 and/or the overrides can be specified
0013 %   as a set of name value pairs (e.g. NAME1, VAL1, ...). Note that the
0014 %   name in the name value pairs can be a string containing '.', such as
0015 %   'ea.parallel.numcores'.
0016 %
0017 %   The SynGrid options are as follows, with the default values in parenthesis:
0018 %
0019 %       general options:
0020 %           verbose (0) - controls level of progress output displayed
0021 %               0 : print no progress info
0022 %               1 : print a little progress info
0023 %               2 : print a lot of progress info
0024 %               3 : print all progress info
0025 %           debug (0) - debug mode switch
0026 %               0 : run in normal mode
0027 %               1 : run in debug mode (not currently used)
0028 %           mpopt (see MPOPTION) - MATPOWER options struct, default is
0029 %               given by MPOPTION() with the following two exceptions:
0030 %               (1) 'out.all' and 'verbose' are set to 0, unless
0031 %                   'mpoptprint' is set to 1
0032 %               (2) if IPOPT is available, 'opf.ac.solver' is set to 'IPOPT'
0033 %                   and several 'ipopt.opts.*' are set explicitly, as follows:
0034 %                       'file_print_level', 5
0035 %                       'print_user_options', 'yes'
0036 %                       'tol', 1e-6
0037 %                       'dual_inf_tol', 1e-5
0038 %                       'max_iter', 500
0039 %                       'print_timing_statistics', 'yes'
0040 %                       'constr_viol_tol', 1e-6
0041 %                       'acceptable_tol', 1e-6
0042 %           mpoptprint (0) - determine whether mpopt controls MATPOWER output
0043 %               0 : turn off all MATPOWER screen output
0044 %               1 : use values in 'mpopt' to control MATPOWER screen output
0045 %
0046 %       base mode options:
0047 %           bm.loading ('D') - loading level
0048 %               'D' : default - depends on system size
0049 %                               (based on stats from realistic grids)
0050 %               'L' : low     - total load = 30%-40% of generation capacity
0051 %               'M' : medium  - total load = 50%-60% of generation capacity
0052 %               'H' : high    - total load = 70%-80% of generation capacity
0053 %           bm.br2b_ratio (1.5) - ratio of number of branches to number of buses
0054 %                              valid range (1.25 - 2.5)
0055 %           bm.br_overload (0) - overloaded branches
0056 %               0 : without overloaded branches
0057 %               1 : with same percentage of overloaded branches as
0058 %                   realistic grids
0059 %           bm.bta_method (0) - bus type assignment method
0060 %               0 : "W0" method - simpler & faster
0061 %               1 : "W1" method - more accurate & slower
0062 %           bm.cost_model (2) - generation cost model
0063 %               1 : linear cost function
0064 %               2 : quadratic cost function
0065 %
0066 %       variations mode options:
0067 %           vm.opflogpath ('') - path to log files if IPOPT used
0068 %           vm.ea.generations (5) - number of iterations in variations mode
0069 %           vm.ea.inds (4) - # of unique cases active in each iteration
0070 %           vm.ea.select (5) - # of cases returned upon termination
0071 %           vm.ea.randnew (0) - # of new cases via the initialization method
0072 %           vm.ea.initfill (0) - handling when fewer individuals than vm.ea.inds
0073 %               0 : do not initialize new individuals
0074 %               1 : initialize new individuals
0075 %           vm.parallel.use (0) - controls whether PARFOR loops are used
0076 %               0 : do not use parallelization
0077 %               1 : use parallelization
0078 %           vm.parallel.numcores (0) - # of cores for parallelization
0079 %           vm.branchperm.niter (1) - # of branch permutation iterations
0080 %               per generation
0081 %           vm.branchperm.verbose (0) - print progress for branch permutation
0082 %               0 : no progress info
0083 %               1 : some progress info
0084 %           vm.branchperm.overload_frac_factor (0.95) - scaling factor in
0085 %               [0, 1] used to update what is considered overload.
0086 %               E.g., if x0=1 initially is the overload factor, in the next
0087 %               branch permutation x1=0.95
0088 %           vm.nodeperm.niter (1) - # of node permutation iterations per
0089 %               generation
0090 %           vm.nodeperm.verbose (0) - print progress for node permutation
0091 %               0 : no progress info
0092 %               1 : some progress info
0093 %               2 : even more progress info
0094 %               3 : all progress info including from LP solver
0095 %           vm.nodeperm.nox (1) - handling of impact of V on P and theta
0096 %               on Q in sgvm_calc_injection_delta()
0097 %               0 : include impact
0098 %               1 : exclude impact
0099 %           vm.nodeperm.usedv (0) - INITIAL handling of voltage change
0100 %               constraints in sgvm_calc_injection_delta()
0101 %               0 : ignore constraints initially
0102 %               1 : include constraints initially
0103 %           vm.nodeperm.scale_s (1) - initial scaling factor for determining
0104 %               overloaded lines in node permutation
0105 %           vm.nodeperm.scale_s_factor (0.95) - factor for decreasing
0106 %               'vm.nodeperm.scale_s'
0107 %           vm.shunts (see SGVM_SHUNTSOPTS) - options for adding reactive
0108 %               shunts
0109 %           vm.smpl (see SGVM_SMPLOPTS) - sampling options for creating a
0110 %               seed MATPOWER case
0111 
0112 %   SynGrid
0113 %   Copyright (c) 2018, Power Systems Engineering Research Center (PSERC)
0114 %   by Ray Zimmerman, PSERC Cornell
0115 %
0116 %   This file is part of SynGrid.
0117 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0118 
0119 %% default values
0120 varidx = 1;     %% input variable counter
0121 sgopt = struct( ...
0122     'verbose',      0, ...      %% no progress output
0123     'debug', 0, ...             %% debug mode
0124     'mpopt', mpoption(), ...    %% MATPOWER options structure
0125     'mpoptprint', 0, ...        %% flag to mpopt print options
0126     'bm', struct ( ...
0127         'refsys',       2, ...      %% reference system 2
0128         'loading',      'D', ...    %% default - depends on system size
0129         'br2b_ratio',   1.5, ...
0130         'br_overload',  0, ...      %% without overloaded branches
0131         'bta_method',   0, ...      %% "W0" method - simpler, faster
0132         'cost_model',   2 ), ...    %% quadratic
0133     'vm', struct(...            %% options for variations mode
0134         'opflogpath', '', ...   %% path to log files if IPOPT used
0135         'ea', struct( ...
0136             'generations', 5, ...
0137             'inds', 4, ...
0138             'select', 5, ...
0139             'randnew', 0, ...
0140             'initfill', 0 ), ...
0141         'parallel', struct( ...
0142             'use', 0, ...
0143             'numcores', 0 ), ...
0144         'branchperm', struct( ...
0145             'niter', 1, ...
0146             'verbose', 0, ...
0147             'overload_frac_factor', 0.95 ), ...
0148         'nodeperm', struct( ...
0149             'niter', 1, ...
0150             'verbose', 0, ...
0151             'nox', 1, ...
0152             'usedv', 0, ...
0153             'scale_s', 1, ...
0154             'scale_s_factor', 0.95 ), ...
0155         'shunts', sgvm_shuntsopts(), ...
0156         'smpl', sgvm_smplopts() ) ...
0157 );
0158 
0159 nsc_opt = struct('check', 1);
0160 overrides = [];
0161 if nargin
0162     if isstruct(varargin{varidx}) && ~isempty(varargin{varidx})
0163         %% update SGOPT using SGOPT0
0164         %% (could be OVERRIDES structure, but treatment is identical)
0165         sgopt = nested_struct_copy(sgopt, varargin{varidx}, nsc_opt);
0166         varidx = varidx + 1;
0167     end
0168     if varidx <= nargin
0169         if isstruct(varargin{varidx})
0170             %% OVERRIDES provided as a struct
0171             overrides = varargin{varidx};
0172         elseif ischar(varargin{varidx}) && (mod( nargin - varidx + 1, 2) == 0)
0173             %% OVERRIDES provided with key-value pairs
0174             %% convert pairs to struct
0175             while varidx < nargin
0176                 name = varargin{varidx};
0177                 val  = varargin{varidx+1};
0178                 varidx = varidx + 2;
0179                 c = regexp(name, '([^\.]*)', 'tokens');
0180                 s = struct();
0181                 for i = 1:length(c)
0182                     s(i).type = '.';
0183                     s(i).subs = c{i}{1};
0184                 end
0185                 overrides = subsasgn(overrides, s, val);
0186             end
0187         else
0188             error('sg_options: invalid calling syntax, see ''help sg_options'' to double-check the valid options');
0189         end
0190     end
0191 end
0192 
0193 %% apply overrides, if specified
0194 if nargin && ~isempty(overrides)
0195     sgopt = nested_struct_copy(sgopt, overrides, nsc_opt);
0196 end
0197 
0198 %% validate options
0199 if ~isnumeric(sgopt.bm.refsys) || sgopt.bm.refsys < 1 || sgopt.bm.refsys > 3
0200     error('sg_options: reference system SGOPT.bm.refsys must be 1, 2 or 3');
0201 end
0202 if length(sgopt.bm.loading) ~= 1 || ( upper(sgopt.bm.loading) ~= 'D' && ...
0203                                       upper(sgopt.bm.loading) ~= 'L' && ...
0204                                       upper(sgopt.bm.loading) ~= 'M' && ...
0205                                       upper(sgopt.bm.loading) ~= 'H' )
0206     error('sg_options: reference system SGOPT.bm.loading must be ''D'' (default), ''L'' (low), ''M'' (medium), or ''H'' (high)');
0207 end
0208 if ~isnumeric(sgopt.bm.br2b_ratio) || sgopt.bm.br2b_ratio < 1.25 || sgopt.bm.br2b_ratio > 2.5
0209     error('sg_options: branch to bus ratio SGOPT.bm.br2b_ratio must between 1.25 and 2.5');
0210 end
0211 if ~isnumeric(sgopt.bm.bta_method) || (sgopt.bm.bta_method ~= 0 && sgopt.bm.bta_method ~= 1)
0212     error('sg_options: bus type assignment method SGOPT.bm.bta_method must 0 or 1');
0213 end
0214 if ~isnumeric(sgopt.bm.cost_model) || (sgopt.bm.cost_model ~= 1 && sgopt.bm.cost_model ~= 2)
0215     error('sg_options: generation cost model SGOPT.bm.cost_model must 1 or 2');
0216 end
0217 if ~isnumeric(sgopt.bm.br_overload) || (sgopt.bm.br_overload ~= 0 && sgopt.bm.br_overload ~= 1)
0218     error('sg_options: branch overload option SGOPT.bm.br_overload must 0 or 1');
0219 end
0220 
0221 %% handle MATPOWER options
0222 sgopt.mpopt = mpoption(sgopt.mpopt, 'opf.softlims.default', 0); %% required for variations mode
0223 if ~sgopt.mpoptprint
0224     %% print options overridden here unless explicitly prohibited
0225     %% by setting SGOPT.mpoptprint
0226 
0227     %% turn off all printing
0228     sgopt.mpopt = mpoption(sgopt.mpopt, 'out.all', 0, 'verbose', 0);
0229 end
0230 
0231 %% set default AC OPF solver to IPOPT, if available
0232 if strcmp(sgopt.mpopt.opf.ac.solver, 'DEFAULT') && have_fcn('ipopt')
0233     sgopt.mpopt = mpoption(sgopt.mpopt, 'opf.ac.solver', 'IPOPT');
0234 end
0235 
0236 %% add IPOPT specific settings, if available
0237 if strcmp(sgopt.mpopt.opf.ac.solver, 'IPOPT')
0238     sg_ipopt_defaults = struct( ...
0239         'file_print_level', 5, ...
0240         'print_user_options', 'yes', ...
0241         'tol', 1e-6, ...
0242         'dual_inf_tol', 1e-5, ...
0243         'max_iter', 500, ...
0244         'print_timing_statistics', 'yes', ...
0245         'constr_viol_tol', 1e-6, ...
0246         'acceptable_tol', 1e-6 );
0247     if isempty(sgopt.mpopt.ipopt.opts)
0248         ipopt_opts = sg_ipopt_defaults;
0249     else
0250         ipopt_opts = nested_struct_copy(sg_ipopt_defaults, sgopt.mpopt.ipopt.opts);
0251     end
0252     sgopt.mpopt = mpoption(sgopt.mpopt, 'ipopt.opts', ipopt_opts);
0253 end

Generated on Mon 24-Jun-2019 15:58:45 by m2html © 2005