Repast for Python (Repast4Py) User Guide

Repast4Py can run on Linux, macOS and Windows provided there is a working MPI implementation installed and mpi4py is supported. Repast4Py is developed and tested on Linux. We recommend that Windows users use the Windows Subsystem for Linux (WSL). Installation instructions for WSL can be found here.

Under Linux, MPI can be installed using your OS’s package manager. For example, under Ubuntu 20.04 (and thus WSL), the mpich MPI implementation can be installed with:

Installation instructions for MPI on macOS can be found here.

A typical campus cluster, or HPC resource will have MPI and mpi4py installed. Check the resource’s documentation on available software for more details.

Repast4Py can be downloaded and installed from PyPI using pip. Since Repast4Py includes native MPI C++ code that needs to be compiled, the C compiler CC environment variable must be set to the mpicxx (or mpic++) compiler wrapper provided by your MPI installation.

In addition to filing issues on GitHub, support is also available via Stack Overflow. Please use the repast4py tag to ensure that we are notified of your question. Software announcements will be made on the repast-interest mailing list.

Jonathan Ozik is the Repast project lead. Please contact him through the Argonne Staff Directory if you have project-related questions.

A typical agent-based simulation consists of a population of agents each of which performs some behavior each timestep or at some frequency. In practice, this is often implemented as a loop over the agent population in which each agent executes its behavior. The time it takes to complete the loop depends on the number of agents and the complexity of the behavior. By distributing the agent population across multiple processes running in parallel, each process executes its own loop over only a subset of the population, allowing for larger agent populations and more complex behavior.

While Repas4Py is meant to make the development of distributed ABMs easier, we encourage users new to the Repast Suite to look through the different versions of Repast to determine which toolkit is most appropriate for their needs. Of note, we recommend users new to agent-based modeling to first check out Repast Simphony to develop a better understanding of the concepts behind agent-based modeling and learn how to quickly build such models.

The following sections will provide some conceptual background for a Repast-style simulation, describe how such a simulation is distributed across multiple processes with Repast4Py, and end with providing a few basic tutorials.

Like the other members of the Repast ABM family, Repast4Py organizes a model in terms of contexts and projections. A context is a simple container with set semantics. Any type of object can be put into a context, with the simple caveat that only one instance of any given object can be contained by the context. From a modeling perspective, the context represents a population of agents. The agents in a context are the population of a model. However, the context does not inherently provide any relationship or structure for that population. Projections take the population as defined in a context and impose a structure on it. Actual projections are such things as a network structure that allows agents to form links (network type relations) with each other, a grid where each agent is located in a matrix-type space, or a continuous space where an agent’s location is expressible as a non-discrete coordinate. Projections have a many-to-one relationship with contexts. Each context can have an arbitrary number of projections associated with it. When writing a model, you will create a context, populate it with agents, and attach projections to that context.

A Repast simulation moves forward by repeatedly determining the next event to execute and then executing that event. Events in Repast simulations are driven by a discrete-event scheduler. These events are scheduled to occur at a particular tick. Ticks do not necessarily represent clock-time but rather the priority of an associated event. In this way, ticks determine the order in which events occur with respect to each other. For example, if event A is scheduled at tick 3 and event B at tick 6, event A will occur before event B. Assuming nothing is scheduled at the intervening ticks, A will be immediately followed by B. There is no inherent notion of B occurring after a duration of 3 ticks. Of course, ticks can and are often given some temporal significance through the model implementation. A traffic simulation, for example, may move the traffic forward the equivalent of 30 seconds for each tick. Events can also be scheduled dynamically such that the execution of an event may schedule further events at that same or at some future tick. When writing a model, you will create a Schedule object and schedule events using that object. The events are essentially Python Callables (methods or functions) scheduled for execution at some particular tick or tick frequency.

Repast4Py was designed from the ground up as a distributed simulation framework. In practice, this means that the simulation is spread over multiple computer processes none of which have access to each other’s memory, and communicate via message passing using the Message Passing Interface (MPI) and its Python implementation MPI for Python (mpi4py).

Repast4Py distributes a simulation by providing shared implementations of the components described above. By shared, we want to emphasize the partitioned and distributed nature of the simulation. The global simulation is shared among a pool of processes, each of which is responsible for some portion of it, and stiched into a global whole through the use of non-local, or ghost, agents and buffered projections.

An MPI application identifies its processes by a rank id. For example, if the application is run with 4 processes, there will be 4 ranks: 0 - 3. The code in an MPI appliction is run concurrently on each rank. Anything instantiated in that code resides in that processes' memory and is local to that process. Other processes do not have access to the variables, objects, etc. created on another process. A simple "hello world" type MPI4Py script illustrates this.

