Getting started#

Modelly is a modular framework for building, analyzing and visualizing agent-based models.

Agent-based models are computer simulations involving multiple entities (the agents) acting and interacting with one another based on their programmed behavior. Agents can be used to represent living cells, animals, individual humans, even entire organizations or abstract entities. Sometimes, we may have an understanding of how the individual components of a system behave, and want to see what system-level behaviors and effects emerge from their interaction. Other times, we may have a good idea of how the system overall behaves, and want to figure out what individual behaviors explain it. Or we may want to see how to get agents to cooperate or compete most effectively. Or we may just want to build a cool toy with colorful little dots moving around.

Overview#

If you want to get a general idea of Modelly’s features and structure, start here:

Tutorials#

If you want to learn how to build agent-based models step by step using Modelly, follow these tutorials:

  • Creating Your First Model: Learn how to create your first Modelly model.

  • AgentSet: Learn how to more effectively manage agents with Modelly’s AgentSet.

  • Agent Activation: Learn different ways to activate agents using do, shuffle_do, and map — covering random, sequential, simultaneous, staged, type-based, and conditional activation patterns.

  • Event Scheduling: Learn how to schedule events and manage time in your Modelly model.

  • Adding Space: Learn how to add space to your Modelly model and understand Modelly’s space architecture.

  • Collecting Data: Learn how to collect model level and agent level data with Modelly’s DataCollector.

  • Basic Visualization: Learn how to build an interactive dashboard with Modelly’s visualization module.

  • Dynamic Agent Visualization: Learn how to dynamically represent your agents in your interactive dashboard.

  • Visualization using SpaceRenderer: Learn how to use SpaceRenderer to its full extent to enhance your visualizations.

  • Property Layer Visualization: Learn how to visualize property layers in Modelly.

  • Custom Visualization Components: Learn how to add custom visual components to your interactive dashboard.

  • Discrete Event Simulation: Learn how to build a pure event-driven model with schedule_event and validate it against queuing theory.

  • Hybrid ABM-DEVS Models: Learn how to combine step()-based agent activation with scheduled events in a spatial epidemic model.

Examples#

Modelly ships with a collection of example models. These are classic ABMs, so if you are familiar with ABMs and want to get a quick sense of how MODELLY works, these examples are great place to start. You can find them here.

Further resources#

To further explore Modelly and its features, we have the following resources available:

Best practices#

API documentation#

  • Modelly API reference: Detailed documentation of Modelly’s classes and functions, one page per package (modelly.core, modelly.space, modelly.time, modelly.data, modelly.behaviour, modelly.scenarios, modelly.batch, modelly.viz).

Source Code and development#

Community and support#

Enjoy modelling with Modelly, and feel free to reach out!

Coming from Mesa#

  • Migrating from Mesa: a construct-by-construct map and a codemod, python -m modelly.migrate, that rewrites the mechanical parts and reports the rest.