mp.sm_nln_constraint

class mp.sm_nln_constraint

Bases: mp.set_manager_opt_model

mp.sm_nln_constraint - MP Set Manager class for nonlinear constraints.

nln = mp.sm_nln_constraint()
nln = mp.sm_nln_constraint(label)

MP Set Manager class for nonlinear constraints

(13)\[\g(\x) = 0\]

or

(14)\[\g(\x) \le 0\]

Manages nonlinear constraint sets and their indexing.

By convention, nln (general), nle (equality), or nli (inequality) are the variable names used for mp.sm_nln_constraint objects.

mp.sm_nln_constraint Methods:

sm_nln_constraint() - constructor
add() - add a subset of nonlinear constraints
params() - return nonlinear constraint parameters
set_params() - modify nonlinear constraint parameter data
eval() - evaluate individual or full set of nonlinear constraints
eval_hess() - evaluate “Hessian” for full set of nonlinear constraints
display_soln() - display solution values for nonlinear constraints
get_soln() - fetch solution values for specific named/indexed subsets
parse_soln() - parse solution for nonlinear constraints

Constructor Summary

sm_nln_constraint(varargin)

Constructor.

nln = mp.sm_nln_constraint(label)

Method Summary

add(var, name, idx, varargin)

Add a subset of nonlinear constraints.

nln.add(var, name, N, fcn, hess);
nln.add(var, name, N, fcn, hess, vs);

nln.add(var, name, idx_list, N, fcn, hess);
nln.add(var, name, idx_list, N, fcn, hess, vs);

Add a named, and possibly indexed, subset of nonlinear constraints \(\g(\x) = 0\) or \(\g(\x) \le 0\) 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 constraint function to be defined in terms of only the relevant variables without the need to manually account for the locations of other variable sets.

Inputs:

var (mp.sm_variable) – corresponding mp.sm_variable object
name (char array or cell array) – name(s) 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)
N (integer) – number of constraints in the set, i.e. the dimension \(n\) of constraint function \(\g(\x)\)
fcn (function handle) – handle to function that evaluates the \(n \times 1\) constraint vector \(\g(\x)\), and optionally the corresponding \(n \times n_x\) Jacobian \(\g_\x = \der{\g}{\x}\)
hess (function handle) – handle to function that evaluates the constraint “Hessian” \(\g_{\x\x}(\lam)\) as described below
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

Constraint Function Implmentation : fcn

For a constraint function \(\g(\x)\), the fcn input should point to a function with the following interface:

g = fcn(x)
[g, dg] = fcn(x)

Input:

x (double or cell array of doubles) – variable \(\x\) corresponding to the full variable vector, or to a set of sub-vectors defined by the variable set provided in vs

Outputs:

g (double) – \(n \times 1\) constraint vector \(\g(\x)\)
dg (double) – \(n \times n_x\) constraint Jacobian \(\g_\x = \der{\g}{\x}\)

Note

The dg return value is the transpose of what is expected from an input function for nlps_master() and friends.

Hessian Function Implmentation : hess

Similarly, the hess input should point to a function that returns an \(n_x \times n_x\) matrix constraint “Hessian” matrix \(\g_{\x\x}(\lam)\) for a given set of multipliers, with the following interface:

d2g = hess(x, lam)

Inputs:

x (double or cell array of doubles) – variable \(\x\) corresponding to the full variable vector, or to a set of sub-vectors defined by the variable set provided in vs
lam (double) – \(n \times 1\) vector of multipliers \(\lam\)

Output:

d2g (double) – \(n_x \times n_x\) “Hessian” matrix \(\g_{\x\x}(\lam) = \der{}{\x}(\trans{\g_\x} \lam)\)

For both functions, the input argument x takes one of two forms. If the constraint set is added with varset input vs empty or missing, then x will be the full variable vector. Otherwise it will be a cell array of vectors corresponding to the variable sets specified in vs.

Special Case

For simple (not indexed) named sets, name can be a cell array of constraint set names, in which case N is a vector specifying the number of constraints in each corresponding set. fcn and hess are each still a single function handle, but the values computed by each correspond to the entire stacked collection of constraint sets together, as if they were a single set.

Likewise, if fcn or hess are empty, it indicates a placeholder in the indexing for a constraint set whose implementation is included in another constraint set. This functionality is only intended to be used internally to handle constraint/gradient and Hessian functions that compute the values for more than one constraint set simultaneously.

Examples:

% nonlinear equality constraint with constraint/gradient and
% Hessian evaluation functions provided
nle.add('var, Qmis', nb, 1, fcn, hess);

% nonlinear inequality constraints with indexed named set 'S(i,j)'
nli.init_indexed_name('S', {2, 3});
for i = 1:2
  for j = 1:3
    nli.add('S', {i, j}, N{i,j}, 0, ...);
  end
end

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

params(var, name, idx)

Return nonlinear constraint parameters.

N = nln.params(var, name)
N = nln.params(var, name, idx_list)
[N, fcn] = nln.params(...)
[N, fcn, hess] = nln.params(...)
[N, fcn, hess, vs] = nln.params(...)
[N, fcn, hess, vs, include] = nln.params(...)

Returns the parameters for the general nonlinear constraint subset corresponding to the name or name and index list provided. The parameters are those supplied via the add method when the subset was added.

Inputs:

var (mp.sm_variable) – corresponding mp.sm_variable object
name (char array) – name of subset
idx_list (cell array) – (optional) index list for subset

Outputs:

N (integer) – number of constraints in the set, i.e. the dimension \(n\) of constraint function \(\g(\x)\)
fcn (function handle) – handle to function that evaluates the \(n \times 1\) constraint vector \(\g(\x)\), and optionally the corresponding \(n \times n_x\) Jacobian \(\g_\x = \der{\g}{\x}\)
hess (function handle) – handle to function that evaluates the constraint “Hessian” \(\g_{\x\x}(\lam)\); see add() for details
vs (struct array) – variable set, name, idx pairs specifying the set of variables defining vector \(\x\) for this cost subset; order of vs determines order of blocks in \(\x\)
include (struct) – (optional) for constraint sets whose functions compute the constraints for additional sets, struct with fields:
- name - cell array of additional set names computed
- N - array of corresponding dimensions

See also add(), params().

display_soln(var, soln, iseq, varargin)

Display solution values for nonlinear constraints.

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

Displays the solution values for all nonlinear 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
iseq (logical) – true for equality constraints, false for inequality constraints
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, iseq, varargin)

Fetch solution values for specific named/indexed subsets.

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

Returns named/indexed nonlinear 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
iseq (logical) – true for equality constraints, false for inequality constraints
tags (char array or cell array of char arrays) – names of desired outputs, default is {'g', 'lam', 'dg'} with valid values:
- 'g' or 'h' - constraint value \(\g(\x)\)
- 'lam' or 'mu' - shadow price \(\lam\) on constraint
- 'dg' or 'dh' - constraint Jacobian \(\g_\x = \der{\g}{\x}\)
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, lam, dg] = nln.get_soln(var, soln, false, 'flow');
dg_Pmis_5_3 = nln.get_soln(var, soln, true, 'dg', 'Pmis', {5,3});

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