csnlp.wrappers.NlpSensitivity#

class csnlp.wrappers.NlpSensitivity(nlp, target_parameters=None, include_barrier_term=True)[source]#

Bases: Wrapper[SymType]

Wraps an instance of csnlp.Nlp to allow to perform symbolical and numerical sensitivity analysis and compute its derivates w.r.t. to different quantities, including primal variables and parameters. See [4] for nonlinear programming sensitivity analysis. The computations are tailored to the IPOPT solver, so no guarantees are provided for other solvers. This is due to the fact that IPOPT, as an interior-point solver, guarantees that the KKT conditions at the solution are satisfied. This may not the case for others.

Parameters:

nlpNlp: The NLP problem to be wrapped.
target_parameterscasadi.SX or MX, optional: If provided, computes the sensitibity only w.r.t. these parameters. Of course, these parameters must be a subset of all of the NLP’s parameters. If None, then the derivatives and sensitivity are computed w.r.t. all parameters. If new parameters are added after wrapping the nlp in this, be sure to call set_target_parameters` again.
include_barrier_termbool, optional: If True, includes in the KKT matrix a new symbolic variable that represents the barrier function of the interior-point solver. Otherwise, no additional variable is added. See property kkt for more details. By default, True.

Methods

`constraint`(name, lhs, op, rhs[, soft, simplify])	See `csnlp.Nlp.constraint`.
`hessian`(which)	Computes a hessian of the NLP problem's Lagrangian w.r.t.
`hojacobian`(which)	Computes a higher-order jacobian of NLP problem's KKT conditions w.r.t.
`is_wrapped`(wrapper_type)	Gets whether the NLP instance is wrapped or not by the given wrapper type.
`jacobian`(which)	Computes a jacobian of one of the NLP problem's quantity w.r.t.
`minimize`(objective)	See `csnlp.Nlp.minimize`.
`parameter`(name[, shape])	See `csnlp.Nlp.parameter`.
`parametric_sensitivity`([expr, solution, ...])	Performs the (symbolic or numerical) sensitivity of the NLP w.r.t.
`set_target_parameters`(parameters)	Sets the target parameters of the sensitivity wrapper.
`variable`(name[, shape, discrete, lb, ub])	See `csnlp.Nlp.variable`.

Attributes

`kkt`	Gets the KKT conditions of the NLP problem in vector form, i.e.,
`lagrangian`	Gets the Lagrangian of the NLP problem (usually denoted as `L`).
`licq`	Gets the symbolic matrix for the LICQ, defined as
`target_parameters`	Gets the parameters of the NLP that are the target of the sensitivity wrapper, i.e., derivatives and sensitivities are limited to these parameters.
`unwrapped`	'Returns the original NLP of the wrapper.

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

See csnlp.Nlp.constraint.

Return type:: tuple[TypeVar(SymType, SX, MX), ...]

hessian(which)[source]#

Computes a hessian of the NLP problem’s Lagrangian w.r.t. the primal variables, the parameters, or both.

Parameters:

which{“L-pp”, “L-xx”, “L-px”}

Indicates which hessian to compute. The possible values are:

"L-pp": hessian of the lagrangian w.r.t. parameters (twice)
"L-xx": hessian of the lagrangian w.r.t. primal variables (twice)
"L-px": hessian of the lagrangian w.r.t. parameters and then primal variables

Returns:

SymType: The requested hessian, in the form of a symbolic variable.

Raises:

ValueError: Raises if which is not one of the accepted values.

Return type:

TypeVar(SymType, SX, MX)

hojacobian(which)[source]#

Computes a higher-order jacobian of NLP problem’s KKT conditions w.r.t. the primal-dual variables, the parameters, or both. See csnlp.core.derivatives.hojacobian for more information on higher-order jacobians.

Parameters:

which{“K-pp”, “K-yp”, “K-yy”, “K-py”}

Indicates which hessian to compute. The possible values are:

"K-pp": higher-order jacobian of the KKT conditions w.r.t. parameters (twice)
"K-yp": higher-order jacobian of the KKT conditions w.r.t. primal-dual variables and then parameters
"K-yy": higher-order jacobian of the KKT conditions w.r.t. primal-dual variables (twice)
"K-py": higher-order jacobian of the KKT conditions w.r.t. parameters and then primal-dual variables

Returns:

SymType: The requested higher-order jacobian, in the form of a symbolic variable.

Raises:

ValueError: Raises if which is not one of the accepted values.

Return type:

ndarray

is_wrapped(wrapper_type)#

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

Parameters:

wrapper_typetype of Wrapper: Type of wrapper to check if the NLP is wrapped with.

Returns:

bool: True if wrapped by an instance of wrapper_type; False, otherwise.

Return type:

bool

jacobian(which)[source]#

Computes a jacobian of one of the NLP problem’s quantity w.r.t. another one.

Parameters:

which{“L-x”, “L-p”, “g-x”, “h-x”, “K-p”, “K-y”}

Indicates which jacobian to compute. The possible values are:

"L-x": jacobian of the lagrangian w.r.t. primal variables
"L-p": jacobian of the lagrangian w.r.t. parameters
"g-x": jacobian of the equality constraints w.r.t. primal variables
"h-x": jacobian of the inequality constraints w.r.t. primal variables
"K-p": jacobian of the kkt conditions w.r.t. parameters
"K-y": jacobian of the kkt conditions w.r.t. primal-dual variables.

Returns:

SymType: The requested jacobian, in the form of a symbolic variable.

Raises:

ValueError: Raises if which is not one of the accepted values.

Return type:

TypeVar(SymType, SX, MX)

property kkt: tuple[SymType, SymType | None]#

Gets the KKT conditions of the NLP problem in vector form, i.e.,

\[\begin{split}K = \begin{bmatrix} \frac{\partial L}{\partial x} \\ G \\ \text{diag}(\lambda_h) \cdot H \\ \end{bmatrix}\end{split}\]

where \(\frac{\partial L}{\partial x}\) is the gradient of the lagrangian w.r.t. the primal variables \(x\), \(G\) collects the equality constraints, \(H\) collects the inequality constraints and \(\lambda_h\) its corresponding dual variables.

If include_barrier_term=True, the inequalities include an additional barrier term tau, so that

\[\text{diag}(\lambda_h) \cdot H + \tau\]

which is also returned as the second element of the tuple. Otherwise, tau is None.

property lagrangian: SymType#: Gets the Lagrangian of the NLP problem (usually denoted as L).

property licq: SymType#

Gets the symbolic matrix for the LICQ, defined as

\[\begin{split}LICQ = \begin{bmatrix} \frac{\partial g}{\partial x} \\ \frac{\partial h}{\partial x} \\ \frac{\partial h_{lbx}}{\partial x} \\ \frac{\partial h_{ubx}}{\partial x} \end{bmatrix}\end{split}\]

If the matrix is linear independent, then the NLP satisfies the Linear Independence Constraint Qualification.

Notes

Theoretically, the LICQ is computed for only the active inenquality constraints. Since this is merely a symbolic representation, all constraints are included, and it’s up to the user to eliminate the inactive ones.

minimize(objective)[source]#

See csnlp.Nlp.minimize.

Return type:: None

parameter(name, shape=(1, 1))[source]#

See csnlp.Nlp.parameter.

Return type:: TypeVar(SymType, SX, MX)

parametric_sensitivity(expr=None, solution=None, second_order=False)[source]#

Performs the (symbolic or numerical) sensitivity of the NLP w.r.t. its parametrization, according to [4].

Parameters:

exprcasadi.SX or MX, optional: If provided, computes the sensitivity of this expression (which must be dependent on the primal-dual variables and/or parameters of the NLP) w.r.t. the NLP parameters. If None, then the sensitivity of the primal-dual variables is returned.
solutionSolution, optional: If a solution is passed, then the sensitivity is numerically computed for that solution; otherwise, the sensitivity is carried out symbolically (however, this is much more computationally intensive).
second_orderbool, optional: If second_order=False, the analysis is stopped at the first order; otherwise, also second-order information is computed.

Returns:

2-element tuple of casadi.SX, or MX, or DM: The 1st and 2nd-order NLP parametric sensitivity in the form of an array/DM, if a solution is passed, or a symbolic vector SX/MX. When second_order=False the second element in the tuple is None.

Raises:

numpy.linalg.LinAlgError: Raises if the KKT conditions lead to a singular matrix.

Return type:

Union[tuple[TypeVar(SymType, SX, MX), Optional[TypeVar(SymType, SX, MX)]], tuple[DM, Optional[DM]]]

set_target_parameters(parameters)[source]#

Sets the target parameters of the sensitivity wrapper.

Parameters:

parameterscasadi.MX or SX or None: New parameters to target during the sensitivity analyses. If None, all NLP parameters are included.

Return type:

None

property target_parameters: SymType#: Gets the parameters of the NLP that are the target of the sensitivity wrapper, i.e., derivatives and sensitivities are limited to these parameters.