ADD_CONSTRAINTS Adds a set of constraints to the model.
----- DEPRECATED - Please use one of the following instead: -----
----- ADD_LIN_CONSTRAINT, ADD_NLN_CONSTRAINT, INIT_INDEXED_NAME -----
OM.ADD_CONSTRAINTS(NAME, A, L, U);
OM.ADD_CONSTRAINTS(NAME, A, L, U, VARSETS);
OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS);
OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS, VARSETS);
OM.ADD_CONSTRAINTS(NAME, DIM_LIST); %% linear
OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'lin'); %% linear
OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nle'); %% nonlinear equality
OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nli'); %% nonlinear inequality
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U);
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U, VARSETS);
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS);
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS);
Linear Constraints
OM.ADD_CONSTRAINTS(NAME, A, L, U);
OM.ADD_CONSTRAINTS(NAME, A, L, U, VARSETS);
Linear constraints are of the form L <= A * x <= U, where
x is a vector made of the vars specified in VARSETS (in
the order given). This allows the A matrix to be defined only
in terms of the relevant variables without the need to manually
create a lot of zero columns. If VARSETS is empty, x is taken
to be the full vector of all optimization variables. If L or
U are empty, they are assumed to be appropriately sized vectors
of -Inf and Inf, respectively.
Nonlinear Constraints
OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS);
OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS, VARSETS);
For nonlinear constraints, N specifies the number of constraints
in the set, ISEQ is a 1 for an equality constraint set, 0 for
inequality, FCN is the handle of a function that evaluates the
constraint and its gradients, and HESS is the handle of a function
that evaluates the Hessian of the constraints.
For a constraint G(x) = 0, FCN should point to a function with the
following interface:
G = FCN(X)
[G, DG] = FCN(X)
where G is an N x 1 vector and DG is the N x NX gradient, where
DG(i, j) = dG(i)/dX(j)
and NX is the number of elements in X.
HESS should point to a function that returns an NX x NX matrix
of derivatives of DG * LAMBDA, with the following interface:
D2G = HESS(X, LAMBDA)
For both functions, the first input argument X can take two forms.
If the constraint set is added VARSETS empty or missing, then X
will be the full optimization vector. Otherwise it will be a cell
array of vectors corresponding to the variable sets specified in
VARSETS.
For nonlinear constraints, NAME can be a cell array of constraint
set names, in which case N is a vector, specifying the number of
constraints in each set. FCN and HESS are still single function
handles for functions that compute the values for the entire
collection of constraint sets together.
Similarly, if the third argument is a string containing 'nle' or
'nli', it indicates a placeholder in the indexing for a constraint
set whose implmentation is included in another constraint set. This
functionality is only intended to be used internally to handle
constraint/gradient and Hessian functions that handle more than one
constraint set simultaneously.
Indexed Named Sets
A constraint set can be identified by a single NAME, as described
above, such as 'Pmismatch', or by a name that is indexed by one
or more indices, such as 'Pmismatch(3,4)'. For an indexed named
set, before adding the constraint sets themselves, the dimensions
of the indexed set must be set by calling one of the following,
where DIM_LIST is a cell array of the dimensions, and the 4th
argument indicates the type of constraint set (linear by default).
OM.ADD_CONSTRAINTS(NAME, DIM_LIST); %% linear
OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'lin'); %% linear
OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nle'); %% nonlin equality
OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nli'); %% nonlin inequality
The constraints are then added using one of the following, where
all arguments are as described above, except IDX_LIST is a cell
array of the indices for the particular constraint set being added.
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U);
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U, VARSETS);
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS);
OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS);
Examples:
%% linear constraint
om.add_constraints('vl', Avl, lvl, uvl, {'Pg', 'Qg'});
%% nonlinear equality constraint with constraint/gradient and Hessian
%% evaluation functions provided
om.add_constraints('Qmis', nb, 1, fcn, hess);
%% linear constraints with indexed named set 'R(i,j)'
om.add_constraints('R', {2, 3}, 'lin');
for i = 1:2
for j = 1:3
om.add_constraints('R', {i, j}, A{i,j}, ...);
end
end
See also OPT_MODEL, LINEAR_CONSTRAINTS, EVAL_NLN_CONSTRAINT.0001 function om = add_constraints(om, name, varargin) 0002 %ADD_CONSTRAINTS Adds a set of constraints to the model. 0003 % 0004 % ----- DEPRECATED - Please use one of the following instead: ----- 0005 % ----- ADD_LIN_CONSTRAINT, ADD_NLN_CONSTRAINT, INIT_INDEXED_NAME ----- 0006 % 0007 % OM.ADD_CONSTRAINTS(NAME, A, L, U); 0008 % OM.ADD_CONSTRAINTS(NAME, A, L, U, VARSETS); 0009 % 0010 % OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS); 0011 % OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS, VARSETS); 0012 % 0013 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST); %% linear 0014 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'lin'); %% linear 0015 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nle'); %% nonlinear equality 0016 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nli'); %% nonlinear inequality 0017 % 0018 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U); 0019 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U, VARSETS); 0020 % 0021 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS); 0022 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS); 0023 % 0024 % Linear Constraints 0025 % 0026 % OM.ADD_CONSTRAINTS(NAME, A, L, U); 0027 % OM.ADD_CONSTRAINTS(NAME, A, L, U, VARSETS); 0028 % 0029 % Linear constraints are of the form L <= A * x <= U, where 0030 % x is a vector made of the vars specified in VARSETS (in 0031 % the order given). This allows the A matrix to be defined only 0032 % in terms of the relevant variables without the need to manually 0033 % create a lot of zero columns. If VARSETS is empty, x is taken 0034 % to be the full vector of all optimization variables. If L or 0035 % U are empty, they are assumed to be appropriately sized vectors 0036 % of -Inf and Inf, respectively. 0037 % 0038 % Nonlinear Constraints 0039 % 0040 % OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS); 0041 % OM.ADD_CONSTRAINTS(NAME, N, ISEQ, FCN, HESS, VARSETS); 0042 % 0043 % For nonlinear constraints, N specifies the number of constraints 0044 % in the set, ISEQ is a 1 for an equality constraint set, 0 for 0045 % inequality, FCN is the handle of a function that evaluates the 0046 % constraint and its gradients, and HESS is the handle of a function 0047 % that evaluates the Hessian of the constraints. 0048 % 0049 % For a constraint G(x) = 0, FCN should point to a function with the 0050 % following interface: 0051 % G = FCN(X) 0052 % [G, DG] = FCN(X) 0053 % where G is an N x 1 vector and DG is the N x NX gradient, where 0054 % DG(i, j) = dG(i)/dX(j) 0055 % and NX is the number of elements in X. 0056 % 0057 % HESS should point to a function that returns an NX x NX matrix 0058 % of derivatives of DG * LAMBDA, with the following interface: 0059 % D2G = HESS(X, LAMBDA) 0060 % 0061 % For both functions, the first input argument X can take two forms. 0062 % If the constraint set is added VARSETS empty or missing, then X 0063 % will be the full optimization vector. Otherwise it will be a cell 0064 % array of vectors corresponding to the variable sets specified in 0065 % VARSETS. 0066 % 0067 % For nonlinear constraints, NAME can be a cell array of constraint 0068 % set names, in which case N is a vector, specifying the number of 0069 % constraints in each set. FCN and HESS are still single function 0070 % handles for functions that compute the values for the entire 0071 % collection of constraint sets together. 0072 % 0073 % Similarly, if the third argument is a string containing 'nle' or 0074 % 'nli', it indicates a placeholder in the indexing for a constraint 0075 % set whose implmentation is included in another constraint set. This 0076 % functionality is only intended to be used internally to handle 0077 % constraint/gradient and Hessian functions that handle more than one 0078 % constraint set simultaneously. 0079 % 0080 % Indexed Named Sets 0081 % A constraint set can be identified by a single NAME, as described 0082 % above, such as 'Pmismatch', or by a name that is indexed by one 0083 % or more indices, such as 'Pmismatch(3,4)'. For an indexed named 0084 % set, before adding the constraint sets themselves, the dimensions 0085 % of the indexed set must be set by calling one of the following, 0086 % where DIM_LIST is a cell array of the dimensions, and the 4th 0087 % argument indicates the type of constraint set (linear by default). 0088 % 0089 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST); %% linear 0090 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'lin'); %% linear 0091 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nle'); %% nonlin equality 0092 % OM.ADD_CONSTRAINTS(NAME, DIM_LIST, 'nli'); %% nonlin inequality 0093 % 0094 % The constraints are then added using one of the following, where 0095 % all arguments are as described above, except IDX_LIST is a cell 0096 % array of the indices for the particular constraint set being added. 0097 % 0098 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U); 0099 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, A, L, U, VARSETS); 0100 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS); 0101 % OM.ADD_CONSTRAINTS(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS); 0102 % 0103 % Examples: 0104 % %% linear constraint 0105 % om.add_constraints('vl', Avl, lvl, uvl, {'Pg', 'Qg'}); 0106 % 0107 % %% nonlinear equality constraint with constraint/gradient and Hessian 0108 % %% evaluation functions provided 0109 % om.add_constraints('Qmis', nb, 1, fcn, hess); 0110 % 0111 % %% linear constraints with indexed named set 'R(i,j)' 0112 % om.add_constraints('R', {2, 3}, 'lin'); 0113 % for i = 1:2 0114 % for j = 1:3 0115 % om.add_constraints('R', {i, j}, A{i,j}, ...); 0116 % end 0117 % end 0118 % 0119 % See also OPT_MODEL, LINEAR_CONSTRAINTS, EVAL_NLN_CONSTRAINT. 0120 0121 % MATPOWER 0122 % Copyright (c) 2008-2017, Power Systems Engineering Research Center (PSERC) 0123 % by Ray Zimmerman, PSERC Cornell 0124 % 0125 % This file is part of MATPOWER. 0126 % Covered by the 3-clause BSD License (see LICENSE file for details). 0127 % See https://matpower.org for more info. 0128 0129 %% determine whether it's linear or nonlinear, simple or indexed 0130 %% and if indexed, just setting dimensions or actually adding constraints 0131 %% linear : nonlin = 0, ff = 'lin' 0132 %% nonlinear : nonlin = 1 0133 %% equality : ff = 'nle' 0134 %% inequality : ff = 'nli' 0135 %% simple : idx empty, args not empty 0136 %% indexed : idx not empty 0137 %% set dims only : args empty 0138 %% add idx'd cons: args not empty 0139 nonlin = 0; 0140 ff = 'lin'; 0141 if iscell(varargin{1}) %% indexed named set 0142 idx = varargin{1}; %% dimensions or indices 0143 if length(varargin) < 3 %% set dimensions for indexed set 0144 args = {}; 0145 if length(varargin) > 1 0146 ff = lower(varargin{2}); 0147 if strcmp(ff, 'nle') 0148 nonlin = 1; 0149 elseif strcmp(ff, 'nli') 0150 nonlin = 1; 0151 elseif ~strcmp(ff, 'lin') 0152 error('@opt_model/add_constraints: ''%s'' is not a valid type (''lin'', ''nle'', or ''nli'') for an indexed constraint set', ff); 0153 end 0154 end 0155 else %% indexed set 0156 args = varargin(2:end); 0157 if isa(args{3}, 'function_handle') 0158 if args{2} 0159 ff = 'nle'; 0160 else 0161 ff = 'nli'; 0162 end 0163 nonlin = 1; 0164 end 0165 end 0166 else %% simple named set 0167 idx = {}; 0168 args = varargin; 0169 0170 if length(args) < 3 || isa(args{3}, 'function_handle') 0171 if args{2} 0172 ff = 'nle'; 0173 else 0174 ff = 'nli'; 0175 end 0176 nonlin = 1; 0177 end 0178 end 0179 nargs = length(args); 0180 0181 if ~isempty(idx) && nargs == 0 %% just set dimensions for indexed set 0182 om.init_indexed_name(ff, name, idx); 0183 else 0184 if nonlin %% nonlinear 0185 if nargs == 2 0186 [N, iseq, fcn, hess, varsets] = deal(args{:}, [], [], {}); 0187 elseif nargs < 5 0188 [N, iseq, fcn, hess, varsets] = deal(args{1:4}, {}); 0189 else 0190 [N, iseq, fcn, hess, varsets] = deal(args{1:5}); 0191 end 0192 om.add_nln_constraint(name, idx, N, iseq, fcn, hess, varsets); 0193 else %% linear 0194 if nargs < 4 0195 [A, l, u, varsets] = deal(args{1:3}, {}); 0196 else 0197 [A, l, u, varsets] = deal(args{1:4}); 0198 end 0199 om.add_lin_constraint(name, idx, A, l, u, varsets); 0200 end 0201 end