Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

init documentation for user-supplied parameters checkings #972

Merged
merged 2 commits into from
Jul 4, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ makedocs(
"User-defined Callbacks" => joinpath("man", "callbacks.md"),
],
"API" => Any[
"Verification of algorithms parameters and consistency" => joinpath("api", "check_algos.md"),
"Benders" => joinpath("api", "benders.md"),
"Branching" => joinpath("api", "branching.md"),
"ColGen" => joinpath("api", "colgen.md"),
Expand Down
98 changes: 98 additions & 0 deletions docs/src/api/check_algos.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Verification of algorithms parameters and consistency

The algorithms used in Coluna usually have many parameters and are sometimes interdependent and nested. As a result, it is crucial to perform checks when the user parameters the solver.
In this section, we describe the strategies put in place to ensure the consistency of the parameters and algorithms used.

## Abstract types

Several abstract types are used to organize, clarify and make code more concise.
```
"""
The generic type of any algorithm.
"""
abstract type AbstractAlgorithm end
```

```
"""
An algorithm that solves a MIP.
"""
abstract type AbstractSolver end
```

```
"""
An algorithm used in a tree search solver to evaluate (conquer) a node.
"""
abstract type AbstractConquerAlgo end
```

```
"""
An algorithm used in a tree search solver to generate nodes (branching).
"""
abstract type AbstractDivideAlgo end
```

```
"""
A decomposition of the MIP ahead of its resolution.
"""
abstract type AbstractDecomposition end
```

## Checking strategies

The entry point for user-supplied parameters is the ```optimize!``` function, which takes as input the model containing both the user-customized solver and the decomposition used. The entry point for checks ```check_model_consistency``` is therefore logically located at the start of ```optimize!```.

```
"""
Entry point for the user-supplied parameters checking.
"""
check_model_consistency(::Model) = nothing ## TODO
```

An initial compatibility check between solver and decomposition is performed before diving into the tree of algorithms used to check their consistency.

```
"""
Checks if the decomposition supplied by the user is compatible with the solver.
"""
support(::AbstractSolver, ::AbstractDecomposition) = nothing ## TODO
```

We then retrieve the child algorithms (i.e. the nested algorithms used as solver parameters)
```
"""
Returns all the algorithms used directly or indirectly by the solver.
"""
get_child_algorithms(::AbstractSolver) = nothing ## TODO
```

Each unit algorithm is responsible for checking the consistency of its input parameters via ```check_parameters```. Compatibility checks between algorithms are performed on the fly with redefinitions of method ```support```

```
"""
Checks the consistency of the parameters of the given algorithm.
"""
check_parameters(alg::AbstractAlgorithm) = nothing ## TODO
```
```
"""
Checks if a child algorithm can be called by a parent algorithm.
"""
support(parent::AbstractAlgorithm, child::AbstractAlgorithm) = nothing ##
```

The following diagram sums up the verification tree:

```mermaid
flowchart
model(model) --> consis1[check consistency \n between \n decomposition and solver]
consis1 --> |failed| fallback(fallback)
consis1 --> |passed| children[retrieve child algorithms \n from the solver]
children --> consis2[check child algorithms \n compatibility]
children --> param[check parameters for each \n child algorithm]
param --> |failed| fallback
consis2 --> |failed| fallback
```