Commit 9f3ae599 authored by LIGNEUL CLEMENT's avatar LIGNEUL CLEMENT
Browse files

Merge branch 'Documentation' into 'master'

Documentation

See merge request !4
parents 7c4feafd 4b57d9a1
......@@ -3,4 +3,5 @@ dist/
deploy/
node_modules/
package-lock.json
plotting/
\ No newline at end of file
plotting/
EASEA-compiler-app/
\ No newline at end of file
all:
@echo "\n##### Début du packaging #####\n"
install:
@echo "\n##### Install modules #####\n"
@echo "\n##### Initialisation #####\n"
npm install
@echo "\n##### Start the packaging #####\n"
@echo "\n##### Initialization #####\n"
rm -rf deploy dist
npx nodegui-packer --init EASEA-compiler-app
@echo "\n##### Build de dist #####\n"
@echo "\n##### Build dist #####\n"
npm run build
@echo "\n##### Packaging en cours #####\n"
@echo "\n##### Packaging in progress #####\n"
npx nodegui-packer --pack ./dist
@echo "\n##### Copie du script de graphe #####\n"
@echo "\n##### Copy additional files #####\n"
find 'deploy/' -type d -name doc | sed 's/doc//' | xargs -n 1 cp -v src/scripts/plot.py
find 'deploy/' -type d -name doc | sed 's/doc//' | xargs -n 1 cp -v src/plot.py
find 'deploy/' -type d -name doc | sed 's/doc//' | xargs -n 1 cp -v src/3D_plot.py
find 'deploy/' -type d -name doc | sed 's/doc//' | xargs -n 1 cp -rv documentation/
ifneq ($(TYPE), DEV)
find 'deploy/' -type d -name doc | sed 's/doc//' | xargs -n 1 cp -rt ./
rm -rf deploy/
endif
# else keep the deploy dir
@echo "\n##### Packaging finished #####\n"
@echo "\n##### Packaging terminé #####\n"
update-documentation:
asciidoctor documentation/*.adoc
clean:
rm -rf deploy dist
\ No newline at end of file
rm -rf deploy dist EASEA-compiler-app
\ No newline at end of file
# EASEA-compiler-app
Cette application est une interface graphique pour la plateforme [EASEA](http://easea.unistra.fr/index.php/EASEA_platform)
## Dépendances
This application is a graphical interface for the [ESEA](http://easea.unistra.fr/index.php/EASEA_platform) platform.
Cette application a été conçu et testé sur Ubuntu 20.10
## Dependencies
Pour utiliser ce programme il est nécessaire d'avoir installé la version la plus récente d'EASEA (voir http://easea.unistra.fr/index.php/Downloading_EASEA)
This application has been designed and tested on Ubuntu 20.10
### Dépendances générales
To use this program, it is necessary to have installed the most recent version of EASEA (see http://easea.unistra.fr/index.php/Downloading_EASEA)
- Python 3
- [Plotly](https://plotly.com/python/) pour tracer les graphes :
- Avec pip : `pip install plotly==5.1.0`
- Avec conda : `conda install -c plotly plotly=5.1.0`
### General dependencies
- Python (Python 3 recommended)
- [Plotly](https://plotly.com/python/) to plot graphs :
- With pip : `pip install plotly==5.1.0`
- With conda : `conda install -c plotly plotly=5.1.0`
- Pandas :
- Avec pip : `pip install pandas`
- kaleido pour exporter les graphes :
- Avec pip : `pip install kaleido`
- Avec conda : `conda install -c conda-forge python-kaleido`
- With pip : `pip install pandas`
- kaleido to export graphs :
- With pip : `pip install kaleido`
- With conda : `conda install -c conda-forge python-kaleido`
### pendances Linux
### Linux dependencies
- Make, GCC v7
- CMake 3.1 ou ultérieur
- Node.JS version 12 et plus
- CMake 3.1 or later
- Node.JS version 12 or later
### pendances macOS
### macOS dependencies
- macOS 10.10 et plus (OS 64 bits seulement)
- macOS 10.10 or later (OS 64 bits only)
- Make, GCC v7
- CMake 3.1 ou ultérieur
- Node.JS version 12 et plus
- CMake 3.1 or later
- Node.JS version 12 or later
## Installation
- Cloner ce dépôt
- Installer les modules avec `npm install` ou `npm i` depuis la racine. Cette installation peut prendre un certains temps
- Pour lancer le programme exécuter `npm start` depuis la racine.
- Clone this repository
- Run `make install` in `easea-compiler-app/`
- The executable is located in `EASEA-compiler-app/`
- To remove the generated executable use `make clean`
(DEV) To run the application execute `npm start`
---
## Génération de l'exécutable pour l'export de l'application
## Next features
- Exécuter `make`
- L'exécutable se trouve dans `deploy/linux/build/easea-compiler-app` dans le cas d'une utilisation sur Linux.
- Pour supprimer l'exécutable généré utiliser `make clean`
\ No newline at end of file
- See all results after the runs
- Analyze and repair csv files to fix the bug on very fast runs (<1s)
- Gitlab pages for documentation ?
= EASEA Compiler App Documentation
Clément Ligneul <clement.ligneul@etu.unistra.fr>
v1.1 2021-07-21
:toc: left
:toclevels: 4
:hide-uri-scheme:
<<doc_fr.adoc#, Version Française>>
== About
=== About EASEA
EASEA (EAsy Specification of Evolutionary Algorithms) is an Artificial Evolution platform that allows scientists with only basic skills in computer science to implement evolutionary algorithms and to exploit the massive parallelism of many-core architectures in order to optimize virtually any real-world problems (continous, discrete, combinatorial, mixed and more (with Genetic Programming)), typically allowing for speedups up to x500 on a $3,000 machine, depending on the complexity of the evaluation function of the inverse problem to be solved.
More informations http://easea.unistra.fr/index.php/EASEA_platform[here, window=_blank].
=== About this application
This application simplifies the compilation and execution process by implementing a user interface. This way it is possible to compile and run `.ez` programs with just a few clicks.
== Dependencies
=== EASEA
You must install EASEA to use this application. To do this, clone the https://github.com/EASEA/easea[following repository, window=_blank] and follow the README.
=== Plot results
To plot your results, you need to install :
- Python (Python 3 recommended)
- Plotly :
* with pip : `pip install plotly==5.1.0`
* with conda : `conda install -c plotly plotly=5.1.0`
- Pandas :
* with pip : `pip install pandas`
- Kaleido to export graphics :
* with pip : `pip install kaleido`
* with conda : `conda install -c conda-forge python-kaleido`
Note that if you are using macOS, plotly only works on version 10.10 or more (OS 64 bits).
== Installation
Once the dependencies are installed :
- clone https://git.unistra.fr/ligneul/easea-compiler-app[this repository, window=_blank]
- run `npm install` in the main directory
- compile this app running `make` in the main directory
- run the executable in `EASEA-compiler-app/`
== Dev version
Running `npm start` in the main directory will allow you to see all the debugging information in the terminal. This is useful if you have any problems. This command recompiles everything each time you use it. You can also see debugging information from the executable if you run it into a terminal.
== Quick tutorials
=== Simple run
In this tutorial we will compile and run the file `weierstrass.ez` from the `/examples` directory of EASEA in the easiest way.
==== Compilation
. In the compile tab load `easea/examples/weierstrass.ez`
. We don't use any options in this compilation so just click on the `Compile` button
. After clicking on this button you see this :
image::images/compile_weierstrass.png[compile_weierstrass image, 700, align=center]
==== Run
Go to `Run` tab.
We just want a simple execution of our program so we just have to click `Run!`.
If you want to add more options to the execution, take a look at the different menus depending on your needs.
The description of these menus is given below.
==== Plot results
If the run finished correctly you can now see the plot in the Result Plot tab (see more in the <<Result Plot tab>> section)
=== Run in batch
[red]#Don't use the run in batch if you have compiled with options for <<Multi-objective problems, Multi-objective problems>>.#
This application allows to run the same program several times at the same time (batch). In this tutorial we will use the file `weierstrass.ez` from the `/examples` directory of EASEA.
1) Load and compile the file in the `Compile` tab without any options
2) In the `Run` tab click on `General Options` and set "Batch size" to 10, then save
image::images/general_menu_batch.png[general menu batch image, 850, align=center]
3) Under the `General options` button we can choose the number of violin plots. Set it to 5 and click `Run!`
4) At the end of these runs you should see something like this :
image::images/end_run_batch.png[end run batch image, 700, align=center]
5) In the `Result Plot` tab you can see the graph generated as we requested : 5 violin plots (for more informations about this graph see <<Result Plot tab>>)
image::images/2d_results.png[2d results image, 700, align=center]
== Interface detailed
When you open the app, you go to the first tab which allows you to compile.
The second lets you select your options and run.
The last one is dedicated to plotting the results according to the compilation and execution options.
=== Compile tab
image::images/empty_compile.png[empty compilation image, 700, align=center]
① Load your file
② Choose your compilation options. The `cuda` and `cuda_gp` options appear only if you have installed CUDA SDK and `nvcc` (https://developer.nvidia.com/cuda-downloads[ window=_blank])
③ You can add more options to get a detailed compilation
④ Run the compilation
⑤ Once you have compiled/runned your project, a Makefile with other files will be generated. To remove these files click on `Make clean` button (note that the `.log` files will not be deleted).
EASEA offers many options for compiling your `.ez` projects. If you want to see them in detail, check out http://easea.unistra.fr/index.php/EASEA_command_line[easea commands, window=_blank]
=== Run tab
You must compile your project before running it.
image::images/islands_activated.png[island activation image, 700, align=center]
① Size of the batch (see <<Run in batch>>)
② Activate the island model
③ Options for running the island model. This button appear only when you activate the island model. This menu is more detailed <<Island model options, here>>.
④ General options. Here you will find all the options regarding the global execution. This menu is more detailed <<General options, here>>.
⑤ Parents options. Here you will find all the options regarding the parents settings. This menu is more detailed <<Parents options, here>>.
⑥ Offsping options. Here you will find all the options regarding the offspring settings. This menu is more detailed <<Offspring options, here>>.
⑦ The number of plots desired. The number entered gives the number of violin plots to be traced and distribute generations in these graphs (e.g if you have a total of 100 generations and you want 10 plots you will have 10 graphs of 10 generations). This option is only available if you are not running a program with options for <<Multi-objective problems>>.
⑧ Start the runs
⑨ Stop all runs in progress
In the output window are written the commands executed and the output of the first run if you are running in batch.
==== General options
image::images/general_menu.png[general menu image, 900, align=center]
- [underline]#Plot Stats# : Plot the graph associated with the first run
- [underline]#Generate CSV File# : Save results to a CSV file
- [underline]#Print Initial Population# : Print the initial population used
- [underline]#Print Final Population# : Print the population at the end of the run
- [underline]#Start From File# : Use a `.pop` file as a starting population
- [underline]#Generate R Script# : Generate a R script to plot the Stats
- [underline]#Generate Plot Script# : Generate a Gnuplot script to plot the Stats
- [underline]#Save Population# : Save the population at the end
- [underline]#Population Size# : Set the population size
- [underline]#Nb Generations# : Set the number of generations
- [underline]#Time Limit# : Set the time limit for each run. For no time limit, set it to 0.
- [underline]#Elite Type# : Set the elite type. You can choose between Strong and Weak
- [underline]#Elite Size# : Set the elite size
- [underline]#Selection Operator# : Set the selection operator (Tournament by default)
- [underline]#Selection Pressure# : Set the selection pressure. This field is available only if you are using Tournament as selection operator. This value must be between 0.5 and 0.9999... inclusive or greater than 2 inclusive (default 2)
- [underline]#Reduce Final Operator# : Set the final reducing operator (Tournament by default)
- [underline]#Reduce Final Pressure# : Set the final reducing pressure. This field is available only if you are using Tournament as final reduction operator. This value must be between 0.5 and 0.9999... inclusive or greater than 2 inclusive (default 2)
- [underline]#Baldwinism# : Only keep fitness (default 0)
- [underline]#Number of the first GPU used for computation# : ...
- [underline]#Number of the first GPU NOT used for computation# : ...
- [underline]#Initial Population# : File containing the population to use
- [underline]#Output File# : Set an output file for the final population
- [underline]#Optimize Iterations# : Set the number of optimisation iterations (default 100)
- [underline]#Compression# : Set the compression level
- [underline]#Batch Size# : Number of runs at the same time. [red]#Don't use this option if you have compiled with options for <<Multi-objective problems>>#
- [underline]#Nb Of Threads# : Number of threads to use
- [underline]#User parameters# : Parameters to use for the program (up to 5)
===== Seeds
- [underline]#First seed# : Value of the first seed. If this field is empty the current timestamp in secondes is the first seed
- [underline]#Seeds by run# : This table allows to choose a seed for each run. You have to specify the batch size before. If a cell is empty, its run will have for seed the first incremented by the number of empty cells before (e.g first seed = 0 and we have 3 runs. If the seed for the run 2 is 42 and empty cell for the others, the seed for run 1 = 0 and the seed for run 3 = 1)
By default, most of the options are taken from the `.ez` file.
Note that if you run in batch only information about the first run will be displayed
==== Parents options
image::images/parents_menu.png[parents menu image, 300, align=center]
- [underline]#Surviving Parents# : Set the reduction size for parent population. It is possible to set an absolute value (`#`) or a percentage (`%`)
- [underline]#Reduction Operator# : Set the reduction operator (Tournament by default)
- [underline]#Reduce Pressure# : Set the reduction pressure. This field is available only if you are using Tournament as reduction operator. This value must be between 0.5 and 0.9999... inclusive or greater than 2 inclusive (default 2)
==== Offspring options
image::images/off_menu.png[offspring menu image, 300, align=center]
- [underline]#Offspring Size# : Set the offspring population size
- [underline]#Surviving Offspring# : Set the reduction size for offspring population. It is possible to set an absolute value (`#`) or a percentage (`%`)
- [underline]#Reduction Operator# : Set the reduction operator (Tournament by default)
- [underline]#Reduce Pressure# : Set the reduction pressure. This field is available only if you are using Tournament as reduction operator. This value must be between 0.5 and 0.9999... inclusive or greater than 2 inclusive (default 2)
==== Island model options
This menu is available after activating the remote island model
image::images/island_menu.png[island menu image, 300, align=center]
- [underline]#Migration Probability# : Probability to send an individual each generation
- [underline]#IP file# : File containing all the IPs of the remote islands
- [underline]#Server Port# : Port of the server
- [underline]#Evaluate Immigrants# : ...
=== Result Plot tab
After all the runs, if there is no problem during the execution, the application will generate a graph according to your compilation options.
If you used options for <<Multi-objective problems>> you will have a 3D plot, otherwise, you will have a series of violin plots.
==== Violin plots
In the Run tab, before you launch the execution, you can choose the number of violin plots to trace. The number of points in each graph depend of the number of generations and the batch size.
[underline]#Example# :
The following example uses `easea/examples/weierstrass.ez`.
In this file we have 35 generations. We choose to run a batch of 10 and print 5 plots. After the execution we have 5 violin plots with 7 generations each (35 generations / 5 plots). But we had runned a batch of 10 so in each violin plot we have 7x10 = 70 points. Each point representing the best fitness for the calculated generation.
The first graph takes the 7 first generations, the second takes the next 7 etc...
image::images/2d_results.png[2d results image, 700, align=center]
The image quality is reduced to put it in the application, we recommend using the interactive version of the graph to see the details.
==== Violin plots interactive version
To access the interactive version of the generated plot *double-click* on the graph. This version allows to handle it in a browser.
image::images/full_2d_plot.png[2d results interactive image, 1000, align=center]
To zoom on a figure, frame it. To return to the default view double-click anywhere.
image::images/rect.png[rect zoom 2d interactive image, 1000, align=center]
image::images/zoom_2d.png[zoomed 2d interactive image, 1000, align=center]
In each graph there are 3 elements :
- ① The raw data
- ② The violin plot
- ③ The box plot
==== 3D plot
This plot replaces the graph with the violin plots if you have compiled and run a program with the options for <<Multi-objective problems>>.
image::images/3D_update.png[3d results image, 700, align=center]
==== 3D plot interactive version
To open the interactive version *double-click* on the graph.
image::images/interactive_3d.png[3d interactive results image, 1000, align=center]
Holding the left click rotates the figure.
Right click moves the graph on the x y axis.
You can reset the view with the toolbar at the top right.
==== Save the results graph
To save the results you can click on the appropriate button :
- `Save static plot` will save the plot as you can see it in the application.
- `Save interactive plot` will save the html file that you open when you double-click the image in the app.
We recommend to save your plots from the interactive version with camera icon. This way you can save the view you want with a better quality.
==== Edit the results graph
image::images/update_menu.png[ update plot menu image, 300, align=center]
Once you have generated the result plot you can edit it. It is possible to change :
- The plot title
- The axis name if the plot is a 3D plot
- The number of violin plots if the plot is a 2D plot
== Multi-objective problems
Compilation options for multi-objective problems are :
- `nsgaii`
- `nsgaiii`
- `asrea`
- `ibea`
- `cdas`
If you use one of these options do not run in batch because the results will be overwritten with each other.
== Tips
- If the run takes a long time, set "Time limit" option to 0 to have complete execution
- You can go to the EASEA website with the help menu. You can find a lot of useful information in this site like description of the compilation parameters
- The usual shortcuts are available here like ctrl+tab to switch of tab, tab and shift+tab to change focus etc...
- If you launch the executable from a terminal you can see more debug information
\ No newline at end of file
This diff is collapsed.
= EASEA Compiler App Documentation
Clément Ligneul <clement.ligneul@etu.unistra.fr>
v1.1 2021-07-21
:toc: left
:toc-title: Table des matières
:toclevels: 4
:hide-uri-scheme:
<<doc_en.adoc#, English Version>>
== A propos
Cette application implémente une interface graphique dans le but de simplifier la compilation et l'exécution de programmes utilisant la plateforme http://easea.unistra.fr/index.php/EASEA_platform[EASEA, window=_blank]. Elle offre aussi d'autres fonctionnalités utiles comme l'exécution en batch ou la représentation graphique de résultats.
== Dépendances
=== EASEA
Vous devez avoir installé EASEA avant d'utiliser cette application. Pour cela, cloner https://github.com/EASEA/easea[ce dépôt, window=_blank] et suivez les instructions du README.
=== Représentation graphique des résultats
Pour générer le graphe des résultats vous devez installer :
- Python (Python 3 recommandé)
- Plotly :
* avec pip : `pip install plotly==5.1.0`
* avec conda : `conda install -c plotly plotly=5.1.0`
- Pandas :
* avec pip : `pip install pandas`
- Kaleido pour exporter les graphes :
* avec pip : `pip install kaleido`
* avec conda : `conda install -c conda-forge python-kaleido`
Notez que plotly ne fonctionne qu'à partir de la version 10.10 sur macOS (64 bit seulement).
== Installation
Une fois les dépendances installées :
- clonez https://git.unistra.fr/ligneul/easea-compiler-app[ce dépôt, window=_blank]
- exécutez `npm install` dans le repertoire principal
- compilez l'exécutable avec `make` dans le répertoire principal
- lancez l'exécutable du répertoire `EASEA-compiler-app/`
== Version développeur
Lancer la commande `npm start` dans le répertoire principal permet d'ouvrir l'application sans devoir générer d'exécutable mais aussi d'afficher dans la console les informations pouvant servir au débogage. Démarrer l'application en lançant l'exécutable depuis une console permet aussi d'afficher ces informations.
== Tutoriels
=== Simple exécution
Dans ce tutoriel nous allons simplement compiler et exécuter le fichier `weierstrass.ez` se trouvant dans le répertoire `/examples` d'EASEA.
==== Compilation
. Dans l'onglet `Compile` chargez le fichier `easea/examples/weierstrass.ez`
. Nous n'utilisons aucune option pour cette compilation, cliquez donc directement sur `Compile`
. Après avoir lancé la compilation vous devez voir ceci :
image::images/compile_weierstrass.png[compile_weierstrass image, 700, align=center]
==== Lancement du programme
Allez dans l'onglet `Run`.
Nous ne faisons qu'une simple exécution sans aucun paramètre, cliquez donc juste sur `Run!`.
Si vous voulez modifier certains paramètres avant le lancement, vous pouvez le faire via les différents boutons qui sont détaillés plus bas.
==== Affichage graphique des résultats
Si l'exécution se termine correctement vous pouvez voir le résultat dans la console et le graphe dans l'onglet `Result plot`. Vous trouverez plus d'informations à la section <<Onglet Result Plot>>.
=== Exécution en batch
[red]#N'utilisez pas l'exécution en batch avec les options de compilation pour <<Problèmes multi-objectifs, problèmes multi-objectifs>> car seuls les resultats vont s'écraser entre eux#
Cette application permet de lancer plusieurs fois le même programme en même temps (batch). Dans ce tutoriel nous utiliserons le fichier `weierstrass.ez` du répertoire `/examples` d'EASEA.
1) Dans l'onglet `Compile`, chargez le fichier puis compilez-le sans ajouter d'options
2) Dans l'onglet `Run`, cliquez sur `General Options` et mettez 10 pour l'option "Batch size" puis sauvegardez
image::images/general_menu_batch.png[general menu batch image, 850, align=center]
3) En dessous du bouton `General options` il est possible de définir le nombre de diagrammes en violon (violin plot) que nous souhaitons dessiner. Mettez 5 et cliquez sur `Run!`
4) Lorsque toutes les exécutions sont terminées vous devez voir ceci :
image::images/end_run_batch.png[end run batch image, 700, align=center]
5) Dans l'onglet `Result Plot` vous pouvez voir le graphe généré comme nous l'avons demandé, c'est-à-dire avec les 5 diagrammes en violon. Vous pouvez trouver plus d'informations sur ce type de diagramme dans la section <<Onglet Result Plot>>
image::images/2d_results.png[2d results image, 700, align=center]
== Détails de l'interface
Lorsque vous ouvrez l'application vous arrivez sur le premier onglet qui vous permet de compiler votre programme.
Le deuxième onglet permet de choisir les options d'exécution puis de le lancer.
Le troisième est dédié à la représentation graphique des résultats selon les paramètres sélectionnés au préalable.
=== Onglet Compile
image::images/empty_compile.png[empty compilation image, 700, align=center]
① Permet de charger le fichier à exécuter
② Options de compilation. Les options `cuda` et `cuda_gp` n'apparaissent que si vous avez installé CUDA SDK et `nvcc` (https://developer.nvidia.com/cuda-downloads[ window=_blank])
③ D'autres options qui permettent d'obtenir une compilation plus détaillée
④ Lance la compilation
⑤ Lorsque vous avez compilé/exécuté votre projet, un Makefile ainsi que d'autres fichiers sont générés. Pour les supprimer et "nettoyer" le répertoire cliquez sur `Make clean` (notez que les fichiers `.log` ne seront pas effacés)
EASEA offre plusieurs options pour compiler votre projet. Pour plus de détails sur ces options consultez la documentation http://easea.unistra.fr/index.php/EASEA_command_line[ici, window=_blank].
=== Onglet Run
Vous devez compiler votre projet avant de le lancer.
image::images/islands_activated.png[island activation image, 700, align=center]
① Taille du batch (voir <<Exécution en batch>>)
② Active le modèle en ilots
③ Options pour l'exécution en ilots. Ce bouton apparaît seulement après avoir activé cette fonction. Ce menu est détaillé dans la section <<Island model options>>.
④ Options g