# GeneralDichotomy

### A general and minimalist toolkit for multi-objective optimization

GeneralDichotomy is a library and a package to enumerate supported extreme solutions of general multi-objective optimization problems.

This package is **independent** of any single-objective optimization solver.
The user implements the `solving function` that is called by the GeneralDichotomy algorithm.
In return, the `solving function` provides to the algorithm the objective cost vector associated to the solution.
Solution assignments are managed by the user and they can be associated to the objective cost vectors from their indices at the end of the search.

Internally, the GeneralDichotomy algorithm relies on polytope vertices enumeration to maintain a precise description of the convex hull of the Pareto front.
Two polytope computation libraries can be currently used as backends: [CDD](https://github.com/cddlib/cddlib) and [PPL](https://github.com/BUGSENG/PPL).
This organized search procedure provide an **exhaustive** set of supported (extreme) solutions when such set is enumerable.
More generally, this tool can also be used with **stochastic** and **heuristic** optimizers to create a *proxy* of the Pareto convex hull.

The GeneralDichotomy core algorithm is implemented in C++.
A C++ and a Python interface are available for the user-side (see examples).
An additional Julia implementation interfaced with the [JuMP](https://jump.dev/) package is also available.


## build pygeneraldichotomy

Build and install from sources:

```
python -m build --wheel
pip install dist/*.whl
```

Build and test locally (for developers only):

```
cd "your_build_directory"
cmake .. [...]
cmake --build . -t pygdichotomy
export PYTHONPATH="your_build_directory"
python your_test_script.py
```

Or, in your python script:

```
import sys
sys.path.append("path_to_your_build_directory")
```

## Usage

The GeneralDichomy package can be used via the C++ or the Python programming interface.
In both cases, the used creates a class where they can implement the call to their solver (which can be run from an external package for instance).


## Library and package compilation

As a C++ library, the GeneralDichotomy development package must be compiled from its sources to be tested.
Compilation instructions can be found on the dedicated wiki page [[Library compilation|Library-compilation]].
Note that the Python binding also needs a compilation step.

## Examples

* Linear assignment [cpp,ortools]

`cmake --build . -t example_lap_cpp_otools`

* Linear assignment [cpp,toulbar2]

`cmake --build . -t example_lap_cpp_tb2`

* Linear assignment [python,pytoulbar2]

This example depends on the python package pytoulbar2 (python binding of the toulbar2 solver).
It can be installed via `pip install pytoulbar2` in a python environment.

To run the example from the example/python_lap directory:

`export PYTHONPATH="${PYTHONPATH}:generaldichotomy_build_dir/pydgichotomy" && python3 python_lap.py`

## Known issues

with python 3.12.3 on ubuntu 24.04 (apptainer env), ortools python package does not work with version 9.14.6206. It has been tested successfully with version 9.12.4544. 