csnlp.nlps.HasConstraints#

class csnlp.nlps.HasConstraints(sym_type='SX', remove_redundant_x_bounds=True)[source]#

Bases: HasVariables[SymType]

Class for the creation and storage symbolic constraints for an NLP problem. It builds on top of HasVariables, which handles both parameters and variables.

Constraints are stored and managed in the canonical way. Equality constraints are in the form \(g(x,p) = 0\) or \(G(x,p) = 0\), whereas inequality constraints are in the form \(h(x,p) \le 0\) or \(H(x,p) \le 0\). Separated from the latter are the lower and upper bounds of the primary variables, which are also inequalities, i.e., \(lbx - x \le 0\) and \(x - ubx \le 0\), but are passed differently to the CasADi solver interface. Moreover, the class is equipped with a mechanism to automatically remove lower and upper bounds that are redundant, i.e., when the lower bound is \(-\infty\) and the upper bound is \(+\infty\), which often create numerical issues if passed to the solver as is.

Parameters:

sym_type{“SX”, “MX”}, optional: The CasADi symbolic variable type to use in the NLP, by default "SX".
remove_redundant_x_boundsbool, optional: If True, then redundant entries in lbx and ubx are removed when properties h_lbx and h_ubx are called. See these two properties for more details. By default, True.

Methods

`constraint`(name, lhs, op, rhs[, soft, simplify])	Adds a constraint to the NLP problem, e.g., \(lhs \le rhs\).
`parameter`(name[, shape])	Adds a parameter to the NLP scheme.
`remove_constraints`(name[, idx])	Removes one or more (equality or inequality) constraints from the problem.
`remove_variable_bounds`(name, direction[, idx])	Removes one or more lower and/or upper bounds from the given variable
`variable`(name[, shape, discrete, lb, ub])	Adds a variable to the NLP problem.

Attributes

`constraints`	Gets the constraints of the NLP scheme.
`discrete`	Gets the boolean array indicating which variables are discrete.
`dual_variables`	Gets the dual variables of the NLP scheme.
`g`	Gets the equality constraint expressions of the NLP scheme in vector form.
`h`	Gets the inequality constraint expressions of the NLP scheme in vector form.
`h_lbx`	Gets the inequalities cor to `lbx`, i.e., \(lbx - x\).
`h_ubx`	Gets the inequalities due to `ubx`, i.e., \(x - ubx\).
`lam`	Gets the dual variables of the NLP scheme in vector form.
`lam_g`	Gets the dual variables of the equality constraints of the NLP scheme in vector form.
`lam_h`	Gets the dual variables of the inequality constraints of the NLP scheme in vector form.
`lam_lbx`	Gets the dual variables of the primary variables lower bound constraints of the NLP scheme in vector form.
`lam_ubx`	Gets the dual variables of the primary variables upper bound constraints of the NLP scheme in vector form.
`lbx`	Gets the lower bound constraints of primary variables of the NLP scheme in masked vector form.
`ng`	Number of equality constraints in the NLP scheme.
`nh`	Number of inequality constraints in the NLP scheme.
`nonmasked_lbx_idx`	Gets the indices of non-masked entries in `lbx` (or the full slice).
`nonmasked_ubx_idx`	Gets the indices of non-masked entries in `ubx` (or the full slice).
`np`	Number of parameters in the NLP scheme.
`nx`	Number of variables in the NLP scheme.
`p`	Gets the parameters of the NLP scheme.
`parameters`	Gets the parameters of the NLP scheme.
`primal_dual`	Gets the collection of primal-dual variables (usually, denoted as `y`)
`ubx`	Gets the upper bound constraints of primary variables of the NLP scheme in masked vector form.
`variables`	Gets the primal variables of the NLP scheme.
`x`	Gets the primary variables of the NLP scheme in vector form.

constraint(name, lhs, op, rhs, soft=False, simplify=True)[source]#

Adds a constraint to the NLP problem, e.g., \(lhs \le rhs\).

Parameters:

namestr: Name of the new constraint. Must not be already in use.
lhscasadi.SX, MX, DM or numerical: Symbolic expression of the left-hand term of the constraint.
op: {“==”, “>=”, “<=”}: Operator relating the two terms.
rhscasadi.SX, MX, DM or numerical: Symbolic expression of the right-hand term of the constraint.
softbool, optional: If True, then a slack variable with appropriate size is added to the NLP to make the inequality constraint soft, and returned. This slack is automatically lower-bounded by 0, but remember to manually penalize its magnitude in the objective. Slacks are not supported for equality constraints. Defaults to False.
simplifybool, optional: Optionally simplies the constraint expression, but can be disabled.

Returns:

exprcasadi.SX or MX: The constraint expression in canonical form, i.e., \(g(x,p) = 0\) or \(h(x,p) \le 0\).
lamcasadi.SX or MX: The symbol corresponding to the constraint’s multipliers.
slackcasadi.SX or MX, optional: The slack variable in case of soft=True; otherwise, only a 2-tuple is returned.

Raises:

ValueError: Raises if there is already another constraint with the same name; or if the operator is not recognized.
NotImplementedError: Raises if a soft equality constraint is requested.
TypeError: Raises if the constraint is not symbolic.

Return type:

tuple[TypeVar(SymType, SX, MX), ...]

