Home > matpower7.1 > mp-opt-model > lib > @opt_model > add_nln_cost.m

add_nln_cost

PURPOSE ^

ADD_NLN_COST Adds a set of general nonlinear costs to the model.

SYNOPSIS ^

function om = add_nln_cost(om, name, idx, N, fcn, varsets)

DESCRIPTION ^

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, DF 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.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

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, DF 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 %   MP-Opt-Model
0061 %   Copyright (c) 2008-2020, Power Systems Engineering Research Center (PSERC)
0062 %   by Ray Zimmerman, PSERC Cornell
0063 %
0064 %   This file is part of MP-Opt-Model.
0065 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0066 %   See https://github.com/MATPOWER/mp-opt-model 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);

Generated on Fri 09-Oct-2020 11:21:31 by m2html © 2005