mp.sm_quad_constraint

class mp.sm_quad_constraint

Bases: mp.set_manager_opt_model

mp.sm_quad_constraint - MP Set Manager class for quadratic constraints.

qcn = mp.sm_quad_constraint()
qcn = mp.sm_quad_constraint(label)

MP Set Manager class for quadratic constraints of the form

(17)\[\li \le \frac{1}{2}\trans{\x} \QQ_i \x + \b_i \x \le \ui, \ \ \ i = 1,2,..., n_q\]

Manages quadratic constraint sets and their indexing.

The parameters defining the set of constraints are \(\QQ_1, \dots, \QQ_{n_q}, \Bb, \l, \u\), where \(\b_i\) in (17) is row \(i\) of matrix \(\Bb\), \(\li\) and \(\ui\) are the \(i\)-th elements of vectors \(\l\) and \(\u\), respectively, and \(n_q\) is the number of quadratic constraints.

Let \(\{\rmat{A}\}_{\times n}\) denote the set \(\{\rmat{A}, \rmat{A}, \dots, \rmat{A}\}\) where \(\rmat{A}\) is repeated \(n\) times, let \(\mathcal{A} = \{\rmat{A}_i\}_{i=1}^n\) be a set of \(n\) matrices or vectors indexed by \(i\), and let \(\textrm{diag}(\rmat{A}) = \trans{\left[a_{11} \ a_{22} \ \dots \ a_{nn}\right]}\) denote the matrix-to-vector diagonal operator. If we also let \(\diag{\mathcal{A}}\) denote a block diagonal matrix with the set \(\mathcal{A}\) of matrices or vectors on the block diagonal, then (17) can be expressed in matrix form as:

(18)\[\begin{split}\l &\le \frac{1}{2}\textrm{diag}\left(\trans{\Xblk} \Qblk \Xblk\right) + \Bb \x \le \u \\ \l &\le \frac{1}{2}\textrm{diag}\left(\trans{\diag{\{\x\}_{\times n_q}}} \diag{\{\QQ_i\}_{i=1}^{n_q}} \diag{\{\x\}_{\times n_q}}\right) + \Bb \x \le \u,\end{split}\]

where

(19)\[\begin{split}\Xblk = \diag{\{\x\}_{\times n_q}} \\ \Qblk = \diag{\{\QQ_i\}_{i=1}^{n_q}}.\end{split}\]

By convention, qcn is the variable name used for mp.sm_quad_constraint objects.

mp.sm_quad_constraint Properties:

cache - struct for caching aggregated parameters for the set

mp.sm_quad_constraint Methods:

sm_quad_constraint() - constructor
add() - add a subset of quadratic constraints, with parameters \(\QQ_1, \dots, \QQ_{n_q}, \Bb, \l, \u\)
params() - build and return quadratic constraint parameters \(\QQ_1, \dots, \QQ_{n_q}, \Bb, \l, \u\)
set_params() - modify quadratic constraint parameter data
eval() - evaluate individual or full set of quadratic constraints
display_soln() - display solution values for quadratic constraints
get_soln() - fetch solution values for specific named/indexed subsets
parse_soln() - parse solution for quadratic constraints
blkprod2vertcat() - compute all products of two block diagonal matrices

Constructor Summary

sm_quad_constraint(varargin)

Constructor.

qcn = mp.sm_quad_constraint(label)

Property Summary

cache = []: struct for caching aggregated parameters for quadratic constraints

Method Summary

add(var, name, idx, varargin)

Add a subset of quadratic constraints, with parameters \(\QQ_1, \dots, \QQ_{n_q}, \Bb, \l, \u\).

qcn.add(var, name, Q, B, l, u);
qcn.add(var, name, Q, B, l, u, vs);

qcn.add(var, name, idx_list, Q, B, l, u);
qcn.add(var, name, idx_list, Q, B, l, u, vs);

Add a named, and possibly indexed, subset of \(n_q\) quadratic constraints to the set, of the form in (17) and (18), where \(\x\) is a vector made up of the variables specified in the optional vs (in the order given). This allows the set of \(\QQ_i\) matrices and \(\Bb\) matrix to be defined in terms of only the relevant variables without the need to manually create a lot of properly located zero rows and/or columns.

Inputs:

