mp.sm_variable

class mp.sm_variable

Bases: mp.set_manager_opt_model

mp.sm_variable - MP Set Manager class for variables.

var = mp.sm_variable()
var = mp.sm_variable(label)

MP Set Manager class for variables. Manages variable initial values, lower and upper bounds, and variable type, along with indexing.

By convention, var is the variable name used for mp.sm_variable objects.

mp.sm_variable Properties:

• cache - struct for caching aggregated parameters for the set

mp.sm_variable Methods:

• sm_variable() - constructor

• add() - add a subset of variables, with initial value, bounds, and var type

• params() - return initial values, lower bounds, upper bounds, and var type

• set_params() - modify parameter data for variables

• display_soln() - display solution values for variables

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

• parse_soln() - parse solution for variables

• varsets_idx() - return vector of indices into full \(\x\) corresponding to vs

• varsets_len() - return the total number of variables specified by vs

• varsets_x() - return subset of \(\x\) specified by vs

• varsets_cell2struct() - convert vs from cell array to struct array

See also mp.set_manager, mp.set_manager_opt_model.

Constructor Summary

sm_variable(varargin)

Constructor.

var = mp.sm_variable(label)

Property Summary

cache = []

struct for caching aggregated parameters for variables

Method Summary

add(name, idx, varargin)

Add a subset of variables with initial value, bounds, type.

var.add(name, N, v0, vl, vu, vt)
var.add(name, N, v0, vl, vu)
var.add(name, N, v0, vl)
var.add(name, N, v0)
var.add(name, N)

var.add(name, idx_list, N, v0, vl, vu, vt)
var.add(name, idx_list, N, v0, vl, vu)
var.add(name, idx_list, N, v0, vl)
var.add(name, idx_list, N, v0)
var.add(name, idx_list, N)

Add a named, and possibly indexed, subset of variables to the set.

Inputs:

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

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

• N (integer) – number of variables in the subset

• v0 (double) – (optional, default = 0) scalar or \(N \times 1\) vector of variable initial values

• vl (double) – (optional, default = -Inf) scalar or \(N \times 1\) vector of variable lower bounds

• vu (double) – (optional, default = Inf) scalar or \(N \times 1\) vector of variable upper bounds

• vt (char array) – (optional, default = 'C' ) scalar or \(1 \times N\) char array of variable types, where accepted types are:

  • 'C' - continuous

  • 'I' - integer

  • 'B' - binary

Examples:

var.add('V', nb, V0, Vmin, Vmax, 'C');

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

See also params(), set_params().

params(name, idx)

Return initial values, lower bounds, upper bounds and var type.

[v0, vl, vu] = var.params()
[v0, vl, vu] = var.params(name)
[v0, vl, vu] = var.params(name, idx_list)
[v0, vl, vu, vt] = var.params(...)

Returns the initial value, lower bound, upper bound, and variable type for the full set of variables, if called without input arguments, or for a specific named or named and indexed subset. Values for the full set are cached for subsequent calls.

Inputs:

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

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

Outputs:

• v0 (double) – column vector of variable initial values

• vl (double) – column vector of variable lower bounds

• vu (double) – column vector of variable upper bounds

• vt (char array) – char array of variable types:

  • 'C' - continuous

  • 'I' - integer

  • 'B' - binary

Examples:

[x0, xmin, xmax] = var.params();
[Pg0, Pmin, Pmax] = var.params('Pg');
[zij0, zijmin, zijmax, ztype] = var.params('z', {i, j});

See also add(), set_params().

set_params(name, idx, params, vals)

set_params() - Modify parameter data for variables.

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

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

Inputs:

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

• idx_list (cell array) – (optional) index list for subset/block of variables 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, v0, vl, vu, vt.

Note

Changing the dimension of a variable subset is not allowed.

Examples:

var.set_params('Pg', 'v0', Pg0);
var.set_params('y', {2,3}, {'vl', 'vu'}, {yl, yu});
var.set_params('Va', 'all', {N, va0, val, vau, vat});

See also add(), params().

display_soln(soln, varargin)

Display solution values for variables.

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

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

Inputs:

• 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(soln, varargin)

Fetch solution values for specific named/indexed subsets.

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

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

Inputs:

• 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 {'x', 'mu_l', 'mu_u'}, with valid values:

  • 'x' - value of solution variable

  • 'mu_l' - shadow price on variable lower bound

  • 'mu_u' - shadow price on variable upper bound

• 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:

[P, muPmin, muPmax] = var.get_soln(soln, 'P');
muRmin_2_3 = var.get_soln(soln, 'mu_l', 'R', {2,3});

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

See also parse_soln().

parse_soln(soln, stash)

Parse solution for variables.

ps = var.parse_soln(soln)
ps = var.parse_soln(soln, stash)

Parse a full solution struct into parts corresponding to individual variable subsets.

Input:

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

  • 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

• stash (logical) – if true, store return value in soln property

Output:

ps (struct) – parsed solution, struct where each field listed below is a struct whos names are the names of the relevant variable subsets and values are scalars for named sets, arrays for named/indexed sets:

• val - variable values

• mu_l - variable lower bound shadow prices

• mu_u - variable upper bound shadow prices

varsets_idx(vs)

varsets_idx() - Return vector of indices into full \(\x\) corresponding to vs.

k = var.varsets_idx(vs)

Returns a vector of indices into the full variable \(\x\) corresponding to the variable sub-vector specified by vs.

Input:

vs (struct array) – variable set, struct array of name, idx pairs of indexed named subsets of variables

Output:

k (integer) – vector of indices into full variable \(\x\) for sub-vector specified by vs.

See also varsets_x().

varsets_len(vs)

varsets_len() - Return the total number of variables specified by vs.

nv = var.varsets_len(vs)

Return the total number of elements in the variable sub-vector specified by vs.

Input:

vs (struct array) – variable set, struct array of name, idx pairs of indexed named subsets of variables

Output:

nv (integer) – total number of elements in the variable sub-vector specified by vs.

See also varsets_cell2struct().

varsets_x(x, vs, return_vector)

varsets_x() - Return subset of \(\x\) specified by vs.

xx = obj.varsets_x(x, vs)
xx = obj.varsets_x(x, vs, return_vector)

Returns a cell array of sub-vectors of \(\x\) specified by vs, or a stacked variable vector.

Input:

• x (double) – full variable vector \(\x\)

• vs (struct array) – variable set, struct array of name, idx pairs of indexed named subsets of variables

• return_vector – if present and true, returns a stacked vector instead of a cell array

Output:

xx (cell array or double) – cell array of sub-vectors of \(\x\) specified by vs or vector of stacked sub-vectors, depending on presence and value of return_vector; returns full stacked variable vector if vs is missing or empty.

See also varsets_len().

static varsets_cell2struct(vs)

varsets_cell2struct() - Convert vs from cell array to struct array.

vs = mp.sm_variable.varsets_cell2struct(vs)

Converts vs from a cell array to a struct array, if necessary.

Input:

vs (cell or struct array) – variable set, cell array of names of variable subsets, or a struct array of name, idx pairs of indexed named subsets of variables

Output:

vs (struct array) – variable set, struct array of name, idx pairs of indexed named subsets of variables

See also varsets_len().