From 7a1f5112f79fe4bb29d5be655df86b6038703d05 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 17 Jan 2024 14:45:46 +0000 Subject: [PATCH] build based on 77cd7d9 --- previews/PR1116/.documenter-siteinfo.json | 2 +- previews/PR1116/api/algorithm/index.html | 2 +- previews/PR1116/api/algos/index.html | 4 +-- previews/PR1116/api/benders/index.html | 10 +++---- previews/PR1116/api/branching/index.html | 4 +-- previews/PR1116/api/colgen/index.html | 14 +++++----- previews/PR1116/api/presolve/index.html | 2 +- previews/PR1116/api/storage/index.html | 4 +-- previews/PR1116/api/treesearch/index.html | 4 +-- .../PR1116/dynamic_sparse_arrays/index.html | 2 +- previews/PR1116/index.html | 2 +- previews/PR1116/man/algorithm/index.html | 26 +++++++++---------- .../PR1116/man/blockdecomposition/index.html | 2 +- previews/PR1116/man/callbacks/index.html | 4 +-- previews/PR1116/man/config/index.html | 4 +-- previews/PR1116/man/decomposition/index.html | 2 +- previews/PR1116/man/presolve/index.html | 2 +- previews/PR1116/qa/index.html | 2 +- .../PR1116/start/advanced_demo/index.html | 2 +- previews/PR1116/start/custom_data/index.html | 4 +-- previews/PR1116/start/cuts/index.html | 2 +- previews/PR1116/start/identical_sp/index.html | 2 +- .../PR1116/start/initial_columns/index.html | 2 +- previews/PR1116/start/other_pbs/index.html | 2 +- previews/PR1116/start/pricing/index.html | 2 +- previews/PR1116/start/start/index.html | 2 +- 26 files changed, 55 insertions(+), 55 deletions(-) diff --git a/previews/PR1116/.documenter-siteinfo.json b/previews/PR1116/.documenter-siteinfo.json index e32ae4dd1..b4bd1b90c 100644 --- a/previews/PR1116/.documenter-siteinfo.json +++ b/previews/PR1116/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-17T13:55:14","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-17T14:45:35","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/previews/PR1116/api/algorithm/index.html b/previews/PR1116/api/algorithm/index.html index d552338be..1745d262e 100644 --- a/previews/PR1116/api/algorithm/index.html +++ b/previews/PR1116/api/algorithm/index.html @@ -4,4 +4,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/api/algos/index.html b/previews/PR1116/api/algos/index.html index 7ffe341e3..2c0964729 100644 --- a/previews/PR1116/api/algos/index.html +++ b/previews/PR1116/api/algos/index.html @@ -25,9 +25,9 @@ param1::Int param2::Int MyAlgorithmParams(; param1::Int = 1, param2::Int = 2) = new(param1, param2) - endsource

Init

Parameters checking

When Coluna starts, it initializes the algorithms chosen by the user. A most important step is to check the consistency of the parameters supplied by the user and the compatibility of the algorithms with the model that will be received (usually MathProg.Reformulation). Algorithms usually have many parameters and are sometimes interdependent and nested. It is crucial to ensure that the user-supplied parameters are correct and give hints to fix them otherwise.

The entry-point of the parameter consistency checking is the following method:

Coluna.Algorithm.check_alg_parameters — Function
check_alg_parameters(top_algo, reform) -> Vector{Tuple{Symbol, AbstractAlgorithm, Any}}

Checks the consistency of the parameters of the top algorithm and its children algorithms. Returns a vector of tuples (name of the parameter, algorithm, value of the parameter) that lists all the inconsistencies found in the algorithms tree.

source

Developer of an algorithm must implement the following methods:

Missing docstring.

Missing docstring for Coluna.Algorithm.check_parameter. Check Documenter's build log for details.

Units usage

Missing docstring.

Missing docstring for Coluna.AlgoAPI.get_child_algorithms. Check Documenter's build log for details.

Missing docstring.

Missing docstring for Coluna.AlgoAPI.get_units_usage. Check Documenter's build log for details.

Run

Coluna.AlgoAPI.run! — Function
run!(algo::AbstractAlgorithm, env, model, input)

Default method to call an algorithm.

source
+ diff --git a/previews/PR1116/api/benders/index.html b/previews/PR1116/api/benders/index.html index 01fe79bcf..bb890cff8 100644 --- a/previews/PR1116/api/benders/index.html +++ b/previews/PR1116/api/benders/index.html @@ -1,5 +1,5 @@ -Benders · Coluna.jl
GitHub

Benders cut generation

Coluna provides an interface and generic functions to implement a Benders cut generation algorithm.

In this section, we are first going to present the generic functions, the implementation with some theory backgrounds and then give the references of the interface. The default implementation is based on the paper of

You can find the generic functions and the interface in the Benders submodule and the default implementation in the Algorithm submodule at src/Algorithm/benders.

Context

The Benders submodule provides an interface and generic functions to implement a benders cut generation algorithm. The implementation depends on an object called context.

Coluna.Benders.AbstractBendersContext — Type

Supertype for the objects to which belongs the implementation of the Benders cut generation and that stores any kind of information during the execution of the Bender cut generation algorithm.

source

Benders provides two types of context:

Coluna.Algorithm.BendersPrinterContext — Type
BendersPrinterContext(reformulation, algo_params) -> BendersPrinterContext

Creates a context to run the default implementation of the Benders algorithm together with a printer that prints information about the algorithm execution.

source

Generic functions

Generic functions are the core of the Benders cut generation algorithm. There are three generic functions:

See ...

See ...

These functions are independent of any other submodule of Coluna. You can use them to implement your own Benders cut generation algorithm.

Reformulation

The default implementation works with a reformulated problem contained in MathProg.Reformulation where master and subproblems are MathProg.Formulation objects.

The master has the following form:

