Introduction

Agent-based Model (ABM)

ABMs characterize physical, biological, and social economic systems as dynamic interactions among agents from a bottom-up perspective. The agents can be molecules, animals, or human beings. The interactions can be water molecules forming a vortex, ants searching for food, or people trading stocks in the market.

Agents’ interactions can bring emergent properties to a system and turn it into a complex system. To model such mechanism is usually the core reason for using ABMs. Besides, taking social economic systems as example, ABMs are also flexible to consider agents’ (1) heterogeneity (e.g., wealth, risk attitude, preference, decision-making rule, etc.) based on micro-data; (2) bounded rationality and adaptation behavior based on psychological and behavioral studies.

Melodie Framework

As a general framework for developing agent-based models (ABMs), Melodie is designed in a modular structure and the modules are organized into four clusters: Model, Scenario, Modeling Manager, and Infrastructure.

The Model

The modules in the Model Cluster focus on describing the logics of the target system. Developed with Melodie, a model: Model object can contain following components:

agent: Agent - makes decisions, interacts with others, and stores the micro-level variables.
agents: AgentList - contains a list of agents and provides relevant functions.
environment: Environment - coordinates the agents’ decision-making and interaction processes and stores the macro-level variables.
data_collector: DataCollector - collects the micro- and macro-level variables from the agents and environment, then saves them to the database.
grid: Grid - constructed with spot: Spot objects, describes the grid (if exists) that the agents walk on, stores grid variables, and provides the relevant functions.
network: Network - constructed with edge: Edge objects, describes the network (if exists) that links the agents, and provides the relevant functions.

The Scenario

The modules in the Scenario Cluster focus on formatting, importing, and delivering the input data to the model.

Scenario - is the central component for data handling. Its instance contains all input data needed to run the model. It can load data directly via its load_data method, making it accessible to all other model components.

Modelling Manager

To combine everything and finally start running, the Modelling Manager Cluster includes three modules in parallel, which can be constructed and run for different objectives:

Simulator - simulates the logics written in the model.
Calibrator - calibrates model parameters by minimizing the distance between simulation output and empirical data.
Trainer - trains agents to find behavioral parameters that optimize their payoffs.

Taking the CovidContagion model from the tutorial as an example, the Simulator is initialized with a Config object and the classes for the Model and Scenario.

import os
from Melodie import Config, Simulator
from core.model import CovidModel
from core.scenario import CovidScenario

# In a real script, 'core' would be the folder containing your model files.

config = Config(
    project_name="CovidContagion",
    project_root=os.path.dirname(__file__),
    input_folder="data/input",
    output_folder="data/output",
)

 simulator = Simulator(
      config=config,
      model_cls=CovidModel,
      scenario_cls=CovidScenario
 )
 simulator.run()

At last, by calling the simulator.run() method, the simulation starts.

Infrastructure

The Infrastructure Cluster provides a rich set of foundational modules that support the entire framework. Key components include:

Config: A centralized object for managing all project settings, such as names and file paths.
DBConn: Handles database connections, allowing models to read from and write to databases.
Parallel: Provides the backend for parallel simulation runs.
Visualizer & MelodieStudio: An API (Visualizer) to connect the simulation to MelodieStudio (a separate package) for real-time, browser-based visualization.
Table & JSONObject: Utilities for robust data handling, serialization, and validation.
MelodieException: A set of pre-defined custom exceptions to aid in debugging and error handling.