search

jMetal / jMetalCpp

A C++ version of jMetal, a Java framework aimed at multi-objective optimization with metaheuristics.
64 stars 34 forks source link

readme

jMetalCpp project Web site

jMetalCpp is a C++ based framework for multi-objective optimization. It is a fork of the jMetal project.

TABLE OF CONTENTS

  1. Updates
  2. Requirements
  3. Installing jMetalCpp
  4. Executing jMetalCpp
  5. Choosing a problem
  6. Configuring a problem
  7. Calculating quality indicators
  8. Advanced: Building a Experiment 7.1. Executing a experiment 7.2. Generating reports from a experiment
  9. Installation

0. Updates

Version 1.11:

Version 1.10:

Version 1.9:

Version 1.8:

Version 1.7:

Version 1.6:

Version 1.5:

Version 1.0.1:

Version 1.0:

Version 0.1:

1. Requirements

jMetalCpp has been developed in Unix machines (Ubuntu and MacOS X) as well as in Windows making use of Cygwin. The make utility has been used to compile the software package.

From version 1.5, it is mandatory to use a C++ compilator with C++11 support. This is needed to use the C++11 threads library.

2. Installing jMetalCpp

Copy the compressed file to the location where you want to install jMetal and unzip it.

Then, compile the code with the following command:

% make

One can also use the CMake building system to compile the project independently of the OS. Example for building on Linux can be found below:

mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=../install
make

3. Executing jMetal

All the main binaries are in the subfolder main included in the bin folder. Enter this folder to execute jMetal.

% cd bin
% cd main

The following multi-objective metaheuristics are provided in this version of jMetal:

  Algorithm                                   Command
  ---------------------------------------------------------
  NSGA-II                                     NSGAII_main
  ssNSGA-II                                   ssNSGAII_main
  GDE3                                        GDE3_main
  SMPSO                                       SMPSO_main
  SMPSOhv (NEW)                               SMPSOhv_main
  OMOPSO (NEW)                                OMOPSO_main
  PAES (NEW)                                  PAES_main
  SMS-EMOA                                    SMSEMOA_main
  MOEA/D                                      MOEAD_main

Additionally, we include single-objective variants of these techniques:

  Algorithm                                   Command
  ---------------------------------------------------------
  DE (Differential Evolution)                 DE_main
  gGA (Generational Genetic Algorithm)        gGA_main
  PSO (Particle Swarm Optimization)           PSO_main
  PSO (Standard 2007) (NEW)                   StandardPSO2007_main
  PSO (Standard 2011) (NEW)                   StandardPSO2011_main
  ssGA (Steady-state Genetic Algorithm)       ssGA_main
  CMA-ES                                      CMAES_main
  GWO (Grey Wolf Optimizer)                   GWO_main
  WOA (Whale Optimizer Algorithm)             WOA_main
  MFO (Moth-Flame Optimization Algorithm)     MFO_main

To execute one metaheuristic just use its associated command. For example, to execute GDE3 simply type the following command:

% ./GDE3_main

4. Choosing a problem

If you execute an algorithm like before, a default problem will be used for each algorithm. You can specify what problem to solve by passing it as a parameter. For example, if you desire to execute the Generational Genetic Algorithm to solve the Sphere problem, you need to execute the following command:

% ./gGA_main Sphere

The following multi-objective problems are currently included:

The list of single-objective problems currently is composed of:

5. Configuring a problem

When you select a problem to solve, you can configure some problem parameters passing them as parameters. If a problem has three parameters, you can choose to specify one, two or the three of them.

The following parameters can be configured when going to solve a problem:

 Problem        Parameter 1         Parameter 2             Parameter 3
--------------------------------------------------------------------------------------
 Fonseca        Solution type
 Griewank       Solution type       Number of variables
 Kursawe        Solution type       Number of variables
 OneMax         Number of bits      Number of strings
 Rastrigin      Solution type       Number of variables
 Rosenbrock     Solution type       Number of variables
 Shaffer        Solution type
 Sphere         Solution type       Number of variables
 Srinivas       Solution type
 Tanaka         Solution type
 DTLZ1          Solution type       Number of variables     Number of objectives
 DTLZ2          Solution type       Number of variables     Number of objectives
 DTLZ3          Solution type       Number of variables     Number of objectives
 DTLZ4          Solution type       Number of variables     Number of objectives
 DTLZ5          Solution type       Number of variables     Number of objectives
 DTLZ6          Solution type       Number of variables     Number of objectives
 DTLZ7          Solution type       Number of variables     Number of objectives
 LZ09_F1        Solution type
 LZ09_F2        Solution type
 LZ09_F3        Solution type
 LZ09_F4        Solution type
 LZ09_F5        Solution type
 LZ09_F6        Solution type
 LZ09_F7        Solution type
 LZ09_F8        Solution type
 LZ09_F9        Solution type
 ZDT1           Solution type       Number of variables
 ZDT2           Solution type       Number of variables
 ZDT3           Solution type       Number of variables
 ZDT4           Solution type       Number of variables
 ZDT5           Solution type       Number of variables
 ZDT6           Solution type       Number of variables

The following values are allowed for the 'Solution type' parameter:

For example, if you want to solve the DTLZ5 problem using SMPSO using 'Real" as solution type, you would need to execute the following command:

% ./SMPSO_main DTLZ5 Real

In the future, a binary-real encoding will be available.

If you intend to modify the default parameters of the DTLZ5 problem with ten variables and two objectives, the following command must be executed:

%./SMPSO_main DTLZ5 Real 10 2

The CEC 2005 problems are an exception, as the order of the parameters change if you are setting one, two or the three of them.

 Problem        Parameter 1         Parameter 2             Parameter 3
--------------------------------------------------------------------------------------
 CEC2005        Problem number
 CEC2005        Solution type       Problem number
 CEC2005        Solution type       Problem number          Number of variables

The variable accepts values from 1 to 25. The default values for Solution type and Number of variables are Real and 10. Examples:

% ./gGA_main CEC2005 1
% ./gGA_main CEC2005 Real 1
% ./gGA_main CEC2005 Real 1 20

6. Calculating quality indicators

To assess the performance of multi-objective metaheuristics, quality indicators are needed to evaluate the quality of the obtained Pareto front approximations.

The following quality indicators are provided in this version of jMetal:

  Quality Indicator                     Command
  ---------------------------------------------------------------------
  Hypervolume                           Hypervolume
  Spread                                Spread
  Epsilon                               Epsilon
  Generational Distance                 GenerationalDistance
  Inverted Generational Distance        InvertedGenerationalDistance

This quality indicators require to know the true Pareto front of the problems. In the case of the included benchmark problems, their Pareto fronts can be downloaded from http://jmetal.sourceforge.net/problems.html

The quality indicator binaries are included in bin/qualityIndicator/main. Enter this folder to execute any indicator.

% cd bin
% cd qualityIndicator
% cd main

To calculate a quality indicator you have to execute the following command:

% ./<QualityIndicatorCommand> <SolutionFrontFile> <TrueFrontFile> <numberOfObjectives>

