ADD_NLN_COST Adds a set of general nonlinear costs to the model.
OM.ADD_NLN_COST(NAME, N, FCN);
OM.ADD_NLN_COST(NAME, N, FCN, VARSETS);
OM.ADD_NLN_COST(NAME, IDX_LIST, N, FCN);
OM.ADD_NLN_COST(NAME, IDX_LIST, N, FCN, VARSETS);
Adds a named block of general nonlinear costs to the model. FCN is
a handle to function that evaluates the cost, its gradient and Hessian
as described below.
The N parameter specifies the dimension for vector valued cost
functions, which are not yet implemented. Currently N must equal 1
or it will throw an error.
For a cost function f(x), FCN should point to a function with the
following interface:
F = FCN(X)
[F, DF] = FCN(X)
[F, DF, D2F] = FCN(X)
where F is a scalar with the value of the function, DG is the 1 x NX
gradient, and D2F is the NX x NX Hessian and NX is the number of
elements in X.
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.
Indexed Named Sets
A cost set can be identified by a single NAME, as described
above, such as 'PgCost', or by a name that is indexed by one
or more indices, such as 'PgCost(3,4)'. For an indexed named
set, before adding the cost 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 cost set being added.
OM.ADD_NLN_COST(NAME, IDX_LIST, FCN);
OM.ADD_NLN_COST(NAME, IDX_LIST, FCN, VARSETS);
Examples:
fcn1 = @(x)my_cost_function1(x, other_args)
fcn2 = @(x)my_cost_function2(x, other_args)
om.add_nln_cost('mycost1', 1, fcn1);
om.add_nln_cost('mycost2', 1, fcn2, {'Vm', 'Pg', 'Qg', 'z'});
om.init_indexed_name('c', {2, 3});
for i = 1:2
for j = 1:3
om.add_nln_cost('c', {i, j}, 1, fcn(i,j), ...);
end
end
See also OPT_MODEL, EVAL_NLN_COST.0001 function om = add_nln_cost(om, name, idx, N, fcn, varsets) 0002 %ADD_NLN_COST Adds a set of general nonlinear costs to the model. 0003 % OM.ADD_NLN_COST(NAME, N, FCN); 0004 % OM.ADD_NLN_COST(NAME, N, FCN, VARSETS); 0005 % OM.ADD_NLN_COST(NAME, IDX_LIST, N, FCN); 0006 % OM.ADD_NLN_COST(NAME, IDX_LIST, N, FCN, VARSETS); 0007 % 0008 % Adds a named block of general nonlinear costs to the model. FCN is 0009 % a handle to function that evaluates the cost, its gradient and Hessian 0010 % as described below. 0011 % 0012 % The N parameter specifies the dimension for vector valued cost 0013 % functions, which are not yet implemented. Currently N must equal 1 0014 % or it will throw an error. 0015 % 0016 % For a cost function f(x), FCN should point to a function with the 0017 % following interface: 0018 % F = FCN(X) 0019 % [F, DF] = FCN(X) 0020 % [F, DF, D2F] = FCN(X) 0021 % where F is a scalar with the value of the function, DG is the 1 x NX 0022 % gradient, and D2F is the NX x NX Hessian and NX is the number of 0023 % elements in X. 0024 % 0025 % The first input argument X can take two forms. If the constraint set 0026 % is added with VARSETS empty or missing, then X will be the full 0027 % optimization vector. Otherwise it will be a cell array of vectors 0028 % corresponding to the variable sets specified in VARSETS. 0029 % 0030 % Indexed Named Sets 0031 % A cost set can be identified by a single NAME, as described 0032 % above, such as 'PgCost', or by a name that is indexed by one 0033 % or more indices, such as 'PgCost(3,4)'. For an indexed named 0034 % set, before adding the cost sets themselves, the dimensions 0035 % of the indexed set must be set by calling INIT_INDEXED_NAME. 0036 % 0037 % The constraints are then added using the following, where 0038 % all arguments are as described above, except IDX_LIST is a cell 0039 % array of the indices for the particular cost set being added. 0040 % 0041 % OM.ADD_NLN_COST(NAME, IDX_LIST, FCN); 0042 % OM.ADD_NLN_COST(NAME, IDX_LIST, FCN, VARSETS); 0043 % 0044 % Examples: 0045 % 0046 % fcn1 = @(x)my_cost_function1(x, other_args) 0047 % fcn2 = @(x)my_cost_function2(x, other_args) 0048 % om.add_nln_cost('mycost1', 1, fcn1); 0049 % om.add_nln_cost('mycost2', 1, fcn2, {'Vm', 'Pg', 'Qg', 'z'}); 0050 % 0051 % om.init_indexed_name('c', {2, 3}); 0052 % for i = 1:2 0053 % for j = 1:3 0054 % om.add_nln_cost('c', {i, j}, 1, fcn(i,j), ...); 0055 % end 0056 % end 0057 % 0058 % See also OPT_MODEL, EVAL_NLN_COST. 0059 0060 % MATPOWER 0061 % Copyright (c) 2008-2017, Power Systems Engineering Research Center (PSERC) 0062 % by Ray Zimmerman, PSERC Cornell 0063 % 0064 % This file is part of MATPOWER. 0065 % Covered by the 3-clause BSD License (see LICENSE file for details). 0066 % See https://matpower.org for more info. 0067 0068 %% initialize input arguments 0069 if iscell(idx) %% indexed named set 0070 if nargin < 6 0071 varsets = {}; 0072 end 0073 else %% simple named set 0074 if nargin < 5 0075 varsets = {}; 0076 else 0077 varsets = fcn; 0078 end 0079 fcn = N; 0080 N = idx; 0081 idx = {}; 0082 end 0083 0084 if N ~= 1 0085 error('@opt_model/add_nln_cost: not yet implemented for vector valued functions (i.e. N currently must equal 1)'); 0086 end 0087 0088 %% convert varsets from cell to struct array if necessary 0089 varsets = om.varsets_cell2struct(varsets); 0090 0091 %% add the named general nonlinear cost set 0092 om.add_named_set('nlc', name, idx, N, fcn, varsets);