\[\begin{aligned} +Benders · Coluna.jl

GitHub

Benders cut generation

Coluna provides an interface and generic functions to implement a Benders cut generation algorithm.

In this section, we are first going to present the generic functions, the implementation with some theory backgrounds and then give the references of the interface. The default implementation is based on the paper of

You can find the generic functions and the interface in the Benders submodule and the default implementation in the Algorithm submodule at src/Algorithm/benders.

Context

The Benders submodule provides an interface and generic functions to implement a benders cut generation algorithm. The implementation depends on an object called context.

Coluna.Benders.AbstractBendersContext — Type

Supertype for the objects to which belongs the implementation of the Benders cut generation and that stores any kind of information during the execution of the Bender cut generation algorithm.

source

Benders provides two types of context:

Coluna.Algorithm.BendersPrinterContext — Type
BendersPrinterContext(reformulation, algo_params) -> BendersPrinterContext

Creates a context to run the default implementation of the Benders algorithm together with a printer that prints information about the algorithm execution.

source

Generic functions

Generic functions are the core of the Benders cut generation algorithm. There are three generic functions:

See ...

See ...

These functions are independent of any other submodule of Coluna. You can use them to implement your own Benders cut generation algorithm.

Reformulation

The default implementation works with a reformulated problem contained in MathProg.Reformulation where master and subproblems are MathProg.Formulation objects.

The master has the following form:

\[\begin{aligned} \min \quad& cx + \sum_{k \in K} \eta_k & &\\ \text{s.t.} \quad& Ax \geq a & & (1) \\ & \text{< benders cuts>} & & (2) \\ @@ -10,7 +10,7 @@ \text{s.t.} \quad& Dy {\color{gray} + z'} \geq d - B\bar{x} && (5) \quad& {\color{blue}(\pi)} \\ & Ey {\color{gray} + z''} \geq e && (6) \quad& {\color{blue}(\rho)} \\ & l_2 \leq y \leq u_2 && (7) \quad& {\color{blue}(\sigma)} -\end{aligned}\]

where $y$ are second-stage variables, $z'$ and $z''$ are artificial variables (in grey because they are deactivated by default), constraints (5) are the reformulation of linking constraints using the first-stage solution $\bar{x}$, constraints (6) are the second-stage constraints, and constraints (7) are the bounds on the second-stage variables. In blue, we define the dual variables associated to these constraints.

References:

Main loop

This is a description of how the Coluna.Benders.run_benders_loop! generic function behaves with the default implementation.

The loop stops if one of the following conditions is met:

  • the master is infeasible
  • a separation subproblem is infeasible
  • the time limit is reached
  • the maximum number of iterations is reached
  • no new cut is generated

The default implementation returns:

Coluna.Algorithm.BendersOutput — Type

Output of the default implementation of the Benders algorithm.

It contains:

  • infeasible: the original problem is infeasible
  • time_limit_reached: the time limit was reached
  • mlp: the final bound obtained with the Benders cut algorithm
  • ip_primal_sol: the best primal solution to the original problem found by the Benders cut algorithm
source

References:

Coluna.Benders.benders_output_type — Function
benders_output_type(context) -> Type{<:AbstractBendersOutput}

Returns the type of the custom object that will store the output of the Benders cut generation algorithm.

source

Benders cut generation iteration

This is a description of how the Coluna.Benders.run_benders_iteration! generic function behaves with the default implementation.

These are the main steps of a Benders cut generation iteration without stabilization. Click on the step to go to the corresponding section.

flowchart TB; +\end{aligned}\]

where $y$ are second-stage variables, $z'$ and $z''$ are artificial variables (in grey because they are deactivated by default), constraints (5) are the reformulation of linking constraints using the first-stage solution $\bar{x}$, constraints (6) are the second-stage constraints, and constraints (7) are the bounds on the second-stage variables. In blue, we define the dual variables associated to these constraints.

References:

Main loop

This is a description of how the Coluna.Benders.run_benders_loop! generic function behaves with the default implementation.

The loop stops if one of the following conditions is met:

  • the master is infeasible
  • a separation subproblem is infeasible
  • the time limit is reached
  • the maximum number of iterations is reached
  • no new cut is generated

The default implementation returns:

Coluna.Algorithm.BendersOutput — Type

Output of the default implementation of the Benders algorithm.

It contains:

  • infeasible: the original problem is infeasible
  • time_limit_reached: the time limit was reached
  • mlp: the final bound obtained with the Benders cut algorithm
  • ip_primal_sol: the best primal solution to the original problem found by the Benders cut algorithm
source

References:

Coluna.Benders.benders_output_type — Function
benders_output_type(context) -> Type{<:AbstractBendersOutput}

Returns the type of the custom object that will store the output of the Benders cut generation algorithm.

source

Benders cut generation iteration

This is a description of how the Coluna.Benders.run_benders_iteration! generic function behaves with the default implementation.

These are the main steps of a Benders cut generation iteration without stabilization. Click on the step to go to the corresponding section.

flowchart TB; id1(Optimize master) id2(Treat unbounded master) id3(Setup separation subproblems) @@ -43,14 +43,14 @@ click id9 href "#Unboundedness-check" "Link to doc" click id11 href "#Current-primal-solution" "Link to doc" click id7 href "#Cuts-insertion" "Link to doc" - click id8 href "#Iteration-output" "Link to doc"

In the default implementation, some sections may have different behaviors depending on the result of previous steps.

Master optimization

This operation consists in optimizing the master problem in order to find a first-level solution $\bar{x}$.

In the default implementation, master optimization can be performed using SolveLpForm (LP solver) or SolveIpForm (MILP solver). When getting the solution, we store the current value of second stage variables $\bar{\eta}_k$ as incumbent value (see Coluna.MathProg.getcurincval).

It returns an object of the following type:

Coluna.Algorithm.BendersMasterResult — Type

Output of the default implementation of the Benders.optimize_master_problem! method.

It contains:

  • ip_solver: true if the master problem is solved with a MIP solver and involves integral variables, false otherwise.
  • result: the result of the master problem optimization stored in an OptimizationState object.
  • infeasible: true if the master at the current iteration is infeasible; false otherwise.
  • unbounded: true if the master at the current iteration is unbounded; false otherwise.
  • certificate: true if the master at the current iteration is unbounded and if the current result is a dual infeasibility certificate, false otherwise.
source

References:

Coluna.Benders.optimize_master_problem! — Function
optimize_master_problem!(master, context, env) -> MasterResult

Returns an instance of a custom object MasterResult that implements the following methods:

  • is_unbounded(res::MasterResult) -> Bool
  • is_infeasible(res::MasterResult) -> Bool
  • is_certificate(res::MasterResult) -> Bool
  • get_primal_sol(res::MasterResult) -> Union{Nothing, PrimalSolution}
source

Go back to the cut generation iteration diagram.

Unbounded master case

Second stage cost $\eta_k$ variables are free. As a consequence, the master problem is unbounded when there is no optimality Benders cuts.

In this case, Coluna.Benders.treat_unbounded_master_problem_case! is called. The main goal of the default implementation of this method is to get the dual infeasibility certificate of the master problem.

If the master has been solved with a MIP solver at the previous step, we need to relax the integrality constraints to get a dual infeasibility certificate.

If the solver does not provide a dual infeasibility certificate, the implementation has an "emergency" routine to provide a first-stage feasible solution by solving the master LP with cost of second stage variables set to zero. We recommend using a solver that provides a dual infeasibility certificate and avoiding the "emergency" routine.

References:

Coluna.Benders.treat_unbounded_master_problem_case! — Function
treat_unbounded_master_problem_case!(master, context, env) -> MasterResult

When after a call to optimize_master_problem!, the master is unbounded, this method is called. Returns an instance of a custom object MasterResult.

source

Go back to the cut generation iteration diagram.

Setup separation subproblems

Info

The separation subproblems differs depending on whether the restricted master is unbounded or not:

  • if the restricted master is optimal, the generic function calls Coluna.Benders.update_sp_rhs!
  • if the restricted master is unbounded, the generic function calls Coluna.Benders.setup_separation_for_unbounded_master_case!

Default implementation of Coluna.Benders.update_sp_rhs! updates the right-hand side of the linking constraints (5).

Reference:

Coluna.Benders.update_sp_rhs! — Function
update_sp_rhs!(context, sp, mast_primal_sol)

Updates the right-hand side of the separation problem sp by fixing the first-level solution obtained by solving the master problem mast_primal_sol.

source

Default implementation of Coluna.Benders.setup_separation_for_unbounded_master_case! gives rise to the formulation proposed in Lemma 2 of Bonami et al:

\[\begin{aligned} + click id8 href "#Iteration-output" "Link to doc"

In the default implementation, some sections may have different behaviors depending on the result of previous steps.

Master optimization

This operation consists in optimizing the master problem in order to find a first-level solution $\bar{x}$.

In the default implementation, master optimization can be performed using SolveLpForm (LP solver) or SolveIpForm (MILP solver). When getting the solution, we store the current value of second stage variables $\bar{\eta}_k$ as incumbent value (see Coluna.MathProg.getcurincval).

It returns an object of the following type:

Coluna.Algorithm.BendersMasterResult — Type

Output of the default implementation of the Benders.optimize_master_problem! method.

It contains:

  • ip_solver: true if the master problem is solved with a MIP solver and involves integral variables, false otherwise.
  • result: the result of the master problem optimization stored in an OptimizationState object.
  • infeasible: true if the master at the current iteration is infeasible; false otherwise.
  • unbounded: true if the master at the current iteration is unbounded; false otherwise.
  • certificate: true if the master at the current iteration is unbounded and if the current result is a dual infeasibility certificate, false otherwise.
source

References:

Coluna.Benders.optimize_master_problem! — Function
optimize_master_problem!(master, context, env) -> MasterResult

Returns an instance of a custom object MasterResult that implements the following methods:

  • is_unbounded(res::MasterResult) -> Bool
  • is_infeasible(res::MasterResult) -> Bool
  • is_certificate(res::MasterResult) -> Bool
  • get_primal_sol(res::MasterResult) -> Union{Nothing, PrimalSolution}
source

Go back to the cut generation iteration diagram.

Unbounded master case

Second stage cost $\eta_k$ variables are free. As a consequence, the master problem is unbounded when there is no optimality Benders cuts.

In this case, Coluna.Benders.treat_unbounded_master_problem_case! is called. The main goal of the default implementation of this method is to get the dual infeasibility certificate of the master problem.

If the master has been solved with a MIP solver at the previous step, we need to relax the integrality constraints to get a dual infeasibility certificate.

If the solver does not provide a dual infeasibility certificate, the implementation has an "emergency" routine to provide a first-stage feasible solution by solving the master LP with cost of second stage variables set to zero. We recommend using a solver that provides a dual infeasibility certificate and avoiding the "emergency" routine.

References:

Coluna.Benders.treat_unbounded_master_problem_case! — Function
treat_unbounded_master_problem_case!(master, context, env) -> MasterResult

When after a call to optimize_master_problem!, the master is unbounded, this method is called. Returns an instance of a custom object MasterResult.

source

Go back to the cut generation iteration diagram.

Setup separation subproblems

Info

The separation subproblems differs depending on whether the restricted master is unbounded or not:

  • if the restricted master is optimal, the generic function calls Coluna.Benders.update_sp_rhs!
  • if the restricted master is unbounded, the generic function calls Coluna.Benders.setup_separation_for_unbounded_master_case!

Default implementation of Coluna.Benders.update_sp_rhs! updates the right-hand side of the linking constraints (5).

Reference:

Coluna.Benders.update_sp_rhs! — Function
update_sp_rhs!(context, sp, mast_primal_sol)

Updates the right-hand side of the separation problem sp by fixing the first-level solution obtained by solving the master problem mast_primal_sol.

source

Default implementation of Coluna.Benders.setup_separation_for_unbounded_master_case! gives rise to the formulation proposed in Lemma 2 of Bonami et al:

\[\begin{aligned} (SepB) \equiv \min \quad& fy + {\color{gray} \mathbf{1}z' + \mathbf{1}z''} &&& \\ \text{s.t.} \quad& Dy {\color{gray} + z'} \geq -B\bar{x} && (5a) \quad& {\color{blue}(\pi)} \\ & Ey {\color{gray} + z''} \geq 0 && (6a) \quad& {\color{blue}(\rho)} \\ & y \geq 0 && (7a) \quad& {\color{blue}(\sigma)} -\end{aligned}\]

where $y$ are second-stage variables, $z'$ and $z''$ are artificial variables (in grey because they are deactivated by default), and $\bar{x}$ is an unbounded ray of the restricted master.

Reference:

Subproblem iterator

Not implemented yet.

Separation subproblem optimization

The default implementation first optimize the subproblem without the artificial variables $z'$ and $z''$. In the case where it finds $(\bar{\pi}, \bar{\rho}, \bar{\sigma})$ an optimal dual solution to the subproblem, the following cut is generated:

\[\eta_k + \bar{\pi}Bx \geq d\bar{\pi} + \bar{\rho}e + \bar{\sigma_{\leq}} l_2 + \bar{\sigma_{\geq}} u_2\]

with $\bar{\sigma_{\leq}} l_2$ (respectively $\bar{\sigma_{\geq}} u_2$) the dual of the left part (respectively the right part) of constraint $l_2 \leq y \leq u_2$ of the subproblem.

In the case where it finds the subproblem infeasible, it calls Coluna.Benders.treat_infeasible_separation_problem_case!. The default implementation of this method activates the artificial variables $z'$ and $z''$, sets the cost of second stage variables to 0, and optimizes the subproblem again.

If a solution with no artificial variables is found, the following cut is generated:

\[\bar{\pi}Bx \geq d\bar{\pi} + \bar{\rho}e + \bar{\sigma_{\leq}} l_2 + \bar{\sigma_{\geq}} u_2\]

Both methods return an object of the following type:

Coluna.Algorithm.BendersSeparationResult — Type

Output of the default implementation of the Benders.optimize_separation_problem! and Benders.treat_infeasible_separation_problem_case! methods.

It contains:

  • second_stage_estimation_in_master: the value of the second stage cost variable in the solution to the master problem.
  • second_stage_cost: the value of the second stage cost variable in the solution to the separation problem.
  • lp_primal_sol: the primal solution to the separation problem.
  • infeasible: true if the current separation problem is infeasible; false otherwise.
  • unbounded: true if the current separation problem is unbounded; false otherwise.
  • cut: the cut generated by the separation problem.
  • infeasible_treatment: true if this object is an output of the Benders.treat_infeasible_separation_problem_case! method; false otherwise.
  • unbounded_master: true if the separation subproblem has the form of Lemma 2 to separate a cut to truncate an unbounded ray of the restricted master problem; false otherwise.
source

References:

Coluna.Benders.optimize_separation_problem! — Function
optimize_separation_problem!(context, sp_to_solve, env, unbounded_master) -> SeparationResult

Returns an instance of a custom object SeparationResult that implements the following methods:

  • is_unbounded(res::SeparationResult) -> Bool
  • is_infeasible(res::SeparationResult) -> Bool
  • get_obj_val(res::SeparationResult) -> Float64
  • get_primal_sol(res::SeparationResult) -> Union{Nothing, PrimalSolution}
  • get_dual_sp_sol(res::SeparationResult) -> Union{Nothing, DualSolution}
source
Coluna.Benders.treat_infeasible_separation_problem_case! — Function
treat_infeasible_separation_problem_case!(context, sp_to_solve, env, unbounded_master) -> SeparationResult

When after a call to optimize_separation_problem!, the separation problem is infeasible, this method is called. Returns an instance of a custom object SeparationResult.

source

Go back to the cut generation iteration diagram.

Set of generated cuts

You can define your data structure to manage the cuts generated at a given iteration. Columns are inserted after the optimization of all the separation subproblems to allow the parallelization of the latter.

In the default implementation, cuts are represented by the following data structure:

Coluna.Algorithm.GeneratedCut — Type

Solution to the separation problem together with its corresponding benders cut.

It contains:

  • min_sense: true if it's a minimization problem; false otherwise.
  • lhs: the left-hand side of the cut.
  • rhs: the right-hand side of the cut.
  • dual_sol: an optimal dual solution to the separation problem.
source

We use the following data structures to store the cuts and the primal solutions to the subproblems:

Coluna.Algorithm.SepSolSet — Type

Primal solutions to the separation problems optimized at the current iteration. This is used to build a primal solution.

It contains sols a vector of primal solutions.

source

The default implementation of push_in_set! has the responsibility to check if the cut is violated. Given $\bar{\eta}_k$ solution to the restricted master and $\bar{y}$ solution to the separation problem, the cut is considered as violated when:

  • the separation subproblem was infeasible
  • or $\bar{\eta}_k \geq f\bar{y}$

References:

Coluna.Benders.set_of_cuts — Function

Returns an empty container that will store all the cuts generated by the separation problems during an iteration of the Benders cut generation algorithm. One must be able to iterate on this container to insert the cuts in the master problem.

source
Coluna.Benders.set_of_sep_sols — Function

Returns an empty container that will store the primal solutions to the separation problems at a given iteration of the Benders cut generation algorithm.

source
Coluna.Benders.push_in_set! — Function
push_in_set!(context, cut_pool, sep_result) -> Bool

Inserts a cut in the set of cuts generated at a given iteration of the Benders cut generation algorithm. The cut_pool structure is generated by set_of_cuts(context).

push_in_set!(context, sep_sp_sols, sep_result) -> Bool

Inserts a primal solution to a separation problem in the set of primal solutions generated at a given iteration of the Benders cut generation algorithm. The sep_sp_sols structure is generated by set_of_sep_sols(context).

Returns true if the cut or the primal solution was inserted in the set, false otherwise.

source

Go back to the cut generation iteration diagram.

Unboundedness check

Info

This check is performed only when the restricted master is unbounded.

To perform this check, we need a solution to each separation problem.

Let $(\bar{\eta}_k)_{k \in K}$ be the value of second stage variables in the dual infeasibility certificate of the restricted master. Let $\bar{y}$ be an optimal solution to the separation problem (SepB).

As indicated by Bonami et al., if $f\bar{y} \leq \sum\limits_{k \in K} \bar{\eta}_k$, then the original problem is unbounded (by definition of an unbounded ray of the original problem).

References:

Cuts insertion

The default implementation inserts into the master all the cuts stored in the CutsSet object.

Reference:

Go back to the cut generation iteration diagram.

Current primal solution

Lorem ipsum.

References:

Iteration output

Coluna.Algorithm.BendersIterationOutput — Type

Output of the default implementation of an iteration of the Benders algorithm.

It contains:

  • min_sense: the original problem is a minimization problem
  • nb_new_cuts: the number of new cuts added to the master problem
  • ip_primal_sol: the primal solution to the original problem found during this iteration
  • infeasible: the original problem is infeasible
  • time_limit_reached: the time limit was reached
  • master: the solution value to the master problem
source

References:

Go back to the cut generation iteration diagram.

Getters for Result data structures

Method nameMasterSeparation
is_unboundedXX
is_infeasibleXX
is_certificateX
get_primal_solXX
get_dual_solX
get_obj_valXX

Go back to the cut generation iteration diagram.

Stabilization

Not implemented yet.

+
diff --git a/previews/PR1116/api/branching/index.html b/previews/PR1116/api/branching/index.html index 62213702c..6bb532e64 100644 --- a/previews/PR1116/api/branching/index.html +++ b/previews/PR1116/api/branching/index.html @@ -1,7 +1,7 @@ -Branching · Coluna.jl
GitHub

Branching API

Coluna provides default implementations for the branching algorithm and the strong branching algorithms. Both implementations are built on top of an API that we describe here.

Candidates selection

Candidates selection is the first step (and sometimes the only step) of any branching algorithm. It chooses what are the possible branching constraints that will generate the children of the current node of the branch-and-bound tree.

Coluna provides the following function for this step:

It works as follows.

The user chooses one or several branching rules that indicate the type of branching he wants to perform. This may be on a single variable or on a linear expression of variables for instance.

The branching rule must implement apply_branching_rule that generates the candidates. The latter are the variables or expressions on which the branch-and-bound may branch with additional information that is requested by Coluna's branching implementation through the API.

Then, candidates are sorted according to a selection criterion (e.g. most fractional). The algorithm keeps a certain number of candidates (one for classic branching, and several for strong branching). It generates the children of each candidate kept. At last, it returns the candidates kept.

Branching rule

Candidate

Coluna.Branching.generate_children! — Function
generate_children!(branching_context, branching_candidate, lhs, env, reform, node)

This method generates the children of a node described by branching_candidate.

source

Selection criterion

Coluna.Branching.AbstractSelectionCriterion — Type

Supertype of selection criteria of branching candidates.

A selection criterion provides a way to keep only the most promising branching candidates. To create a new selection criterion, one needs to create a subtype of AbstractSelectionCriterion and implements the method select_candidates!.

source

Branching API

Method advanced_select! is part of the API but presented just below.

Advanced candidates selection

If the candidates' selection returns several candidates will all their children, advanced candidates selection must keep only one of them.

The advanced candidates' selection is the place to evaluate the children to get relevant additional key performance indicators about each branching candidate.

Coluna provides the following function for this step.

Coluna has two default implementations for this method:

  • for the classic branching that does nothing because the candidates selection returns 1 candidate
  • for the strong branching that performs several evaluations of the candidates.

Let us focus on the strong branching. Strong branching is a procedure that heuristically selects a branching constraint that potentially gives the best progress of the dual bound. The procedure selects a collection of branching candidates based on their branching rule (done in classic candidate selection) and their score (done in advanced candidate selection). Then, the procedure evaluates the progress of the dual bound in both branches of each branching candidate by solving both potential children using a conquer algorithm. The candidate that has the largest score is chosen to be the branching constraint.

However, the score can be difficult to compute. For instance, when the score is based on dual bound improvement produced by the branching constraint which is time-consuming to evaluate in the context of column generation Therefore, one can let the branching algorithm quickly estimate the score of each candidate and retain the most promising branching candidates. This is called a phase. The goal is to first evaluate a large number of candidates with a very fast conquer algorithm and retain a certain number of promising ones. Then, over the phases, it evaluates the improvement with a more precise conquer algorithm and restricts the number of retained candidates until only one is left.

Strong Branching API

The following methods are part of the API but have a default implementation. We advise you to not change them.

Missing docstring.

Missing docstring for Branching.perform_branching_phase!. Check Documenter's build log for details.

Missing docstring.

Missing docstring for Branching.eval_candidate!. Check Documenter's build log for details.

Score

GitHub

Branching API

Coluna provides default implementations for the branching algorithm and the strong branching algorithms. Both implementations are built on top of an API that we describe here.

Candidates selection

Candidates selection is the first step (and sometimes the only step) of any branching algorithm. It chooses what are the possible branching constraints that will generate the children of the current node of the branch-and-bound tree.

Coluna provides the following function for this step:

It works as follows.

The user chooses one or several branching rules that indicate the type of branching he wants to perform. This may be on a single variable or on a linear expression of variables for instance.

The branching rule must implement apply_branching_rule that generates the candidates. The latter are the variables or expressions on which the branch-and-bound may branch with additional information that is requested by Coluna's branching implementation through the API.

Then, candidates are sorted according to a selection criterion (e.g. most fractional). The algorithm keeps a certain number of candidates (one for classic branching, and several for strong branching). It generates the children of each candidate kept. At last, it returns the candidates kept.

Branching rule

Candidate

Coluna.Branching.generate_children! — Function
generate_children!(branching_context, branching_candidate, lhs, env, reform, node)

This method generates the children of a node described by branching_candidate.

source

Selection criterion

Coluna.Branching.AbstractSelectionCriterion — Type

Supertype of selection criteria of branching candidates.

A selection criterion provides a way to keep only the most promising branching candidates. To create a new selection criterion, one needs to create a subtype of AbstractSelectionCriterion and implements the method select_candidates!.

source

Branching API

Method advanced_select! is part of the API but presented just below.

Advanced candidates selection

If the candidates' selection returns several candidates will all their children, advanced candidates selection must keep only one of them.

The advanced candidates' selection is the place to evaluate the children to get relevant additional key performance indicators about each branching candidate.

Coluna provides the following function for this step.

Coluna has two default implementations for this method:

  • for the classic branching that does nothing because the candidates selection returns 1 candidate
  • for the strong branching that performs several evaluations of the candidates.

Let us focus on the strong branching. Strong branching is a procedure that heuristically selects a branching constraint that potentially gives the best progress of the dual bound. The procedure selects a collection of branching candidates based on their branching rule (done in classic candidate selection) and their score (done in advanced candidate selection). Then, the procedure evaluates the progress of the dual bound in both branches of each branching candidate by solving both potential children using a conquer algorithm. The candidate that has the largest score is chosen to be the branching constraint.

However, the score can be difficult to compute. For instance, when the score is based on dual bound improvement produced by the branching constraint which is time-consuming to evaluate in the context of column generation Therefore, one can let the branching algorithm quickly estimate the score of each candidate and retain the most promising branching candidates. This is called a phase. The goal is to first evaluate a large number of candidates with a very fast conquer algorithm and retain a certain number of promising ones. Then, over the phases, it evaluates the improvement with a more precise conquer algorithm and restricts the number of retained candidates until only one is left.

Strong Branching API

The following methods are part of the API but have a default implementation. We advise you to not change them.

Missing docstring.

Missing docstring for Branching.perform_branching_phase!. Check Documenter's build log for details.

Missing docstring.

Missing docstring for Branching.eval_candidate!. Check Documenter's build log for details.

Score

+
diff --git a/previews/PR1116/api/colgen/index.html b/previews/PR1116/api/colgen/index.html index dfad7d0c1..e294e55cb 100644 --- a/previews/PR1116/api/colgen/index.html +++ b/previews/PR1116/api/colgen/index.html @@ -1,5 +1,5 @@ -ColGen · Coluna.jl
GitHub

Column generation

Coluna provides an interface and generic functions to implement a multi-stage column generation algorithm together with a default implementation of this algorithm.

In this section, we are first going to present the generic functions, the implementation with some theory backgrounds and then give the references of the interface.

You can find the generic functions and the interface in the ColGen submodule and the default implementation in the Algorithm submodule at src/Algorithm/colgen.

Context

The ColGen submodule provides an interface and generic functions to implement a column generation algorithm. The implementation depends on an object called context.

Coluna.ColGen.AbstractColGenContext — Type

Supertype for the objects to which belongs the implementation of the column generation and that stores any kind of information during the execution of the column generation algorithm.

IMPORTANT: implementation of the column generation mainly depends on the context type.

source

Coluna provides two types of context:

Coluna.Algorithm.ColGenContext — Type
ColGenContext(reformulation, algo_params) -> ColGenContext

Creates a context to run the default implementation of the column generation algorithm.

source
Coluna.Algorithm.ColGenPrinterContext — Type
ColGenPrinterContext(reformulation, algo_params) -> ColGenPrinterContext

Creates a context to run the default implementation of the column generation algorithm together with a printer that prints information about the algorithm execution.

source

Generic functions

Generic functions are the core of the column generation algorithm. There are three generic functions:

Coluna.ColGen.run! — Function
run!(ctx, env, ip_primal_sol; iter = 1) -> AbstractColGenOutput

Runs the column generation algorithm.

Arguments are:

  • ctx: column generation context
  • env: Coluna environment
  • ip_primal_sol: current best primal solution to the master problem
  • iter: iteration number (default: 1)

This function is responsible for initializing the column generation context, the reformulation, and the stabilization. We iterate on the loop each time the phase or the stage changes.

source

See the main loop section for more details.

Coluna.ColGen.run_colgen_phase! — Function
run_colgen_phase!(ctx, phase, stage, env, ip_primal_sol, stab; iter = 1) -> AbstractColGenPhaseOutput

Runs a phase of the column generation algorithm.

Arguments are:

  • ctx: column generation context
  • phase: current column generation phase
  • stage: current column generation stage
  • env: Coluna environment
  • ip_primal_sol: current best primal solution to the master problem
  • stab: stabilization
  • iter: iteration number (default: 1)

This function is responsible for running the column generation iterations until the phase is finished.

source

See the phase loop section for more details.

Coluna.ColGen.run_colgen_iteration! — Function
run_colgen_iteration!(context, phase, stage, env, ip_primal_sol, stab) -> AbstractColGenIterationOutput

Runs an iteration of column generation.

Arguments are:

  • context: column generation context
  • phase: current column generation phase
  • stage: current column generation stage
  • env: Coluna environment
  • ip_primal_sol: current best primal solution to the master problem
  • stab: stabilization
source

See the column generation iteration section for more details.

They are independent of any other submodule of Coluna. You can use them to implement your own column generation algorithm.

Reformulation

The default implementation works with a reformulated problem contained in MathProg.Reformulation where master and subproblems are MathProg.Formulation objects.

The master has the following form:

\[\begin{aligned} +ColGen · Coluna.jl

GitHub

Column generation

Coluna provides an interface and generic functions to implement a multi-stage column generation algorithm together with a default implementation of this algorithm.

In this section, we are first going to present the generic functions, the implementation with some theory backgrounds and then give the references of the interface.

You can find the generic functions and the interface in the ColGen submodule and the default implementation in the Algorithm submodule at src/Algorithm/colgen.

Context

The ColGen submodule provides an interface and generic functions to implement a column generation algorithm. The implementation depends on an object called context.

Coluna.ColGen.AbstractColGenContext — Type

Supertype for the objects to which belongs the implementation of the column generation and that stores any kind of information during the execution of the column generation algorithm.

IMPORTANT: implementation of the column generation mainly depends on the context type.

source

Coluna provides two types of context:

Coluna.Algorithm.ColGenContext — Type
ColGenContext(reformulation, algo_params) -> ColGenContext

Creates a context to run the default implementation of the column generation algorithm.

source
Coluna.Algorithm.ColGenPrinterContext — Type
ColGenPrinterContext(reformulation, algo_params) -> ColGenPrinterContext

Creates a context to run the default implementation of the column generation algorithm together with a printer that prints information about the algorithm execution.

source

Generic functions

Generic functions are the core of the column generation algorithm. There are three generic functions:

Coluna.ColGen.run! — Function
run!(ctx, env, ip_primal_sol; iter = 1) -> AbstractColGenOutput

Runs the column generation algorithm.

Arguments are:

  • ctx: column generation context
  • env: Coluna environment
  • ip_primal_sol: current best primal solution to the master problem
  • iter: iteration number (default: 1)

This function is responsible for initializing the column generation context, the reformulation, and the stabilization. We iterate on the loop each time the phase or the stage changes.

source

See the main loop section for more details.

Coluna.ColGen.run_colgen_phase! — Function
run_colgen_phase!(ctx, phase, stage, env, ip_primal_sol, stab; iter = 1) -> AbstractColGenPhaseOutput

Runs a phase of the column generation algorithm.

Arguments are:

  • ctx: column generation context
  • phase: current column generation phase
  • stage: current column generation stage
  • env: Coluna environment
  • ip_primal_sol: current best primal solution to the master problem
  • stab: stabilization
  • iter: iteration number (default: 1)

This function is responsible for running the column generation iterations until the phase is finished.

source

See the phase loop section for more details.

Coluna.ColGen.run_colgen_iteration! — Function
run_colgen_iteration!(context, phase, stage, env, ip_primal_sol, stab) -> AbstractColGenIterationOutput

Runs an iteration of column generation.

Arguments are:

  • context: column generation context
  • phase: current column generation phase
  • stage: current column generation stage
  • env: Coluna environment
  • ip_primal_sol: current best primal solution to the master problem
  • stab: stabilization
source

See the column generation iteration section for more details.

They are independent of any other submodule of Coluna. You can use them to implement your own column generation algorithm.

Reformulation

The default implementation works with a reformulated problem contained in MathProg.Reformulation where master and subproblems are MathProg.Formulation objects.

The master has the following form:

\[\begin{aligned} \min \quad& \sum_{k \in K} c^k \lambda^k+\bar{c} y & \\ \text{s.t.} \quad& \sum_{k \in K} A^k \lambda^k+\bar{A} y \geq a & (1)\\ & l_k \leq \mathbf{1} \lambda^k \leq u_k & (2) \\ @@ -8,7 +8,7 @@ \min \quad& cx + 0z \\ \text{s.t.} \quad& Bx \geq b \\ & 1 \leq z \leq 1 -\end{aligned}\]

where $x$ are the subproblem variables, $z$ is a setup variable that always takes the value one in a solution to the subproblem.

The coefficients of the columns in constraints (1) and (2) of the master are computed using representative variables of the subproblems. You can read this section (TODO Natacha) to understand how we map the subproblem solutions into master columns.

References:

Main loop

This is a description of how the Coluna.ColGen.run! generic function behaves in the default implementation.

The main loop stops when the Coluna.ColGen.stop_colgen method returns true. This is the case when one of the following conditions holds:

  • the master or a pricing subproblem is infeasible
  • the time limit is reached
  • the maximum number of iterations is reached

Otherwise, the main loop runs until there is no more phase or stage to execute.

The method returns:

References:

Coluna.ColGen.new_output — Function
new_output(OutputType, colgen_phase_output) -> OutputType

Returns the column generation output where colgen_phase_output is the output of the last column generation phase executed.

source

Phase loop

This is a description of how the Coluna.ColGen.run_colgen_phase! generic function behaves in the default implementation.

This function is responsible for maintaining the incumbent dual bound and the incumbent master IP primal solution.

The phase loop stops when the Coluna.ColGen.stop_colgen_phase method returns true. This is the case when one of the following conditions holds:

  • the maximum number of iterations is reached
  • the time limit is reached
  • the master is infeasible
  • the master is unbounded
  • a pricing subproblem is infeasible
  • a pricing subproblem is unbounded
  • there is no new column generated at the last iteration
  • there is a new constraint or valid inequality in the master
  • the incumbent dual bound and the primal master LP solution value converged

The method returns:

References:

Coluna.ColGen.before_colgen_iteration — Function

Placeholder method called before the column generation iteration. Does nothing by default but can be redefined to print some informations for instance. We strongly advise users against the use of this method to modify the context or the reformulation.

source
Coluna.ColGen.after_colgen_iteration — Function

Placeholder method called after the column generation iteration. Does nothing by default but can be redefined to print some informations for instance. We strongly advise users against the use of this method to modify the context or the reformulation.

source

Phase iterator

In the first iterations, the restricted master LP contains a few columns and may be infeasible. To prevent this, we introduced artificial variables $v$ and we activate/deactivate these variables depending on whether we want to prove the infeasibility of the master LP or find the optimal LP solution. The default implementation provides three phases:

Coluna.Algorithm.ColGenPhase0 — Type

Phase 0 is a mix of phase 1 and phase 2. It sets a very large cost to artifical variables to force them to be removed from the master LP solution. If the final master LP solution contains artifical variables either the master is infeasible or the cost of artificial variables is not large enough. Phase 1 must be run.

source
Coluna.Algorithm.ColGenPhase1 — Type

Phase 1 sets the cost of variables to 0 except for artifical variables. The goal is to find a solution to the master LP problem that has no artificial variables.

source
Coluna.Algorithm.ColGenPhase2 — Type

Phase 2 solves the master LP without artificial variables. To start, it requires a set of columns that forms a feasible solution to the LP master. This set is found with phase 1.

source

Column generation always starts with Phase 0.

The default implementation of the phase iterator belongs to the following type:

Transitions between the phases depend on four conditions:

  • (A) the presence of artificial variables in the master LP solution
  • (B) the generation of new essential constraints (may happen when a new master IP solution is found)
  • (C) the current stage is exact
  • (D) column generation converged

Transitions are the following:

flowchart TB; +\end{aligned}\]

where $x$ are the subproblem variables, $z$ is a setup variable that always takes the value one in a solution to the subproblem.

The coefficients of the columns in constraints (1) and (2) of the master are computed using representative variables of the subproblems. You can read this section (TODO Natacha) to understand how we map the subproblem solutions into master columns.

References:

Main loop

This is a description of how the Coluna.ColGen.run! generic function behaves in the default implementation.

The main loop stops when the Coluna.ColGen.stop_colgen method returns true. This is the case when one of the following conditions holds:

  • the master or a pricing subproblem is infeasible
  • the time limit is reached
  • the maximum number of iterations is reached

Otherwise, the main loop runs until there is no more phase or stage to execute.

The method returns:

References:

Coluna.ColGen.new_output — Function
new_output(OutputType, colgen_phase_output) -> OutputType

Returns the column generation output where colgen_phase_output is the output of the last column generation phase executed.

source

Phase loop

This is a description of how the Coluna.ColGen.run_colgen_phase! generic function behaves in the default implementation.

This function is responsible for maintaining the incumbent dual bound and the incumbent master IP primal solution.

The phase loop stops when the Coluna.ColGen.stop_colgen_phase method returns true. This is the case when one of the following conditions holds:

  • the maximum number of iterations is reached
  • the time limit is reached
  • the master is infeasible
  • the master is unbounded
  • a pricing subproblem is infeasible
  • a pricing subproblem is unbounded
  • there is no new column generated at the last iteration
  • there is a new constraint or valid inequality in the master
  • the incumbent dual bound and the primal master LP solution value converged

The method returns:

References:

Coluna.ColGen.before_colgen_iteration — Function

Placeholder method called before the column generation iteration. Does nothing by default but can be redefined to print some informations for instance. We strongly advise users against the use of this method to modify the context or the reformulation.

source
Coluna.ColGen.after_colgen_iteration — Function

Placeholder method called after the column generation iteration. Does nothing by default but can be redefined to print some informations for instance. We strongly advise users against the use of this method to modify the context or the reformulation.

source

Phase iterator

In the first iterations, the restricted master LP contains a few columns and may be infeasible. To prevent this, we introduced artificial variables $v$ and we activate/deactivate these variables depending on whether we want to prove the infeasibility of the master LP or find the optimal LP solution. The default implementation provides three phases:

Coluna.Algorithm.ColGenPhase0 — Type

Phase 0 is a mix of phase 1 and phase 2. It sets a very large cost to artifical variables to force them to be removed from the master LP solution. If the final master LP solution contains artifical variables either the master is infeasible or the cost of artificial variables is not large enough. Phase 1 must be run.

source
Coluna.Algorithm.ColGenPhase1 — Type

Phase 1 sets the cost of variables to 0 except for artifical variables. The goal is to find a solution to the master LP problem that has no artificial variables.

source
Coluna.Algorithm.ColGenPhase2 — Type

Phase 2 solves the master LP without artificial variables. To start, it requires a set of columns that forms a feasible solution to the LP master. This set is found with phase 1.

source

Column generation always starts with Phase 0.

The default implementation of the phase iterator belongs to the following type:

Transitions between the phases depend on four conditions:

  • (A) the presence of artificial variables in the master LP solution
  • (B) the generation of new essential constraints (may happen when a new master IP solution is found)
  • (C) the current stage is exact
  • (D) column generation converged

Transitions are the following:

flowchart TB; id1(Phase 0) id2(Phase 1) id3(Phase 2) @@ -24,7 +24,7 @@ id3 -- otherwise --> id3 id3 -- B --> id2 id3 -- A --> id5 - style id5 stroke:#f66

References:

Coluna.ColGen.decrease_stage — Function

Returns the next stage involving a "more exact solver" than the current one. Returns nothing if the algorithm has already reached the exact phase (last phase).

source

Phase output

Coluna.ColGen.new_phase_output — Function
new_phase_output(OutputType, min_sense, phase, stage, colgen_iter_output, iter, inc_dual_bound) -> OutputType

Returns the column generation phase output.

Arguments of this function are:

  • OutputType: the type of the column generation phase output
  • min_sense: true if it is a minimization problem; false otherwise
  • phase: the current column generation phase
  • stage: the current column generation stage
  • col_gen_iter_output: the last column generation iteration output
  • iter: the last iteration number
  • inc_dual_bound: the current incumbent dual bound
source

Stages

A stage is a set of consecutive iterations in which we use a given pricing solver. The aim is to speed up the resolution of the pricing problem by first using an approximate but fast pricing algorithm and then switching to increasingly less heuristic algorithms until the last stage where an exact solver is used. and an exact solver at the last stage. Given a pricing solver, when the column generation does not progress anymore or the pricing solver does not return any new column, the default implementation switch to a more exact pricing solver. Stages are created using the stages_pricing_solver_ids of the ColumnGenerationAlgorithm parameter object. The default implementation implements the interface around the following object:

Coluna.Algorithm.ColGenStageIterator — Type

Default implementation of the column generation stages works as follows.

Consider a set {A,B,C} of subproblems each of them associated to the following sets of pricing solvers: {a1, a2, a3}, {b1, b2}, {c1, c2, c3, c4}. Pricing solvers a1, b1, c1 are exact solvers; others are heuristic.

The column generation algorithm will run the following stages:

  • stage 4 with pricing solvers {a3, b2, c4}
  • stage 3 with pricing solvers {a2, b1, c3}
  • stage 2 with pricing solvers {a1, b1, c2}
  • stage 1 with pricing solvers {a1, b1, c1} (exact stage)

Column generation moves from one stage to another when all solvers find no column.

source

References:

Column generation iteration

This is a description of how the Coluna.ColGen.run_colgen_iteration! generic function behaves in the default implementation.

These are the main steps of a column generation iteration without stabilization. Click on the step to go to the relevant section.

flowchart TB; + style id5 stroke:#f66

References:

Coluna.ColGen.decrease_stage — Function

Returns the next stage involving a "more exact solver" than the current one. Returns nothing if the algorithm has already reached the exact phase (last phase).

source

Phase output

Coluna.ColGen.new_phase_output — Function
new_phase_output(OutputType, min_sense, phase, stage, colgen_iter_output, iter, inc_dual_bound) -> OutputType

Returns the column generation phase output.

Arguments of this function are:

  • OutputType: the type of the column generation phase output
  • min_sense: true if it is a minimization problem; false otherwise
  • phase: the current column generation phase
  • stage: the current column generation stage
  • col_gen_iter_output: the last column generation iteration output
  • iter: the last iteration number
  • inc_dual_bound: the current incumbent dual bound
source

Stages

A stage is a set of consecutive iterations in which we use a given pricing solver. The aim is to speed up the resolution of the pricing problem by first using an approximate but fast pricing algorithm and then switching to increasingly less heuristic algorithms until the last stage where an exact solver is used. and an exact solver at the last stage. Given a pricing solver, when the column generation does not progress anymore or the pricing solver does not return any new column, the default implementation switch to a more exact pricing solver. Stages are created using the stages_pricing_solver_ids of the ColumnGenerationAlgorithm parameter object. The default implementation implements the interface around the following object:

Coluna.Algorithm.ColGenStageIterator — Type

Default implementation of the column generation stages works as follows.

Consider a set {A,B,C} of subproblems each of them associated to the following sets of pricing solvers: {a1, a2, a3}, {b1, b2}, {c1, c2, c3, c4}. Pricing solvers a1, b1, c1 are exact solvers; others are heuristic.

The column generation algorithm will run the following stages:

  • stage 4 with pricing solvers {a3, b2, c4}
  • stage 3 with pricing solvers {a2, b1, c3}
  • stage 2 with pricing solvers {a1, b1, c2}
  • stage 1 with pricing solvers {a1, b1, c1} (exact stage)

Column generation moves from one stage to another when all solvers find no column.

source

References:

Column generation iteration

This is a description of how the Coluna.ColGen.run_colgen_iteration! generic function behaves in the default implementation.

These are the main steps of a column generation iteration without stabilization. Click on the step to go to the relevant section.

flowchart TB; id1(Optimize master LP) id2{{Solution to master LP is integer?}} id3(Update incumbent primal solution if better than current one) @@ -55,16 +55,16 @@ click id7 href "#Set-of-generated-columns" "Link to doc" click id8 href "#Dual-bound-calculation" "Link to doc" click id9 href "#Columns-insertion" "Link to doc" - click id10 href "#Iteration-output" "Link to doc"

Optimize master LP

At each iteration, the algorithm requires a dual solution to the master LP to compute the reduced cost of subproblem variables.

The default implementation optimizes the master with an LP solver through MathOptInterface. It returns a primal and a dual solution.

In the default implementation, the master LP output is in the following data structure:

Coluna.Algorithm.ColGenMasterResult — Type

Output of the ColGen.optimize_master_lp_problem! method.

Contains result, an OptimizationState object that is the output of the SolveLpForm algorithm called to optimize the master LP problem.

source

References:

Coluna.ColGen.optimize_master_lp_problem! — Function
optimize_master_lp_problem!(master, context, env) -> MasterResult

Returns an instance of a custom object MasterResult that implements the following methods:

  • get_obj_val: objective value of the master (mandatory)
  • get_primal_sol: primal solution to the master (optional)
  • get_dual_sol: dual solution to the master (mandatory otherwise column generation stops)

It should at least return a dual solution (obtained with LP optimization or subgradient) otherwise column generation cannot continue.

source

You can see the additional methods to implement in the result data structures section.

Go back to the column generation iteration overview.

Check the integrality of the master LP solution

The algorithm checks the integrality of the primal solution to the master LP to improve the global primal bound of the branch-cut-price algorithm.

In the default implementation, the integrality check is done using the MathProg.proj_cols_is_integer method. It implements the procedure described in the paper (TODO). Basically, it sorts the column used in the master LP primal solution in lexicographic order. It assigns a weight to each column equal to the value of the column in the master LP solution. It then forms columns of weight one by accumulating the columns of the fractional solution. If columns are integral, the solution is integral. This is a heuristic procedure so it can miss some integer solutions.

If the solution is integral, the essential cut callback is called to make sure it is feasible.

References:

Go back to the column generation iteration overview.

Update incumbent primal solution

If the solution to master LP is integral and better than the current best one, we need to update the incumbent. This solution is then used by the tree-search algorithm in the bounding mechanism that prunes the nodes.

References:

Go back to the column generation iteration overview.

Reduced costs calculation

Reduced costs calculation is written as a math operation in the run_colgen_iteration! generic function. As a consequence, the dual solution to the master LP and the implementation of the two following methods must return data structures that support math operations.

To speed up this operation, we cache data in the following data structure:

Coluna.Algorithm.ReducedCostsCalculationHelper — Type

Extracted information to speed-up calculation of reduced costs of subproblem representatives and pure master variables. We extract from the master the information we need to compute the reduced cost of DW subproblem variables:

  • dw_subprob_c contains the perenial cost of DW subproblem representative variables
  • dw_subprob_A is a submatrix of the master coefficient matrix that involves only DW subproblem representative variables.

We also extract from the master the information we need to compute the reduced cost of pure master variables:

  • pure_master_c contains the perenial cost of pure master variables
  • pure_master_A is a submatrix of the master coefficient matrix that involves only pure master variables.

Calculation is c - transpose(A) * master_lp_dual_solution.

This information is given to the generic implementation of the column generation algorithm through methods:

  • ColGen.getsubprobvarorigcosts
  • ColGen.getorigcoefmatrix
source

Reduced costs calculation also requires the implementation of the two following methods:

Go back to the column generation iteration overview.

Pricing subproblem iterator

The pricing strategy is basically an iterator used to iterate over the pricing subproblems to optimize at each iteration of the column generation. The context can serve as a memory of the pricing strategy to change the way we iterate over subproblems between each column generation iteration.

The default implementation iterates over all subproblems.

Here are the references for the interface:

Coluna.ColGen.AbstractPricingStrategy — Type

A pricing strategy defines how we iterate on pricing subproblems. A default pricing strategy consists in iterating on all pricing subproblems.

Basically, this object is used like this:

    pricing_strategy = ColGen.get_pricing_strategy(ctx, phase)
+    click id10 href "#Iteration-output" "Link to doc"

Optimize master LP

At each iteration, the algorithm requires a dual solution to the master LP to compute the reduced cost of subproblem variables.

The default implementation optimizes the master with an LP solver through MathOptInterface. It returns a primal and a dual solution.

In the default implementation, the master LP output is in the following data structure:

Coluna.Algorithm.ColGenMasterResult — Type

Output of the ColGen.optimize_master_lp_problem! method.

Contains result, an OptimizationState object that is the output of the SolveLpForm algorithm called to optimize the master LP problem.

source

References:

Coluna.ColGen.optimize_master_lp_problem! — Function
optimize_master_lp_problem!(master, context, env) -> MasterResult

Returns an instance of a custom object MasterResult that implements the following methods:

  • get_obj_val: objective value of the master (mandatory)
  • get_primal_sol: primal solution to the master (optional)
  • get_dual_sol: dual solution to the master (mandatory otherwise column generation stops)

It should at least return a dual solution (obtained with LP optimization or subgradient) otherwise column generation cannot continue.

source

You can see the additional methods to implement in the result data structures section.

Go back to the column generation iteration overview.

Check the integrality of the master LP solution

The algorithm checks the integrality of the primal solution to the master LP to improve the global primal bound of the branch-cut-price algorithm.

In the default implementation, the integrality check is done using the MathProg.proj_cols_is_integer method. It implements the procedure described in the paper (TODO). Basically, it sorts the column used in the master LP primal solution in lexicographic order. It assigns a weight to each column equal to the value of the column in the master LP solution. It then forms columns of weight one by accumulating the columns of the fractional solution. If columns are integral, the solution is integral. This is a heuristic procedure so it can miss some integer solutions.

If the solution is integral, the essential cut callback is called to make sure it is feasible.

References:

Go back to the column generation iteration overview.

Update incumbent primal solution

If the solution to master LP is integral and better than the current best one, we need to update the incumbent. This solution is then used by the tree-search algorithm in the bounding mechanism that prunes the nodes.

References:

Go back to the column generation iteration overview.

Reduced costs calculation

Reduced costs calculation is written as a math operation in the run_colgen_iteration! generic function. As a consequence, the dual solution to the master LP and the implementation of the two following methods must return data structures that support math operations.

To speed up this operation, we cache data in the following data structure:

Coluna.Algorithm.ReducedCostsCalculationHelper — Type

Extracted information to speed-up calculation of reduced costs of subproblem representatives and pure master variables. We extract from the master the information we need to compute the reduced cost of DW subproblem variables:

  • dw_subprob_c contains the perenial cost of DW subproblem representative variables
  • dw_subprob_A is a submatrix of the master coefficient matrix that involves only DW subproblem representative variables.

We also extract from the master the information we need to compute the reduced cost of pure master variables:

  • pure_master_c contains the perenial cost of pure master variables
  • pure_master_A is a submatrix of the master coefficient matrix that involves only pure master variables.

Calculation is c - transpose(A) * master_lp_dual_solution.

This information is given to the generic implementation of the column generation algorithm through methods:

  • ColGen.getsubprobvarorigcosts
  • ColGen.getorigcoefmatrix
source

Reduced costs calculation also requires the implementation of the two following methods:

Go back to the column generation iteration overview.

Pricing subproblem iterator

The pricing strategy is basically an iterator used to iterate over the pricing subproblems to optimize at each iteration of the column generation. The context can serve as a memory of the pricing strategy to change the way we iterate over subproblems between each column generation iteration.

The default implementation iterates over all subproblems.

Here are the references for the interface:

Coluna.ColGen.AbstractPricingStrategy — Type

A pricing strategy defines how we iterate on pricing subproblems. A default pricing strategy consists in iterating on all pricing subproblems.

Basically, this object is used like this:

    pricing_strategy = ColGen.get_pricing_strategy(ctx, phase)
     next = ColGen.pricing_strategy_iterate(pricing_strategy)
     while !isnothing(next)
         (sp_id, sp_to_solve), state = next
         # Solve the subproblem `sp_to_solve`.
         next = ColGen.pricing_strategy_iterate(pricing_strategy, state)
-    end
source
Coluna.ColGen.pricing_strategy_iterate — Function
pricing_strategy_iterate(pricing_strategy) -> ((sp_id, sp_to_solve), state)
-pricing_strategy_iterate(pricing_strategy, state) -> ((sp_id, sp_to_solve), state)

Returns an iterator with the first pricing subproblem that must be optimized. The next subproblem is returned by a call to Base.iterate using the information provided by this method.

source

Go back to the column generation iteration overview.

Pricing subproblem optimization

At each iteration, the algorithm requires primal solutions to the pricing subproblems. The generic function supports multi-column generation so you can return any number of solutions.

The default implementation supports optimization of the pricing subproblems using a MILP solver or a pricing callback. Non-robust valid inequalities are not supported by MILP solvers as they change the structure of the subproblems. When using a pricing callback, you must be aware of how Coluna calculates the reduced cost of a column:

The reduced cost of a column is split into three contributions:

  • the contribution of the subproblem variables that is the primal solution cost given the reduced cost of subproblem variables
  • the contribution of the non-robust constraints (i.e. master constraints that cannot be expressed using subproblem variables except the convexity constraint) that is not supported by MILP solver but that you must take into account in the pricing callback
  • the contribution of the master convexity constraint that is automatically taken into account by Coluna once the primal solution is returned.

Therefore, when you use a pricing callback, you must not discard some columns based only on the primal solution cost because you don't know the contribution of the convexity constraint.

Coluna.Algorithm.GeneratedColumn — Type

Solution to a pricing subproblem after a given optimization.

It contains:

  • column: the solution stored as a PrimalSolution object
  • red_cost: the reduced cost of the column
  • min_obj: a boolean indicating if the objective is to minimize or maximize
source
Coluna.Algorithm.ColGenPricingResult — Type

Output of the default implementation of ColGen.optimize_pricing_problem!.

It contains:

  • result: the output of the SolveIpForm algorithm called to optimize the pricing subproblem
  • columns: a vector of GeneratedColumn objects obtained by processing of the output of pricing subproblem optimization, it stores the reduced cost of each column
  • best_red_cost: the best reduced cost of the columns
source

References:

Coluna.ColGen.optimize_pricing_problem! — Function
optimize_pricing_problem!(ctx, sp, env, optimizer, mast_dual_sol) -> PricingResult

Returns a custom object PricingResult that must implement the following functions:

  • get_primal_sols: array of primal solution to the pricing subproblem
  • get_primal_bound: best reduced cost (optional ?)
  • get_dual_bound: dual bound of the pricing subproblem (used to compute the master dual bound)
  • master_dual_sol: dual solution $\pi^{\text{out}}$ to the master problem used to compute the real reduced cost of the column when stabilization is active
source

You can see the additional methods to implement in the result data structures section.

Go back to the column generation iteration overview.

Set of generated columns

You can define your data structure to manage the columns generated at a given iteration. Columns are inserted after the optimization of all pricing subproblems to allow the parallelization of the latter.

In the default implementation, we use the following data structure:

Coluna.Algorithm.ColumnsSet — Type

Stores a collection of columns.

It contains:

  • columns: a vector of GeneratedColumn objects by all pricing subproblems that will be inserted into the master
  • subprob_primal_solutions: an object that stores the best columns generated by each pricing subproblem at this iteration.
source
Coluna.Algorithm.SubprobPrimalSolsSet — Type

Columns generated at the current iteration that forms the "current primal solution". This is used to compute the Lagragian dual bound.

It contains:

  • primal_sols a dictionary that maps a formulation id to the best primal solution found by the pricing subproblem associated to this formulation
  • improve_master a dictionary that maps a formulation id to a boolean indicating if the best primal solution found by the pricing subproblem associated to this formulation has negative reduced cost

This structure also helps to compute the subgradient of the Lagrangian function.

source

In the default implementation, push_in_set! is responsible for checking if the column has improving reduced cost. Only columns with improving reduced cost are inserted in the set. The push_in_set! is also responsible to insert he best primal solution to each pricing problem into the SubprobPrimalSolsSet object.

References:

Coluna.ColGen.set_of_columns — Function

Returns an empty container that will store all the columns generated by the pricing problems during an iteration of the column generation algorithm. One must be able to iterate on this container to insert the columns in the master problem.

source
Coluna.ColGen.push_in_set! — Function

Pushes the column in the set of columns generated at a given iteration of the column generation algorithm. Columns stored in the set will then be considered for insertion in the master problem. Returns true if column was inserted in the set, false otherwise.

source

Go back to the column generation iteration overview.

Dual bound calculation

In the default implementation, given a vector $\pi \geq 0$ of dual values to the master constraints (1), the Lagrangian dual function is given by:

\[L(\pi) = \pi a + \sum_{k \in K} \max_{l_k \leq \mathbf{1} \lambda^k \leq u^k} (c^k - \pi A^k)\lambda^k + \max_{ \bar{l} \leq y \leq \bar{u}} (\bar{c} - \pi \bar{A})y\]

Let:

  • element $z_k(\pi) \leq \min_i (c^k_i - \pi A^k_i)$ be a lower bound on the solution value of the pricing problem
  • element $\bar{z}_j(\pi) = \bar{c} - \pi \bar{A}$ be the reduced cost of pure master variable $y_j$

Then, the Lagrangian dual function can be lower bounded by:

\[L(\pi) \geq \pi a + \sum_{k \in K} \max\{ z_k(\pi) \cdot l_k, z_k(\pi) \cdot u_k \} + \sum_{j \in J} \max\{ \bar{z}_j(\pi) \cdot \bar{l}_j, \bar{z}_j(\pi) \cdot \bar{u}_j\}\]

More precisely:

  • the first term is the contribution of the master obtained by removing the contribution of the convexity constraints (computed by ColGen.Algorithm._convexity_contrib), and the pure master variables (but you should see the third term) from the master LP solution value
  • the second term is the contribution of the subproblem variables which is the sum of the best solution value of each pricing subproblem multiplied by the lower and upper multiplicity of the subproblem depending on whether the reduced cost is negative or positive (this is computed by ColGen.Algorithm._subprob_contrib)
  • the third term is the contribution of the pure master variables which is taken into account by master LP value.

Therefore, we can compute the Lagrangian dual bound as follows:

master_lp_obj_val - convexity_contrib + sp_contrib

However, if the smoothing stabilization is active, we compute the dual bound at the sep-point. As a consequence, we can't use the master LP value because it corresponds to the dual solution at the out-point. We therefore need to compute the lagrangian dual bound by strictly applying the above formula.

References:

Coluna.ColGen.compute_dual_bound — Function
compute_dual_bound(ctx, phase, master_lp_obj_val, master_dbs, generated_columns, mast_dual_sol) -> Float64

Caculates the dual bound at a given iteration of column generation. The dual bound is composed of:

  • master_lp_obj_val: objective value of the master LP problem
  • master_dbs: dual values of the pricing subproblems
  • the contribution of the master convexity constraints that you should compute from mast_dual_sol.
source

Go back to the column generation iteration overview.

Columns insertion

The default implementation inserts into the master all the columns stored in the ColumnsSet object.

Reference:

Coluna.ColGen.insert_columns! — Function

Inserts columns into the master. Returns the number of columns inserted. Implementation is responsible for checking if the column must be inserted and warn the user if something unexpected happens.

source

Go back to the column generation iteration overview.

Iteration output

References:

Coluna.ColGen.new_iteration_output — Function
new_iteration_output(::Type{<:AbstractColGenIterationOutput}, args...) -> AbstractColGenIterationOutput

Arguments (i.e. arg...) of this function are the following:

  • min_sense: true if the objective is a minimization function; false otherwise
  • mlp: the optimal solution value of the master LP
  • db: the Lagrangian dual bound
  • nb_new_cols: the number of columns inserted into the master
  • new_cut_in_master: true if valid inequalities or new constraints added into the master; false otherwise
  • infeasible_master: true if the master is proven infeasible; false otherwise
  • unbounded_master: true if the master is unbounded; false otherwise
  • infeasible_subproblem: true if a pricing subproblem is proven infeasible; false otherwise
  • unbounded_subproblem: true if a pricing subproblem is unbounded; false otherwise
  • time_limit_reached: true if time limit is reached; false otherwise
  • master_primal_sol: the primal master LP solution
  • ip_primal_sol: the incumbent primal master solution
  • dual_sol: the dual master LP solution
source

Go back to the column generation iteration overview.

Getters for Result data structures

Method nameMasterPricing
is_unboundedXX
is_infeasibleXX
get_primal_solX
get_primal_solsX
get_dual_solX
get_obj_valX
get_primal_boundX
get_dual_boundX

References:

Coluna.ColGen.get_primal_bound — Function

Returns primal bound of the pricing subproblem; nothing if no primal bound is available and the initial dual bound returned by compute_sp_init_pb will be used to compute the pseudo dual bound.

source

Go back to the column generation iteration overview.

Getters for Output data structures

Method nameColGenPhaseIteration
get_nb_new_colsX
get_master_ip_primal_solXXX
get_master_lp_primal_solX
get_master_dual_solX
get_dual_boundXX
get_master_lp_primal_boundX
is_infeasibleX

References:

Go back to the column generation iteration overview.

Stabilization

Coluna provides a default implementation of the smoothing stabilization with a self-adjusted $\alpha$ parameter, $0 \leq \alpha < 1$.

At each iteration of the column generation algorithm, instead of generating columns for the dual solution to the master LP, we generate columns for a perturbed dual solution defined as follows:

\[\pi^{\text{sep}} = \alpha \pi^{\text{in}} + (1-\alpha) \pi^{\text{out}}\]

where $\pi^{\text{in}}$ is the dual solution that gives the best Lagrangian dual bound so far (also called stabilization center) and $\pi^{\text{out}}$ is the dual solution to the master LP at the current iteration. This solution is returned by the default implementation of Coluna.ColGen.get_stab_dual_sol.

Some elements of the column generation change when using stabilization.

  • Columns are generated using the smoothed dual solution $\pi^{\text{sep}}$ but we still need to compute the reduced cost of the columns using the original dual solution $\pi^{\text{out}}$.
  • The dual bound is computed using the smoothed dual solution $\pi^{\text{sep}}$.
  • The pseudo bound is computed using the smoothed dual solution $\pi^{\text{sep}}$.
  • The smoothed dual bound can result in the generation of no improving columns. This is called a misprice. In that case, we need to move away from the stabilization center $\pi^{\text{in}}$ by decreasing $\alpha$.

When using self-adjusted stabilization, the smoothing coefficient $\alpha$ is adjusted to make the smoothed dual solution $\pi^{\text{sep}}$ closer to the best possible dual solution on the line between $\pi^{\text{in}}$ and $\pi^{\text{out}}$ (i.e. where the subgradient of the current primal solution is perpendicular to the latter line). To compute the subgradient, we use the following data structure:

Coluna.Algorithm.SubgradientCalculationHelper — Type

Precompute information to speed-up calculation of subgradient of master variables. We extract from the master follwowing information:

  • a contains the perenial rhs of all master constraints except convexity constraints;
  • A is a submatrix of the master coefficient matrix that involves only representative of original variables (pure master vars + DW subproblem represtative vars)

Calculation is a - A * (m .* z) where :

  • m contains a multiplicity factor for each variable involved in the calculation (lower or upper sp multiplicity depending on variable reduced cost);
  • z is the concatenation of the solution to the master (for pure master vars) and pricing subproblems (for DW subproblem represtative vars).

Operation m .* z "mimics" a solution in the original space.

source

References:

Coluna.ColGen.update_stabilization_after_master_optim! — Function
update_stabilization_after_master_optim!(stab, phase, mast_dual_sol) -> Bool

Update stabilization after master optimization where mast_dual_sol is the dual solution to the master problem. Returns true if the stabilization will change the dual solution used for the pricing in the current column generation iteration, false otherwise.

source
Coluna.ColGen.update_stabilization_after_pricing_optim! — Function

Updates stabilization after pricing optimization where:

  • mast_dual_sol is the dual solution to the master problem
  • pseudo_db is the pseudo dual bound of the problem after optimization of the pricing problems
  • smooth_dual_sol is the current smoothed dual solution
source
Coluna.ColGen.update_stabilization_after_iter! — Function

Updates stabilization after an iteration of the column generation algorithm. Arguments:

  • stab is the stabilization data structure
  • ctx is the column generation context
  • master is the master problem
  • generated_columns is the set of generated columns
  • mast_dual_sol is the dual solution to the master problem
source
+
diff --git a/previews/PR1116/api/presolve/index.html b/previews/PR1116/api/presolve/index.html index 6324259c7..b988587d9 100644 --- a/previews/PR1116/api/presolve/index.html +++ b/previews/PR1116/api/presolve/index.html @@ -4,4 +4,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/api/storage/index.html b/previews/PR1116/api/storage/index.html index 8522d8d86..dc5cd509e 100644 --- a/previews/PR1116/api/storage/index.html +++ b/previews/PR1116/api/storage/index.html @@ -1,7 +1,7 @@ -Storage · Coluna.jl
GitHub

Storage API

API

To summarize from a developer's point of view, there is a one-to-one correspondence between storage unit types and record types. This correspondence is implemented by methods record_type(StorageUnitType) and storage_unit_type(RecordType).

The developer must also implement methods storage_unit(StorageUnitType) and record(RecordType, id, model, storage_unit) that must call constructors of the custom storage unit and one of its associated records. Arguments of record allow the developer to record the state of entities from both the storage unit and the model.

At last, he must implement restore_from_record!(storage_unit, model, record) to restore the state of the entities represented by the storage unit. Entities can be in the storage unit, the model, or both of them.

This page was generated using Literate.jl.

GitHub

Storage API

API

To summarize from a developer's point of view, there is a one-to-one correspondence between storage unit types and record types. This correspondence is implemented by methods record_type(StorageUnitType) and storage_unit_type(RecordType).

The developer must also implement methods storage_unit(StorageUnitType) and record(RecordType, id, model, storage_unit) that must call constructors of the custom storage unit and one of its associated records. Arguments of record allow the developer to record the state of entities from both the storage unit and the model.

At last, he must implement restore_from_record!(storage_unit, model, record) to restore the state of the entities represented by the storage unit. Entities can be in the storage unit, the model, or both of them.

This page was generated using Literate.jl.

+
diff --git a/previews/PR1116/api/treesearch/index.html b/previews/PR1116/api/treesearch/index.html index c5a265d2b..530915b59 100644 --- a/previews/PR1116/api/treesearch/index.html +++ b/previews/PR1116/api/treesearch/index.html @@ -1,7 +1,7 @@ -TreeSearch · Coluna.jl
GitHub

Tree search API

Danger

Update needed.

Now, we define the two concepts we'll use in the tree search algorithms: the node and the search space. The third concept is the explore strategy and implemented in Coluna.

Every tree search algorithm must be associated to a search space.

Implementing tree search interface

First, we indicate the type of search space used by our algorithms. Note that the type of the search space can depends on the configuration of the algorithm. So there is a 1-to-n relation between tree search algorithm configurations and search space. because one search space can be used by several tree search algorithms configuration.

Now, we implement the method that calls the constructor of a search space. The type of the search space is known from above method. A search space may receive information from the tree-search algorithm. The model, and input arguments are the same than those received by the tree search algorithm.

We implement the method that returns the root node. The definition of the root node depends on the search space.

Then, we implement the method that converts the branching rules into nodes for the tree search algorithm.

We implement the node_change method to update the search space called by the tree search algorithm just after it finishes to evaluate a node and chooses the next one. Be careful, this method is not called after the evaluation of a node when there is no more unevaluated nodes (i.e. tree exploration is finished).

There are two ways to store the state of a formulation at a given node. We can distribute information across the nodes or store the whole state at each node. We follow the second way (so we don't need previous).

Method after_conquer is a callback to do some operations after the conquer of a node and before the divide. Here, we update the best solution found after the conquer algorithm. We implement one method for each search space.

We implement getters to retrieve the input from the search space and the node. The input is passed to the conquer and the divide algorithms.

At last, we implement methods that will return the output of the tree search algorithms. We return the cost of the best solution found. We write one method for each search space.

API

Search space

Node

Additional methods needed for Coluna's algorithms:

Missing docstring.

Missing docstring for Coluna.TreeSearch.get_opt_state. Check Documenter's build log for details.

Missing docstring.

Missing docstring for Coluna.TreeSearch.get_records. Check Documenter's build log for details.

Tree search algorithm

Tree search algorithm for Coluna

The children method has a specific implementation for AbstractColunaSearchSpace` that involves following methods:

Coluna.Algorithm.node_change! — Function

Methods to perform operations before the tree search algorithm evaluates a node (current). This is useful to restore the state of the formulation for instance.

source
Coluna.Algorithm.get_input — Function

Returns the input that will be passed to an algorithm. The input can be built from information contained in a search space and a node.

source

This page was generated using Literate.jl.

GitHub

Tree search API

Danger

Update needed.

Now, we define the two concepts we'll use in the tree search algorithms: the node and the search space. The third concept is the explore strategy and implemented in Coluna.

Every tree search algorithm must be associated to a search space.

Implementing tree search interface

First, we indicate the type of search space used by our algorithms. Note that the type of the search space can depends on the configuration of the algorithm. So there is a 1-to-n relation between tree search algorithm configurations and search space. because one search space can be used by several tree search algorithms configuration.

Now, we implement the method that calls the constructor of a search space. The type of the search space is known from above method. A search space may receive information from the tree-search algorithm. The model, and input arguments are the same than those received by the tree search algorithm.

We implement the method that returns the root node. The definition of the root node depends on the search space.

Then, we implement the method that converts the branching rules into nodes for the tree search algorithm.

We implement the node_change method to update the search space called by the tree search algorithm just after it finishes to evaluate a node and chooses the next one. Be careful, this method is not called after the evaluation of a node when there is no more unevaluated nodes (i.e. tree exploration is finished).

There are two ways to store the state of a formulation at a given node. We can distribute information across the nodes or store the whole state at each node. We follow the second way (so we don't need previous).

Method after_conquer is a callback to do some operations after the conquer of a node and before the divide. Here, we update the best solution found after the conquer algorithm. We implement one method for each search space.

We implement getters to retrieve the input from the search space and the node. The input is passed to the conquer and the divide algorithms.

At last, we implement methods that will return the output of the tree search algorithms. We return the cost of the best solution found. We write one method for each search space.

API

Search space

Node

Additional methods needed for Coluna's algorithms:

Missing docstring.

Missing docstring for Coluna.TreeSearch.get_opt_state. Check Documenter's build log for details.

Missing docstring.

Missing docstring for Coluna.TreeSearch.get_records. Check Documenter's build log for details.

Tree search algorithm

Tree search algorithm for Coluna

The children method has a specific implementation for AbstractColunaSearchSpace` that involves following methods:

Coluna.Algorithm.node_change! — Function

Methods to perform operations before the tree search algorithm evaluates a node (current). This is useful to restore the state of the formulation for instance.

source
Coluna.Algorithm.get_input — Function

Returns the input that will be passed to an algorithm. The input can be built from information contained in a search space and a node.

source

This page was generated using Literate.jl.

+
diff --git a/previews/PR1116/dynamic_sparse_arrays/index.html b/previews/PR1116/dynamic_sparse_arrays/index.html index 2074b470a..d1b4b0792 100644 --- a/previews/PR1116/dynamic_sparse_arrays/index.html +++ b/previews/PR1116/dynamic_sparse_arrays/index.html @@ -5,4 +5,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/index.html b/previews/PR1116/index.html index ebc266aea..e085fa03e 100644 --- a/previews/PR1116/index.html +++ b/previews/PR1116/index.html @@ -4,4 +4,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/man/algorithm/index.html b/previews/PR1116/man/algorithm/index.html index 448254002..b155eee9f 100644 --- a/previews/PR1116/man/algorithm/index.html +++ b/previews/PR1116/man/algorithm/index.html @@ -11,7 +11,7 @@ branchingtreefile = "", jsonfile = "", print_node_info = true -)

This algorithm is a branch and bound that uses a search tree to optimize the reformulation. At each node in the tree, it applies conqueralg to evaluate the node and improve the bounds, dividealg to generate branching constraints, and explorestrategy to select the next node to treat.

The three main elements of the algorithm are:

Parameters:

Options:

Warning: if you set a name for the branchingtreefile AND the jsonfile, the algorithm will only write in the json file.

source

Conquer, divide algorithms and the explore strategy available with the TreeSearchAlgorithm are listed in the following mind map.

mindmap +)

This algorithm is a branch and bound that uses a search tree to optimize the reformulation. At each node in the tree, it applies conqueralg to evaluate the node and improve the bounds, dividealg to generate branching constraints, and explorestrategy to select the next node to treat.

The three main elements of the algorithm are:

Parameters:

Options:

Warning: if you set a name for the branchingtreefile AND the jsonfile, the algorithm will only write in the json file.

source

Conquer, divide algorithms and the explore strategy available with the TreeSearchAlgorithm are listed in the following mind map.

mindmap TreeSearchAlgorithm (conquer) BendersConquer @@ -28,17 +28,17 @@ cutgen = CutCallbacks(), primal_heuristics = ParameterizedHeuristic[ParamRestrictedMasterHeuristic()], max_nb_cut_rounds = 3 -)

Column-and-cut-generation based algorithm to find primal and dual bounds for a problem decomposed using Dantzig-Wolfe paradigm.

Parameters :

source
Missing docstring.

Missing docstring for Algorithm.RestrMasterLpConquer. Check Documenter's build log for details.

Divide algorithms

Coluna.Algorithm.NoBranching — Type

Divide algorithm that does nothing. It does not generate any child.

source
Coluna.Algorithm.ClassicBranching — Type
ClassicBranching(
+)

Column-and-cut-generation based algorithm to find primal and dual bounds for a problem decomposed using Dantzig-Wolfe paradigm.

Parameters :

  • colgen: column generation algorithm
  • cutgen: cut generation algorithm
  • primal_heuristics: heuristics to find a feasible solution
  • max_nb_cut_rounds : number of cut generation done by the algorithm
source
Missing docstring.

Missing docstring for Algorithm.RestrMasterLpConquer. Check Documenter's build log for details.

Divide algorithms

Coluna.Algorithm.NoBranching — Type

Divide algorithm that does nothing. It does not generate any child.

source
Coluna.Algorithm.ClassicBranching — Type
ClassicBranching(
     selection_criterion = MostFractionalCriterion()
     rules = [Branching.PrioritisedBranchingRule(SingleVarBranchingRule(), 1.0, 1.0)]
     int_tol = 1e-6
-)

Chooses the best candidate according to a selection criterion and generates the two children.

Parameters

  • selection_criterion: selection criterion to choose the best candidate
  • rules: branching rules to generate the candidates
  • int_tol: tolerance to determine if a variable is integer

It is implemented as a specific case of the strong branching algorithm.

source

Strong branching is the main algorithm that we provide and it is the default implementation of the Branching submodule. You can have more information about the algorithm by reading the Branching submodule documentation.

Coluna.Algorithm.StrongBranching — Type
StrongBranching(
+)

Chooses the best candidate according to a selection criterion and generates the two children.

Parameters

  • selection_criterion: selection criterion to choose the best candidate
  • rules: branching rules to generate the candidates
  • int_tol: tolerance to determine if a variable is integer

It is implemented as a specific case of the strong branching algorithm.

source

Strong branching is the main algorithm that we provide and it is the default implementation of the Branching submodule. You can have more information about the algorithm by reading the Branching submodule documentation.

Coluna.Algorithm.StrongBranching — Type
StrongBranching(
     phases = [],
     rules = [Branching.PrioritisedBranchingRule(SingleVarBranchingRule(), 1.0, 1.0)],
     selection_criterion = MostFractionalCriterion(),
     verbose = true,
     int_tol = 1e-6
-)

The algorithm that performs a (multi-phase) (strong) branching in a tree search algorithm.

Strong branching is a procedure that heuristically selects a branching constraint that potentially gives the best progress of the dual bound. The procedure selects a collection of branching candidates based on their branching rule and their score. Then, the procedure evaluates the progress of the dual bound in both branches of each branching candidate by solving both potential children using a conquer algorithm. The candidate that has the largest product of dual bound improvements in the branches is chosen to be the branching constraint.

When the dual bound improvement produced by the branching constraint is difficult to compute (e.g. time-consuming in the context of column generation), one can let the branching algorithm quickly estimate the dual bound improvement of each candidate and retain the most promising branching candidates. This is called a phase. The goal is to first evaluate a large number of candidates with a very fast conquer algorithm and retain a certain number of promising ones. Then, over the phases, it evaluates the improvement with a more precise conquer algorithm and restrict the number of retained candidates until only one is left.

Parameters:

source

All the possible algorithms that can be used within the strong branching are listed in the following mind map.

mindmap +)

The algorithm that performs a (multi-phase) (strong) branching in a tree search algorithm.

Strong branching is a procedure that heuristically selects a branching constraint that potentially gives the best progress of the dual bound. The procedure selects a collection of branching candidates based on their branching rule and their score. Then, the procedure evaluates the progress of the dual bound in both branches of each branching candidate by solving both potential children using a conquer algorithm. The candidate that has the largest product of dual bound improvements in the branches is chosen to be the branching constraint.

When the dual bound improvement produced by the branching constraint is difficult to compute (e.g. time-consuming in the context of column generation), one can let the branching algorithm quickly estimate the dual bound improvement of each candidate and retain the most promising branching candidates. This is called a phase. The goal is to first evaluate a large number of candidates with a very fast conquer algorithm and retain a certain number of promising ones. Then, over the phases, it evaluates the improvement with a more precise conquer algorithm and restrict the number of retained candidates until only one is left.

Parameters:

source

All the possible algorithms that can be used within the strong branching are listed in the following mind map.

mindmap StrongBranching (phases) (conquer) @@ -52,16 +52,16 @@ SingleVarBranchingRule (selection_criterion) FirstFoundCriterion - MostFractionalCriterion

Explore strategies

Coluna.TreeSearch.DepthFirstStrategy — Type

Explore the tree search space with a depth-first strategy. The next visited node is the last one pushed in the stack of unexplored nodes.

