API Reference

AbstractAlgorithm

A super-type for the solution algorithms. Select one with the Algorithm attribute.

AbstractAlgorithmAttribute <: MOI.AbstractOptimizerAttribute

A super-type for algorithm-specific optimizer attributes. Each algorithm declares MOI.supports for the attributes it consumes and documents them in its docstring.

AbstractSetCover

A super-type for the problems the set-covering pass can solve for its initial combinations; see SetCoverProblem.

Algorithm() <: MOI.AbstractOptimizerAttribute

The algorithm the optimizer runs. Defaults to LOA.

Example

julia> set_attribute(model, DisjunctiveAlgorithms.Algorithm(),
           DisjunctiveAlgorithms.LOA())

BatchedSubproblems()

SubproblemMethod value that solves a vector of indicator combinations as one block-diagonal NLP through the nlp_solver: each combination gets its own copy of the variables and rows, and the objective is the sum of the copies' objectives. The copies do not interact, so the stacked solution is the sequential one; what changes is that the solver sees one large, regular problem, which is what GPU evaluators and factorizations need to pay off. A single combination is a batch of one. A batch whose joint solve fails (one infeasible copy makes the whole stack infeasible) falls back to the sequential path copy by copy, so the results match the default method exactly.

CombinationSource() <: AbstractAlgorithmAttribute -> Any

Where the extra combinations of a MultiGenerationSize iteration come from. The default nothing reads the master's solution pool (result indices past 1), and only without a pool re-solves the master behind no-good cuts. The experimental sources in combination_sources.jl need nothing from the solver: Neighborhood, LPRounding, RandomCombinations, and CutoffResolve. A source extends _candidate_combinations.

ConvergenceTolerance() <: AbstractAlgorithmAttribute -> Float64

Relative incumbent/bound gap tolerance. Defaults to 1e-6.

CutoffResolve(; tolerance = 0.05)

CombinationSource that re-solves the master behind no-good cuts like the default, but with the master objective capped at the current optimum plus tolerance (relative) and the last solution as a warm start, so each re-solve is a small warm MILP. Still one master solve per extra combination.

IterationTimeLimit() <: AbstractAlgorithmAttribute -> Float64

Seconds allotted to the solve loop. Defaults to Inf. The overall budget is the standard MOI.TimeLimitSec attribute.

LOA()

LOA implements logic-based outer approximation (Turkay and Grossmann 1996): a MILP master keeps the linear rows exactly, gates each disjunct's rows on its indicator, and accumulates OA cuts from NLP subproblems solved at fixed indicator combinations. The set-covering pass of Turkay and Grossmann (1996, Appendix D), restricted to the nonlinear disjuncts as in GDPopt (Chen, Johnson, Siirola and Grossmann 2018), initializes it with combinations that activate every nonlinear disjunct once; SetCoverProblem picks the covering problem. The OA bound is only valid on convex problems, so convergence reports LOCALLY_SOLVED, never OPTIMAL.

Supported optimizer attributes

• NumIterationLimit
• SetCoverIterationLimit
• SetCoverProblem
• M_Value
• MasterReformulation
• MaxSlack
• OASlack
• UseNLPF
• ConvergenceTolerance
• SlackTolerance
• IterationTimeLimit
• MultiGenerationSize
• CombinationSource
• SubproblemMethod

LPRounding(; seed = 0)

CombinationSource that samples combinations from the master's LP relaxation: integrality is dropped on a copy of the master, the LP is solved, and each disjunction's active disjunct is drawn with probability proportional to the relaxed value of its activation. One LP per iteration, informed by every cut in the master. The LP solve is not counted in MasterSolveCount.

LogicOnlyCover() <: AbstractSetCover

The covering problem of Turkay and Grossmann (1996, Appendix D): the disjunct binaries under the exactly-one and propositional rows only.

M_Value() <: AbstractAlgorithmAttribute -> Float64

Big-M gating the disjunct OA cuts in the master. Defaults to 1e9.

MasterCover() <: AbstractSetCover

The MILP master with the covering objective swapped in, as Pyomo's GDPopt does (Chen, Johnson, Siirola and Grossmann 2018), so the initial combinations also satisfy the linear rows and their NLPs are far less often infeasible.

MasterReformulation() <: AbstractAlgorithmAttribute -> String