For example, if you need to calculate the hypervolume indicator on the `FUN file obtained by a metaheuristic when trying to solve the ZDT1 problem, you have to execute the following command:

% ./Hypervolume /home/username/jmetalcpp-test/FUN/home/username/jmetalcpp-test/ZDT1.pf 2

Remember to change the file paths to whatever the actual location of the files containing the Pareto fronts is.

7. Advanced: Building a Experiment

Since this version of jMetalCpp, it is possible to create experimental studies. An experiment consists of a list of algorithms which are used to solve a list of problems, performing a number of independent runs. The results are then evaluated by applying quality indicators and, as an output, a set of Latex files and R scripts are produced. These files include Latex tables with means/medians and standard deviations/IQRs, Latex tables including the results of applying the Wilcoxon rank-sum tests, and eps figures containing boxplots.

Experiments are divided in two independent parts: an execution part and a report part. This approach is different from the one used in the Java version of jMetal. The current one included in jMetalCpp is more flexible and includes a more efficient parallel scheme to run the experiments in parallel.

The execution part is the one which executes all the problems using the selected algorithms. Each problem will be executed a specified number of times. As the number of configuration can be high and they are independent among then, the algorithms can be executed concurrently by a specified number of threads in order to take advantage of current multi-core processors.

The report part allows to apply quality indicators to measure the quality of the result data, and calculates statistical information yielding the Latex tables and figures commented previously.

7.1. Executing a experiment

To execute the 'execution part' of a experiment, you only need to execute the corresponding command. This version of jMetalCpp provides two already implemented experiments to be used as templates. Feel free to edit these experiments or create new ones. Remember that after editing the code, you will have to compile the code again.

The two provided experiments are:

The first one is a multi-objective experiment. The second one is a single-objective one. In order to execute a experiment, you only have to enter its corresponding command. For example:

% ./StandardStudyExecution

Before executing the experiments, it is important to change some parameters in the code accordingly to your needs and to your system configuration. Thus, you need to indicate the current paths where to store the output files and from where to read the input files. You will have to edit the corresponding .cpp files located in the 'jmetalcpp/src/experiments/' folder.

In each .cpp file, you can specify the following parameters:


    - <experimentalBaseDirectory/experimentName>
        |-data
          |- <algorithm_1>
          | |- <problem_1>
          | |   Result files from problem 1 using algorithm 1.
          | |   (FUN.1, FUN.2, ..., FUN.X, VAR.1, VAR.2, ..., VAR.X)
          | |- <problem_2>
          | |   Result files from problem 2 using algorithm 1.
          | |   (FUN.1, FUN.2, ..., FUN.X, VAR.1, VAR.2, ..., VAR.X)    
          | |- ...
          | |- <problem_n>
          |   Result files from problem n using algorithm 1.
                    |   (FUN.1, FUN.2, ..., FUN.X, VAR.1, VAR.2, ..., VAR.X)
          |
          |- <algorithm_2>
          | |- <problem_1>
          | |   Result files from problem 1 using algorithm 2.
          | |- <problem_2>
          | |   Result files from problem 2 using algorithm 2.
          | |- ...
          | |- <problem_n>
          |     Result files from problem n using algorithm 2.
          |
          |- ...
          |
          |- <algorithm_m>
            |- <problem_1>
            |   Result files from problem 1 using algorithm m.
            |- <problem_2>
            |   Result files from problem 2 using algorithm m.  
            |- ...
            |- <problem_n>
              Result files from problem n using algorithm m.

Each algorithm used in the execution must be properly configured. This is done in the algorithmSettings method in each .cpp file. For each algorithm (NSGAII, GDE3, gGA...), this version of jMetalCpp provides a Settings class with a default configuration. You can edit these Setting classes to change the algorithm parameters. Don't forget to edit the algorithmSettings to configure each algorithm used in the experiment. It's possible to execute the same algorithm more than once in a experiment with different configurations, but you will have to implement a different Settings class for each variant of the algorithm.

7.2. Generating reports from a experiment

To execute the report part of a experiment, you only need to execute the corresponding command. For this part, this version of jMetalCpp provides three already implemented experiments. The first two ones generate reports for the multi-objective experiment and the third one generate reports for the single-objective variant. As before, they are templates, so feel free to edit them according to your needs or to create new ones from them. Remember that after editing the code, you will have to compile the code again.

The three provided experiments are:

The experiments in the Java version of jMetal assume that you known in advance the true Pareto front of the solved problems, and this assumption is considered in the StandardStudyReportPF (PF stands for "Pareto Front"). However, if the Pareto fronts are unknown, as usually happens when solving real problem, the approach then is to obtain a reference Pareto front from all the front of solutions produced by all the algorithms in every independent run. The StandardStudyReportRF (RF stands for "Reference Front") is designed to get this reference fronts, which are then used to apply the desired quality indicators.

StandardStudyReportSO generates the reports for a single-objective experiment.

In order to execute an experiment report, you only need to enter its corresponding command. For example:

% ./StandardStudyReportPF

As before, the experiment report programs must be properly configured before running them. It is very important that the list of parameters enumerated in the following do match with the ones included in the execution part which was previously run:

In case of executing the StandardStudyReportRF program, a directory <experimentalBaseDirectory/experimentName/referenceFronts> will contain the obtained reference fronts of the solved problems.

8. Installation