source
Coluna.TreeSearch.BestDualBoundStrategy — Type

Explore the tree search space with a best-first strategy. The next visited node is the one with the highest local dual bound.

source

Cut generation algorithms

Coluna.Algorithm.BendersCutGeneration — Type
Coluna.Algorithm.BendersCutGeneration(
+            MostFractionalCriterion

Explore strategies

Cut generation algorithms

Coluna.Algorithm.BendersCutGeneration — Type
Coluna.Algorithm.BendersCutGeneration(
     restr_master_solve_alg = SolveLpForm(get_dual_sol = true, relax_integrality = true),
     restr_master_optimizer_id = 1,
     separation_solve_alg = SolveLpForm(get_dual_sol = true, relax_integrality = true)
     max_nb_iterations::Int = 100,
-)

Benders cut generation algorithm that can be applied to a formulation reformulated using Benders decomposition.

This algorithm is an implementation of the generic algorithm provided by the Benders submodule.

Parameters:

  • restr_master_solve_alg: algorithm to solve the restricted master problem
  • restr_master_optimizer_id: optimizer id to use to solve the restricted master problem
  • separation_solve_alg: algorithm to solve the separation problem (must be a LP solver that returns a dual solution)

Option:

  • max_nb_iterations: maximum number of iterations

About the output

At each iteration, the Benders cut generation algorithm show following statistics:

<it=  6> <et= 0.05> <mst= 0.00> <sp= 0.00> <cuts= 0> <master=  293.5000>

where:

  • it stands for the current number of iterations of the algorithm
  • et is the elapsed time in seconds since Coluna has started the optimisation
  • mst is the time in seconds spent solving the master problem at the current iteration
  • sp is the time in seconds spent solving the separation problem at the current iteration
  • cuts is the number of cuts generated at the current iteration
  • master is the objective value of the master problem at the current iteration

Debug options (print at each iteration):

  • debug_print_master: print the master problem
  • debug_print_master_primal_solution: print the master problem with the primal solution
  • debug_print_master_dual_solution: print the master problem with the dual solution (make sure the restr_master_solve_alg returns a dual solution)
  • debug_print_subproblem: print the subproblem
  • debug_print_subproblem_primal_solution: print the subproblem with the primal solution
  • debug_print_subproblem_dual_solution: print the subproblem with the dual solution
  • debug_print_generated_cuts: print the generated cuts
source
Coluna.Algorithm.CutCallbacks — Type
CutCallbacks(
+)

Benders cut generation algorithm that can be applied to a formulation reformulated using Benders decomposition.

This algorithm is an implementation of the generic algorithm provided by the Benders submodule.

Parameters:

  • restr_master_solve_alg: algorithm to solve the restricted master problem
  • restr_master_optimizer_id: optimizer id to use to solve the restricted master problem
  • separation_solve_alg: algorithm to solve the separation problem (must be a LP solver that returns a dual solution)

Option:

  • max_nb_iterations: maximum number of iterations

About the output

At each iteration, the Benders cut generation algorithm show following statistics:

<it=  6> <et= 0.05> <mst= 0.00> <sp= 0.00> <cuts= 0> <master=  293.5000>

where:

  • it stands for the current number of iterations of the algorithm
  • et is the elapsed time in seconds since Coluna has started the optimisation
  • mst is the time in seconds spent solving the master problem at the current iteration
  • sp is the time in seconds spent solving the separation problem at the current iteration
  • cuts is the number of cuts generated at the current iteration
  • master is the objective value of the master problem at the current iteration

Debug options (print at each iteration):

  • debug_print_master: print the master problem
  • debug_print_master_primal_solution: print the master problem with the primal solution
  • debug_print_master_dual_solution: print the master problem with the dual solution (make sure the restr_master_solve_alg returns a dual solution)
  • debug_print_subproblem: print the subproblem
  • debug_print_subproblem_primal_solution: print the subproblem with the primal solution
  • debug_print_subproblem_dual_solution: print the subproblem with the dual solution
  • debug_print_generated_cuts: print the generated cuts
source
Coluna.Algorithm.CutCallbacks — Type
CutCallbacks(
     call_robust_facultative = true,
     call_robust_essential = true,
     tol::Float64 = 1e-6
-)

Runs the cut user callbacks attached to a formulation.

Parameters:

  • call_robust_facultative: if true, call all the robust facultative cut user callbacks (i.e. user cut callbacks)
  • call_robust_essential: if true, call all the robust essential cut user callbacks (i.e. lazy constraint callbacks)
  • tol: tolerance used to determine if a cut is violated

See the JuMP documentation for more information about user callbacks and the tutorials in the Coluna documentation for examples of user callbacks.

source

Column generation algorithms

Coluna.Algorithm.ColumnGeneration — Type
Coluna.Algorithm.ColumnGeneration(
+)

Runs the cut user callbacks attached to a formulation.

Parameters:

  • call_robust_facultative: if true, call all the robust facultative cut user callbacks (i.e. user cut callbacks)
  • call_robust_essential: if true, call all the robust essential cut user callbacks (i.e. lazy constraint callbacks)
  • tol: tolerance used to determine if a cut is violated

See the JuMP documentation for more information about user callbacks and the tutorials in the Coluna documentation for examples of user callbacks.

source

Column generation algorithms

Coluna.Algorithm.ColumnGeneration — Type
Coluna.Algorithm.ColumnGeneration(
     restr_master_solve_alg = SolveLpForm(get_dual_sol = true),
     pricing_prob_solve_alg = SolveIpForm(
         moi_params = MoiOptimize(
@@ -77,27 +77,27 @@
     cleanup_threshold = 10000,
     cleanup_ratio = 0.66,
     smoothing_stabilization = 0.0 # should be in [0, 1],
-)

Column generation algorithm that can be applied to formulation reformulated using Dantzig-Wolfe decomposition.

This algorithm first solves the linear relaxation of the master (master LP) using restr_master_solve_alg. Then, it solves the subproblems by calling pricing_prob_solve_alg to get the columns that have the best reduced costs and that hence, may improve the master LP's objective the most.

In order for the algorithm to converge towards the optimal solution of the master LP, it suffices that the pricing oracle returns, at each iteration, a negative reduced cost solution if one exists. The algorithm stops when all subproblems fail to generate a column with negative (positive) reduced cost in the case of a minimization (maximization) problem or when it reaches the maximum number of iterations.

Parameters:

  • restr_master_solve_alg: algorithm to optimize the master LP
  • pricing_prob_solve_alg: algorithm to optimize the subproblems
  • essential_cut_gen_alg: algorithm to generate essential cuts which is run when the solution of the master LP is integer.

Options:

  • max_nb_iterations: maximum number of iterations
  • log_print_frequency: display frequency of iterations statistics

Undocumented parameters are in alpha version.

About the ouput

At each iteration (depending on log_print_frequency), the column generation algorithm can display following statistics.

<it= 90> <et=15.62> <mst= 0.02> <sp= 0.05> <cols= 4> <al= 0.00> <DB=  300.2921> <mlp=  310.3000> <PB=310.3000>

Here are their meanings :

  • it stands for the current number of iterations of the algorithm
  • et is the elapsed time in seconds since Coluna has started the optimisation
  • mst is the time in seconds spent solving the master LP at the current iteration
  • sp is the time in seconds spent solving the subproblems at the current iteration
  • cols is the number of column generated by the subproblems at the current iteration
  • al is the smoothing factor of the stabilisation at the current iteration (alpha version)
  • DB is the dual bound of the master LP at the current iteration
  • mlp is the objective value of the master LP at the current iteration
  • PB is the objective value of the best primal solution found by Coluna at the current iteration
source

External call to optimize a linear program

Coluna.Algorithm.SolveLpForm — Type
Coluna.Algorithm.SolveLpForm(
+)

Column generation algorithm that can be applied to formulation reformulated using Dantzig-Wolfe decomposition.

This algorithm first solves the linear relaxation of the master (master LP) using restr_master_solve_alg. Then, it solves the subproblems by calling pricing_prob_solve_alg to get the columns that have the best reduced costs and that hence, may improve the master LP's objective the most.

In order for the algorithm to converge towards the optimal solution of the master LP, it suffices that the pricing oracle returns, at each iteration, a negative reduced cost solution if one exists. The algorithm stops when all subproblems fail to generate a column with negative (positive) reduced cost in the case of a minimization (maximization) problem or when it reaches the maximum number of iterations.

Parameters:

  • restr_master_solve_alg: algorithm to optimize the master LP
  • pricing_prob_solve_alg: algorithm to optimize the subproblems
  • essential_cut_gen_alg: algorithm to generate essential cuts which is run when the solution of the master LP is integer.

Options:

  • max_nb_iterations: maximum number of iterations
  • log_print_frequency: display frequency of iterations statistics

Undocumented parameters are in alpha version.

About the ouput

At each iteration (depending on log_print_frequency), the column generation algorithm can display following statistics.

<it= 90> <et=15.62> <mst= 0.02> <sp= 0.05> <cols= 4> <al= 0.00> <DB=  300.2921> <mlp=  310.3000> <PB=310.3000>

Here are their meanings :

  • it stands for the current number of iterations of the algorithm
  • et is the elapsed time in seconds since Coluna has started the optimisation
  • mst is the time in seconds spent solving the master LP at the current iteration
  • sp is the time in seconds spent solving the subproblems at the current iteration
  • cols is the number of column generated by the subproblems at the current iteration
  • al is the smoothing factor of the stabilisation at the current iteration (alpha version)
  • DB is the dual bound of the master LP at the current iteration
  • mlp is the objective value of the master LP at the current iteration
  • PB is the objective value of the best primal solution found by Coluna at the current iteration
source

External call to optimize a linear program

Coluna.Algorithm.SolveLpForm — Type
Coluna.Algorithm.SolveLpForm(
     get_ip_primal_sol = false,
     get_dual_sol = false,
     relax_integrality = false,
     get_dual_bound = false,
     silent = true
-)

Solve a linear program stored in a formulation using its first optimizer. This algorithm works only if the optimizer is interfaced with MathOptInterface.

You can define the optimizer using the default_optimizer attribute of Coluna or with the method specify! from BlockDecomposition

Parameters:

  • get_ip_primal_sol: update the primal solution of the formulation if equals true
  • get_dual_sol: retrieve the dual solution and store it in the ouput if equals true
  • relax_integrality: relax integer variables of the formulation before optimization if equals true
  • get_dual_bound: store the dual objective value in the output if equals true
  • silent: set MOI.Silent() to its value

Undocumented parameters are alpha.

source

External call to optimize a mixed-integer program / combinatorial problem

Coluna.Algorithm.SolveIpForm — Type
Coluna.Algorithm.SolveIpForm(
+)

Solve a linear program stored in a formulation using its first optimizer. This algorithm works only if the optimizer is interfaced with MathOptInterface.

You can define the optimizer using the default_optimizer attribute of Coluna or with the method specify! from BlockDecomposition

Parameters:

  • get_ip_primal_sol: update the primal solution of the formulation if equals true
  • get_dual_sol: retrieve the dual solution and store it in the ouput if equals true
  • relax_integrality: relax integer variables of the formulation before optimization if equals true
  • get_dual_bound: store the dual objective value in the output if equals true
  • silent: set MOI.Silent() to its value

Undocumented parameters are alpha.

source

External call to optimize a mixed-integer program / combinatorial problem

Coluna.Algorithm.SolveIpForm — Type
Coluna.Algorithm.SolveIpForm(
     optimizer_id = 1
     moi_params = MoiOptimize()
     user_params = UserOptimize()
     custom_params = CustomOptimize()
-)

Solve an optimization problem. This algorithm can call different type of optimizers :

  • subsolver interfaced with MathOptInterface to optimize a mixed integer program
  • pricing callback defined by the user
  • custom optimizer to solve a custom model

You can specify an optimizer using the default_optimizer attribute of Coluna or with the method specify! from BlockDecomposition. If you want to define several optimizers for a given subproblem, you must use specify!:

specify!(subproblem, optimizers = [optimizer1, optimizer2, optimizer3])

Value of optimizer_id is the position of the optimizer you want to use. For example, if optimizer_id is equal to 2, the algorithm will use optimizer2.

By default, the algorihm uses the first optimizer or the default optimizer if no optimizer has been specified through specify!.

Depending on the type of the optimizer chosen, the algorithm will use one the three configurations :

  • moi_params for subsolver interfaced with MathOptInterface
  • user_params for pricing callbacks
  • custom_params for custom solvers

Custom solver is undocumented because alpha.

source
Coluna.Algorithm.MoiOptimize — Type
MoiOptimize(
+)

Solve an optimization problem. This algorithm can call different type of optimizers :

  • subsolver interfaced with MathOptInterface to optimize a mixed integer program
  • pricing callback defined by the user
  • custom optimizer to solve a custom model

You can specify an optimizer using the default_optimizer attribute of Coluna or with the method specify! from BlockDecomposition. If you want to define several optimizers for a given subproblem, you must use specify!:

specify!(subproblem, optimizers = [optimizer1, optimizer2, optimizer3])

Value of optimizer_id is the position of the optimizer you want to use. For example, if optimizer_id is equal to 2, the algorithm will use optimizer2.

By default, the algorihm uses the first optimizer or the default optimizer if no optimizer has been specified through specify!.

Depending on the type of the optimizer chosen, the algorithm will use one the three configurations :

  • moi_params for subsolver interfaced with MathOptInterface
  • user_params for pricing callbacks
  • custom_params for custom solvers

Custom solver is undocumented because alpha.

source
Coluna.Algorithm.MoiOptimize — Type
MoiOptimize(
     time_limit = 600
     deactivate_artificial_vars = false
     enforce_integrality = false
     get_dual_bound = true
-)

Configuration for an optimizer that calls a subsolver through MathOptInterface.

Parameters:

  • time_limit: in seconds
  • deactivate_artificial_vars: deactivate all artificial variables of the formulation if equals true
  • enforce_integrality: enforce integer variables that are relaxed if equals true
  • get_dual_bound: store the dual objective value in the output if equals true
source
Coluna.Algorithm.UserOptimize — Type
UserOptimize(
+)

Configuration for an optimizer that calls a subsolver through MathOptInterface.

Parameters:

  • time_limit: in seconds
  • deactivate_artificial_vars: deactivate all artificial variables of the formulation if equals true
  • enforce_integrality: enforce integer variables that are relaxed if equals true
  • get_dual_bound: store the dual objective value in the output if equals true
source
Coluna.Algorithm.UserOptimize — Type
UserOptimize(
     max_nb_ip_primal_sols = 50
-)

Configuration for an optimizer that calls a pricing callback to solve the problem.

Parameters:

  • max_nb_ip_primal_sols: maximum number of solutions returned by the callback kept
source
+ diff --git a/previews/PR1116/man/blockdecomposition/index.html b/previews/PR1116/man/blockdecomposition/index.html index 2e76ef1fe..9b39b1b78 100644 --- a/previews/PR1116/man/blockdecomposition/index.html +++ b/previews/PR1116/man/blockdecomposition/index.html @@ -23,4 +23,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/man/callbacks/index.html b/previews/PR1116/man/callbacks/index.html index 20863e84b..2771f8179 100644 --- a/previews/PR1116/man/callbacks/index.html +++ b/previews/PR1116/man/callbacks/index.html @@ -1,7 +1,7 @@ -User-defined Callbacks · Coluna.jl
GitHub

User-defined Callbacks

Callbacks are functions defined by the user that allow him to take over part of the default conquer algorithm. The more classical callbacks in Branch-and-Cut and Branch-and-Price solvers are:

  • Pricing callback (only in Branch-and-Price solvers) that takes over the procedure to determine whether the current master LP solution is optimum or produces an entering variable with negative reduced cost by solving subproblems
  • Separation callback that takes over the procedure to determine whether the current master LP solution is feasible or produces a valid problem constraint that is violated
  • Branching callback that takes over the procedure to determine whether the current master LP solution is integer or produces a valid branching disjunctive constraint that rules out the current fractional solution.
Note

You can't change the original formulation in a callback because Coluna does not propagate the changes into the reformulation and does not check if the solutions found are still feasible.

Pricing callbacks

Pricing callbacks let you define how to solve the subproblems of a Dantzig-Wolfe decomposition to generate a new entering column in the master program. This callback is useful when you know an efficient algorithm to solve the subproblems, i.e. an algorithm better than solving the subproblem with a MIP solver.

See the example in the tutorial section.

Errors and Warnings

Coluna.Algorithm.IncorrectPricingDualBound — Type
IncorrectPricingDualBound

Error thrown when transmitting a dual bound larger than the primal bound of the best solution to the pricing subproblem found in a run of the pricing callback.

source
Coluna.Algorithm.MissingPricingDualBound — Type
MissingPricingDualBound

Error thrown when the pricing callback does not transmit any dual bound. Make sure you call MOI.submit(model, BD.PricingDualBound(cbdata), db) in your pricing callback.

source
Coluna.Algorithm.MultiplePricingDualBounds — Type
MultiplePricingDualBounds

Error thrown when the pricing transmits multiple dual bound. Make sure you call MOI.submit(model, BD.PricingDualBound(cbdata), db) only once in your pricing callback.

source

Separation callbacks

Separation callbacks let you define how to separate cuts or constraints.

Facultative & essential cuts (user cut & lazy constraint)

This callback allows you to add cuts to the master problem. The cuts must be expressed in terms of the original variables. Then, Coluna expresses them over the master variables. You can find an example of essential cut separation and facultative cut separation in the JuMP documentation.

GitHub

User-defined Callbacks

Callbacks are functions defined by the user that allow him to take over part of the default conquer algorithm. The more classical callbacks in Branch-and-Cut and Branch-and-Price solvers are:

  • Pricing callback (only in Branch-and-Price solvers) that takes over the procedure to determine whether the current master LP solution is optimum or produces an entering variable with negative reduced cost by solving subproblems
  • Separation callback that takes over the procedure to determine whether the current master LP solution is feasible or produces a valid problem constraint that is violated
  • Branching callback that takes over the procedure to determine whether the current master LP solution is integer or produces a valid branching disjunctive constraint that rules out the current fractional solution.
Note

You can't change the original formulation in a callback because Coluna does not propagate the changes into the reformulation and does not check if the solutions found are still feasible.

Pricing callbacks

Pricing callbacks let you define how to solve the subproblems of a Dantzig-Wolfe decomposition to generate a new entering column in the master program. This callback is useful when you know an efficient algorithm to solve the subproblems, i.e. an algorithm better than solving the subproblem with a MIP solver.

See the example in the tutorial section.

Errors and Warnings

Coluna.Algorithm.IncorrectPricingDualBound — Type
IncorrectPricingDualBound

Error thrown when transmitting a dual bound larger than the primal bound of the best solution to the pricing subproblem found in a run of the pricing callback.

source
Coluna.Algorithm.MissingPricingDualBound — Type
MissingPricingDualBound

Error thrown when the pricing callback does not transmit any dual bound. Make sure you call MOI.submit(model, BD.PricingDualBound(cbdata), db) in your pricing callback.

source
Coluna.Algorithm.MultiplePricingDualBounds — Type
MultiplePricingDualBounds

Error thrown when the pricing transmits multiple dual bound. Make sure you call MOI.submit(model, BD.PricingDualBound(cbdata), db) only once in your pricing callback.

source

Separation callbacks

Separation callbacks let you define how to separate cuts or constraints.

Facultative & essential cuts (user cut & lazy constraint)

This callback allows you to add cuts to the master problem. The cuts must be expressed in terms of the original variables. Then, Coluna expresses them over the master variables. You can find an example of essential cut separation and facultative cut separation in the JuMP documentation.

+
diff --git a/previews/PR1116/man/config/index.html b/previews/PR1116/man/config/index.html index 3694119a4..3b1f03dab 100644 --- a/previews/PR1116/man/config/index.html +++ b/previews/PR1116/man/config/index.html @@ -3,9 +3,9 @@ solver = Coluna.Algorithm.TreeSearchAlgorithm(), global_art_var_cost = 10e6, local_art_var_cost = 10e4 -)

Parameters of Coluna :

source

default_optimizer

todo

Other Supported Parameters

From BlockDecomposition

BlockDecomposition.objectiveprimalbound! — Function
objectiveprimalbound!(model, pb)

Define a primal bound on the optimal objective value (upper bound for a minimisation, lower bound for a maximisation).

source
BlockDecomposition.objectivedualbound! — Function
objectivedualbound!(model, db)

Define a dual bound on the optimal objective value. (lower bound for a minimisation, upper bound for a maximisation)

source

From MathOptInterface

todo

+ diff --git a/previews/PR1116/man/decomposition/index.html b/previews/PR1116/man/decomposition/index.html index 5d8289748..a53656bc1 100644 --- a/previews/PR1116/man/decomposition/index.html +++ b/previews/PR1116/man/decomposition/index.html @@ -35,4 +35,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/man/presolve/index.html b/previews/PR1116/man/presolve/index.html index 1c31e27ef..e900bb3e3 100644 --- a/previews/PR1116/man/presolve/index.html +++ b/previews/PR1116/man/presolve/index.html @@ -4,4 +4,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/qa/index.html b/previews/PR1116/qa/index.html index 1c82d3d51..0150130a1 100644 --- a/previews/PR1116/qa/index.html +++ b/previews/PR1116/qa/index.html @@ -25,4 +25,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/start/advanced_demo/index.html b/previews/PR1116/start/advanced_demo/index.html index 48184e9d1..cf5d3fdd0 100644 --- a/previews/PR1116/start/advanced_demo/index.html +++ b/previews/PR1116/start/advanced_demo/index.html @@ -562,4 +562,4 @@ startOnLoad: true, theme: "neutral" }); - + diff --git a/previews/PR1116/start/custom_data/index.html b/previews/PR1116/start/custom_data/index.html index 278726dcd..4f1568f8c 100644 --- a/previews/PR1116/start/custom_data/index.html +++ b/previews/PR1116/start/custom_data/index.html @@ -14,7 +14,7 @@ ) ) );

