mp.sm_quad_cost

class mp.sm_quad_cost

Bases: mp.set_manager_opt_model

mp.sm_quad_cost - MP Set Manager class for quadratic costs.

qdc = mp.sm_quad_cost()
qdc = mp.sm_quad_cost(label)

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

(15)\[f(\x) = \frac{1}{2}\trans{\x} \Hh \x + \trans{\c} \x + \param{k}\]

or a vector cost function of the form

(16)\[\rvec{f}(\x) = \frac{1}{2} \diag{\param{\h}} \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 \(\Hh, \c, \param{k}\) or \(\param{\h}, \c, \k\), along with indexing.

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

mp.sm_quad_cost Properties:

cache - struct for caching aggregated parameters for the set

mp.sm_quad_cost Methods:

sm_quad_cost() - constructor
add() - add a subset of quadratic costs
params() - build and return cost parameters \(\Hh, \c, \param{k}\) or \(\param{\h}, \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

Constructor Summary

sm_quad_cost(varargin)

Constructor.

qdc = mp.sm_quad_cost(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 H parameter is renamed to Q if the new class is mp.sm_quad_cost_legacy.

add(var, name, idx, varargin)

Add a subset of quadratic costs.

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

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

Add a named, and possibly indexed, subset of quadratic costs of form (15) or (16) 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 \(\Hh\), \(\param{\h}\), \(\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)
H (double) – (optional, default = all zeros) quadratic cost coefficient, \(n_x \times n_x\) matrix \(\Hh\), or \(n_x \times 1\) vector \(\param{\h}\)
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\); scalar k is expanded to a vector if H is a vector
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', H1, 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}, H{i,j}, ...);
  end
end

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

params(var, name, idx)

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

[H, c] = qdc.params(var)
[H, c] = qdc.params(var, name)
[H, c] = qdc.params(var, name, idx_list)
[H, c, k] = qdc.params(...)
[H, 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 \(\Hh, \c\), and optionally \(\param{k}\) for the scalar cost form in (15), or \(\param{\h}, \c\), and optionally \(\k\) for the vector cost form in (16).

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 \(\Hh, \param{\h}, \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:

H (double) – quadratic cost coefficient matrix \(\Hh\) or vector \(\param{\h}\)
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(), 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 (15), or vector cost \(\rvec{f}(\x)\) for (16)
- 'df' - cost first derivatives, gradient of scalar cost \(\der{f}{\x}\) for (15), or vector of cost first derivatives for (16)
- 'd2f' - second derivative of costs, \(\der{^2 f}{\x^2}\) for (15), or vector of cost second derivatives for (16)
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});