eval_nln_cost

EVAL_NLN_COST  Evaluates individual or full set of general nonlinear costs.
   [F, DF, D2F] = OM.EVAL_NLN_COST(X)
   [F, DF, D2F] = OM.EVAL_NLN_COST(X, NAME)
   [F, DF, D2F] = OM.EVAL_NLN_COST(X, NAME, IDX_LIST)
   Evaluates the cost function and its derivatives for an individual named
   set or the full set of general nonlinear costs for a given value of the
   optimization vector X, based on costs added by ADD_NLN_COST.

   Example:
       [f, df, d2f] = om.eval_nln_cost(x)
       [f, df, d2f] = om.eval_nln_cost(x, name)
       [f, df, d2f] = om.eval_nln_cost(x, name, idx_list)

   See also OPT_MODEL, ADD_NLN_COST, PARAMS_NLN_COST.

0001 function [f, df, d2f] = eval_nln_cost(om, x, name, idx)
0002 %EVAL_NLN_COST  Evaluates individual or full set of general nonlinear costs.
0003 %   [F, DF, D2F] = OM.EVAL_NLN_COST(X)
0004 %   [F, DF, D2F] = OM.EVAL_NLN_COST(X, NAME)
0005 %   [F, DF, D2F] = OM.EVAL_NLN_COST(X, NAME, IDX_LIST)
0006 %   Evaluates the cost function and its derivatives for an individual named
0007 %   set or the full set of general nonlinear costs for a given value of the
0008 %   optimization vector X, based on costs added by ADD_NLN_COST.
0009 %
0010 %   Example:
0011 %       [f, df, d2f] = om.eval_nln_cost(x)
0012 %       [f, df, d2f] = om.eval_nln_cost(x, name)
0013 %       [f, df, d2f] = om.eval_nln_cost(x, name, idx_list)
0014 %
0015 %   See also OPT_MODEL, ADD_NLN_COST, PARAMS_NLN_COST.
0016 
0017 %   MP-Opt-Model
0018 %   Copyright (c) 2008-2020, Power Systems Engineering Research Center (PSERC)
0019 %   by Ray Zimmerman, PSERC Cornell
0020 %
0021 %   This file is part of MP-Opt-Model.
0022 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0023 %   See https://github.com/MATPOWER/mp-opt-model for more info.
0024 
0025 %% initialize
0026 if nargin < 4
0027     idx = {};
0028 end
0029 nlc = om.nlc;
0030 
0031 if nargin < 3                       %% full set
0032     f = 0;
0033     nx = om.var.N;          %% number of variables
0034     if nargout > 1
0035         df = zeros(nx, 1);  %% column vector
0036         if nargout > 2
0037             d2f = sparse(nx, nx);   %% symmetric, so transpose (used for speed)
0038         end                         %% is equal
0039     end
0040 
0041     for k = 1:nlc.NS
0042         name = nlc.order(k).name;
0043         idx  = nlc.order(k).idx;
0044         [N, fcn, vs] = om.params_nln_cost(name, idx);
0045         if N ~= 1
0046             error('@opt_model/eval_nln_cost: not yet implemented for vector valued functions');
0047         end
0048         xx = om.varsets_x(x, vs);
0049         if nargout == 3
0050             [fk, dfk, d2fk] = fcn(xx);  %% evaluate kth cost, gradient, Hessian
0051         elseif nargout == 2
0052             [fk, dfk] = fcn(xx);        %% evaluate kth cost and gradient
0053         else
0054             fk = fcn(xx);               %% evaluate kth cost
0055         end
0056 
0057         f = f + fk;
0058         
0059         if nargout > 1              %% assemble gradient
0060             nk = length(dfk);
0061             if isempty(vs)          %% all rows of x
0062                 if nk == nx
0063                     df = df + dfk;
0064                     if nargout > 2  %% assemble Hessian
0065                         d2f = d2f + d2fk;
0066                     end
0067                 else                %% must have added vars since adding
0068                                     %% this cost set
0069                     df(1:nk) = df(1:nk) + dfk;
0070                     if nargout > 2      %% assemble Hessian
0071                         d2fk_all_cols = sparse(nk, nx);
0072                         d2fk_all_cols(:, 1:nk) = d2fk;
0073                         d2fk_full = sparse(nx, nx);
0074                         d2f(:, 1:nk) = d2f(:, 1:nk) + d2fk_all_cols';
0075                     end
0076                 end
0077             else                    %% selected rows of x
0078                 jj = om.varsets_idx(vs);    %% indices for var set
0079                 df(jj) = df(jj) + dfk;
0080                 if nargout > 2      %% assemble Hessian
0081                     d2fk_all_cols = sparse(nk, nx);
0082                     d2fk_all_cols(:, jj) = d2fk;
0083                     d2fk_full = sparse(nx, nx);
0084                     d2f(:, jj) = d2f(:, jj) + d2fk_all_cols';
0085                 end
0086             end
0087         end
0088     end
0089 else                                %% individual named set
0090     dims = size(nlc.idx.i1.(name));
0091     if ~isempty(idx) || prod(dims) == 1 %% indexed, or simple named set
0092         [N, fcn, vs] = om.params_nln_cost(name, idx);
0093         if N ~= 1
0094             error('@opt_model/eval_nln_cost: not yet implemented for vector valued functions');
0095         end
0096         xx = om.varsets_x(x, vs);
0097         if nargout == 3
0098             [f, df, d2f] = fcn(xx);     %% evaluate kth cost, gradient, Hessian
0099         elseif nargout == 2
0100             [f, df] = fcn(xx);          %% evaluate kth cost and gradient
0101         else
0102             f = fcn(xx);                %% evaluate kth cost
0103         end
0104     elseif nargout == 1             %% sum over all indices for name
0105         done = 0;
0106         f = 0;          %% initialize cumulative cost
0107         idx = num2cell(ones(size(dims))); %% initialize idx
0108         while ~done     %% call eval_nln_cost() recursively
0109             f = f + sum(om.eval_nln_cost(x, name, idx));
0110         
0111             %% increment idx
0112             D = length(dims);
0113             idx{D} = idx{D} + 1;    %% increment last dimension
0114             for d = D:-1:2          %% increment next dimension, if necessary
0115                 if idx{d} > dims(d)
0116                     idx{d} = 1;
0117                     idx{d-1} = idx{d-1} + 1;
0118                 end
0119             end
0120             if idx{1} > dims(1)     %% check if done
0121                 done = 1;
0122             end
0123         end
0124     else
0125         error('@opt_model/eval_nln_cost: general nonlinear cost set ''%s'' requires an IDX_LIST arg when requesting DF output', name)
0126     end
0127 end