csnlp.Nlp#

class csnlp.Nlp(sym_type='SX', remove_redundant_x_bounds=True, cache=None, name=None, debug=False)[source]#

Bases: HasObjective[SymType]

The generic NLP class is a controller that solves a (possibly, nonlinear) optimization problem to yield a (possibly, sub-) optimal solution. This is a generic implementation in the sense that it does not solve a particular problem, but only offers the generic methods to build one (e.g., variables, constraints, objective, solver).

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.
cachejoblib.Memory, optional: Optional cache to avoid computing the same exact NLP more than once. By default, no caching occurs.
namestr, optional: Name of the NLP scheme. If None, it is automatically assigned.
debugbool, optional: If True, the NLP logs in the debug property information regarding the creation of parameters, variables and constraints. By default, False.

Raises:

AttributeError: Raises if the specified CasADi’s symbolic type is neither "SX" nor "MX".

Notes

Constraints are internally handled in their canonical form, i.e., \(g(x,p) = 0\) and \(h(x,p) \leq 0\). The objective \(f(x,p)\) is always a scalar function to be minimized.

Methods

`constraint`(name, lhs, op, rhs[, soft, simplify])	Adds a constraint to the NLP problem, e.g., \(lhs \le rhs\).
`init_solver`([opts, solver, type])	Initializes the solver for this NLP with the given options.
`is_wrapped`(_, *__)	Gets whether the NLP instance is wrapped or not by the given wrapper type.
`minimize`(objective)	Sets the objective function to be minimized.
`parameter`(name[, shape])	Adds a parameter to the NLP scheme.
`refresh_solver`()	Refresh and resets the internal solver function (with the same options, if previously set).
`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
`solve`([pars, vals0])	Solves the NLP optimization problem.
`to_function`(name, ins, outs[, name_in, ...])	Converts the optimization problem to an `SX` or `MX` symbolic `casadi.Function`.
`variable`(name[, shape, discrete, lb, ub])	Adds a variable to the NLP problem.

Attributes

`constraints`	Gets the constraints of the NLP scheme.
`debug`	Gets debug information on the NLP scheme.
`discrete`	Gets the boolean array indicating which variables are discrete.
`dual_variables`	Gets the dual variables of the NLP scheme.
`f`	Gets the objective of the NLP scheme, which is `None` if not set previously set via the `minimize` method.
`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\).
`is_multi`	Flag to indicate that this is not a multistart NLP.
`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`)
`solver`	Gets the NLP optimization solver.
`solver_opts`	Gets the NLP optimization solver options.
`sym_type`	Gets the CasADi symbolic type used in this NLP scheme.
`ubx`	Gets the upper bound constraints of primary variables of the NLP scheme in masked vector form.
`unwrapped`	Returns the original NLP of the wrapper.
`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 debug: NlpDebug | None#: Gets debug information on 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 f: SymType | None#: Gets the objective of the NLP scheme, which is None if not set previously set via the minimize method.

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\).

init_solver(opts=None, solver='ipopt', type=None)#

Initializes the solver for this NLP with the given options.

Parameters:

optsdict[str, Any], optional: Options to be passed to the CasADi interface to the solver. Must not contain the "discrete" key, which is automatically set based on the variables’ domains. By default, None.
solverstr, optional: Type of solver to instantiate. For example, "ipopt" and "sqpmethod" trigger the instantiation of an NLP problem, while, e.g., "qrqp", "osqp", and "qpoases" of a conic one. However, the solver type can be overruled with the type argument. By default, "ipopt" is selected.
type“nlp”, “conic”, optional: Type of problem to instantiate. If "nlp", then the problem is forced to be instantiated with casadi.nlpsol. If "conic", then casadi.qpsol is forced instead. If None, then the problem type is selected automatically.

Raises:

ValueError: Raises if the given problem type is not recognized, or if the opts dict contains the
RuntimeError: Raises if the type of the problem cannot be inferred automatically (when the solver supports both conic and NLPs), if the specified solver plugin cannot be found, and if the objective has not yet been specified with minimize.

Return type:

None

is_multi: ClassVar[bool] = False#: Flag to indicate that this is not a multistart NLP.

is_wrapped(*_, **__)[source]#

Gets whether the NLP instance is wrapped or not by the given wrapper type.

Return type:: bool

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.

minimize(objective)#

Sets the objective function to be minimized.

Parameters:

objectivecasadi SX or MX: A Symbolic variable dependent only on the NLP variables and parameters that needs to be minimized.

Raises:

ValueError: Raises if the objective is not scalar.

Return type:

None

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))[source]#

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).

refresh_solver()#

Refresh and resets the internal solver function (with the same options, if previously set).

Return type:: None

remove_constraints(name, idx=None)#

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)#

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

solve(pars=None, vals0=None)#

Solves the NLP optimization problem.

Parameters:

parsdict[str, array_like], optional: Dictionary or structure containing, for each parameter in the NLP scheme, the corresponding numerical value. Can be None if no parameters are present.
vals0dict[str, array_like], optional: Dictionary or structure containing, for each variable in the NLP scheme, the corresponding initial guess. By default, initial guesses are not passed to the solver.

Returns:

solSolution: A solution object containing all the information.

Raises:

RuntimeError: Raises if the solver is un-initialized (see init_solver); or if not all the parameters are not provided with a numerical value.

Return type:

Solution[TypeVar(SymType, SX, MX)]

property solver: Function | None#: Gets the NLP optimization solver. Can be None, if the solver is not set with method init_solver.

property solver_opts: dict[str, Any]#: Gets the NLP optimization solver options. The dict is empty, if the solver options are not set with method init_solver.

property sym_type: type[SymType]#: Gets the CasADi symbolic type used in this NLP scheme.

to_function(name, ins, outs, name_in=None, name_out=None, opts=None, mx_prewrap=False)[source]#

Converts the optimization problem to an SX or MX symbolic casadi.Function. If the NLP is modelled in SX, the function can be pre-wrapped in MX.

Parameters:

namestr: Name of the function.
inssequence of casadi.SX or MX: Input variables of the function. These must be expressions providing the parameters of the NLP and the initial conditions of the primal variables x.
outssequence of casadi.SX or MX: Output variables of the function. These must be expressions depending on the primal variable x, parameters p, and dual variables lam_g, lam_h, lam_lbx, lam_ubx of the NLP.
name_insequence of str, optional: Name of the inputs, by default None.
name_outsequence of str, optional: Name of the outpus, by default None.
optsdict[Any, Any], optional: Options to be passed to casadi.Function, by default None.
mx_prewrapbool, optional: If True, wraps the CasADi interface in an MX wrapper prior to turning it into the function. This is useful when the NLP is defined in SX but the interface is only supported in MX. By default, False.

Returns:

casadi.Function: The NLP solver as an instance of casadi.Function.

Raises:

RuntimeError: Raises if the solver is uninitialized, or if the input or output expressions have free variables that are not provided or cannot be computed by the solver.

Return type:

Function

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

property unwrapped: Nlp[SymType]#: Returns the original NLP of the wrapper.

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: