# 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).