MH-Builder framework

The GitLab project "mh-builder.git" integrates the following 2 elements:

The MH-Builder framework , which is a framework for designing adaptive metaheuristics for single and multi-objective optimization.
The MOCA-I software: this software uses a new algorithm called "MOCA-I" (Multi Objective Classification Algorithm for Imbalanced Data). The implementation of MOCA-I exploits a multi-objective local search algorithm provided by the MH-Builder framework.

1. How to install MH-Builder

1.1. Requirements

The framework has been developed in C++ language. The three following elements are required to download and then compile MH-Builder (including MOCA-I):

C++ compiler (version 20 or higher)
cmake (version 3.10 or higher)
git

Under Windows, the use of Cygwin is available.

1.1.1. Additional optional elements

Doxygen in order to obtain a detailed documentation of the source code. During the documentation generation, doxygen uses different graphical tools to provide visualization tools (such as UML-like diagrams): dia, plantuml, dot tool from graphviz
Google test Framework, note that the compilation process automatically download this framework.
matplotlib Python library for creating interactive visualizations. Python (version 3 or higher) is also required

1.2. Installing MH-Builder (and MOCA-I)

Download the last version by git clone :

git clone https://gitlab.cristal.univ-lille.fr/orkad-public/mh-builder.git

By default, the generation of the documentation is activated but this requires the Doxygen tool, comment on section 4 of mh-builder/CMakeLists.txt file if this tool is not installed.

Then, compile the code with the following commands:

cd mh-builder
mkdir build
cd build
cmake ..
make

All executables are stored in build\bin

2. Discover MH-Builder

2.1. Via generated documentation

During the compilation step (see previous section), the Doxygen tool both generates HTML and LaTeX documentation. In the project, Locations of the generated documentation is:

doxygen/documentation/html/index.html
doxygen/documentation/latex/

The HTML version makes it easy to navigate through all the classes, to see the inheritance hierarchy of each class.

2.2. Via the source code

All sources are available from the src directory.

Source files are stored in different directories. The organisation of the source files respects the following main directories:

core : contains the core classes of the framework.
opt : contains additional classes for the implementation of metaheuristics dedicated to problem-independent optimization, it is divided into several sub-categories:
- criterion for the implementation of components dedicated to the stopping search algorithm (time, iteration, evaluation)
- checkpoint for the implementation of components dedicated to store checkpoints during execution.
- singleSolution for the implementation of metaheuristics dedicated to single solution optimization (single-objective local search, evaluation algorithm, etc.)
- manySolutions for the implementation of metaheuristics dedicated to multi-objective optimization.
- perturbation for the implementation of components dedicated to perturbation methods
representation : for the implementation of components dedicated to a particular type of problem (bitstring, permutation, etc). In particular, this section contains the subdirectory rulemining which contains classes related to machine learning, useful for the MOCA-I software
util : contains utility classes (parser, time management, etc)

2.3. Via binary applications

There are different applications that illustrate how to use the different available (meta)heuristics. Some of these programs load datasets that are available in the instances directory. All application source files are stored in the src-bin directory.

3. Inside MH-Builder

The MH-Builder framework makes extensive use of C++ template classes. In these classes, the () operator is most of the time redefined in order to execute the main function of the class concerned. Examples are the evaluation of a solution (class "Eval"), the update of an archive (class "Archive") or the execution of an Algorithm (class "Algorithm").

3.1. The "core" package

All available heuristics and metaheuristics are implemented by template classes that inherit from the abstract classes defined in the core namespace.

Algorithm: this abstract class described a controlled algorithm parameterized by a in structure the operator () allows to run the algoritm. The init methods allow to initialize different datas if necessary before running the algorithm. An algorithm is controlled by a stop criterion (see class Criterion). Checkpoint allow to store any measure during the execution.
Criterion: this abstract class describe the available interface for derived classes. The role of a criterion is to suspend the execution of an algorithm according to a specific criterion. the MH-Builder framework already includes different kinds of stop criterion (EvalCriterion, Time_Criterion, …). The extensible aspect of the framework allow to add new stop criterion for any algorithm.
Checkpoint: Inside an algorithm, a developper can insert zero to multiple checkpoints. This is useful to analyse the execution of an algorithm and, for instance, discover the evolution of the fitness. MH-Builder already provides different kinds of checkpoints. Contrarily to the criterion, a checkpoint do not suspend the execution of an algorithm.
Eval: this abstract class describes the interface for the evaluating a solution. This class is strongly associated with the problem to be solved. The operator () is the main method which implements the code for the evaluation.
Solution: Any Solution must be derived from this abstract solution. The MH-Builder framework already provides different implementations (derived classes of this abstract class) which are suitable for known kinds of problems (ex: permutation, bitstring)
Fitness: This class in relation with a solution allow to classify a solution according to one or multiple objectives. Two derived classes are available (FitnessMin and FitnessMax). The comparison C++ operators are implemented to facilitate the comparison between two solutions.
Archive: this class allows to store multiple solutions.

4. MH-Builder tutorial

Click here to access to the C++ Tutorial of the MH-Builder framework