property constraints: dict[str, SymType]#: Gets the constraints of the NLP scheme.

property discrete: ndarray[tuple[Any, ...], dtype[bool]]#: Gets the boolean array indicating which variables are discrete.

property dual_variables: dict[str, SymType]#: Gets the dual variables of the NLP scheme.

property g: SymType#: Gets the equality constraint expressions of the NLP scheme in vector form.

property h: SymType#: Gets the inequality constraint expressions of the NLP scheme in vector form.

property h_lbx: SymType#: Gets the inequalities cor to lbx, i.e., \(lbx - x\).

property h_ubx: SymType#: Gets the inequalities due to ubx, i.e., \(x - ubx\).

property lam: SymType#

Gets the dual variables of the NLP scheme in vector form.

Notes

The dual variables are vertically concatenated in the following order: lam_g, lam_h, lam_lbx, lam_ubx.

property lam_g: SymType#: Gets the dual variables of the equality constraints of the NLP scheme in vector form.

property lam_h: SymType#: Gets the dual variables of the inequality constraints of the NLP scheme in vector form.

property lam_lbx: SymType#: Gets the dual variables of the primary variables lower bound constraints of the NLP scheme in vector form.

property lam_ubx: SymType#: Gets the dual variables of the primary variables upper bound constraints of the NLP scheme in vector form.

property lbx: MaskedArray#: Gets the lower bound constraints of primary variables of the NLP scheme in masked vector form.

property ng: int#: Number of equality constraints in the NLP scheme.

property nh: int#: Number of inequality constraints in the NLP scheme.

property nonmasked_lbx_idx: slice | ndarray[tuple[Any, ...], dtype[int64]]#: Gets the indices of non-masked entries in lbx (or the full slice).

property nonmasked_ubx_idx: slice | ndarray[tuple[Any, ...], dtype[int64]]#: Gets the indices of non-masked entries in ubx (or the full slice).

property np: int#: Number of parameters in the NLP scheme.

property nx: int#: Number of variables in the NLP scheme.

property p: SymType#: Gets the parameters of the NLP scheme.

parameter(name, shape=(1, 1))#

Adds a parameter to the NLP scheme.

Parameters:

namestr: Name of the new parameter. Must not be already in use.
shapetuple of 2 ints, optional: Shape of the new parameter. By default a scalar, i.e., (1, 1).

Returns:

casadi.SX or MX: The symbol for the new parameter.

Raises:

ValueError: Raises if there is already another parameter with the same name name.

Return type:

TypeVar(SymType, SX, MX)

property parameters: dict[str, SymType]#: Gets the parameters of the NLP scheme.

property primal_dual: SymType#

Gets the collection of primal-dual variables (usually, denoted as y)

\[\begin{split}y = \begin{bmatrix} x \\ \lambda \end{bmatrix},\end{split}\]

where \(x\) are the primal variables, and \(\lambda\) the dual variables (see x and lam, respectively).

remove_constraints(name, idx=None)[source]#

Removes one or more (equality or inequality) constraints from the problem.

Parameters:

namestr: Name of the constraint to be removed. The name will be used to identify if the constraint is an inequality or an equality constraint.
idxtuple of 2 ints or a list of, optional: A 2D index, or a list of 2D indices, of the constraint entries that must be removed. If not provided, then the constraint is removed entirely.

Return type:

None

Notes

This is a somewhat costly operation, so it is preferable to avoid creating in the first place constraints that will need to be eliminated. Moreover, this operation may compromise the results already obtained in, e.g., sensitivity analysis, because it changes the underlying NLP problem and there is no way to invalidate any user-arbitrary result obtained previously.

remove_variable_bounds(name, direction, idx=None)[source]#

Removes one or more lower and/or upper bounds from the given variable

Parameters:

namestr: Name of the variable whose bounds must be modified
direction{“lb”, “ub”, “both”}: Which bound to modify.
idxtuple[int, int] or a list of, optional: A 2D index, or a list of 2D indices, of the variable entries whose corresponding lower/upper bounds must be removed, i.e., set to -/+ inf. If not provided, then all the bounds for that variable are removed.

Return type:

None

Notes

property ubx: MaskedArray#: Gets the upper bound constraints of primary variables of the NLP scheme in masked vector form.

variable(name, shape=(1, 1), discrete=False, lb=-inf, ub=inf)[source]#

Adds a variable to the NLP problem.

Parameters:

namestr: Name of the new variable. Must not be already in use.
shapetuple of 2 ints, optional: Shape of the new variable. By default, a scalar.
discretebool, optional: Flag indicating if the variable is discrete. Defaults to False.
lb, ub: array_like, optional: Lower and upper bounds of the new variable. By default, unbounded. If provided, their dimension must be broadcastable.

Returns:

varcasadi.SX or MX: The symbol of the new variable.
lam_lbcasadi.SX or MX: The symbol corresponding to the new variable lower bound constraint’s multipliers. The shape of the multiplier is equal to the number of relevant lower bounds (i.e., \(\neq \pm \infty\)), so it may differ from the shape of the variable itself. This behaviour can be disabled by setting remove_redundant_x_bounds=False.
lam_ubcasadi.SX or MX: Same as above, for upper bound.

Raises:

ValueError: Raises if there is already another variable with the same name; or if any element of the lower bound is larger than the corresponding lower bound element.

Return type: