AgentPy: A package for agent-based modeling in Python

Agent-based models allow for computer simulations based on the autonomous behavior of heterogeneous agents. They are used to generate and understand the emergent dynamics of complex systems, with applications in fields like ecology (DeAngelis & Diaz, 2019), cognitive sciences (Madsen et al., 2019), management (North & Macal, 2007), policy analysis (Castro et al., 2020), economics (Arthur, 2021; Farmer & Foley, 2009), and sociology (Bianchi & Squazzoni, 2015).

AgentPy is an open-source library for the development and analysis of agent-based models. It aims to provide an intuitive syntax for the creation of models together with advanced tools for scientific applications. The framework is written in Python 3, and optimized for interactive computing with IPython and Jupyter. A reference of all features as well as a model library with tutorials and examples can be found in the documentation. 1

Statement of Need
There are numerous modeling and simulation tools for agent-based models, each with their own particular focus and style (Abar et al., 2017). Notable examples are NetLogo (Wilensky, 1999), which is written in Scala/Java and has become the most established tool in the field; and Mesa (Masad & Kazil, 2015), a more recent framework that has popularized the development of agent-based models in Python.
AgentPy's main distinguishing feature is that it integrates the many different tasks of agentbased modeling within a single environment for interactive computing. This includes the creation of custom agent and model types, interactive simulations ( Figure 1) similar to the traditional NetLogo interface, numeric experiments over multiple runs, and the subsequent data analysis of the output. All of these can be performed within a Jupyter Notebook.
The software is further designed for scientific applications, and includes tools for parameter sampling (similar to NetLogo's BehaviorSpace), Monte Carlo experiments, random number generation, parallel computing, and sensitivity analysis. Beyond these built-in features, AgentPy is also designed for compatibility with established Python libraries like EMA Workbench, NetworkX, NumPy, pandas, SALib, SciPy, and seaborn.

Basic structure
The AgentPy framework follows a nested structure that is illustrated in Figure 2. The basic building blocks are the agents, which can be placed within (multiple) environments with different topologies such as a network, a spatial grid, or a continuous space. Models are used to initiate these objects, perform a simulation, and record data. Experiments can run a model over multiple iterations and parameter combinations. The resulting output data can then be saved and re-arranged for analysis and visualization.

Model example
The following code shows an example of a simple model that explores the distribution of wealth under a randomly trading population of agents. The original version of this model was written in Mesa, allowing for a comparison of the syntax between the two frameworks. 2 To start, we import the AgentPy library as follows: import agentpy as ap We then define a new type of Agent. The method setup will be called automatically at the agent's creation. Each agent starts with one unit of wealth. wealth_transfer will be called by the model during each time-step. When called, the agent randomly selects a trading partner and hands them one unit of their wealth, given that they have one to spare. Next, we define a Model. The method setup is called at the beginning the simulation, step is called during each time-step, and end is called after the simulation has finished. An AgentList is used to create a set of agents that can then be accessed as a group. The attribute p is used to access the model's parameters. And the method record is used to store data for later analysis. Parameters can also be defined as ranges and used to generate a Sample. This sample can then be used to initiate an Experiment that can repeatedly run the model over multiple parameter combinations and iterations. In the following example, the parameter n is varied from 1 to 100 and the simulation is repeated 10 times for each value of n. The output of both models and experiments is given as a DataDict with tools to save, arrange, and analyse data. Here, we use the seaborn library to display a histogram of the experiment's output. The plot is presented in Figure 3. It shows that the random interaction of the agents creates an inequality of wealth that resembles a Boltzmann-Gibbs distribution.
import seaborn as sns sns.histplot(data=results.variables.MoneyAgent, binwidth=1) More examples -including spatial environments, networks, stochastic processes, interactive simulations (see Figure 1), animations, and sensitivity analysis -can be found in the model library and user guides of the documentation. For questions and ideas, please visit the discussion forum. 3