AgentPy Documentation

AgentPy is an open-source framework designed for agent-based modeling (ABM). It provides a unified environment for:

• Model Design: Defining the structure and logic of agents and their interactions.
• Interactive Simulations: Running models in real-time environments.
• Numerical Experiments: Conducting large-scale parameter sweeps or stochastic simulations.
• Data Analysis: Analyzing the results of simulations.

The package is specifically optimized for interactive computing workflows using IPython and Jupyter notebooks.

To create custom agent types in AgentPy, subclass the Agent base class. Use the setup method to define and initialize the agent's initial variables. This method acts as a template for your custom agent's lifecycle.

import agentpy as ap

class MyCustomAgent(ap.Agent):
    def setup(self):
        # Define initial variables here
        self.my_variable = 10

    def step(self):
        # Define agent behavior per time step
        self.my_variable += 1

The output of both Model.run() and Experiment.run() is a DataDict. This object provides tools to save, arrange, and analyze simulation data. You can access recorded variables via the .variables attribute, which is compatible with scientific libraries like pandas and seaborn.

import seaborn as sns

# Accessing recorded agent data from experiment results
sns.histplot(data=results.variables.WealthAgent, binwidth=1)

Environments define the topology in which agents reside. A model can contain multiple environments. The three supported types are:

• Grid: An n-dimensional spatial topology with discrete positions.
• Space: An n-dimensional spatial topology with continuous positions.
• Network: A graph topology consisting of AgentNode and edges.

In AgentPy, an Environment is an object that defines where agents inhabit and how they are connected to one another via a topology. You must choose a topology based on whether your model requires discrete spatial positions, continuous spatial positions, or a graph-based structure:

1. Grid: An n-dimensional spatial topology with discrete positions (e.g., a 2D lattice).
2. Space: An n-dimensional spatial topology with continuous positions (e.g., coordinates in a 2D plane).
3. Network: A graph topology consisting of AgentNode objects and edges (e.g., social networks or infrastructure maps).

The DataDict class is the primary container for accessing, arranging, analyzing, and storing output data from AgentPy simulations. You can obtain a DataDict instance through the following methods:

• Model.run(): Returns the data generated from a single model run.
• Experiment.run(): Returns the data generated from an entire experiment (multiple runs).
• DataDict.load(): Loads previously saved data from a file.

AgentPy provides containers like AgentList, AgentDList, and AgentSet to manage groups of agents. These containers allow you to perform operations on entire groups at once, such as calling a method on every agent or selecting subsets using boolean operators.

Example of selecting agents with an ID greater than 1: agents.select(agents.id > 1)

There are two primary ways to collect data for analysis:

1. Dynamic Variables: Recorded for each object (agent, environment, or model) at every time-step. Use the .record() method. Access them at runtime via the .log attribute.
2. Reporters: Summary statistics or evaluation measures recorded once per simulation for the model as a whole. Use Model.report(). Access them at runtime via Model.reporters.

AgentPy follows a hierarchical structure for building simulations:

1. Agents: The basic building blocks representing autonomous entities. They can be placed in various Environments (topologies like networks, spatial grids, or continuous space).
2. Models: Used to initialize agents and environments, manage the simulation lifecycle, and record data.
3. Experiments: Used to run a model multiple times over different parameter combinations and iterations.
4. Data: The resulting output from models or experiments, which can be saved and analyzed.

When setting up agent-based models, you can use Range, IntRange, and Values to define the possible values or distributions for model parameters. These classes allow you to specify how parameters should be sampled during simulation runs.

• Range: Typically used for continuous floating-point ranges.
• IntRange: Used for discrete integer ranges.
• Values: Used to specify a fixed set of discrete values from which to sample.