mp.sm_quad_cost_legacy

class mp.sm_quad_cost_legacy

Bases: mp.set_manager_opt_model

mp.sm_quad_cost_legacy - MP Set Manager class for legacy quadratic costs.

Note

Deprecated since version 5.0: For use only with deprecated opt_model. Please use mp.opt_model instead, which uses mp.sm_quad_cost with the Q parameter renamed to H for consistency.

qdc = mp.sm_quad_cost_legacy()
qdc = mp.sm_quad_cost_legacy(label)

MP Set Manager class for legacy quadratic costs. The costs take one of two forms, either a scalar cost function of the form

(24)\[f(\x) = \frac{1}{2}\trans{\x} \QQ \x + \trans{\c} \x + \param{k}\]

or a vector cost function of the form

(25)\[\rvec{f}(\x) = \frac{1}{2} \diag{\q} \x^2 + \diag{\c} \x + \k\]

where \(\x\) is an \(n_x \times 1\) vector, and the corresponding coefficient parameters are conformable.

Manages cost parameters \(\QQ, \c, \param{k}\) or \(\q, \c, \k\), along with indexing.

By convention, qdc is the variable name used for mp.sm_quad_cost_legacy objects.

mp.sm_quad_cost_legacy Properties:

  • cache - struct for caching aggregated parameters for the set

mp.sm_quad_cost_legacy Methods:

  • sm_quad_cost_legacy() - constructor

  • add() - add a subset of quadratic costs

  • params() - build and return cost parameters \(\QQ, \c, \param{k}\) or \(\q, \c, \k\)

  • set_params() - modify quadratic cost parameter data

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

  • display_soln() - display solution values for quadratic costs

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

See also mp.set_manager, mp.set_manager_opt_model.

Constructor Summary
sm_quad_cost_legacy(varargin)

Constructor.

qdc = mp.sm_quad_cost_legacy(label)
Property Summary
cache = []

struct for caching aggregated parameters for quadratic costs

Method Summary
copy(varargin)

Duplicate the object.

new_sm = sm.copy()
new_sm = sm.copy(new_class)
Input:

new_class (char array) – (default = same class) name of class to use for new object

Make a shallow copy() of the object by copying each of the top-level properties. Parent method makes the copy(), then the Q parameter is renamed to H if the new class is mp.sm_quad_cost.

add(var, name, idx, varargin)

Add a subset of quadratic costs.

qdc.add(var, name, Q, c);
qdc.add(var, name, Q, c, k);
qdc.add(var, name, Q, c, k, vs);

qdc.add(var, name, idx_list, Q, c);
qdc.add(var, name, idx_list, Q, c, k);
qdc.add(var, name, idx_list, Q, c, k, vs);

Add a named, and possibly indexed, subset of quadratic costs of form (24) or (25) 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 \(\QQ\), \(\q\), \(\c\), and/or \(\k\) parameters to be defined in terms of only the relevant variables without the need to manually create a lot of properly located zero rows/columns.

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)

  • Q (double) – (optional, default = all zeros) quadratic cost coefficient, \(n_x \times n_x\) matrix \(\QQ\), or \(n_x \times 1\) vector \(\q\)

  • c (double) – (optional, default = all zeros) linear cost coefficient, \(n_x \times 1\) vector \(\c\)

  • k (double) – (optional, default = 0) constant cost term, scalar \(\param{k}\), or \(n_x \times 1\) vector \(\k\)

  • 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

Examples:

qdc.add(var, 'quad_cost1', Q1, c1, 0);
qdc.add(var, 'lin_cost2',  [], c2, k2, {'Vm', 'Pg', 'z'});

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

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

params(var, name, idx)

Build and return quadratic cost parameters \(\QQ, \c, \param{k}\) or \(\q, \c, \k\).

[Q, c] = qdc.params(var)
[Q, c] = qdc.params(var, name)
[Q, c] = qdc.params(var, name, idx_list)
[Q, c, k] = qdc.params(...)
[Q, c, k, vs] = qdc.params(...)

With no input parameters, it assembles and returns the parameters for the aggregate quadratic cost from all quadratic cost sets added using add(). The values of these parameters are cached for subsequent calls. The parameters are \(\QQ, \c\), and optionally \(\param{k}\) for the scalar cost form in (24), or \(\q, \c\), and optionally \(\k\) for the vector cost form in (25).

If a name or name and index list are provided, then it simply returns the parameters for the corresponding set. It can also optionally return the variable sets used by this cost set (the dimensions of \(\QQ, \q, \c, \k\) will be consistent with this variable set).

Inputs:

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

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

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

Outputs:

  • Q (double) – quadratic cost coefficient matrix \(\QQ\) or vector \(\q\)

  • c (double) – linear cost coefficient vector \(\c\)

  • k (double) – constant cost term, scalar \(\param{k}\), or vector \(\k\)

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

See also add().

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

Modify quadratic cost parameter data.

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

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

Inputs:

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

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

  • idx_list (cell array) – (optional) index list for subset/block of quadratic 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 Q, c, k, vs.

Examples:

qdc.set_params(var, 'y', {2,3}, {'c'}, {c});
qdc.set_params(var, 'Pg', 'all', {Q, c, k, vs});

See also add(), params().

eval(var, x, name, idx)

Evaluate individual or full set of quadratic costs.

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

For a given value of the variable vector \(\x\), this method evaluates the quadratic 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) – name of subset/block of quadratic costs to evaluate

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

Outputs:

  • f (double) – scalar cost \(f(\x)\) for (24), or vector cost \(\rvec{f}(\x)\) for (25)

  • df (double) – (optional) cost first derivatives, gradient of scalar cost \(\der{f}{\x}\) for (24), or vector of cost first derivatives for (25)

  • d2f (double) – (optional) second derivative of costs, \(\der{^2 f}{\x^2}\) for (24), or vector of cost second derivatives for (25)

See also add(), params().

display_soln(var, soln, varargin)

Display solution values for quadratic costs.

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

Displays the solution values for all quadratic 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 = qdc.get_soln(var, soln, name)
vals = qdc.get_soln(var, soln, name, idx_list)
vals = qdc.get_soln(var, soln, tags, name)
vals = qdc.get_soln(var, soln, tags, name, idx_list)

Returns named/indexed quadratic 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' - scalar cost \(f(\x)\) for (24), or vector cost \(\rvec{f}(\x)\) for (25)

    • 'df' - cost first derivatives, gradient of scalar cost \(\der{f}{\x}\) for (24), or vector of cost first derivatives for (25)

    • 'd2f' - second derivative of costs, \(\der{^2 f}{\x^2}\) for (24), or vector of cost second derivatives for (25)

  • 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] = qdc.get_soln(var, soln, 'gen');
df_Pg_2_4 = qdc.get_soln(var, soln, 'df', 'Pg', {2,4});