diff --git a/.gitignore b/.gitignore index d87fde40ea9fda723b4c3af21cf2a0a15166aee5..36e82ab8c53f5e2ae65a95b24d42eb8ffd687f08 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 2a5266053dffb0d25aa37cd55b911b0c9b202463..274c8e758e4f45d4215c0374320e7990b9caadfe 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 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0000000000000000000000000000000000000000 diff --git a/AMOEBAonAMAK/documentation/usage.md b/AMOEBAonAMAK/documentation/usage.md deleted file mode 100644 index 4c912d570bcb68f2c2eaa14ab992a36b92399207..0000000000000000000000000000000000000000 --- 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 80b64aab05c2ac584980adbdae886cc1c14f1696..cfd42e6dbd345acb0d93cca857fbd7d90b3d0a76 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 5c3cf54d9cdc2bd5f850a23d34659d6a10c358c2..d3190af0d05d2b493a1c90ee99da5a452dc207d2 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 362aaea34ba4301078511cf7d0c036514d5ee9a7..abd0481772ece772a6e2f4173a1d643676b3c19c 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 5961eb398f2aa00b8d19ccedd137e67bad25f8cd..21b6dcb92b9daf759b0d3cef070165fbcb474fae 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 388a8aa1f2a4b5b7c8030c9494e2c3b32f62376c..2c14ff6c21935f121f77d687355e8b8d95e77cc1 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 0000000000000000000000000000000000000000..874ec65c211c181136023daf4f41e16bc731dde4 --- /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 0000000000000000000000000000000000000000..b96a4288d1f01f4723cad49bde49d98b163be9a9 --- /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 0000000000000000000000000000000000000000..8521ea66530544daa33f2d90bca916ba9bd5afcb --- /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