Let's define the model. Let's $B$ the set of bins and $I$ the set of items. We introduce variable $y_b$ that is equal to 1 if a bin $b$ is used and 0 otherwise. We introduce variable $x_{b,i}$ that is equal to 1 if item $i$ is put in a bin $b$ and 0 otherwise.

model = BlockModel(coluna);

We must assign three items:

I = [1, 2, 3];

And we have three bins:

B = [1, 2, 3];

Each bin is defining a subproblem, we declare our axis:

@axis(axis, collect(B));

We declare subproblem variables y[b]:

@variable(model, y[b in axis], Bin);

And x[b,i]:

@variable(model, x[b in axis, i in I], Bin);

Each item must be assigned to one bin:

@constraint(model, sp[i in I], sum(x[b,i] for b in axis) == 1);

We minimize the number of bins and we declare the decomposition:

@objective(model, Min, sum(y[b] for b in axis))
-@dantzig_wolfe_decomposition(model, dec, axis);

Custom data for non-robust cuts

As said previously, at the end of the column generation at the root node, the master LP solution has 1.5 bins. It corresponds to three bins, each of them used 0.5 times containing one pair (1,2), (1, 3), or (2, 3) of items. We are going to introduce the following non-robust cut to make the master LP solution integral:

\[\sum\limits_{s \in S~if~length(s) \geq 2} λ_s \leq 1\]