How linear disjunct rows enter the master: "indicator" (constraint gated by the binary) or "bigm" (rows relaxed by M_Value * (1 - z), tighter for solvers that cannot strengthen indicators, e.g. with presolve disabled). Defaults to "indicator".

MasterSolveCount() <: MOI.AbstractModelAttribute -> Int

Master MILP solves in the last optimize!, including the set-covering pass and any pool-replacement re-solves.

MasterSolveTime() <: MOI.AbstractModelAttribute -> Float64

Seconds spent inside master MILP solves in the last optimize!.

MaxSlack() <: AbstractAlgorithmAttribute -> Float64

Upper bound of each OA cut slack. Defaults to 1e3.

MultiGenerationSize() <: AbstractAlgorithmAttribute -> Int

Indicator combinations evaluated per master solve in the main loop (multi-generation cuts). Defaults to 1, plain LOA. Extra combinations come from the master's solution pool when the mip_solver exposes one through MOI.ResultCount (Gurobi with PoolSolutions), as many as it holds up to this size, and otherwise from re-solving the master behind a no-good cut per combination already taken. All of them go through _solve_nlps, one stacked NLP under BatchedSubproblems, and every result adds its cuts before the next master solve.

NLPInfeasibleCount() <: MOI.AbstractModelAttribute -> Int

Indicator combinations whose NLP subproblem returned no feasible point in the last optimize! (infeasible or failed), out of NLPSolveCount.

NLPSolveCount() <: MOI.AbstractModelAttribute -> Int

Indicator combinations evaluated by NLP subproblems in the last optimize!; a stacked batch of k counts k.

NLPSolveTime() <: MOI.AbstractModelAttribute -> Float64

Seconds spent inside NLP subproblem solves in the last optimize!, feasibility restoration and stacked batches included.

Neighborhood(; around = :proposal)

CombinationSource made of every combination that differs from the master's proposal (or from the incumbent, around = :incumbent) in exactly one disjunction's choice. Free: no solver call. A disjunction of m disjuncts contributes m - 1 neighbors; when there are more than asked for, an evenly spaced subset over the disjunctions is taken.

NumIterationLimit() <: AbstractAlgorithmAttribute -> Int

Master/NLP iterations after the set-covering seed. Defaults to 10.

OASlack() <: AbstractAlgorithmAttribute -> Float64

Objective penalty per unit of cut slack. Defaults to 1e3.

Optimizer(nlp_solver, mip_solver = nlp_solver)

Solver for models containing DisjunctiveProgramming.DisjunctionSet constraints. nlp_solver and mip_solver are optimizer factories as accepted by MOI.instantiate. The algorithm (default LOA) is selected with the Algorithm attribute and configured through the attributes it documents. A new optimizer starts with a 3600 second MOI.TimeLimitSec safety limit; set it to nothing for no limit.

Example

julia> model = GDPModel(() -> DisjunctiveAlgorithms.Optimizer(
           Ipopt.Optimizer, HiGHS.Optimizer));

julia> optimize!(model, gdp_method = Direct())

RandomCombinations(; seed = 0)

CombinationSource drawing combinations uniformly, one active disjunct per disjunction. The uninformed baseline for the sources above.

SetCoverIterationLimit() <: AbstractAlgorithmAttribute -> Int

Set-covering initialization iterations: each solves the logic-only cover MIP over the indicators and one NLP, until every nonlinear disjunct has been active in a feasible NLP. Defaults to 8.

SetCoverProblem() <: AbstractAlgorithmAttribute -> AbstractSetCover

Which problem the set-covering pass solves for its initial combinations, LogicOnlyCover or MasterCover. Defaults to LogicOnlyCover().

SlackTolerance() <: AbstractAlgorithmAttribute -> Float64

Total cut slack tolerance for convergence. Defaults to 1e-4.

SubproblemMethod() <: AbstractAlgorithmAttribute -> Any

How the NLP subproblems are built and solved. The default nothing builds one MOI model from the nlp_solver and rewrites its binary fixes and disjunct rows per combination. A method object routes the subproblems elsewhere (e.g. a structure-preserving transcription of the original model): it must extend _build_subproblem and _solve_nlp on its type, and may extend _check_nlp_support. _solve_nlp must return (; combination, point, objective, feasible, status) with point indexed by this optimizer's variable indices.

UseNLPF() <: AbstractAlgorithmAttribute -> Bool

Solve a slacked feasibility NLP when the primary NLP is infeasible, so its point still seeds OA cuts. Defaults to true.