ADD_NLN_CONSTRAINT Adds a set of nonlinear constraints to the model.
OM.ADD_NLN_CONSTRAINT(NAME, N, ISEQ, FCN, HESS);
OM.ADD_NLN_CONSTRAINT(NAME, N, ISEQ, FCN, HESS, VARSETS);
OM.ADD_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS);
OM.ADD_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS);
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 with 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 simple (not indexed) named sets, NAME can be a cell array of
constraint set names, in which case N is a vector, specifying the number
of constraints in each corresponding set. FCN and HESS are each still
a single function handle, but the values computed by each correspond
to the entire stacked collection of constraint sets together, as if
they were a single set.
Likewise, if FCN or HESS are empty, it also indicates a placeholder in
the indexing for a constraint set whose implementation is included in
another constraint set. This functionality is only intended to be used
internally to handle constraint/gradient and Hessian functions that
compute the values for 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 INIT_INDEXED_NAME.
The constraints are then added using 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_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS);
OM.ADD_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS);
Examples:
%% nonlinear equality constraint with constraint/gradient and Hessian
%% evaluation functions provided
om.add_nln_constraint('Qmis', nb, 1, fcn, hess);
%% nonlinear inequality constraints with indexed named set 'S(i,j)'
om.init_indexed_name('nli', 'S', {2, 3});
for i = 1:2
for j = 1:3
om.add_nln_constraint('S', {i, j}, N{i,j}, ...);
end
end
See also OPT_MODEL, EVAL_NLN_CONSTRAINT.0001 function om = add_nln_constraint(om, name, idx, N, iseq, fcn, hess, varsets) 0002 %ADD_NLN_CONSTRAINT Adds a set of nonlinear constraints to the model. 0003 % 0004 % OM.ADD_NLN_CONSTRAINT(NAME, N, ISEQ, FCN, HESS); 0005 % OM.ADD_NLN_CONSTRAINT(NAME, N, ISEQ, FCN, HESS, VARSETS); 0006 % 0007 % OM.ADD_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS); 0008 % OM.ADD_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS); 0009 % 0010 % N specifies the number of constraints in the set, ISEQ is a 1 for 0011 % an equality constraint set, 0 for inequality, FCN is the handle of a 0012 % function that evaluates the constraint and its gradients, and HESS is 0013 % the handle of a function that evaluates the Hessian of the constraints. 0014 % 0015 % For a constraint G(x) = 0, FCN should point to a function with the 0016 % following interface: 0017 % G = FCN(X) 0018 % [G, DG] = FCN(X) 0019 % where G is an N x 1 vector and DG is the N x NX gradient, where 0020 % DG(i, j) = dG(i)/dX(j) 0021 % and NX is the number of elements in X. 0022 % 0023 % HESS should point to a function that returns an NX x NX matrix of 0024 % derivatives of DG * LAMBDA, with the following interface: 0025 % D2G = HESS(X, LAMBDA) 0026 % 0027 % For both functions, the first input argument X can take two forms. If 0028 % the constraint set is added with VARSETS empty or missing, then X will 0029 % be the full optimization vector. Otherwise it will be a cell array of 0030 % vectors corresponding to the variable sets specified in VARSETS. 0031 % 0032 % For simple (not indexed) named sets, NAME can be a cell array of 0033 % constraint set names, in which case N is a vector, specifying the number 0034 % of constraints in each corresponding set. FCN and HESS are each still 0035 % a single function handle, but the values computed by each correspond 0036 % to the entire stacked collection of constraint sets together, as if 0037 % they were a single set. 0038 % 0039 % Likewise, if FCN or HESS are empty, it also indicates a placeholder in 0040 % the indexing for a constraint set whose implementation is included in 0041 % another constraint set. This functionality is only intended to be used 0042 % internally to handle constraint/gradient and Hessian functions that 0043 % compute the values for more than one constraint set simultaneously. 0044 % 0045 % Indexed Named Sets 0046 % A constraint set can be identified by a single NAME, as described 0047 % above, such as 'Pmismatch', or by a name that is indexed by one 0048 % or more indices, such as 'Pmismatch(3,4)'. For an indexed named 0049 % set, before adding the constraint sets themselves, the dimensions 0050 % of the indexed set must be set by calling INIT_INDEXED_NAME. 0051 % 0052 % The constraints are then added using the following, where 0053 % all arguments are as described above, except IDX_LIST is a cell 0054 % array of the indices for the particular constraint set being added. 0055 % 0056 % OM.ADD_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS); 0057 % OM.ADD_NLN_CONSTRAINT(NAME, IDX_LIST, N, ISEQ, FCN, HESS, VARSETS); 0058 % 0059 % Examples: 0060 % %% nonlinear equality constraint with constraint/gradient and Hessian 0061 % %% evaluation functions provided 0062 % om.add_nln_constraint('Qmis', nb, 1, fcn, hess); 0063 % 0064 % %% nonlinear inequality constraints with indexed named set 'S(i,j)' 0065 % om.init_indexed_name('nli', 'S', {2, 3}); 0066 % for i = 1:2 0067 % for j = 1:3 0068 % om.add_nln_constraint('S', {i, j}, N{i,j}, ...); 0069 % end 0070 % end 0071 % 0072 % See also OPT_MODEL, EVAL_NLN_CONSTRAINT. 0073 0074 % MP-Opt-Model 0075 % Copyright (c) 2008-2020, Power Systems Engineering Research Center (PSERC) 0076 % by Ray Zimmerman, PSERC Cornell 0077 % 0078 % This file is part of MP-Opt-Model. 0079 % Covered by the 3-clause BSD License (see LICENSE file for details). 0080 % See https://github.com/MATPOWER/mp-opt-model for more info. 0081 0082 %% initialize input arguments 0083 if iscell(idx) %% indexed named set 0084 if nargin < 8 0085 varsets = {}; 0086 end 0087 else %% simple named set 0088 if nargin < 7 0089 varsets = {}; 0090 else 0091 varsets = hess; 0092 end 0093 if nargin > 4 0094 hess = fcn; 0095 fcn = iseq; 0096 end 0097 iseq = N; 0098 N = idx; 0099 idx = {}; 0100 end 0101 if iseq 0102 ff = 'nle'; %% nonlinear equality 0103 else 0104 ff = 'nli'; %% nonlinear inequality 0105 end 0106 0107 %% convert varsets from cell to struct array if necessary 0108 varsets = om.varsets_cell2struct(varsets); 0109 0110 %% add the named nonlinear constraint set 0111 if iscell(name) 0112 if length(name) ~= length(N) 0113 error('@opt_model/add_nln_constraint: dimensions of NAME and N must match'); 0114 end 0115 om.add_named_set(ff, name{1}, idx, N(1), fcn, hess, '', varsets); 0116 for k = 2:length(name) 0117 om.add_named_set(ff, name{k}, idx, N(k), [], [], name{1}, varsets); 0118 end 0119 else 0120 om.add_named_set(ff, name, idx, N, fcn, hess, '', varsets); 0121 end