mp.sm_lin_constraint

class mp.sm_lin_constraint

Bases: mp.set_manager_opt_model

mp.sm_lin_constraint - MP Set Manager class for linear constraints.

lin = mp.sm_lin_constraint()
lin = mp.sm_lin_constraint(label)

MP Set Manager class for linear constraints of the form

(12)\[\l \le \AA \x \le \u\]

Manages constraint parameters \(\AA, \l, \u\), along with indexing.

By convention, lin is the variable name used for mp.sm_lin_constraint objects.

mp.sm_lin_constraint Properties:

cache - struct for caching aggregated parameters for the set

mp.sm_lin_constraint Methods:

sm_lin_constraint() - constructor
add() - add a subset of linear constraints, with parameters \(\AA, \l, \u\)
params() - build and return linear constraint parameters \(\AA, \l, \u\)
set_params() - modify linear constraint parameter data
eval() - evaluate individual or full set of linear constraints
display_soln() - display solution values for linear constraints
get_soln() - fetch solution values for specific named/indexed subsets
parse_soln() - parse solution for linear constraints

Constructor Summary

sm_lin_constraint(varargin)

Constructor.

lin = mp.sm_lin_constraint(label)

Property Summary

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

Method Summary

add(var, name, idx, varargin)

Add a subset of linear constraints, with parameters \(\AA, \l, \u\).

lin.add(var, name, A, l, u);
lin.add(var, name, A, l, u, vs);
lin.add(var, name, A, l, u, vs, tr);

lin.add(var, name, idx_list, A, l, u);
lin.add(var, name, idx_list, A, l, u, vs);
lin.add(var, name, idx_list, A, l, u, vs, tr);

Add a named, and possibly indexed, subset of linear constraints to the set, of the form \(\l \le \AA \x \le \u\), where \(\x\) is a vector made up of the variables specified in the optional vs (in the order given). This allows the \(\AA\) matrix to be defined in terms of only the relevant variables without the need to manually create a lot of properly located zero columns.

There is also the option to take and store the transpose of the constraint matrix \(\AA\). For constraints with many more columns than rows, this can sometimes save significant memory.

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)
A (double) – constraint coefficient matrix \(\AA\)
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
tr (logical) – (optional, default false ) if true, it means that \(\trans{\AA}\) is supplied/stored rather than \(\AA\)

Examples:

lin.add(var, 'vl', Avl, lvl, uvl, {'Pg', 'Qg'});

lin.init_indexed_name('R', {2, 3});
for i = 1:2
    for j = 1:3
        lin.add(var, 'R', {i, j}, A{i,j}, ...);
    end
end

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

params(var, name, idx)

Build and return linear constraint parameters \(\AA, \l, \u\).

[A, l, u] = lin.params(var)
[A, l, u] = lin.params(var, name)
[A, l, u] = lin.params(var, name, idx_list)
[A, l, u, vs] = lin.params(...)
[A, l, u, vs, i1, in] = lin.params(...)
[A, l, u, vs, i1, in, tr] = lin.params(name ...)

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

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 constraint set (the size of \(\AA\) will be consistent with this variable set), the starting and ending row indices of the subset within the full aggregate constraint matrix, and flag indicating whether the transpose of the constraint matrix was supplied/stored for this subset.

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:

A (double) – constraint coefficient matrix \(\AA\)
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
tr (logical) – if true, it means that \(\trans{\AA}\) was supplied/stored rather than \(\AA\)

Examples:

[A, l, u] = lin.params(var);
[A, l, u, vs, i1, iN] = lin.params(var, 'Pmis');

See also add(), params().

display_soln(var, soln, varargin)

Display solution values for linear constraints.

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

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

Returns named/indexed linear 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
  
  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 \(\AA \x - \u\) and \(\l - \AA \x\), respectively
- 'Ax_u' or 'f' - constraint values \(\AA \x - \u\)
- 'l_Ax' - constraint values \(\l - \AA \x\)
- 'mu_l' - shadow price on \(\l - \AA \x\)
- 'mu_u' - shadow price on \(\AA \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] = lin.get_soln(var, soln, 'flow');
mu_l_Pmis_5_3 = lin.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.