where :

This cut means that we cannot have more than one bin with at least two items.

But the problem is that the cut is expressed over the master column and we don't have access to these variables from the JuMP model. To address this problem, Coluna offers a way to compute the coefficient of a column in a constraint by implementing the following method:

Coluna.MathProg.computecoeff — Function
computecoeff(var_custom_data, constr_custom_data) -> Float64

Dispatches on the type of custom data attached to the variable and the constraint to compute the coefficient of the variable in the constraint.

source

We therefore need to attach custom data to the master columns and the non-robust cut to use the method compute_coeff.

For every subproblem solution $s$, we define custom data with the number of items in the bin.

struct MyCustomVarData <: BlockDecomposition.AbstractCustomVarData
+@dantzig_wolfe_decomposition(model, dec, axis);

Custom data for non-robust cuts

As said previously, at the end of the column generation at the root node, the master LP solution has 1.5 bins. It corresponds to three bins, each of them used 0.5 times containing one pair (1,2), (1, 3), or (2, 3) of items. We are going to introduce the following non-robust cut to make the master LP solution integral:

\[\sum\limits_{s \in S~if~length(s) \geq 2} λ_s \leq 1\]

where :

This cut means that we cannot have more than one bin with at least two items.

But the problem is that the cut is expressed over the master column and we don't have access to these variables from the JuMP model. To address this problem, Coluna offers a way to compute the coefficient of a column in a constraint by implementing the following method:

Coluna.MathProg.computecoeff — Function
computecoeff(var_custom_data, constr_custom_data) -> Float64

Dispatches on the type of custom data attached to the variable and the constraint to compute the coefficient of the variable in the constraint.

source

We therefore need to attach custom data to the master columns and the non-robust cut to use the method compute_coeff.

For every subproblem solution $s$, we define custom data with the number of items in the bin.

struct MyCustomVarData <: BlockDecomposition.AbstractCustomVarData
     nb_items::Int
 end
 BlockDecomposition.customvars!(model, MyCustomVarData);

We define custom data for the cut that will contain the minimum number of items in a bin that can be used. The value will be 2 in this example.

struct MyCustomCutData <: BlockDecomposition.AbstractCustomConstrData
@@ -116,4 +116,4 @@
     startOnLoad: true,
     theme: "neutral"
 });
-
+
diff --git a/previews/PR1116/start/cuts/index.html b/previews/PR1116/start/cuts/index.html
index 7f68491dd..ca93930d6 100644
--- a/previews/PR1116/start/cuts/index.html
+++ b/previews/PR1116/start/cuts/index.html
@@ -70,4 +70,4 @@
     startOnLoad: true,
     theme: "neutral"
 });
-
+
diff --git a/previews/PR1116/start/identical_sp/index.html b/previews/PR1116/start/identical_sp/index.html
index e4d50110c..d0aa6cf54 100644
--- a/previews/PR1116/start/identical_sp/index.html
+++ b/previews/PR1116/start/identical_sp/index.html
@@ -68,4 +68,4 @@
     startOnLoad: true,
     theme: "neutral"
 });
