Model

class Melodie.Model(config: Config, scenario: Scenario, run_id_in_scenario: int = 0, visualizer: Visualizer = None)

Bases: object

The base class for a Melodie model.

The model class is the central component that orchestrates the simulation. It follows a structured lifecycle managed by three main methods: create(), setup(), and run(). The Simulator calls create() and then setup() once at the beginning of a simulation run. The run() method is then called to execute the main simulation loop.

To implement a custom model, users should inherit from this class and override these three methods.

Parameters:

  • config – The framework configuration object.

  • scenario – The scenario object providing parameters for the model run.

  • run_id_in_scenario – The ID of the current simulation run for this scenario. It is an integer in [0, scenario.run_num - 1].

  • visualizer – The visualizer instance, if visualization is enabled.

create()

Create and initialize model components.

This method is the first part of the model’s initialization process. It should be used to create all the necessary components of the model, such as agent lists, the environment, grid/network structures, and the data collector.

setup()

Set up the initial state of the model.

This method is the second part of the model’s initialization process, called after create(). It should be used to establish the initial state of the model’s components, such as setting initial agent properties or creating network connections.

create_db_conn() → DBConn

Create a database connection using the project configuration.

Returns:

A DBConn object for database interaction.

create_agent_list(agent_class: Type[AgentType]) → AgentList[AgentType]

Create an AgentList object.

A model can contain multiple agent lists for different types of agents.

Parameters:

agent_class – The class of the agent to be contained in the list.

Returns:

An AgentList object.

create_environment(env_class: Type[EnvironmentType]) → EnvironmentType

Create the environment for the model.

A model should have only one environment.

Parameters:

env_class – The class of the environment to be created.

Returns:

The created environment object.

create_grid(grid_cls: Type[GridType] | None = None, spot_cls: Type[SpotType] | None = None) → GridType

Create a grid for spatial simulations.

Parameters:

  • grid_cls – The class of the grid. Defaults to Grid.

  • spot_cls – The class of the spots that make up the grid. Defaults to Spot.

Returns:

The created grid object.

create_network(network_cls: Type[NetworkType] | None = None, edge_cls: Type[Edge] = None)

Create a network for agent interactions.

Parameters:

  • network_cls – The class of the network. Defaults to Network.

  • edge_cls – The class for edges in the network. Defaults to Edge.

Returns:

The created network object.

create_data_collector(data_collector_cls: Type[DataCollectorType]) → DataCollectorType

Create the data collector for the model.

Parameters:

data_collector_cls – The DataCollector class, which must be a custom class inheriting from DataCollector.

Returns:

A DataCollector object.

create_agent_container(agent_class: Type[Agent], initial_num: int, params_df: pd.DataFrame = None, container_type: str = 'list') → AgentList | AgentDict

Create a container for agents.

Note

This is a legacy method. The recommended way to create agent containers is to use create_agent_list().

Parameters:

  • agent_class – The class of the agent.

  • initial_num – The initial number of agents to create.

  • params_df – A pandas DataFrame to initialize agent properties.

  • container_type – A string specifying the container type, either “list” or “dict”. “dict” is not yet implemented.

Returns:

The created agent container.

run()

The main entry point for the simulation run.

This method should be overridden in a subclass to define the model’s primary logic, which is executed after create() and setup().

iterator(period_num: int)

Get an iterator for the simulation loop.

The iterator yields the current period, from 0 to period_num - 1, and handles visualizer updates at each step.

Parameters:

period_num – The total number of periods for the simulation run.

Returns:

A ModelRunRoutine iterator object.

init_visualize()

A hook for initializing the visualizer.

This method should be overridden in the model subclass if custom visualization setup is required.