pympcc

A Python solver for Mathematical Programs with Complementarity Constraints (MPCC), built on IPOPT via cyipopt.

Problem form

\[\begin{split} \begin{aligned} \min_x \quad & f(x) \\ \text{s.t.} \quad & g(x) \le 0 \\ & h(x) = 0 \\ & G(x) \ge 0,\ H(x) \ge 0,\ G(x)^\top H(x) = 0. \end{aligned} \end{split}\]

Getting started

• Installation
  • System IPOPT
  • Package install
  • Optional: custom IPOPT linear-solver bridge
  • From source
• Quickstart
  • Where to next

User guide

• Problem setup
  • MPCCProblem
  • Variable-paired complementarity
  • StructuredMPCC
  • Derivative shorthand
• Strategies
  • Canonical strategies
  • NCP-function variants
  • Unified NCP-function entry point
  • solve options
  • MPCCResult
  • Iteration history
  • JSON / DataFrame export
• Strategy selection
  • TL;DR
  • Decision tree
  • When the FB-family is stalling
  • Warm-start use cases
  • Diagnostics first
• Troubleshooting
  • IPOPT divergence / restoration failure
  • Biactive pairs at the solution
  • When to use tnlp_refine=True
  • What the diagnostic fields mean
  • When in doubt
• Diagnostics
  • CQ, B-stationarity, SOSC
  • TNLP-certified multipliers
  • Multi-merit cross-check
  • Active-Jacobian diagnostics
  • Condition numbers
  • Initial-point statistics
• Sparse Jacobians and the slack strategy
  • Sparse Jacobians (large-\(n\) problems)
  • Slack strategy for large-\(n\) problems
  • Analytical Lagrangian Hessian
  • Auto pair-scaling
• Parametric sensitivity
  • When to use it
  • API
  • Active-row ordering for dc_dp
  • Skip conditions
  • Multipliers
• Differentiable solve (solve_jax)
  • ParametricMPCC
  • solve_jax
  • Phase-1 limitations
  • Skip behaviour
• Bilevel KKT-emitter frontend
  • API
  • Variable layout
  • When KKT emission is valid
• EPEC: equilibrium problems with equilibrium constraints
  • Problem form
  • Quickstart
  • When to reach for from_epec
  • Derivative requirements
  • Limitations (v1)
  • See also
• Presolve and multistart
  • Presolve
  • Multistart
• AMPL .nl reader
  • MacMPEC fixtures
  • Benchmark runner

Examples

• Examples
  • Getting started
  • Strategies & solvers
  • Diagnostics & certification
  • Bilevel & differentiable

Theory primer

• Theory primer
  • Why MPCCs are hard
  • Constraint qualifications
  • Stationarity hierarchy
  • Second-order sufficient conditions

Reference

• API reference
• Changelog

Why pympcc

• Thirteen reformulation strategies — six canonical (direct, Scholtes, smoothing, Lin-Fukushima, augmented Lagrangian, slack lifting) plus seven NCP-function variants (smooth-min, Chen-Chen-Kanzow, Kanzow-Schwartz, Chen-Mangasarian, Billups, Veelken-Ulbrich pow / sin); pick one with the selection guide.

• Certified stationarity — TNLP refinement extracts MPCC-clean multipliers and classifies S- / W- / C-stationarity.

• Diagnostics — MPCC-LICQ / MPCC-MFCQ check, B-stationarity certification, MPCC-SOSC, multi-merit cross-check.

• Differentiable — pympcc.solve_jax registers the solve as jax.custom_vjp for end-to-end gradients through the converged optimum.

• Bilevel-ready — pympcc.bilevel.from_lower_level compiles bilevel programs to MPCCs by emitting lower-level KKT.

Indices

• Index

• Module Index