pympcc.MPCCProblem

class pympcc.MPCCProblem(n, n_comp, x0, objective, comp_G=None, comp_H=None, gradient=None, comp_G_jacobian=None, comp_H_jacobian=None, derivatives=None, xl=None, xu=None, n_ineq=0, ineq_constraints=None, ineq_jacobian=None, n_eq=0, eq_constraints=None, eq_jacobian=None, fd_h=1.4901161193847656e-08, fd_mode='forward', use_jax_hessian=False, jax_sparsity_tol=1e-12, lagrangian_hessian=None, lagrangian_hessian_sparsity=None, lagrangian_hessian_slack=None, lagrangian_hessian_slack_sparsity=None, comp_G_jacobian_sparsity=None, comp_H_jacobian_sparsity=None, ineq_jacobian_sparsity=None, eq_jacobian_sparsity=None, comp_var_pairs=None, comp_var_pairs_bulk=None, comp_box_pairs=None, comp_G_scale=None, comp_H_scale=None)[source]

Bases: object

Defines an MPCC in the form:

min  f(x)
s.t. g(x) <= 0              (n_ineq inequality constraints)
     h(x)  = 0              (n_eq  equality   constraints)
     G(x) >= 0  }
     H(x) >= 0  }           (n_comp complementarity pairs)
     G(x)^T H(x) = 0  }
Parameters:

  • n (int) – Number of decision variables.

  • n_comp (int) – Number of complementarity pairs.

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

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

  • gradient (callable or "fd") – grad_f(x) -> ndarray, shape (n,). Pass "fd" to use a finite-difference approximation.

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

  • comp_G_jacobian (callable or "fd") – jac_G(x) -> ndarray, shape (n_comp, n) (dense), or a 1-D array of nnz values when comp_G_jacobian_sparsity is set. Pass "fd" to use a finite-difference approximation.

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

  • comp_H_jacobian (callable or "fd") – jac_H(x) -> ndarray, shape (n_comp, n) (dense), or 1-D nnz values when comp_H_jacobian_sparsity is set. Pass "fd" to use a finite-difference approximation.

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

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

  • n_ineq (int) – Number of inequality constraints g(x) <= 0.

  • ineq_constraints (callable, optional) – g(x) -> ndarray, shape (n_ineq,)

  • ineq_jacobian (callable or "fd", optional) – jac_g(x) -> ndarray, shape (n_ineq, n). Pass "fd" to use a finite-difference approximation. Requires n_ineq > 0 and ineq_constraints.

  • n_eq (int) – Number of equality constraints h(x) = 0.

  • eq_constraints (callable, optional) – h(x) -> ndarray, shape (n_eq,)

  • eq_jacobian (callable or "fd", optional) – jac_h(x) -> ndarray, shape (n_eq, n). Pass "fd" to use a finite-difference approximation. Requires n_eq > 0 and eq_constraints.

  • fd_h (float, optional) – Step size used for all finite-difference approximations (default: sqrt(machine_epsilon) ≈ 1.49e-8).

  • fd_mode ({"forward", "central"}, optional) – Finite-difference scheme (default: "forward"). "forward" costs n+1 evaluations per Jacobian column (O(h) error). "central" costs 2n evaluations per column (O(h²) error).

  • derivatives (str | None)

  • use_jax_hessian (bool)

  • jax_sparsity_tol (float)

  • lagrangian_hessian (Callable | None)

  • lagrangian_hessian_sparsity (tuple | None)

  • lagrangian_hessian_slack (Callable | None)

  • lagrangian_hessian_slack_sparsity (tuple | None)

  • comp_G_jacobian_sparsity (tuple | None)

  • comp_H_jacobian_sparsity (tuple | None)

  • ineq_jacobian_sparsity (tuple | None)

  • eq_jacobian_sparsity (tuple | None)

  • comp_var_pairs (list | None)

  • comp_var_pairs_bulk (tuple | None)

  • comp_box_pairs (list | None)

  • comp_G_scale (ndarray | None)

  • comp_H_scale (ndarray | None)

Notes

Jacobians may be dense (n_con, n) arrays or, when the corresponding *_jacobian_sparsity field is set, 1-D arrays of nnz nonzero values in COO order. Passing "fd" always produces dense Jacobians; combine with sparsity fields only if the problem is genuinely sparse.

A UserWarning is emitted at construction whenever any "fd" sentinel is active. Finite differences are suitable for prototyping; use exact Jacobians in production for speed and accuracy.

__init__(n, n_comp, x0, objective, comp_G=None, comp_H=None, gradient=None, comp_G_jacobian=None, comp_H_jacobian=None, derivatives=None, xl=None, xu=None, n_ineq=0, ineq_constraints=None, ineq_jacobian=None, n_eq=0, eq_constraints=None, eq_jacobian=None, fd_h=1.4901161193847656e-08, fd_mode='forward', use_jax_hessian=False, jax_sparsity_tol=1e-12, lagrangian_hessian=None, lagrangian_hessian_sparsity=None, lagrangian_hessian_slack=None, lagrangian_hessian_slack_sparsity=None, comp_G_jacobian_sparsity=None, comp_H_jacobian_sparsity=None, ineq_jacobian_sparsity=None, eq_jacobian_sparsity=None, comp_var_pairs=None, comp_var_pairs_bulk=None, comp_box_pairs=None, comp_G_scale=None, comp_H_scale=None)
Parameters:
Return type:

None

Methods

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

Attributes

comp_G

comp_G_jacobian

comp_G_jacobian_sparsity

comp_G_scale

comp_H

comp_H_jacobian

comp_H_jacobian_sparsity

comp_H_scale

comp_box_pairs

comp_var_pairs

comp_var_pairs_bulk

derivatives

eq_constraints

eq_jacobian

eq_jacobian_sparsity

fd_h

fd_mode

gradient

has_comp_scale

True if either complementarity scale vector is set.

ineq_constraints

ineq_jacobian

ineq_jacobian_sparsity

is_sparse

True if any Jacobian block has an explicit sparsity structure.

jax_sparsity_tol

lagrangian_hessian

lagrangian_hessian_slack

lagrangian_hessian_slack_sparsity

lagrangian_hessian_sparsity

n_eq

n_ineq

use_jax_hessian

xl

xu

n

n_comp

x0

objective

n: int
n_comp: int
x0: ndarray
objective: Callable[[ndarray], float]
comp_G: Callable[[ndarray], ndarray] | None = None
comp_H: Callable[[ndarray], ndarray] | None = None
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
n_ineq: int = 0
ineq_constraints: Callable[[ndarray], ndarray] | None = None
ineq_jacobian: Callable[[ndarray], ndarray] | str | None = None
n_eq: int = 0
eq_constraints: Callable[[ndarray], ndarray] | None = None
eq_jacobian: 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
lagrangian_hessian: Callable | None = None
lagrangian_hessian_sparsity: tuple | None = None
lagrangian_hessian_slack: Callable | None = None
lagrangian_hessian_slack_sparsity: tuple | None = None
comp_G_jacobian_sparsity: tuple | None = None
comp_H_jacobian_sparsity: tuple | None = None
ineq_jacobian_sparsity: tuple | None = None
eq_jacobian_sparsity: tuple | None = None
comp_var_pairs: list | None = None
comp_var_pairs_bulk: tuple | None = None
comp_box_pairs: list | None = None
comp_G_scale: ndarray | None = None
comp_H_scale: ndarray | None = None
property is_sparse: bool

True if any Jacobian block has an explicit sparsity structure.

property has_comp_scale: bool

True if either complementarity scale vector is set.