mp.sm_nln_cost

class mp.sm_nln_cost

Bases: mp.set_manager_opt_model

mp.sm_nln_cost - MP Set Manager class for general nonlinear costs.

nlc = mp.sm_nln_cost()
nlc = mp.sm_nln_cost(label)

MP Set Manager class for general nonlinear costs \(f(\x)\) where \(\x\) is an \(n_x \times 1\) vector.

Manages general nonlinear cost sets and their indexing.

By convention, nlc is the variable name used for mp.sm_nln_cost objects.

mp.sm_nln_cost Methods:

• sm_nln_cost() - constructor

• add() - add a subset of general nonlinear costs

• params() - return general nonlinear cost parameters

• set_params() - modify general nonlinear cost parameter data

• eval() - evaluate individual or full set of general nonlinear costs

• display_soln() - display solution values for general nonlinear costs

• get_soln() - fetch solution values for specific named/indexed subsets

See also mp.set_manager, mp.set_manager_opt_model.

Constructor Summary

sm_nln_cost(varargin)

Constructor.

nlc = mp.sm_nln_cost(label)

Method Summary

add(var, name, idx, varargin)

Add a subset of nonlinear costs.

nlc.add(var, name, N, fcn);
nlc.add(var, name, N, fcn, vs);

nlc.add(var, name, idx_list, N, fcn);
nlc.add(var, name, idx_list, N, fcn, vs);

Add a named, and possibly indexed, subset of general nonlinear costs \(f(\x)\) to the set, where \(\x\) is an \(n_x \times 1\) vector made up of the variables specified in the optional vs (in the order given). This allows the cost function to be defined in terms of only the relevant variables without the need to manually account for the locations of other variable sets.

Inputs:

• var (mp.sm_variable) – corresponding mp.sm_variable object

• name (char array) – name of subset/block of costs to add()

• idx_list (cell array) – (optional) index list for subset/block of costs to add() (for an indexed subset)

• N (integer) – dimension of cost function; currently this must equal 1; vector-valued cost functions are not yet implemented

• fcn (function handle) – handle to function that evaluates the cost \(f(\x)\), its gradient \(\trans{f_\x}\), and Hessian \(f_{\x\x}\) as described below

• vs (cell or struct array) – (optional, default {} ) variable set defining vector \(\x\) for this cost subset; can be either a cell array of names of variable subsets, or a struct array of name, idx pairs of indexed named subsets of variables; order of vs determines order of blocks in \(\x\); if empty, \(\x\) is assumed to be the full variable vector

Cost Function Implmentation : fcn

For a cost function \(f(\x)\), the fcn input should point to a function with the following interface:

f = fcn(x)
[f, df] = fcn(x)
[f, df, d2f] = fcn(x)

Input:

x (double or cell array of doubles) – variable \(\x\) corresponding to the full variable vector, or to a set of sub-vectors defined by the variable set provided in vs

Outputs:

• f (double) – scalar value of cost function \(f(\x)\)

• df (double) – (optional) \(n_x \times 1\) cost gradient, transpose of \(f_\x = \der{f}{\x}\)

• d2f (double) – (optional) \(n_x \times n_x\) Hessian matrix \(f_{\x\x} = \der{}{\x}(\trans{f_\x})\)

The input argument x takes one of two forms. If the cost set is added with varset input vs empty or missing, then x will be the full variable vector. Otherwise it will be a cell array of vectors corresponding to the variable sets specified in vs.

Examples:

fcn1 = @(x)my_cost_function1(x, other_args)
fcn2 = @(x)my_cost_function2(x, other_args)
nlc.add(var, 'mycost1', 1, fcn1);
nlc.add(var, 'mycost2', 1, fcn2, {'Vm', 'Pg', 'Qg', 'z'});

nlc.init_indexed_name('c', {2, 3});
for i = 1:2
  for j = 1:3
    nlc.add(var, 'c', {i, j}, 1, fcn(i,j), ...);
  end
end

See also params(), set_params(), eval().

params(var, name, idx)

Return general nonlinear cost parameters.

[N, fcn] = nlc.params(var, name)
[N, fcn] = nlc.params(var, name, idx_list)
[N, fcn, vs] = nlc.params(...)

Returns the parameters for the general nonlinear cost subset corresponding to the name or name and index list provided. The parameters are those supplied via the add method when the subset was added.

Inputs:

• var (mp.sm_variable) – corresponding mp.sm_variable object

• name (char array) – name of subset

• idx_list (cell array) – (optional) index list for subset

Outputs:

• N (integer) – dimension of cost function; currently equals 1; vector-valued cost functions are not yet implemented

• fcn (function handle) – handle to function that evaluates the cost \(f(\x)\), its gradient \(\trans{f_\x}\), and Hessian \(f_{\x\x}\); see add() for details

• vs (struct array) – variable set, name, idx pairs specifying the set of variables defining vector \(\x\) for this cost subset; order of vs determines order of blocks in \(\x\)

See also add(), eval().

set_params(var, name, idx, params, vals)

Modify general nonlinear cost parameter data.

nlc.set_params(var, name, params, vals)
nlc.set_params(var, name, idx_list, params, vals)

