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: