pympcc.StructuredMPCC

class pympcc.StructuredMPCC(n, n_comp, x0, objective, comp_G, comp_H, gradient=None, comp_G_jacobian=None, comp_H_jacobian=None, derivatives=None, xl=None, xu=None, A_eq=None, b_eq=None, n_nl_eq=0, eq_nl=None, jac_eq_nl=None, A_ineq=None, b_ineq=None, n_nl_ineq=0, ineq_nl=None, jac_ineq_nl=None, fd_h=1.4901161193847656e-08, fd_mode='forward', use_jax_hessian=False, jax_sparsity_tol=1e-12)[source]

Bases: object

MPCC with explicitly separated linear and nonlinear constraint layers.

Parameters:

  • n (int) – Number of decision variables.

  • n_comp (int) – Number of complementarity pairs (>= 1).

  • x0 (array-like, shape (n,)) – Initial guess.

  • objective (callable) – f(x) -> float

  • gradient (callable) – ∇f(x) -> ndarray, shape (n,)

  • comp_G (callable) – G(x) -> ndarray, shape (n_comp,) with G(x) >= 0

  • comp_G_jacobian (callable) – ∇G(x) -> ndarray, shape (n_comp, n)

  • comp_H (callable) – H(x) -> ndarray, shape (n_comp,) with H(x) >= 0

  • comp_H_jacobian (callable) – ∇H(x) -> ndarray, shape (n_comp, n)

  • xl (array-like, shape (n,), optional) – Lower bounds on x (default: -inf).

  • xu (array-like, shape (n,), optional) – Upper bounds on x (default: +inf).

  • b_eq (ndarray, shape (n_lin_eq,), optional)

  • ----------------------------------------

  • A_eq (ndarray, shape (n_lin_eq, n), optional)

  • b_eq – Must be supplied together.

  • 0 (Nonlinear inequalities g_nl(x) ≤)

  • ----------------------------------------

  • n_nl_eq (int) – Number of nonlinear equality constraints (default 0).

  • eq_nl (callable, optional) – h_nl(x) -> ndarray, shape (n_nl_eq,)

  • jac_eq_nl (callable, optional) – ∇h_nl(x) -> ndarray, shape (n_nl_eq, n)

  • b_ineq (ndarray, shape (n_lin_ineq,), optional)

  • -----------------------------------------------

  • A_ineq (ndarray, shape (n_lin_ineq, n), optional)

  • b_ineq – Must be supplied together.

  • 0

  • ------------------------------------------

  • n_nl_ineq (int) – Number of nonlinear inequality constraints (default 0).

  • ineq_nl (callable, optional) – g_nl(x) -> ndarray, shape (n_nl_ineq,)

  • jac_ineq_nl (callable, optional) – ∇g_nl(x) -> ndarray, shape (n_nl_ineq, n)

  • derivatives (str | None)

  • fd_h (float)

  • fd_mode (Literal['forward', 'central'])

  • use_jax_hessian (bool)

  • jax_sparsity_tol (float)

Notes

All Jacobians (linear and nonlinear) must be dense 2-D arrays. Dimensions and callables shapes are validated at construction time by evaluating every callable at x0.

Examples

>>> import numpy as np
>>> import pympcc
>>>
>>> model = pympcc.StructuredMPCC(
...     n=3, n_comp=1,
...     x0=np.ones(3),
...     xl=np.zeros(3),
...     objective=lambda x: x[0]**2 + x[1]**2 + x[2]**2,
...     gradient=lambda x: 2*x,
...     # linear equality:  x[0] + x[1] = 1
...     A_eq=np.array([[1.0, 1.0, 0.0]]),
...     b_eq=np.array([1.0]),
...     # nonlinear equality:  x[0]^2 + x[2] = 1
...     n_nl_eq=1,
...     eq_nl=lambda x: np.array([x[0]**2 + x[2] - 1.0]),
...     jac_eq_nl=lambda x: np.array([[2*x[0], 0.0, 1.0]]),
...     # complementarity:  x[0] >= 0, x[1] >= 0, x[0]*x[1] = 0
...     comp_G=lambda x: np.array([x[0]]),
...     comp_G_jacobian=lambda x: np.array([[1.0, 0.0, 0.0]]),
...     comp_H=lambda x: np.array([x[1]]),
...     comp_H_jacobian=lambda x: np.array([[0.0, 1.0, 0.0]]),
... )
>>> result = pympcc.solve(model)
__init__(n, n_comp, x0, objective, comp_G, comp_H, gradient=None, comp_G_jacobian=None, comp_H_jacobian=None, derivatives=None, xl=None, xu=None, A_eq=None, b_eq=None, n_nl_eq=0, eq_nl=None, jac_eq_nl=None, A_ineq=None, b_ineq=None, n_nl_ineq=0, ineq_nl=None, jac_ineq_nl=None, fd_h=1.4901161193847656e-08, fd_mode='forward', use_jax_hessian=False, jax_sparsity_tol=1e-12)
Parameters:
Return type:

None

Methods

__init__(n, n_comp, x0, objective, comp_G, ...)

to_mpcc_problem()

Assemble a MPCCProblem from the structured constraint layers.

Attributes

A_eq

A_ineq

b_eq

b_ineq

comp_G_jacobian

comp_H_jacobian

derivatives

eq_nl

fd_h

fd_mode

gradient

ineq_nl

jac_eq_nl

jac_ineq_nl

jax_sparsity_tol

n_eq

linear + nonlinear.

n_ineq

linear + nonlinear.

n_lin_eq

Number of linear equality constraints (rows of A_eq).

n_lin_ineq

Number of linear inequality constraints (rows of A_ineq).

n_nl_eq

n_nl_ineq

use_jax_hessian

xl

xu

n

n_comp

x0

objective

comp_G

comp_H

n: int
n_comp: int
x0: ndarray
objective: Callable[[ndarray], float]
comp_G: Callable[[ndarray], ndarray]
comp_H: Callable[[ndarray], ndarray]
gradient: Callable[[ndarray], ndarray] | str | None = None
comp_G_jacobian: Callable[[ndarray], ndarray] | str | None = None
comp_H_jacobian: Callable[[ndarray], ndarray] | str | None = None
derivatives: str | None = None
xl: ndarray | None = None
xu: ndarray | None = None
A_eq: ndarray | None = None
b_eq: ndarray | None = None
n_nl_eq: int = 0
eq_nl: Callable[[ndarray], ndarray] | None = None
jac_eq_nl: Callable[[ndarray], ndarray] | str | None = None
A_ineq: ndarray | None = None
b_ineq: ndarray | None = None
n_nl_ineq: int = 0
ineq_nl: Callable[[ndarray], ndarray] | None = None
jac_ineq_nl: Callable[[ndarray], ndarray] | str | None = None
fd_h: float = 1.4901161193847656e-08
fd_mode: Literal['forward', 'central'] = 'forward'
use_jax_hessian: bool = False
jax_sparsity_tol: float = 1e-12
property n_lin_eq: int

Number of linear equality constraints (rows of A_eq).

property n_lin_ineq: int

Number of linear inequality constraints (rows of A_ineq).

property n_eq: int

linear + nonlinear.

Type:

Total equality constraints

property n_ineq: int

linear + nonlinear.

Type:

Total inequality constraints

to_mpcc_problem()[source]

Assemble a MPCCProblem from the structured constraint layers.

The linear and nonlinear equality (inequality) blocks are stacked in order — linear first, nonlinear second — into a single callable pair suitable for MPCCProblem.

Return type:

MPCCProblem