From a1422b0ba38ff17868d386a26b52205d2e6e31f4 Mon Sep 17 00:00:00 2001
From: Hugo Roussel <hugo.roussel@univ-tlse3.fr>
Date: Fri, 7 Jun 2019 15:22:34 +0200
Subject: [PATCH] Add starting guides
In the documentation folder :
Added what_is.md : explain what AMAK and AMOEBA are
Added installing.md : guide you throught installing AMOEBAonAMAK
Added usage.md : guide you throught the necessary step to get your amoeba running, and how to use it.
---
.gitignore | 3 +
AMAKFX/pom.xml | 4 +-
AMOEBAonAMAK/documentation/save-and-load.md | 0
AMOEBAonAMAK/documentation/usage.md | 61 ------
.../resources/100DimensionsLauncher.xml | 200 +++++++++---------
.../resources/fourDimensionsLauncher.xml | 10 +-
AMOEBAonAMAK/resources/genNDimLauncher.py | 4 +-
.../resources/threeDimensionsLauncher.xml | 8 +-
.../resources/twoDimensionsLauncher.xml | 12 +-
.../benchmark.md => documentation/gui.md | 0
documentation/installing.md | 36 ++++
documentation/usage.md | 147 +++++++++++++
documentation/what_is.md | 11 +
13 files changed, 313 insertions(+), 183 deletions(-)
delete mode 100644 AMOEBAonAMAK/documentation/save-and-load.md
delete mode 100644 AMOEBAonAMAK/documentation/usage.md
rename AMOEBAonAMAK/documentation/benchmark.md => documentation/gui.md (100%)
create mode 100644 documentation/installing.md
create mode 100644 documentation/usage.md
create mode 100644 documentation/what_is.md
diff --git a/.gitignore b/.gitignore
index d87fde40..36e82ab8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -81,3 +81,6 @@ local.properties
.cache-main
.scala_dependencies
.worksheet
+
+# vscode
+.vscode
\ No newline at end of file
diff --git a/AMAKFX/pom.xml b/AMAKFX/pom.xml
index 2a526605..274c8e75 100644
--- a/AMAKFX/pom.xml
+++ b/AMAKFX/pom.xml
@@ -37,13 +37,13 @@
<dependency>
<groupId>org.kordamp.ikonli</groupId>
<artifactId>ikonli-javafx</artifactId>
- <version>11.0.2</version>
+ <version>2.4.0</version>
</dependency>
<dependency>
<groupId>org.kordamp.ikonli</groupId>
<artifactId>ikonli-dashicons-pack</artifactId>
- <version>11.3.4</version>
+ <version>2.4.0</version>
</dependency>
<!-- Local jars dependencies -->
diff --git a/AMOEBAonAMAK/documentation/save-and-load.md b/AMOEBAonAMAK/documentation/save-and-load.md
deleted file mode 100644
index e69de29b..00000000
diff --git a/AMOEBAonAMAK/documentation/usage.md b/AMOEBAonAMAK/documentation/usage.md
deleted file mode 100644
index 4c912d57..00000000
--- a/AMOEBAonAMAK/documentation/usage.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Usage
-*This is a markdown version of the example in Main.java*
-
-## Basic usage
-Set AMAK configuration before creating an AMOEBA
-```Java
-Configuration.commandLineMode = false;
-Configuration.allowedSimultaneousAgentsExecution = 2;
-```
-Create a World, a Studied System, and an AMOEBA
-```Java
-World world = new World();
-StudiedSystem studiedSystem = new F_XY_System(50.0);
-AMOEBA amoeba = new AMOEBA(world, studiedSystem);
-```
-*Note : if you plan on only using the learn method, you can leave studiedSystem at null when creating an amoeba.*
-
-A window appeared, allowing to control the simulation, but if you try to run it, it will crash (there's no percepts !). We need to load a configuration :
-
-Create a backup system for the AMOEBA and load a configuration matching the studied system.
-```Java
-IBackupSystem backupSystem = new BackupSystem(amoeba);
-File file = new File("resources\\twoDimensionsLauncher.xml");
-backupSystem.loadXML(file);
-```
-The amoeba is ready to be used.
-
-## Controling amoeba and learning
-AMOEBA extends AMAK's Amas class, you can control the simulation with the methods it provide. If at the creation of the amoeba a studied system was provided, you can launch the simulation and amoeba will learn.
-
-We provide an additionnal way to learn with amoeba, as described in IAMOEBA.
-Here is an exemple :
-
-We deny the possibility to change simulation speed with the UI, and allow rendering.
-```Java
-amoeba.allowGraphicalScheduler(false);
-amoeba.setRenderUpdate(true);
-```
-We run some learning cycles.
-```Java
-int nbCycle = 1000;
-for (int i = 0; i < nbCycle; ++i) {
- studiedSystem.playOneStep();
- amoeba.learn(studiedSystem.getOutput());
-}
-```
-Rendering the UI slow a lot the simulation, we can partially deactivate it during runtime with
-```Java
-amoeba.setRenderUpdate(false);
-```
-and then activate it back with
-```Java
-amoeba.setRenderUpdate(true);
-```
-*Note that when rendering is deactivated, graph and some statistics are no longer updated.*
-
-But after activating rendering we need to run a cycle to update the render of contexts agents. For this example we use a request call to avoid change in contexts.
-```Java
-amoeba.request(studiedSystem.getOutput());
-```
-You can ignore this step if you run the simulation after activating rendering.
\ No newline at end of file
diff --git a/AMOEBAonAMAK/resources/100DimensionsLauncher.xml b/AMOEBAonAMAK/resources/100DimensionsLauncher.xml
index 80b64aab..cfd42e6d 100644
--- a/AMOEBAonAMAK/resources/100DimensionsLauncher.xml
+++ b/AMOEBAonAMAK/resources/100DimensionsLauncher.xml
@@ -8,106 +8,106 @@
<StartingAgents>
- <Sensor Name="px1" Source="x1"></Sensor>
- <Sensor Name="px2" Source="x2"></Sensor>
- <Sensor Name="px3" Source="x3"></Sensor>
- <Sensor Name="px4" Source="x4"></Sensor>
- <Sensor Name="px5" Source="x5"></Sensor>
- <Sensor Name="px6" Source="x6"></Sensor>
- <Sensor Name="px7" Source="x7"></Sensor>
- <Sensor Name="px8" Source="x8"></Sensor>
- <Sensor Name="px9" Source="x9"></Sensor>
- <Sensor Name="px10" Source="x10"></Sensor>
- <Sensor Name="px11" Source="x11"></Sensor>
- <Sensor Name="px12" Source="x12"></Sensor>
- <Sensor Name="px13" Source="x13"></Sensor>
- <Sensor Name="px14" Source="x14"></Sensor>
- <Sensor Name="px15" Source="x15"></Sensor>
- <Sensor Name="px16" Source="x16"></Sensor>
- <Sensor Name="px17" Source="x17"></Sensor>
- <Sensor Name="px18" Source="x18"></Sensor>
- <Sensor Name="px19" Source="x19"></Sensor>
- <Sensor Name="px20" Source="x20"></Sensor>
- <Sensor Name="px21" Source="x21"></Sensor>
- <Sensor Name="px22" Source="x22"></Sensor>
- <Sensor Name="px23" Source="x23"></Sensor>
- <Sensor Name="px24" Source="x24"></Sensor>
- <Sensor Name="px25" Source="x25"></Sensor>
- <Sensor Name="px26" Source="x26"></Sensor>
- <Sensor Name="px27" Source="x27"></Sensor>
- <Sensor Name="px28" Source="x28"></Sensor>
- <Sensor Name="px29" Source="x29"></Sensor>
- <Sensor Name="px30" Source="x30"></Sensor>
- <Sensor Name="px31" Source="x31"></Sensor>
- <Sensor Name="px32" Source="x32"></Sensor>
- <Sensor Name="px33" Source="x33"></Sensor>
- <Sensor Name="px34" Source="x34"></Sensor>
- <Sensor Name="px35" Source="x35"></Sensor>
- <Sensor Name="px36" Source="x36"></Sensor>
- <Sensor Name="px37" Source="x37"></Sensor>
- <Sensor Name="px38" Source="x38"></Sensor>
- <Sensor Name="px39" Source="x39"></Sensor>
- <Sensor Name="px40" Source="x40"></Sensor>
- <Sensor Name="px41" Source="x41"></Sensor>
- <Sensor Name="px42" Source="x42"></Sensor>
- <Sensor Name="px43" Source="x43"></Sensor>
- <Sensor Name="px44" Source="x44"></Sensor>
- <Sensor Name="px45" Source="x45"></Sensor>
- <Sensor Name="px46" Source="x46"></Sensor>
- <Sensor Name="px47" Source="x47"></Sensor>
- <Sensor Name="px48" Source="x48"></Sensor>
- <Sensor Name="px49" Source="x49"></Sensor>
- <Sensor Name="px50" Source="x50"></Sensor>
- <Sensor Name="px51" Source="x51"></Sensor>
- <Sensor Name="px52" Source="x52"></Sensor>
- <Sensor Name="px53" Source="x53"></Sensor>
- <Sensor Name="px54" Source="x54"></Sensor>
- <Sensor Name="px55" Source="x55"></Sensor>
- <Sensor Name="px56" Source="x56"></Sensor>
- <Sensor Name="px57" Source="x57"></Sensor>
- <Sensor Name="px58" Source="x58"></Sensor>
- <Sensor Name="px59" Source="x59"></Sensor>
- <Sensor Name="px60" Source="x60"></Sensor>
- <Sensor Name="px61" Source="x61"></Sensor>
- <Sensor Name="px62" Source="x62"></Sensor>
- <Sensor Name="px63" Source="x63"></Sensor>
- <Sensor Name="px64" Source="x64"></Sensor>
- <Sensor Name="px65" Source="x65"></Sensor>
- <Sensor Name="px66" Source="x66"></Sensor>
- <Sensor Name="px67" Source="x67"></Sensor>
- <Sensor Name="px68" Source="x68"></Sensor>
- <Sensor Name="px69" Source="x69"></Sensor>
- <Sensor Name="px70" Source="x70"></Sensor>
- <Sensor Name="px71" Source="x71"></Sensor>
- <Sensor Name="px72" Source="x72"></Sensor>
- <Sensor Name="px73" Source="x73"></Sensor>
- <Sensor Name="px74" Source="x74"></Sensor>
- <Sensor Name="px75" Source="x75"></Sensor>
- <Sensor Name="px76" Source="x76"></Sensor>
- <Sensor Name="px77" Source="x77"></Sensor>
- <Sensor Name="px78" Source="x78"></Sensor>
- <Sensor Name="px79" Source="x79"></Sensor>
- <Sensor Name="px80" Source="x80"></Sensor>
- <Sensor Name="px81" Source="x81"></Sensor>
- <Sensor Name="px82" Source="x82"></Sensor>
- <Sensor Name="px83" Source="x83"></Sensor>
- <Sensor Name="px84" Source="x84"></Sensor>
- <Sensor Name="px85" Source="x85"></Sensor>
- <Sensor Name="px86" Source="x86"></Sensor>
- <Sensor Name="px87" Source="x87"></Sensor>
- <Sensor Name="px88" Source="x88"></Sensor>
- <Sensor Name="px89" Source="x89"></Sensor>
- <Sensor Name="px90" Source="x90"></Sensor>
- <Sensor Name="px91" Source="x91"></Sensor>
- <Sensor Name="px92" Source="x92"></Sensor>
- <Sensor Name="px93" Source="x93"></Sensor>
- <Sensor Name="px94" Source="x94"></Sensor>
- <Sensor Name="px95" Source="x95"></Sensor>
- <Sensor Name="px96" Source="x96"></Sensor>
- <Sensor Name="px97" Source="x97"></Sensor>
- <Sensor Name="px98" Source="x98"></Sensor>
- <Sensor Name="px99" Source="x99"></Sensor>
- <Sensor Name="px100" Source="x100"></Sensor>
+ <Sensor Name="px1" ></Sensor>
+ <Sensor Name="px2" ></Sensor>
+ <Sensor Name="px3" ></Sensor>
+ <Sensor Name="px4" ></Sensor>
+ <Sensor Name="px5" ></Sensor>
+ <Sensor Name="px6" ></Sensor>
+ <Sensor Name="px7" ></Sensor>
+ <Sensor Name="px8" ></Sensor>
+ <Sensor Name="px9" ></Sensor>
+ <Sensor Name="px10" ></Sensor>
+ <Sensor Name="px11" ></Sensor>
+ <Sensor Name="px12" ></Sensor>
+ <Sensor Name="px13" ></Sensor>
+ <Sensor Name="px14" ></Sensor>
+ <Sensor Name="px15" ></Sensor>
+ <Sensor Name="px16" ></Sensor>
+ <Sensor Name="px17" ></Sensor>
+ <Sensor Name="px18" ></Sensor>
+ <Sensor Name="px19" ></Sensor>
+ <Sensor Name="px20" ></Sensor>
+ <Sensor Name="px21" ></Sensor>
+ <Sensor Name="px22" ></Sensor>
+ <Sensor Name="px23" ></Sensor>
+ <Sensor Name="px24" ></Sensor>
+ <Sensor Name="px25" ></Sensor>
+ <Sensor Name="px26" ></Sensor>
+ <Sensor Name="px27" ></Sensor>
+ <Sensor Name="px28" ></Sensor>
+ <Sensor Name="px29" ></Sensor>
+ <Sensor Name="px30" ></Sensor>
+ <Sensor Name="px31" ></Sensor>
+ <Sensor Name="px32" ></Sensor>
+ <Sensor Name="px33" ></Sensor>
+ <Sensor Name="px34" ></Sensor>
+ <Sensor Name="px35" ></Sensor>
+ <Sensor Name="px36" ></Sensor>
+ <Sensor Name="px37" ></Sensor>
+ <Sensor Name="px38" ></Sensor>
+ <Sensor Name="px39" ></Sensor>
+ <Sensor Name="px40" ></Sensor>
+ <Sensor Name="px41" ></Sensor>
+ <Sensor Name="px42" ></Sensor>
+ <Sensor Name="px43" ></Sensor>
+ <Sensor Name="px44" ></Sensor>
+ <Sensor Name="px45" ></Sensor>
+ <Sensor Name="px46" ></Sensor>
+ <Sensor Name="px47" ></Sensor>
+ <Sensor Name="px48" ></Sensor>
+ <Sensor Name="px49" ></Sensor>
+ <Sensor Name="px50" ></Sensor>
+ <Sensor Name="px51" ></Sensor>
+ <Sensor Name="px52" ></Sensor>
+ <Sensor Name="px53" ></Sensor>
+ <Sensor Name="px54" ></Sensor>
+ <Sensor Name="px55" ></Sensor>
+ <Sensor Name="px56" ></Sensor>
+ <Sensor Name="px57" ></Sensor>
+ <Sensor Name="px58" ></Sensor>
+ <Sensor Name="px59" ></Sensor>
+ <Sensor Name="px60" ></Sensor>
+ <Sensor Name="px61" ></Sensor>
+ <Sensor Name="px62" ></Sensor>
+ <Sensor Name="px63" ></Sensor>
+ <Sensor Name="px64" ></Sensor>
+ <Sensor Name="px65" ></Sensor>
+ <Sensor Name="px66" ></Sensor>
+ <Sensor Name="px67" ></Sensor>
+ <Sensor Name="px68" ></Sensor>
+ <Sensor Name="px69" ></Sensor>
+ <Sensor Name="px70" ></Sensor>
+ <Sensor Name="px71" ></Sensor>
+ <Sensor Name="px72" ></Sensor>
+ <Sensor Name="px73" ></Sensor>
+ <Sensor Name="px74" ></Sensor>
+ <Sensor Name="px75" ></Sensor>
+ <Sensor Name="px76" ></Sensor>
+ <Sensor Name="px77" ></Sensor>
+ <Sensor Name="px78" ></Sensor>
+ <Sensor Name="px79" ></Sensor>
+ <Sensor Name="px80" ></Sensor>
+ <Sensor Name="px81" ></Sensor>
+ <Sensor Name="px82" ></Sensor>
+ <Sensor Name="px83" ></Sensor>
+ <Sensor Name="px84" ></Sensor>
+ <Sensor Name="px85" ></Sensor>
+ <Sensor Name="px86" ></Sensor>
+ <Sensor Name="px87" ></Sensor>
+ <Sensor Name="px88" ></Sensor>
+ <Sensor Name="px89" ></Sensor>
+ <Sensor Name="px90" ></Sensor>
+ <Sensor Name="px91" ></Sensor>
+ <Sensor Name="px92" ></Sensor>
+ <Sensor Name="px93" ></Sensor>
+ <Sensor Name="px94" ></Sensor>
+ <Sensor Name="px95" ></Sensor>
+ <Sensor Name="px96" ></Sensor>
+ <Sensor Name="px97" ></Sensor>
+ <Sensor Name="px98" ></Sensor>
+ <Sensor Name="px99" ></Sensor>
+ <Sensor Name="px100" ></Sensor>
<Controller Name="Controller" Oracle="test">
<ErrorMargin ErrorAllowed="2000.0" AugmentationFactorError="5.0" DiminutionFactorError="0.4" MinErrorAllowed="0.1" NConflictBeforeAugmentation="40" NSuccessBeforeDiminution="80" />
diff --git a/AMOEBAonAMAK/resources/fourDimensionsLauncher.xml b/AMOEBAonAMAK/resources/fourDimensionsLauncher.xml
index 5c3cf54d..d3190af0 100644
--- a/AMOEBAonAMAK/resources/fourDimensionsLauncher.xml
+++ b/AMOEBAonAMAK/resources/fourDimensionsLauncher.xml
@@ -9,12 +9,12 @@
<StartingAgents>
- <Sensor Name="px1" Source="x1"></Sensor>
- <Sensor Name="px2" Source="x2"></Sensor>
- <Sensor Name="px3" Source="x3"></Sensor>
- <Sensor Name="px4" Source="x4"></Sensor>
+ <Sensor Name="px1" Enum="false"/>
+ <Sensor Name="px2" Enum="false"/>
+ <Sensor Name="px3" Enum="false"/>
+ <Sensor Name="px4" Enum="false"/>
- <Controller Name="Controller" Oracle="test">
+ <Controller Name="Controller">
<ErrorMargin ErrorAllowed="2000.0" AugmentationFactorError="5.0" DiminutionFactorError="0.4" MinErrorAllowed="0.1" NConflictBeforeAugmentation="40" NSuccessBeforeDiminution="80" />
<InexactMargin InexactAllowed="500.0" AugmentationInexactError="2.5" DiminutionInexactError="0.2" MinInexactAllowed="0.05" NConflictBeforeInexactAugmentation="40" NSuccessBeforeInexactDiminution="80" />
</Controller>
diff --git a/AMOEBAonAMAK/resources/genNDimLauncher.py b/AMOEBAonAMAK/resources/genNDimLauncher.py
index 362aaea3..abd04817 100644
--- a/AMOEBAonAMAK/resources/genNDimLauncher.py
+++ b/AMOEBAonAMAK/resources/genNDimLauncher.py
@@ -13,10 +13,10 @@ start = """<?xml version="1.0" encoding="UTF-8"?>
<StartingAgents>
"""
-sensor = '\t\t<Sensor Name="px%d" Source="x%d"></Sensor>\n'
+sensor = '\t\t<Sensor Name="px%d" Enum="false">\n'
end = """
- <Controller Name="Controller" Oracle="test">
+ <Controller Name="Controller">
<ErrorMargin ErrorAllowed="2000.0" AugmentationFactorError="5.0" DiminutionFactorError="0.4" MinErrorAllowed="0.1" NConflictBeforeAugmentation="40" NSuccessBeforeDiminution="80" />
<InexactMargin InexactAllowed="500.0" AugmentationInexactError="2.5" DiminutionInexactError="0.2" MinInexactAllowed="0.05" NConflictBeforeInexactAugmentation="40" NSuccessBeforeInexactDiminution="80" />
</Controller>
diff --git a/AMOEBAonAMAK/resources/threeDimensionsLauncher.xml b/AMOEBAonAMAK/resources/threeDimensionsLauncher.xml
index 5961eb39..21b6dcb9 100644
--- a/AMOEBAonAMAK/resources/threeDimensionsLauncher.xml
+++ b/AMOEBAonAMAK/resources/threeDimensionsLauncher.xml
@@ -9,11 +9,11 @@
<StartingAgents>
- <Sensor Name="px1" Source="x1"></Sensor>
- <Sensor Name="px2" Source="x2"></Sensor>
- <Sensor Name="px3" Source="x3"></Sensor>
+ <Sensor Name="px1" Enum="false" />
+ <Sensor Name="px2" Enum="false" />
+ <Sensor Name="px3" Enum="false" />
- <Controller Name="Controller" Oracle="test">
+ <Controller Name="Controller">
<ErrorMargin ErrorAllowed="2000.0" AugmentationFactorError="5.0" DiminutionFactorError="0.4" MinErrorAllowed="0.1" NConflictBeforeAugmentation="40" NSuccessBeforeDiminution="80" />
<InexactMargin InexactAllowed="500.0" AugmentationInexactError="2.5" DiminutionInexactError="0.2" MinInexactAllowed="0.05" NConflictBeforeInexactAugmentation="40" NSuccessBeforeInexactDiminution="80" />
</Controller>
diff --git a/AMOEBAonAMAK/resources/twoDimensionsLauncher.xml b/AMOEBAonAMAK/resources/twoDimensionsLauncher.xml
index 388a8aa1..2c14ff6c 100644
--- a/AMOEBAonAMAK/resources/twoDimensionsLauncher.xml
+++ b/AMOEBAonAMAK/resources/twoDimensionsLauncher.xml
@@ -6,20 +6,14 @@
<Learning allowed = "true" creationOfNewContext = "true" loadPresetContext = "false"></Learning>
</Configuration>
-
<StartingAgents>
+ <Sensor Name="px" Enum="false" />
+ <Sensor Name="py" Enum="false" />
- <Sensor Name="px" Source="x"></Sensor>
- <Sensor Name="py" Source="y"></Sensor>
-
- <Controller Name="Controller" Oracle="test">
+ <Controller Name="Controller">
<ErrorMargin ErrorAllowed="2000.0" AugmentationFactorError="5.0" DiminutionFactorError="0.4" MinErrorAllowed="0.1" NConflictBeforeAugmentation="40" NSuccessBeforeDiminution="80" />
<InexactMargin InexactAllowed="500.0" AugmentationInexactError="2.5" DiminutionInexactError="0.2" MinInexactAllowed="0.05" NConflictBeforeInexactAugmentation="40" NSuccessBeforeInexactDiminution="80" />
</Controller>
-
-
-
</StartingAgents>
-
</System>
diff --git a/AMOEBAonAMAK/documentation/benchmark.md b/documentation/gui.md
similarity index 100%
rename from AMOEBAonAMAK/documentation/benchmark.md
rename to documentation/gui.md
diff --git a/documentation/installing.md b/documentation/installing.md
new file mode 100644
index 00000000..874ec65c
--- /dev/null
+++ b/documentation/installing.md
@@ -0,0 +1,36 @@
+# Installing and build AMOEBAonAMAK
+
+## Dependencies
+- maven (tested with 3.6.0) or eclipse (tested with 2019)
+- Java 8 or more (tested with Java 8 and 11)
+
+## Build AMOEBAonAMAK
+Clone the repo : `git clone https://github.com/Hugi-R/AMOEBA3.git`
+
+To get the latest, but less stable, version : `git clone https://github.com/Hugi-R/AMOEBA3.git -b dev`
+
+### Build with maven
+Compile and run tests :
+
+`mvn clean test` or `mvn test`
+
+Build an executable jar with all dependencies :
+
+`mvn clean compile assembly:single`
+
+Results are in `target` folder.
+
+You may have to tweak the `pom.xml` to make it compatible with your maven/java setup, or to chose the starting class of your executable jar.
+
+### Build with eclipse
+`File > Open project from file system`, select the folder `AMOEBA3`, eclipse should detect 3 maven projects :
+```
+AMOEBA-parent
+ | AMAKFX
+ | AMOEBAonAMAK
+```
+`Finish`
+
+Make sure it works by right-clicking on `AMOEBA-parent` > `Run as > Maven test`. You should get a `BUILD SUCCES`.
+
+Make sure it works with JavaFX : right-click on `AMAKFX.src.fr.irit.smac.amak.examples.philosophers.PhilosopherLaunchExample.java` or any other example and `Run as > Java application`. Do the same for `AMOEBAonAMAK.src.experiments.MinimalMain.java`. You should get a new window, and no error in the console.
\ No newline at end of file
diff --git a/documentation/usage.md b/documentation/usage.md
new file mode 100644
index 00000000..b96a4288
--- /dev/null
+++ b/documentation/usage.md
@@ -0,0 +1,147 @@
+# How to use AMOEBA
+
+## What AMOEBA can do :
+AMOEBA is a learning function, and it does that by building a model of the function.
+
+The inputs of that function can be any amount of numerical variables (usually continuous, like the x and y coordinate in an Euclidian space), we call these variables Percepts. The output (result) of our function is a single, numerical variable (like whether or not that point in our Euclidian space has the colour red), we call this result Prediction, and the correct prediction is called Oracle.
+
+ Amoeba can be asked to learn, or to provide a prediction, at any time. Making it suitable for real time usage and lifelong learning.
+
+# Preparations
+First, make sure that you properly [installed AMOEBAonAMAK](installing.md), preferably with eclipse.
+
+Depending on your problem, determine what AMOEBA should learn, and from what. But keep in mind that an amoeba predict one variable, if you have multiple variables to predict, you'll need multiple amoebas.
+
+## Create a config file
+A config file is a xml file used to initialize your amoeba. Most importantly it contain the list of percepts.
+
+Your config file should look like this :
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<System>
+
+ <!-- General config options -->
+ <Configuration>
+ <Learning allowed = "true" creationOfNewContext = "true" loadPresetContext = "false"></Learning>
+ </Configuration>
+
+ <StartingAgents>
+ <!-- List your percepts here -->
+ <Sensor Name="px" Enum="false" />
+ <Sensor Name="py" Enum="false" />
+
+ <Controller Name="Controller">
+ <ErrorMargin ErrorAllowed="2000.0" AugmentationFactorError="5.0" DiminutionFactorError="0.4" MinErrorAllowed="0.1" NConflictBeforeAugmentation="40" NSuccessBeforeDiminution="80" />
+ <InexactMargin InexactAllowed="500.0" AugmentationInexactError="2.5" DiminutionInexactError="0.2" MinInexactAllowed="0.05" NConflictBeforeInexactAugmentation="40" NSuccessBeforeInexactDiminution="80" />
+ </Controller>
+ </StartingAgents>
+
+</System>
+```
+With :
+- **Configuration** make sure `Learning` and `creationOfNewContext` are at `true` if you want to train your model.
+- **Sensor** represent one percept, make sure to remember the name, we will use it later. `Enum` tell AMOEBA whether or not the variable linked to this percept is continuous, or discrete.
+- **Controller** these are hyperparameter for the AMOEBA, they affect how fast and how well an amoeba learn. They can be dynamically adjusted during training, AMOEBA even does it automatically ! You still might want to adjust `MinErrorAllowed` and `MinInexactAllowed`, as they're dependent on your problem.
+
+## Create your studied system java class
+We have to tell AMOEBA what we want it to learn. Although we can hand-feed an amoeba with our data, providing a studied system allow to make full use of the graphical user interface.
+
+Your studied system must implement the `StudiedSystem` interface. Most importantly :
+- `public void playOneStep()` advance the simulation of the studied system by one step (for example, read the next data point in a file).
+- `public HashMap<String, Double> getOutput()` give the value of percepts and oracle for the current step.
+
+The hash map returned by `getOutput()` MUST have this structure :
+```
+{
+ "contextName1":value1,
+ "contextName2":value2,
+ ...
+ "oracle":expectedPrediction
+}
+```
+Where the keys ("contextNameX") are the ones set in the config file, and values the value of that percept at that step.
+
+For example it can look like :
+```Java
+public HashMap<String, Double> getOutput(){
+ HashMap<String, Double> ret = new HashMap<>();
+ ret.put("px",x);
+ ret.put("py",y);
+ ret.put("oracle", computeOracleFor(x,y));
+ return ret;
+}
+```
+Where `px` and `py` are the name of our 2 percepts, `x` and `y` where set in `playOneStep()`, and `computeOracleFor(x,y)` return the oracle for the point (x,y).
+
+Usage example with a basic learning loop :
+```Java
+for(int i = 0; i < 1000; i++){
+ studiedSystem.playOneStep();
+ amoeba.learn(studiedSystem.getOutput())
+}
+```
+There's a 3rd method in StudiedSystem : `public double requestOracle(HashMap<String, Double> request)` it is used when the user ask amoeba (via the GUI) to learn at a specific point. The GUI will ask the studied system what the oracle is at that point, then ask the amoeba to learn that point. If you don't use that feature, no need to put any meaningful code in that method.
+
+# Your main method
+Your main method is where you'll instantiate, configure, and use your amoeba.
+```Java
+public static void main(String[] args) {
+ //TODO your code for creating an amoeba
+}
+```
+## Global configuration
+AMAK offers some configuration that must be changed before the creation of a new amoeba. They are in `AMAKFX.src.fr.irit.smac.amak.Configuration.java` and the most important are :
+- `allowedSimultaneousAgentsExecution` : control multithreading of agents.
+- `commandLineMode` : tell whether or not to use the graphical user interface.
+```Java
+public static void main(String[] args) {
+ //global configuration
+ Configuration.commandLineMode = false;
+ Configuration.allowedSimultaneousAgentsExecution = 4;
+}
+```
+## Instantiating an amoeba
+There's multiple ways to instantiate an amoeba, the easiest is :
+```Java
+public static void main(String[] args) {
+ //global configuration
+ Configuration.commandLineMode = false;
+ Configuration.allowedSimultaneousAgentsExecution = 4;
+
+ //intantiate an amoeba
+ StudiedSystem studiedSystem = new myStudiedSystem();
+ AMOEBA amoeba = new AMOEBA("path/to/my/configFile.xml", studiedSystem);
+}
+```
+With that you get a perfectly functioning amoeba, but it can only be [controlled with the GUI](gui.md), which can be very limiting.
+
+## Using an amoeba
+Like shown before, you can control amoeba's learning with a very simple loop. And the same can be done when asking amoeba for predictions :
+```Java
+public static void main(String[] args) {
+ //global configuration
+ Configuration.commandLineMode = false;
+ Configuration.allowedSimultaneousAgentsExecution = 4;
+
+ //intantiate an amoeba
+ StudiedSystem studiedSystem = new myStudiedSystem();
+ AMOEBA amoeba = new AMOEBA("path/to/my/configFile.xml", studiedSystem);
+
+ //learn 1000 points
+ for(int i = 0; i < 1000; i++){
+ studiedSystem.playOneStep();
+ amoeba.learn(studiedSystem.getOutput());
+ }
+
+ //make prediction for 1000 other points
+ for(int i = 0; i < 1000; i++){
+ studiedSystem.playOneStep();
+ System.out.println(
+ amoeba.request(studiedSystem.getOutput())
+ );
+ }
+}
+```
+We can ask amoeba how well it performed on the last prediction with `amoeba.getHeads().get(0).getCriticity()`.
+
+For more example on how to use amoeba, check `AdvancedMain.java`, `MinimalMain.java`, and `Main.java` in the `experiments` package.
\ No newline at end of file
diff --git a/documentation/what_is.md b/documentation/what_is.md
new file mode 100644
index 00000000..8521ea66
--- /dev/null
+++ b/documentation/what_is.md
@@ -0,0 +1,11 @@
+# What is ...
+## AMAKFX :
+AMAKFX is a fork of [AMAK](https://bitbucket.org/perlesa/amak/src/master/) (A Multi Agent frameworK), modified to use JavaFX instead of Swing for the user interface.
+It also provide various improvements or modifications allowing for easier use with AMOEBA.
+
+## AMOEBA :
+AMOEBA (Agnostic MOdElBuilder by self-Adaptation) is a Multi-Agent system based on the Adaptative Multi Agent System (AMAS) approach, designed for building model of complex Systems at real time. Real time meaning it adapt quickly.
+For more information on AMOEBA, see [Self-Adaptive Model Generation for Ambient Systems](https://www.sciencedirect.com/science/article/pii/S1877050916301818).
+
+## AMOEBAonAMAK :
+AMOEBAonAMAK, as its name implies, is a port of AMOEBA onto AMAKFX, allowing AMOEBA's developer and user to focus on agent's behaviour, and not nitty-gritty details like, scheduling, multithreading, and GUI.
\ No newline at end of file
--
GitLab