-
+
diff --git a/previews/PR1116/start/initial_columns/index.html b/previews/PR1116/start/initial_columns/index.html
index a904c8f3e..cc4034ee1 100644
--- a/previews/PR1116/start/initial_columns/index.html
+++ b/previews/PR1116/start/initial_columns/index.html
@@ -47,4 +47,4 @@
     startOnLoad: true,
     theme: "neutral"
 });
-
+
diff --git a/previews/PR1116/start/other_pbs/index.html b/previews/PR1116/start/other_pbs/index.html
index 663d3df93..8a94e2966 100644
--- a/previews/PR1116/start/other_pbs/index.html
+++ b/previews/PR1116/start/other_pbs/index.html
@@ -4,4 +4,4 @@
     startOnLoad: true,
     theme: "neutral"
 });
-
+
diff --git a/previews/PR1116/start/pricing/index.html b/previews/PR1116/start/pricing/index.html
index 81be6ea13..39381921e 100644
--- a/previews/PR1116/start/pricing/index.html
+++ b/previews/PR1116/start/pricing/index.html
@@ -60,4 +60,4 @@
     startOnLoad: true,
     theme: "neutral"
 });
-
+
diff --git a/previews/PR1116/start/start/index.html b/previews/PR1116/start/start/index.html
index 8ad7a6941..3ae179782 100644
--- a/previews/PR1116/start/start/index.html
+++ b/previews/PR1116/start/start/index.html
@@ -47,4 +47,4 @@
     startOnLoad: true,
     theme: "neutral"
 });
-
+