pympcc.bilevel.from_lower_level

pympcc.bilevel.from_lower_level(*, n_x, n_y, x0, y0, f_upper, f_lower, n_g_lower=0, g_lower=None, n_h_lower=0, h_lower=None, derivatives='jax', xl=None, xu=None, yl=None, yu=None, lambda0=None, mu0=None)[source]

Emit an MPCCProblem from a bilevel program.

Parameters:

  • n_x (int) – Sizes of the upper-level and lower-level decision-variable blocks.

  • n_y (int) – Sizes of the upper-level and lower-level decision-variable blocks.

  • x0 (array-like) – Initial guesses for x and y.

  • y0 (array-like) – Initial guesses for x and y.

  • f_upper (callable) – Upper-level objective F(x, y) -> float.

  • f_lower (callable) – Lower-level objective f(x, y) -> float.

  • n_g_lower (int) – Number of lower-level inequality constraints g(x, y) ≤ 0. Must be ≥ 1 (a bilevel without lower-level inequalities is not an MPCC; solve it as a regular NLP).

  • g_lower (callable) – g(x, y) -> ndarray, shape (n_g_lower,). Required when n_g_lower > 0.

  • n_h_lower (int) – Number of lower-level equality constraints h(x, y) = 0 (default 0).

  • h_lower (callable, optional) – h(x, y) -> ndarray, shape (n_h_lower,). Required when n_h_lower > 0.

  • derivatives ({"jax", "fd"}, default "jax") – Backend used both to form the stationarity rows and to fill every Jacobian on the emitted MPCC. "jax" requires the user-supplied callables to be jax.numpy-traceable and is dramatically more accurate (single-level autodiff) than the "fd" fallback (nested finite differences).

  • xl (array-like, optional) – Bounds on the upper- and lower-level variable blocks (default ±inf). The λ block is automatically lower-bounded at 0; μ stays free.

  • xu (array-like, optional) – Bounds on the upper- and lower-level variable blocks (default ±inf). The λ block is automatically lower-bounded at 0; μ stays free.

  • yl (array-like, optional) – Bounds on the upper- and lower-level variable blocks (default ±inf). The λ block is automatically lower-bounded at 0; μ stays free.

  • yu (array-like, optional) – Bounds on the upper- and lower-level variable blocks (default ±inf). The λ block is automatically lower-bounded at 0; μ stays free.

  • lambda0 (array-like, optional) – Initial multipliers for λ and μ (default zeros).

  • mu0 (array-like, optional) – Initial multipliers for λ and μ (default zeros).

Returns:

With n = n_x + n_y + n_g_lower + n_h_lower, n_comp = n_g_lower, n_eq = n_y + n_h_lower.

Return type:

MPCCProblem

Notes

No lower-level inequality slacks are introduced; the complementarity pair lives directly between λ and -g(x, y). The stationarity rows depend on y, λ, μ through the lower-level Lagrangian’s second-order partials, so the MPCC’s own Jacobian computation involves second derivatives of f_lower, g_lower, and h_lower. With derivatives="jax" JAX takes those derivatives exactly; with "fd" they are computed by nested finite differences (acceptable for prototyping, noisy on tight tolerances).