GAMA Platform: Spatial Agent-Based Modeling for Complex Social and Environmental Systems

GAMA (GIS & Agent-based Modeling Architecture) is an open-source, spatially explicit agent-based modeling platform that bridges the gap between geographic information systems (GIS) and agent-based simulation. Developed by the IRD/SU International Research Unit UMMISCO and a global consortium of academic partners, GAMA enables technical teams to build, calibrate, and analyze large-scale simulations where geography is a first-class citizen — not an afterthought.

Why Spatial Explicitness Matters in Social Simulation

Most mainstream ABM platforms treat space as a grid or a network. GAMA treats space as a full GIS environment. Agents in GAMA can inhabit real-world geometries imported directly from shapefiles, OpenStreetMap exports, or GeoJSON files. This distinction is critical for applications such as:

• Urban mobility and pedestrian flow — agents navigate actual street networks with realistic topology
• Disease spread and epidemiology — infection dynamics tied to real building footprints and population density layers
• Disaster evacuation modeling — agents respond to flood inundation rasters or wildfire spread polygons
• Market adoption and opinion dynamics — social influence weighted by spatial proximity and network centrality

When your simulation question is inherently geographic, GAMA eliminates the translation layer between your GIS data and your behavioral model.

The GAML Language: Declarative Agent Specification

GAMA uses its own domain-specific language, GAML (GAMA Modeling Language), which is purpose-built for agent-based modeling. GAML is declarative and readable, combining species definitions, behavioral rules, and spatial queries in a single coherent syntax.

A minimal GAML species definition looks like this:

species Citizen {
    float infection_risk <- 0.05;
    geometry location <- any_location_in(city_boundary);

    reflex move {
        do wander speed: 1.5;
    }

    reflex spread when: infection_risk > 0.3 {
        ask Citizen at_distance 5 {
            infection_risk <- infection_risk + 0.1;
        }
    }
}

Key GAML constructs that distinguish it from general-purpose languages:

• reflex — a behavior that fires every simulation step, optionally gated by a when condition
• at_distance — a spatial query returning all agents within a given radius, computed efficiently via spatial indexing
• do wander — a built-in action for random movement respecting geometric boundaries
• any_location_in — places an agent at a random point within a polygon geometry

GAML's spatial operators are backed by the Java Topology Suite (JTS), giving modelers access to union, intersection, buffer, convex hull, and Voronoi operations directly within behavioral rules.

Loading and Using Real GIS Data

One of GAMA's most powerful features is its native GIS pipeline. Importing a shapefile is a single line:

file city_shapefile <- shapefile("../data/city_districts.shp");
geometry city_boundary <- envelope(city_shapefile);

init {
    create District from: city_shapefile with: [district_name:: "NAME", population:: "POP_2020"];
}

GAMA automatically reprojects coordinate reference systems (CRS) and exposes shapefile attributes as agent variables. Raster data (GeoTIFF, ASCII grids) can be loaded similarly and queried with grid species that map directly onto raster cells — enabling terrain-aware movement, pollution dispersion, or land-use change models.

For dynamic scenarios, GAMA supports real-time GIS updates: a simulation can reload a shapefile mid-run to reflect, for example, a flood boundary expanding over time.

Batch Experimentation and Calibration

GAMA includes a built-in Batch Experiment mode that automates parameter sweeps and stochastic replication without external scripting. A batch experiment block specifies parameter ranges and a stopping criterion:

experiment Calibration type: batch repeat: 30 keep_seed: false until: (time > 500) {
    parameter "Infection Risk" var: infection_risk min: 0.01 max: 0.2 step: 0.01;
    parameter "Movement Speed" var: move_speed min: 0.5 max: 3.0 step: 0.5;
}

Results are automatically aggregated across replications and exported to CSV for analysis in R, Python, or any statistical tool. For calibration against empirical data, GAMA integrates with the OpenMOLE workflow engine, which provides distributed parameter space exploration using genetic algorithms, PSE (Pattern Space Exploration), and Sobol sensitivity analysis — all without modifying the GAMA model itself.

Multi-Level Modeling: Agents Within Agents

GAMA supports multi-level architectures where macro-level agents contain and govern populations of micro-level agents. A District agent can own a sub-population of Citizen agents, apply district-level policies (e.g., lockdown rules), and aggregate statistics upward to a City agent. This hierarchical structure maps naturally onto real administrative and organizational systems and avoids the flat-world assumption that limits many ABM platforms.

Performance Considerations for Large-Scale Models

GAMA is implemented in Java and uses Eclipse as its IDE foundation. For models with hundreds of thousands of agents, key performance levers include:

• Spatial indexing — GAMA uses a quadtree index by default; switching to an R-tree index (use_regular_agents_optimization: true) can improve at_distance query performance by 3–5× for dense populations
• Headless mode — running GAMA without the GUI via gama-headless.sh reduces memory overhead significantly and is essential for HPC cluster deployments
• Grid species — replacing individual raster-cell agents with a grid species reduces object overhead for terrain models
• Parallel execution — GAMA 1.9+ supports multi-threaded agent activation via the parallel keyword on reflex blocks, enabling near-linear scaling on multi-core machines for embarrassingly parallel behavioral rules

Practical Use Cases and Community Resources

GAMA has been applied in peer-reviewed research across urban planning (Hanoi flood resilience), epidemiology (COVID-19 spatial spread in West Africa), and traffic simulation (Hanoi motorcycle flow). The GAMA Platform website hosts a model library with over 150 documented examples, and the GitHub repository is actively maintained with regular releases.

For teams evaluating GAMA against alternatives:

• vs. NetLogo — GAMA offers superior GIS integration and performance at scale; NetLogo has a gentler learning curve
• vs. Mesa (Python) — GAMA's GAML is more expressive for spatial models; Mesa integrates better with Python ML pipelines
• vs. AnyLogic — GAMA is fully open-source with no licensing cost; AnyLogic offers a more polished commercial IDE and better process-flow modeling

Getting Started

GAMA is available for Windows, macOS, and Linux. The recommended entry point is the GAMA 1.9.3 release, which includes the IDE, a bundled JDK, and the full model library. The official documentation portal covers GAML syntax, GIS integration, batch experiments, and headless deployment in depth.

For teams building spatially grounded social simulations — where the where is as important as the who and what — GAMA Platform is one of the most capable and production-ready open-source tools available.