Pandora: High-Performance C++ Agent-Based Modeling for Large-Scale Social Simulations

Agent-based modeling (ABM) of social systems frequently hits a wall when population sizes exceed tens of thousands of agents or when spatial resolution demands fine-grained raster environments. Most popular ABM platforms—NetLogo, Mesa, Repast Simphony—are designed for research prototyping and struggle to scale to millions of agents without significant re-engineering. Pandora, an open-source C++ framework developed at the Barcelona Supercomputing Center (BSC), was built from the ground up to address exactly this gap: production-scale social simulations running on HPC clusters with minimal boilerplate.

Architecture and Design Philosophy

Pandora's core design separates the simulation engine from the model logic through a clean inheritance hierarchy. Every simulation inherits from Simulation, agents from Agent, and raster layers from DynamicRaster or StaticRaster. The framework handles:

• Domain decomposition: The spatial world is automatically partitioned across MPI ranks. Each process owns a rectangular sub-domain and exchanges ghost-cell buffers with neighbors at each time step.
• Agent migration: When an agent moves across a sub-domain boundary, Pandora serializes it, transfers it to the owning rank, and deserializes it—transparently to the model code.
• Raster I/O: Environments are loaded from GeoTIFF or ASCII grid files, enabling direct integration with GIS data (land use, elevation, population density).

This architecture allows a single model codebase to run on a laptop (1 MPI rank) or a 512-core cluster without modification.

Defining Agents and Environments

A minimal Pandora agent overrides two virtual methods:

class Farmer : public Engine::Agent {
public:
    void updateState() override {
        // Decision logic: move to highest-yield raster cell within radius
        Engine::Point2D<int> best = selectBestCell(getWorld(), 5);
        setPosition(best);
    }
    void serialize() override {
        serializeAttribute("yield_accumulated", _yieldAccumulated);
    }
private:
    float _yieldAccumulated = 0.0f;
};

The updateState() method is called once per time step for every agent. Raster queries (getWorld()->getValue(raster, pos)) are thread-safe within the MPI rank's sub-domain. The serialize() method writes agent attributes to HDF5 output files for post-processing.

Environments are configured in XML:

<config>
  <Size>1000 1000</Size>
  <NumSteps>500</NumSteps>
  <raster id="yield" type="dynamic" file="yield_map.tif"/>
</config>

Scaling Characteristics

Pandora's MPI-based parallelism delivers near-linear strong scaling for spatially explicit models. Benchmarks on BSC's MareNostrum supercomputer show:

The key bottleneck at high rank counts is ghost-cell synchronization latency, which grows with perimeter-to-area ratio. For models with dense agent-to-agent interactions (e.g., social network diffusion), communication overhead increases; purely spatial movement models scale most efficiently.

Post-Processing with Cassandra

Pandora ships with Cassandra, a Qt-based visualization tool that reads the HDF5 output files and renders:

• Agent trajectories overlaid on raster layers
• Time-series plots of aggregate statistics
• Spatial heatmaps of agent density or attribute values

For scripted analysis, the Python bindings (pyPandora) expose the HDF5 schema through pandas-compatible interfaces, enabling integration with standard data science workflows.

Practical Use Cases

Land-use change modeling: Researchers at BSC have used Pandora to simulate 2 million farming households across sub-Saharan Africa, each responding to rainfall rasters and market price signals. The spatial decomposition allowed 50-year projections to complete in under 2 hours on 128 cores—a run that would take days in NetLogo.

Conflict and displacement: The FLEE model (forced migration) has been prototyped in Pandora to simulate refugee movement across road networks encoded as raster cost surfaces, with agents following least-cost paths updated dynamically as conflict zones expand.

Epidemiological spread with behavior: Unlike compartmental ODE models, Pandora agents can carry individual health states, mobility patterns, and social network links simultaneously, enabling spatially explicit SEIR variants at national population scales.

Getting Started

Pandora requires CMake ≥ 3.10, an MPI implementation (OpenMPI or MPICH), HDF5, and GDAL for GeoTIFF support. Installation on Ubuntu:

sudo apt-get install libhdf5-dev libgdal-dev libboost-dev openmpi-bin
git clone https://github.com/xrubio/pandora.git
cd pandora && mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

The repository includes four tutorial examples (Conway's Game of Life, a foraging model, a resource competition model, and a basic social diffusion model) that progressively introduce the API.

Limitations and When to Choose Alternatives

Pandora's strengths come with trade-offs. The C++ requirement raises the barrier to entry compared to Python-based frameworks. There is no built-in network topology support—social graphs must be encoded as raster proximity or managed manually. The GUI tooling (Cassandra) is functional but less polished than commercial alternatives.

For models under ~50K agents, Mesa or Repast Simphony offer faster iteration cycles. For network-centric social dynamics without spatial embedding, NetworkX + Mesa or Repast4Py are better fits. Pandora's niche is firmly in spatially explicit, population-scale simulations where HPC resources are available.

Further Resources

• Pandora GitHub Repository — source code, tutorials, and issue tracker
• BSC Computational Social Science Group — research publications using Pandora
• Pandora Documentation — API reference and user guide
• Rubio-Campillo, X. (2014). Pandora: A Versatile Agent-Based Modelling Platform for Social Simulation. JASSS, 17(1).