This method can be used to modify parameters for an existing subset of general nonlinear costs.

Inputs:

• var (mp.sm_variable) – corresponding mp.sm_variable object

• name (char array) – name of subset/block of general nonlinear costs to modify

• idx_list (cell array) – (optional) index list for subset/block of general nonlinear costs to modify (for an indexed subset)

• params – can be one of three options:

  • 'all' - indicates that vals is a cell array whose elements correspond to the input parameters of the add() method

  • name of a parameter - val is the value of that parameter

  • cell array of parameter names - vals is a cell array of corresponding values

• vals – new value or cell array of new values corresponding to params

Valid parameter names are N, fcn, vs.

Examples:

nlc.set_params(var, 'y', {2,3}, {'fcn'}, {fcn});
nlc.set_params(var, 'Pg', 'all', {N, fcn, vs});

See also add(), params().

eval(var, x, name, idx)

Evaluate individual or full set of general nonlinear costs.

f = nlc.eval(var, x ...)
[f, df] = nlc.eval(var, x ...)
[f, df, d2f] = nlc.eval(var, x ...)
[f, df, d2f] = nlc.eval(var, x, name)
[f, df, d2f] = nlc.eval(var, x, name, idx_list)

For a given value of the variable vector \(\x\), this method evaluates the general nonlinear cost function and optionally its derivatives for an individual subset, if name or name and index list are provided, otherwise, for the full set of costs.

Inputs:

• var (mp.sm_variable) – corresponding mp.sm_variable object

• x (double) – full \(n_x \times 1\) variable vector \(\x\)

• name (char array) – (optional) name of subset/block of general nonlinear costs to evaluate

• idx_list (cell array) – (optional) index list for subset/block of general nonlinear costs to evaluate (for an indexed subset)

Outputs:

• f (double) – scalar value of cost function \(f(\x)\)

• df (double) – (optional) \(n_x \times 1\) cost gradient, transpose of \(f_\x = \der{f}{\x}\)

• d2f (double) – (optional) \(n_x \times n_x\) Hessian matrix \(f_{\x\x} = \der{}{\x}(\trans{f_\x})\)

See also add(), params().

display_soln(var, soln, varargin)

Display solution values for general nonlinear costs.

nlc.display_soln(var, soln)
nlc.display_soln(var, soln, name)
nlc.display_soln(var, soln, name, idx_list)
nlc.display_soln(var, soln, fid)
nlc.display_soln(var, soln, fid, name)
nlc.display_soln(var, soln, fid, name, idx_list)

Displays the solution values for all general nonlinear costs (default) or an individual named or named/indexed subset.

Inputs:

• var (mp.sm_variable) – corresponding mp.sm_variable object

• soln (struct) – full solution struct with these fields (among others):

  • eflag - exit flag, 1 = success, 0 or negative = solver-specific failure code

  • x - variable values

  • lambda - constraint shadow prices, struct with fields:

    • eqnonlin - nonlinear equality constraints

    • ineqnonlin - nonlinear inequality constraints

    • mu_l - linear constraint lower bounds

    • mu_u - linear constraint upper bounds

    • lower - variable lower bounds

    • upper - variable upper bounds

• fid (fileID) – fileID of open file to write to (default is 1 for standard output)

• name (char array) – (optional) name of individual subset

• idx_list (cell array) – (optional) indices of individual subset

get_soln(var, soln, varargin)

Fetch solution values for specific named/indexed subsets.

vals = nlc.get_soln(var, soln, name)
vals = nlc.get_soln(var, soln, name, idx_list)
vals = nlc.get_soln(var, soln, tags, name)
vals = nlc.get_soln(var, soln, tags, name, idx_list)

Returns named/indexed nonlinear cost results for a solved model, evaluated at the solution found.

Inputs:

• var (mp.sm_variable) – corresponding mp.sm_variable object

• soln (struct) – full solution struct with these fields (among others):

  • eflag - exit flag, 1 = success, 0 or negative = solver-specific failure code

  • x - variable values

  • lambda - constraint shadow prices, struct with fields:

    • eqnonlin - nonlinear equality constraints

    • ineqnonlin - nonlinear inequality constraints

    • mu_l - linear constraint lower bounds

    • mu_u - linear constraint upper bounds

    • lower - variable lower bounds

    • upper - variable upper bounds

• tags (char array or cell array of char arrays) – names of desired outputs, default is {'f', 'df', 'd2f'} with valid values:

  • 'f' - cost function value \(f(\x)\)

  • 'df' - cost gradient, transpose of \(f_\x = \der{f}{\x}\)

  • 'd2f' - cost Hessian \(f_{\x\x} = \der{}{\x}(\trans{f_\x})\)

• name (char array) – name of the subset

• idx_list (cell array) – (optional) indices of the subset

Outputs:

Variable number of outputs corresponding to tags input. If tags is empty or not specified, the calling context will define the number of outputs, returned in order of default tags.

Example:

[f, df, d2f] = nlc.get_soln(var, soln, 'gen');
df_Pg_2_4 = nlc.get_soln(var, soln, 'df', 'Pg', {2,4});