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 case0001 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