Fast Preference Learning README

@page readme FastPL README

Introduction

This work is based on Olivier Sobrie's work on preference learning algorithms (python code : https://github.com/oso/pymcda, thesis: https://tel.archives-ouvertes.fr/tel-01370555/document).

The objective of this repository is to translate the previous code (py-mcda) in C++ and set up the parallelisation tools needed to process a greater amount of entrypoints.

The README contains information on how to run the application and help future developpers to set their environment.

The full description and documentation of the project can be found at https://mostah.github.io/fastPL/.

Repository structure

include : Header files
src : Sources files
test : Test files
data : Data (datasets and models) repository
doc : Doxygen documentation repository
.circleci : CircleCi pipelines configuration

Run project in Docker (Recommended)

You can find here some documentation on docker.

Build

The following command will build a Docker image with all this project's dependencies, then build the project in ./build and run its automated tests.

./run-dev.sh make -j8

Run the main app

The following command will show the run config options (helper):

./run-dev.sh build/bin/fastpl -h

To run the app with on a specific dataset:

./run-dev.sh build/bin/fastpl -d $dataset_path -o $output_path

In that command, both arguments are paths to files, relative to the data_dir specified in app-config.yml. For example, with the app-config.yml from the repository, the following command generates the data/output/model1.xml file: mkdir -p data/outputs; ./run-dev.sh build/bin/fastpl -d tests/in1dataset.xml -o outputs/model1.xml.

At the end of the algorithm, the model will be stored in the $output_path

Logs

They are in ./logs/.

Run project locally

This is not supported but may work if you have all dependencies installed. You'll find what's required in dev-container/dockerfile.

Then just run the commands that are after ./run-dev.sh in the previous section:

make -j8
build/bin/fastpl -h
build/bin/fastpl -d $dataset_path -o $output_path

Application configuration

The application configuration can be found at: app-config

The application configuration holds the general config of the learning algorithms.

Parameters

log_level: log filter, values in INFO, ERROR, DEBUG
log_file: path of the logfile
data_dir: data directory path. When changed, the args -d and -o passed along with ./Main program is set relatively to the data directory path configured here
model_batch_size: model population size used in the metaheuristic
max_iterations: max iteration of the metaheuristic before terminating the application
n_profile_update: number of iteration of profile update for one weight update

CircleCi pipelines

CircleCi pipelines configuration can be found at: .circleci

pipelines

Build: Try to build all the project
Tests (requires build): Try to pass all the tests
Doc generation (requires build): Try to generate the documentation

Documentation

The documentation of this project is generated by doxygen. In order to generate locally or update the online documentation, the following modules must be installed: doxygen, doxygen-doc, doxygen-gui, graphviz.

The documentation configuration and files can be found at: doc

Update online documentation

The online documentation is currently host on GitHub Pages: https://mostah.github.io/fastPL/.

The GitHub Page displays static html files from a specified branch. The files used by GitHub Pages to display the latest documentation are set on the gh-pages branch and must not be changed manually.

The following script updates the gh-pages branch by generating the documentation from the latest master commit.

From root directory:

sh doc_generation.sh

Generate documentation locally

From /doc directory:

cmake . && doxygen Doxyfile.Doxigen

Open the documentation on your browser, from /doc/html directory:

open index.html

jacquev6 / fastPL