Distribution Model

This document outlines the DistributionModel project, which contains proof-of-concept implementations and experiments for distribution models within the GAMA Platform.

Running with Docker (recommended)

The only requirement is Docker (with Docker Compose). Java 17, Maven 3.8.6, and Open MPI 4.1.4 (with Java bindings) are all installed and GAMA is compiled automatically inside the image — no manual setup needed.

1. Build the image (compiles GAMA + the MPI extension, this takes a while):

   docker compose build

2. Start the container in the background:

   docker compose up -d

3. Open a shell inside the container:

   docker compose exec app bash

4. Run a simulation from inside the container (see Running the Thematic Model and How to Start the Distribution Models below for the available commands), e.g.:

   ./startHeadless ThematicModel/Continuous_Move.xml
   ./startMpiModel DistributionModel/Distribution_model_K-mean.xml 4

   Or directly from the host without an interactive shell:

   docker compose exec app bash -c "./startMpiModel DistributionModel/Distribution_model_grid.xml 6"

5. Stop the container when done:

   docker compose down

Only the Distributed_Evacuation_Model/ directory is bind-mounted into the container, so models and output.log/ results are visible/editable on the host without rebuilding the image. gama/ and gama.experimental/ are compiled into the image at build time.

Requirements (manual / non-Docker setup)

To set up and run this project, you'll need the following:

• Java 17
• mpirun (Open MPI) 4.1.4: Download from https://www.open-mpi.org/software/ompi/v4.1/
• Apache Maven 3.8.6
• Java Binding for Open MPI: Refer to https://www.open-mpi.org/faq/?category=java for details.

Compiling the Project

Follow these steps to compile the project:

1. Navigate to the gama directory:

   cd gama

2. Run the build script. This process might take some time:

   ./travis/build.sh

3. Change to the Distributed_Evacuation_Model directory:

   cd ../Distributed_Evacuation_Model/

4. Give execution permissions to the script:

   chmod +x startHeadless
   chmod +x startMpiModel

---

Running the Thematic Model (for testing)

To start the Thematic Model for testing purposes , execute the following command:

./startHeadless ThematicModel/Continuous_Move.xml # Evacuation Model   

Warning : l.61 (do die;) must be uncommented for centralized execution but commented for distributed execution

How to Start the Distribution Models

KMEAN Model ------------------------------------------

For the KMEAN Model, the number of processors M must be greater than 2 and less than the total number of cores on your machine. You can find this limit using the UNIX command: grep -m 1 'cpu cores' /proc/cpuinfo. To simulate the Evacuation Model using the KMEAN model, use this command:

./startMpiModel DistributionModel/Distribution_model_K-mean.xml M

GRID Model ------------------------------------------

For the GRID Model, the number of processors N must be greater than 2 and less than the total number of cores on your machine. You can find this limit using the UNIX command: grep -m 1 'cpu cores' /proc/cpuinfo.

To adjust the number of cores used for the GRID Model, you'll need to modify two parameters within the model configuration:

• int grid_width <- 1; // grid width in cells
• int grid_height <- 2; // grid height in cells

The product of grid_width and grid_height should always equal the number of processors you intend to use.

Example: If you use 6 cores:

• int grid_width <- 3;
• int grid_height <- 2;
• // 3 x 2 = 6

Alternatively, this could also be:

• int grid_width <- 1;

• int grid_height <- 3;

• // 1 x 6 = 6

./startMpiModel DistributionModel/Distribution_model_grid.xml N      # Simulate the Evacuation Model using the GRID model

---

Results

All results from these simulations will be located in the Distributed_Evacuation_Model/output.log/ directory after the model execution. Specifically, /output.log/snapshot/ will contain the snapshots of the simulation from each Processor.

KMEAN Model gif :

---

GRID Model gif :