--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Tue Jun 04 15:18:01 2024 +0000
@@ -0,0 +1,188 @@
+# Galaxy tools for GAMA platform
+
+Desc
+====
+
+The **gama_tool.xml** tool runs a **GAMA Python client**
+interacting with **gama-server (Headless server)**
+concerning a **"Predator Prey" agent-based simulation**.
+It relies on the **gama.simg** container.
+
+See also :
+[containers](../containers) from where container gama.simg comes ;
+[use-containers](../use-containers) ;
+[../../README.md](../../README.md)
+
+The **gama_tool.xml** tool case has been written **from an existing example**
+(*same example as in [use-containers](../use-containers)*) :
+
+  - example code of https://github.com/gitrdm/gama-client-python
+    project
+  - URL : https://github.com/gitrdm/gama-client-python?tab=readme-ov-file#example-code
+  - more : see [../../README.md](../../README.md)
+
+The **gama_tool.xml** tool case is based on :
+
+  - A **"Predator Prey" agent-based model** of the **GAMA platform**.
+  - A **Python program** (*MY_sequential_example.py*) interacting with
+    the GAMA platform in headless mode, as a GAMA Python client to :
+    - **drive the experiment** : initialization, parameters settings,
+      running, pausing, running some more steps, stop.
+    - **observe the experiment** : getting information values such as :
+      cycle, nb_preys/nb_preys_init...
+
+Sources
+=======
+
+The reused existing files have been copied
+at **[src/originals](./src/originals)** folder so :
+
+  - **sequential_example.py**
+    from gama-client-python/examples/sequential_example.py :
+
+    ```
+    # examples
+    cd src/originals
+    mkdir TMP; cd TMP
+    git clone https://github.com/gitrdm/gama-client-python.git
+    cd ..
+    cp -fr TMP/gama-client-python/examples .
+    rm -fr TMP
+    ```
+
+  - **predatorPrey.gaml** and **gama-headless.sh** from gama-platform/headless
+    (gama-platform/headless/samples/predatorPrey/predatorPrey.gaml, 
+    gama-platform/headless/gama-headless.sh)
+    by gama.simg :
+
+    ```
+    # headless
+    gama_SIMGPATH=../../../containers/gama.simg
+    cd src/originals
+    mkdir OPT
+    singularity exec --bind ./OPT:/OPT $gama_SIMGPATH bash -c "cp -fr /opt/gama-platform /OPT/."
+    cp -fr OPT/gama-platform/headless headless
+    rm -fr OPT
+    ```
+
+Galaxy tool Inputs / Outputs
+============================
+
+**[gama_tool.xml](./gama_tool.xml) Inputs** :
+
+  - **nb_preys_init** (integer)
+  - **nb_predators_init** (integer)
+  - **nb_more_steps** (integer)
+
+**[gama_tool.xml](./gama_tool.xml) Outputs** :
+
+  - **results .txt file** produced while running the simulator 
+    (cf 'reflex save_result' into MY_predatorPrey.gaml).
+  - **run_server .txt file** : gama-server screen display capture
+  - **run_client .txt file** : gama-client screen display capture
+
+Galaxy tool Code
+================
+
+The Galaxy tool **[src](./src) folder** contains :
+
+  - **[MY_sequential_example.py](./src/MY_sequential_example.py)** :
+    **Python code**
+
+    - created from [src/originals/examples/sequential_example.py](./src/originals/examples/sequential_example.py)
+    - modification : variables values for gama-server
+      (*MY_SERVER_URL, MY_SERVER_PORT, GAML_FILE_PATH_ON_SERVER*),
+      for experiment (*EXPERIMENT_NAME, MY_EXP_INIT_PARAMETERS*).
+    - modification : added some "print"
+
+  - **[MY_predatorPrey.gaml](./src/MY_predatorPrey.gaml)** :
+    **"Predator Prey" agent-based simulator** file
+
+    - created from [src/originals/headless/samples/predatorPrey/predatorPrey.gaml](./src/originals/headless/samples/predatorPrey/predatorPrey.gaml)
+    - modification : added **'reflex save_result'** to save some results data
+      into results.txt file.
+
+  - **[cmd_gama_headless.sh](./src/cmd_gama_headless.sh)** :
+    **commands file** (Shell script)
+    launching GAMA Headless gama-server *(by calling MY_gama-headless.sh)*
+
+  - **[cmd_python_client.sh](./src/cmd_python_client.sh)** :
+    **commands file** (Shell script)
+    launching Python program MY_sequential_example.py
+
+  - **[MY_gama-headless.sh](./src/MY_gama-headless.sh)** :
+
+    - created from [src/originals/headless/gama-headless.sh](./src/originals/headless/gama-headless.sh)
+    - modify : setting **java.io.tmpdir** property
+      (```-Djava.io.tmpdir=$MY_TEMP_DIR```),
+      because of gama_tool.xml running error :
+      ```
+      javax.imageio.IIOException: Can't create cache file!
+        at java.desktop/javax.imageio.ImageIO.createImageInputStream(ImageIO.java:361)
+        ....
+      Caused by: java.nio.file.FileSystemException: /tmp/imageio10268746820164254686.tmp: Read-only file system
+        ....
+      SLF4J: No SLF4J providers were found.
+      SLF4J: Defaulting to no-operation (NOP) logger implementation
+      SLF4J: See http://www.slf4j.org/codes.html#noProviders for further details.
+      ```
+
+      *Default temporary directory for Linux is /tmp.  The JVM automatically
+      sets the temporary directory path as a system property. It can be
+      changed by setting the java.io.tmpdir property to the desired
+      path when starting the JVM.*
+
+Local run by 'planemo serve'
+============================
+
+**Installs** :
+
+  - Install Singularity : singularity version 3.8.5
+
+  - Install Galaxy code :
+    ```
+    cd ~/DEVS
+    git clone https://github.com/galaxyproject/galaxy.git
+    ```
+
+  Note : Galaxy requiring at least singularity 3.7
+         (cf singularity exec : --no-mount option)
+
+  - Install Planemo into a Python virtualenv :
+    ```
+    pip3 install --upgrade pip wheel setuptools virtualenv
+    python3 -m venv _venv_planemo
+    source _venv_planemo/bin/activate
+
+    python3 -m pip install planemo
+    ```
+
+**Use** :
+
+  ```
+  source _fab/_venv_planemo/bin/activate
+  ```
+
+  - Survey :
+    ```
+    htop
+    ```
+
+  - Check tool syntax :
+    ```
+    planemo lint --report_level all --fail_level error gama_tool.xml
+    ```
+
+  - Run tool :
+    ```
+    make serveGAMA
+    ```
+
+  => http://127.0.0.1:9090
+
+Use those Galaxy tools
+======================
+
+See [use-tools](../use-tools).
+
+