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