Skip to content

Changes

Page history
Explain how simulation can be run through the different version of GAMA authored by ThibautDemare's avatar ThibautDemare
Show whitespace changes
Inline Side-by-side
Guide_utilisation.md 0 → 100644
View page @ 9a8148b3
# Guide d'utilisation
Le modèle DALSim fonctionne grâce à une version particulière de GAMA incluant un ensemble de plugins créés spécialement pour ce modèle.
On présente ici une description des différentes possibilités pour exécuter des simulations de DALSim.
## Version stable<a name="stable"></a>
La façon la plus simple d'utiliser le modèle DALSim est de télécharger le dernier build de GAMA à cette adresse :
[https://git.litislab.fr/tdemare/DALSim/tags](https://git.litislab.fr/tdemare/DALSim/tags).
Il faut télécharger la version de GAMA qui vous intéresse (en fonction de la plateforme sur laquelle vous êtes), et le code source du modèle.
Une fois que GAMA est extrait, vous pouvez le lancer et indiquer comme workspace le dossier correspondant au repo de DALSim.
## Version headless
Si vous souhaitez utiliser DALSim avec le mode headless de GAMA (par exemple, si vous devez l'exécuter sur un serveur), il est nécessaire d'avoir un build de GAMA.
Vous pouvez soit récupérer la dernière version stable (voir [partie précédente](#stable)), soit créer votre propre build via la version "développement" ((voir [partie suivante](#dev))).
### Sans container Docker
Si vous ne souhaitez pas utiliser de container Docker, vous pouvez directement vous référer aux pages du wiki de GAMA concernant le mode headless (le fonctionnement ne change pas, même avec le build personnalisé pour DALSim) :
- [https://github.com/gama-platform/gama/wiki/Headless](https://github.com/gama-platform/gama/wiki/Headless)
- [https://github.com/gama-platform/gama/wiki/Headless-mode-for-dummies](https://github.com/gama-platform/gama/wiki/Headless-mode-for-dummies)
### Avec container Docker
Vous pouvez également utiliser un container Docker pour faciliter le déploiement de GAMA. On propose ici une architecture pour générer une image et pour lancer des containers de cette image.
#### Création de l'image
Pour créer l'image, on utilise un Dockerfile. On part du principe qu'il existe un dossier `gama` dans le répertoire courant au Dockerfile, et que ce dossier `gama` contient le build du logiciel.
Voici le Dockerfile à partir duquel on génère l'image :
```docker
FROM ubuntu:18.04
RUN apt update && apt install -y openjdk-8-jdk
COPY ./gama /gama
RUN mkdir /bd && mkdir /DALSim && mkdir /simulation_configs && mkdir /output && mkdir /CSV && chmod -R +x /gama
WORKDIR /gama/headless
ENTRYPOINT ["./gama-headless.sh"]
CMD ["/simulation_configs/simulation_config.xml /output/"]
```
Ensuite vous pouvez utiliser la commande suivante depuis le répertoire courant au Dockerfile :
```console
[user@localhost]$ docker build -t gama .
```
#### Démarrage d'un container
On a essayé de rendre l'image Docker la plus généraliste possible afin qu'un utilisateur puisse lancer plusieurs containers avec des paramétrages différents. Ainsi, l'image Docker proposée n'inclut pas directement ni le modèle, ni la base de donnée, ni le fichier de configuration du mode headless. Il faut donc les ajouter en créant des points de montage.
Si on se place dans un répertoire `run1` pour lancer le container, alors on supposera qu'on ait l'arborescence suivante :
```
/run1
|- /DALSim
|- /models # contient l'ensemble des fichiers .gaml du modèle
|- /bd
|- /Used # Chaque sous dossier contient les différents Shapefile utilisés par DALSim
|- /Countries
|- /FinalDestination
|- /ForwardingAgent
|- /LogisticProvider
|- /Maritime
|- /Provider
|- /Regions
|- /River
|- /Roads
|- /Terminals
|- /Warehouse
|- /simulation_configs
|- /simulation_config.xml # Le fichier de configuration pour le mode headless
|- /CSV # Contient l'ensemble des fichiers CSV généré par le modèle
|- /output # Contient les logs de la console GAMA et les snapshots
```
Voici une proposition de configuration du mode headless décrit dans le fichier `simulation_config.xml` :
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Experiment_plan>
<Simulation id="1" sourcePath="../DALSim/models/merged.gaml" finalStep="6000" experiment="Docker with traffic screenshots">
<Parameters>
<Parameter name="saveObservations" type="BOOLEAN" value="true" />
<Parameter name="pathBD" type="STRING" value="/bd/Used/" />
<Parameter name="CSVFolderPath" type="STRING" value="/CSV/" />
</Parameters>
<Outputs>
<Output id="1" name="Road traffic" framerate="1" />
<Output id="2" name="Maritime and River traffic" framerate="1" />
</Outputs>
</Simulation>
</Experiment_plan>
```
Et enfin voici la commande `docker run` que l'on peut exécuter avec cette configuration :
```console
[user@localhost]$ docker run --name run1 \
-v $(pwd)/simulation_configs:/simulation_configs \
-v $(pwd)/output:/output -v $(pwd)/CSV:/CSV \
-v $(pwd)/DALSim:/DALSim \
-v $(pwd)/bd:/bd \
gama
```
## Version "développement"<a name="dev"></a>
Le mode "développement" permet d'une part de modifier les plugins associés au projet, et d'autre part de générer un build de GAMA pour proposer une version stable aux utilisateurs.
La première étape pour utiliser cette version consiste à installer la version "Git" de GAMA en suivant ce guide :
- https://github.com/gama-platform/gama/wiki/InstallingGitVersion
Ensuite, il vous faudra rapatrier les différents plugins ci-dessous en les important comme projet à Eclipse :
- https://github.com/graphstream/gs-gama
- https://git.litislab.fr/tdemare/TransportOrganizerPlugin
- https://git.litislab.fr/tdemare/MovingOnNetworkPlugin
- https://git.litislab.fr/tdemare/AnalyseNetworkPlugin
Ces quatre plugins sont configurés pour fonctionner avec la librairie Graphstream (version 1.3). Vous devrez donc ajouter cette librairie. Pour cela, télécharger "gs-core" et "gs-algo" à ces deux adresses :
- https://data.graphstream-project.org/pub/1.x/nightly-build/last/gs-algo-1.3-SNAPSHOT-last.jar
- https://data.graphstream-project.org/pub/1.x/nightly-build/last/gs-core-1.3-SNAPSHOT-last.jar
Ensuite, dans Eclipse, pour chaque plugin, faites un clic droit sur le projet (le projet contenant les sources et non la feature), aller dans properties > Java Build Path > Libraries > Add External Jars > Sélectionner les deux fichiers téléchargés > Apply and Close.
Puis, pour chaque plugin, vous devrez les inclure à GAMA en suivant la section "Addition of a feature to the product" de ce tutoriel :
- https://github.com/gama-platform/gama/wiki/DevelopingPlugins
À partir de ce point vous pouvez lancer GAMA (selon la méthode décrite ici https://github.com/gama-platform/gama/wiki/InstallingGitVersion) qui vous demandera de choisir un workspace. Une fois lancé, vous pouvez importer à votre workspace le modèle GAMA de ce projet.
\ No newline at end of file