Add Bridges.Constraint.InequalityToComplementsBridge

[odow]

Closes #2581

Basic

• Create a new file in src/Bridges/XXX/bridges
• Define the bridge, following existing examples. The name of the bridge
  struct must end in Bridge
• Check if your bridge can be a subtype of MOI.Bridges.Constraint.SetMapBridge
• Define a new const that is a SingleBridgeOptimizer wrapping the
  new bridge. The name of the const must be the name of the bridge, less
  the Bridge suffix
• include the file in src/Bridges/XXX/bridges/XXX.jl
• If the bridge should be enabled by default, add the bridge to
  add_all_bridges at the bottom of src/Bridges/XXX/XXX.jl

Tests

• Create a new file in the appropriate subdirectory of tests/Bridges/XXX
• Use MOI.Bridges.runtests to test various inputs and outputs of the
  bridge
• If, after opening the pull request to add the bridge, some lines are not
  covered by the tests, add additional bridge-specific tests to cover the
  untested lines.

Documentation

• Add a docstring which uses the same template as existing bridges.

Final touch

If the bridge depends on run-time values of other variables and constraints in
the model:

• Implement MOI.Utilities.needs_final_touch(::Bridge)
• Implement MOI.Utilities.final_touch(::Bridge, ::MOI.ModelLike)
• Ensure that final_touch can be called multiple times in a row

[odow]

@mitchphillipson with this PR you will be able to do:

julia> using JuMP, PATHSolver

julia> model = Model(PATHSolver.Optimizer);

julia> @variable(model, x >= 0, start = 1.0);

julia> @constraint(model, 2 * x == 1.0)
2 x = 1

julia> optimize!(model)
Path 5.1.99 (Mon Jul 24 14:47:28 2023)
Written by Todd Munson, Steven Dirkse, Youngdae Kim, and Michael Ferris

MCPR: One:    0 Two:    2 Thr:    0 Qua:    0 WBd:    0 Fix:    0 IFx:    0

Major Iterations. . . . 0
Minor Iterations. . . . 0
Restarts. . . . . . . . 0
Crash Iterations. . . . 0
Gradient Steps. . . . . 0
Function Evaluations. . 0
Gradient Evaluations. . 0
Basis Time. . . . . . . 0.000000
Total Time. . . . . . . 0.000167
Residual. . . . . . . . 0.000000e+00
Postsolved residual: 0.0000e+00

julia> value(x)
0.5

[mitchphillipson]

@mitchphillipson with this PR you will be able to do:

julia> using JuMP, PATHSolver

julia> model = Model(PATHSolver.Optimizer);

julia> @variable(model, x >= 0, start = 1.0);

julia> @constraint(model, 2 * x == 1.0)
2 x = 1

julia> optimize!(model)
Path 5.1.99 (Mon Jul 24 14:47:28 2023)
Written by Todd Munson, Steven Dirkse, Youngdae Kim, and Michael Ferris

MCPR: One:    0 Two:    2 Thr:    0 Qua:    0 WBd:    0 Fix:    0 IFx:    0

Major Iterations. . . . 0
Minor Iterations. . . . 0
Restarts. . . . . . . . 0
Crash Iterations. . . . 0
Gradient Steps. . . . . 0
Function Evaluations. . 0
Gradient Evaluations. . 0
Basis Time. . . . . . . 0.000000
Total Time. . . . . . . 0.000167
Residual. . . . . . . . 0.000000e+00
Postsolved residual: 0.0000e+00

julia> value(x)
0.5

How does JuMP know that 2x=1 is complimentary to x? Or is this being passed to PATH directly?

[odow]

know that 2x=1 is complimentary to x

It isn't.

This PR adds a bridge which reformulates 2x == 1 into a new constraint and variable:

y = @variable(model)
@constraint(model, 2x - 1 ⟂ y)

If no complementarity constraint is set for a variable, it is defined as

@constraint(model, 0 ⟂ x)

so the full model is equivalent to

model = Model(PATHSolver.Optimizer)
@variable(model, x >= 0, start = 1)
@variable(model, y)
@constraint(model, 0      ⟂ x)
@constraint(model, 2x - 1 ⟂ y)