Running this with 4 process ranks (mpirun -n 4 python hello_world.py) will produce something like following output where can see how each of the 4 ranks runs the script independently on its own process rank.

In a more ABM flavored example, assuming 4 ranks, the following code creates 10 agents on each rank, for a total of 40 agents.

These agents are said to be local to the ranks on which they are created. In order to stitch these individual ranks into a global whole, Repast4Py uses the concept of a non-local, ghost agent: a copy of an agent from another rank that local agents can interact with. Repast4Py provides the functionality to create these ghosts and keep their state synchronized from the ghosts' local ranks to the ranks on which they are ghosted. Ghosts are also used to create projections, such as a network or grid that span across process ranks.

Figure 1 illustrates how ghosts are used in a network projection. The top part of the figure shows that agent A1 is local to process 1 and has a directed netework link to agent B2, which is local to process 2. Presumably, some aspect of the agent’s behavior is conditional on the network link, for example checking some attribute of its network neighbors and responding accordingly. Given that B2 is on a different process there is no way for A1 to query B2. However, the bottom part of the figure shows how ghost agents are used to tie the network together. B2 is copied to process 1 where a local link is created between it and A1. A1 can now query the state of B2. Similarly, a ghost of A1 is copied to process 2 where B2 can now interact with it.

Spatial projections such as a grid or continuous space are stitched together through the use of buffers and ghosts agents.

This is illustrated in Figure 2, where the full 6x8 grid is distributed across 4 process ranks. Each rank is responsible for its own 3x4 quarter of the global grid (left hand side of Figure 2). On the right hand side, we see how the quarters are stitched together. Each subsection of the grid contains a buffer that is a copy of the contents of the adjacent subsections. The blue part of the image is the area for process 1’s grid subsection. There, we can see the ghost agents C3 and B2 copied from processes 3 and 2 respectively. In this way, agent A1 can see and interact with agents C3 and B2.

Agents can, of course, move around grids and continuous spaces. When an agent moves beyond the borders of its local subsection then it is moved from that rank to the rank of the new subsection to which it has moved. For example, if in Figure 2, agent D4 moves from grid coordinate 4,4 to 4,2 then it will be moved during Repast4Py’s synchronization phase to process 2 where it becomes local to that process. Cross-process movement and synchronization will be discussed more in the next sections.

For moving and copying agents across processes to work each agent must have a unique id. This id has three components:

Combining the first component with the last allows us to uniquely identify an agent across the multi-process simulation while the second allows us to create agents of the appropriate type when they are copied between ranks.

In order to ensure that all agents in Repast4Py have an agent id, all agents must inherit from the repast4py.core.Agent class which requires these components in its constructor. For example, in the Zombies demonstration model, the Human agents are subclasses of the repast4py.core.Agent.

The components as well as the full unique id are accessible as attributes of the repast4py.core.Agent class.

Moving or copying an agent between processes consists of saving the agent state, moving / copying that state to another process, and then restoring the agent state as an agent on the destination process. For this to work, each agent is required to implement a save method that returns a tuple containing the full agent state. The first element of this full state tuple is the agent’s unique id, itself a tuple (accessed via the uid attribute), and the second is the dynamic state of that agent. For example, in the Zombie demonstration model the state of each Human is represented by two variables:

The save method creates a tuple consisting of these two variables and the unique id tuple.

You must also provide a restore function that takes the tuple produced by the save method and returns an agent either created from or updated with that state. The function is used during synchronization to create the agents on the destination ranks. In the Zombies demonstration model, the restore_agent function, when given agent state, returns Human and Zombie agents. It uses a caching scheme to avoid re-instantiating agents that have previously been created on a rank, and updates the state of those previously created agents. This can be a useful performance improvement at the expense of using more memory.

Lastly, in a distributed network, agents are not typically moved between processes but rather the ghost agents remain on a process once the network is created. Repast4Py tracks these ghost agents and does not recreate the agents every synchronization step via a restore method, instead a state update is sent to the appropriate ghost agents. In that case, an agent’s update method is called to handle the state update. The Rumor demonstration model has an example of this.

As mentioned in the Distributed Simulation section, each process in a Repast4Py application runs in a separate memory space from all the other processes. Consequently, we need to synchronize the model state across processes by moving agents, filling projection buffers with ghosts, and updating ghosted states, as necessary. Synchronization is performed by calling the SharedContext.synchronizemethod and passing it your restore function. The synchronization method will use the agent save method(s) and your restore function to synchronize the state of the simulation across its processes.

The Walker class implements our Walker agent, encapsulating its:

As required for all Repast4Py agent implementations, the Walker class subclasses repast4py.core.Agent, passing it the components of the unique agent id tuple.

The agent’s behavior is implemented in the walk and the count_colocations methods. In the walk method, the agent randomly chooses an offset from its current location (self.pt), adds those offsets to its current location to create a new location, and then moves to that new location on the grid. The moved-to-location becomes the agent’s new current location.

The Model class encapsulates the simulation and is responsible for initialization. It schedules events, creates agents and the grid the agents inhabit, and manages logging. In addition, the scheduled events that drive the simulation forward are methods of the Model class.

In the Model constructor, we create the simulation schedule, the context that holds our agents, the grid on which they move, the agents themselves, and the loggers that we use to log various simulation statistics to files. We begin with the constructor signature, and the schedule runner creation.

The restore_walker function is used to create an individual Walker when that Walker has moved (i.e., walked) to another process. This function is passed to the synchronize method (i.e., self.context.synchronize(restore_walker)) and is called in the synchronization mechanism. The restore_walker function is the reverse of the Walker.save method discussed in Section 5.1.3, “Serializing the Walker”, unpacking the tuple returned by that to create a Walker agent.

The simulation is run from the command line:

mpirun -n 4 python examples/rndwalk/rndwalk.py examples/rndwalk/random_walk.yaml

Here we are running the simulation with 4 process ranks and the model input parameters are in the examples/rndwalk/random_walk.yaml file.

The Rumor model is a simple network model that illustrates Repast4Py’s network agent-based model features. The simulation models the spread of a rumor through a networked population. During initialization some number of agents (network nodes) are marked as rumor spreaders. At each iteration of the simulation, a random draw is made to determine if the neighbors of any rumor-spreading nodes have received the rumor. This draw is performed once for each neighbor. After all of the neighbors that can receive the rumor have been processed, the collection of rumor spreaders is updated to include those nodes that received the rumor.

This text assumes you have already read the Repast4Py Users Guide up through Tutorial 1.

See the Repast4Py Examples page to download the source code for this model and for more information on getting started with the examples.

The Rumor model network is initialized from the examples/rumor/network.txt file included with the example model. This file assigns each network node, corresponding to each model agent, to a process rank. Repast4Py creates a repast4py.network.SharedNetwork from this file, instantiating the agents on the correct ranks and creating the edges between the agents appropriately. When an edge is between agents on different process ranks Repast4Py will create a ghost agent whose state mirrors that of the agent on the other process, and then create an edge using this ghost. For example, if an edge exists between A and B and A is on rank 1 and B on rank 2, then Repast4Py will:

For more information about ghost agents and how their state is maintained see the Distributed Simulation and Cross-Process Code Requirements sections.

The network.txt file was created using rumor.generate_network_file to distribute a connected Watts and Strogatz graph generated by the networkx Python package across 4 process ranks. rumor.generate_network_file uses Repast4Py’s capability to take a networkx Graph object and distribute it across a specified number of process ranks and write this distributed network to a file. A model can then create a SharedNetwork instance from this file.

See the API documentation for repast4py.network.write_network for more information.

The Rumor Model implementation follows the typical Repast4Py structure and consists of the following parts.

The Zombies model implements two agent classes: a Zombie and a Human. The zombie’s behavior is to pursue humans across a two dimensional Cartesian space and infect them. The human’s behavior is to flee from zombies. Humans contain a boolean (infected) field indicating whether or not they are infected, and an integer (infected_duration) field tracking the duration of the infection. When that value reaches 10, that human is replaced with a zombie. The methods that implement infection, and the transition from human to zombie are described in the Zombie step method, the the Human step method, and the Model class scheduled step method.

Both agents inhabit two two-dimensional projections: a SharedGrid and a SharedCSpace. The first of these is a matrix type grid where the agent locations are expressible as discrete integer coordinates. The second is a continuous space where the agent locations are expressible as continuous floating point coordinates. The grid is used to implement agent vision. Humans and zombies can see the zombies and humans in the grid locations that neighbor their own, and act accordingly. The continuous space is used for movement, and unlike the Walker agents in Tutorial 1 which move a single grid unit at a time, the human and zombie agents move in fractions of a grid unit, 0.25 for zombies, and 0.5 grid units for humans. In this way, the humans are twice as fast as the zombies. When a human or zombie moves in the continuous space, a method in the Model class updates its location in the grid space. These spatial aspects are described in detail in the Implementing Spatial Projections subsection.

As was demonstrated in the earlier tutorials, the Model class encapsulates the simulation and is responsible for initialization, scheduling events, creating agents and their grid/space environment, and managing logging. In addition, the scheduled events that drive the simulation forward are methods of the Model class.