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.

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.

Scenario

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

  • DataFrameInfo and MatrixInfo - provide standard format for input tables as parameters.

  • DataLoader - whose object loads all the input data into the model.

  • Scenario - whose object contains all the input data that is needed to run the model, and can be accessed by the model, the environment, the data_collector, and each agent.

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 the parameters of the scenario by minimizing the distance between model output and empirical evidence.

  • Trainer - trains the agents to update their behavioral parameters for higher payoff.

Taking the CovidContagion model in the tutorial as example, as shown below, the simulator is initialized with a config object (incl. project name and folder paths) and the class variables of the model, the scenario, and the data_loader.

from Melodie import Simulator
from config import config
from source.model import CovidModel
from source.scenario import CovidScenario
from source.data_loader import CovidDataLoader

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

At last, by calling the simulator.run function, the simulation starts.

Infrastructure

The last Infrastructure Cluster includes the modules that provide support for the modules above.

  • Visualizer - provides the APIs to interact with MelodieStudio for visualization.

  • MelodieStudio - another separate package which goes in parallel with Melodie, which supports the visualization of simulation results in your browser.

  • Config - provides the channel to define project information, e.g., project name, folder paths.

  • DBConn - provides the functions to write to or read from the database.

  • MelodieException - provides the pre-defined exceptions in Melodie to support debugging.