# ParametricMCPs

This package provides a generic, differentiable mathematical programming layer by compiling mixed complementarity problems (MCPs) parameterized by a "runtime"-parameter vector. The resulting `ParametricMCP`

can be solved for different parameter instantiations using `solve(problem, parameters)`

and the `solve`

routine is made differentiable via ChainRulesCore and ForwardDiff.

## Installation

ParametricMCPs is a registered package. Thus, installation is as simple as:

`] add ParametricMCPs`

This package uses the proprietary PATH solver under the hood (via PATHSolver.jl). Therefore, you will need a license key to solve larger problems. However, by courtesy of Steven Dirkse, Michael Ferris, and Tudd Munson, temporary licenses are available free of charge. Please consult the documentation of PATHSolver.jl to learn about loading the license key.

## Quickstart by Example

Simple forward computation:

```
using ParametricMCPs
# setup a simple MCP which represents a QP with
# - cost: sum((z[1:2] - θ).^2)
# - constaints: z[1:2] >= 0
f(z, θ) = [2z[1:2] - z[3:4] - 2θ; z[1:2]]
lower_bounds = [-Inf, -Inf, 0, 0]
upper_bounds = [Inf, Inf, Inf, Inf]
parameter_dimension = 2
problem = ParametricMCP(f, lower_bounds, upper_bounds, parameter_dimension)
some_parameter = [1.0, 2.0]
solve(problem, some_parameter)
```

Since we provide differentiation rules via `ChainRulesCore`

, the solver can be
differentiated using your favourite ad-framework, e.g., Zygote:

```
using Zygote
function dummy_pipeline(θ)
solution = ParametricMCPs.solve(problem, θ)
sum(solution.z .^ 2)
end
Zygote.gradient(dummy_pipeline, some_parameter)
```

## Acknowledgements

This package is effectively a thin wrapper around the great work of other people. Special thanks goes to the maintainers of the following packages:

## Related Packages

For some specialized, closely related applications, you may want to consider the following packages (all of which also provide differentiation rules):

- TensorGames.jl solves finite N-player normal-form games.
- DifferentiableTrajectoryOptimization.jl solves parametric (single-player) trajectory optimization problems. The interface is very similar to ParametricMCPs.jl. Beyond the PATH solver, this package also supports backends like IPOPT and OSQP.