var (mp.sm_variable) – corresponding mp.sm_variable object
name (char array) – name of subset/block of constraints to add()
idx_list (cell array) – (optional) index list for subset/block of constraints to add() (for an indexed subset)
Q (cell vector) – \(n_q \times 1\) cell array of sparse quadratic coefficient matrices \(\QQ_i\), where the size of each element must be consistent with \(\x\).
B (double) – possibly sparse matrix \(\Bb\) of linear coefficients, with row vector \(\b_i\) corresponding to quadratic constraint \(i\).
l (double) – (optional, default = -Inf ) constraint left-hand side vector \(\l\), or scalar which is expanded to a vector
u (double) – (optional, default = Inf ) constraint right-hand side vector \(\u\), or scalar which is expanded to a vector
vs (cell or struct array) – (optional, default {} ) variable set defining vector \(\x\) for this constraint 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:

qcn.add(var, 'my_quad', Q1, B1, l1, u1, {'my_var1', 'my_var2'});

qcn.init_indexed_name('my_set', {3, 2})
for i = 1:3
    for j = 1:2
        qcn.add(var, 'my_set', {i, j}, Q{i,j}, B{i,j}, l{i,j}, ...);
    end
end

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

params(var, name, idx, isblk)

Build and return quadratic constraint parameters \(\Qblk, \Bb, \l, \u\).

[Qblk, B, l, u] = qcn.params(var)
[Qblk, B, l, u] = qcn.params(var, name)
[Qblk, B, l, u] = qcn.params(var, name, idx_list)
[Qblk, B, l, u, vs] = qcn.params(...)
[Qblk, B, l, u, vs, i1, iN] = qcn.params(name ...)

With no input parameters, it assembles and returns the parameters for the aggregate quadratic constraints from all quadratic constraint sets added using add(). The values of these parameters are cached for subsequent calls. The parameters are \(\Qblk\), \(\Bb\), \(\l\), and \(\u\), where the quadratic constraint is of the form in (18).

If isblk is 1, Qblk is the block diagonal matrix \(\Qblk\) of (19). If isblk is 0, Qblk is a vertical cell array containing the individual quadratic coefficient matrices \(\QQ_i\) for all quadratic constraint sets. If a name or name and index list are provided, then it simply returns the parameters for the corresponding named set, as a block diagonal matrix or cell array, depending on the value of isblk. It can also optionally return the variable sets used by this constraint set (the size of \(\QQ_i\) and \(\Bb\) will be consistent with this variable set), and the starting and ending row indices of the subset within the full aggregate constraint 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
isblk – (optional default = 0) determines form of Qblk output, 1 for block diagonal matrix \(\Qblk\), 0 for individual \(\QQ_i\) matrices stacked vertically in separate elements of a cell array

Outputs:

Qblk (double or cell array) – constraint coefficient matrix \(\Qblk\) or cell array of individual \(\QQ_i\) depending on the value of input isblk
B (double) – linear term contraint coefficient matrix \(\Bb\)
l (double) – constraint left-hand side vector \(\l\)
u (double) – constraint right-hand side vector \(\u\)
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\)
i1 (integer) – index of 1st row of specified subset in full set
iN (integer) – index of last row of specified subset in full set

Examples:

[Qblk, B, l, u] = qcn.params(var)
[Qblk, B, l, u] = qcn.params(var, 'my_set')

See also add(), params().

display_soln(var, soln, varargin)

Display solution values for quadratic constraints.

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

Displays the solution values for all quadratic constraints (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
  
  mu_lq - quadratic constraint lower bounds
  
  mu_uq - quadratic 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 = qcn.get_soln(var, soln, name)
vals = qcn.get_soln(var, soln, name, idx_list)
vals = qcn.get_soln(var, soln, tags, name)
vals = qcn.get_soln(var, soln, tags, name, idx_list)

Returns named/indexed quadratic constraint 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
  
  mu_lq - quadratic constraint lower bounds
  
  mu_uq - quadratic 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 {'g', 'mu_l', 'mu_u'} with valid values:
- 'g' - 2 element cell array with constraint values \(\g(\x) - \u\) and \(\l - \g(\x)\), respectively, where \(\g(\x)\) is the quadratic form shown in (23) for the quadratic constraints specified
- 'g_u' or 'f' - constraint values \(\g(\x) - \u\)
- 'l_g' - constraint values \(\l - \g(\x)\)
- 'mu_l' - shadow price on \(\l - \g(\x)\)
- 'mu_u' - shadow price on \(\g(\x) - \u\)
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:

[g, mu_l, mu_u] = qcn.get_soln(var, soln, 'flow');
mu_lq_Pmis_5_3 = qcn.get_soln(var, soln, 'mu_l', 'Pmis', {5,3});

For a complete set of solution values, using the parse_soln() method may be more efficient.