Modelly: agent-based modeling in Python

Modelly is an agent-based modeling (ABM) framework for Python. Declare a typed scenario, give your agents behaviour, run the world forward in time, then measure, replay and publish it. Seeded runs, numpy-backed agents, grids, networks and continuous space, discrete-event time, pandas data collection, browser visualization. Fast by construction, reproducible by default.

Documentation · Tutorials · Examples · Coming from Mesa · Changelog

Status: stable, Python 3.12+. Every public package (core, space, time, data, behaviour, scenarios, batch, viz) follows semantic versioning; there is no experimental area. The current version is modelly.__version__.

pip install modelly-abm
python -c "import modelly; print(modelly.__version__)"   # the import name is modelly

Then run the wealth-exchange example, which prints its Gini coefficient.

Vision

Agent-based models are how researchers study systems whose behaviour emerges from many interacting parts: markets, epidemics, ecosystems, cities, opinions. The models are easy to describe and hard to keep correct, reproducible and fast. Modelly exists to remove that gap.

What we are building

• A research instrument, not a toy. Every run is seeded, every parameter lives in a typed scenario, every dataset lands in pandas. A result you got once is a result you can get again.
• Fast by construction. The hot paths of a simulation (activating agents, moving them, looking up neighbours, recording data) are measured, benchmarked in CI, and written so the cost per agent-step stays flat as models grow. Performance is a feature with a test, not a hope.
• Small, readable modules. A researcher should be able to open any file and understand it in one sitting. Files stay under 300 lines, functions under 25, and the rule is enforced by a script, not by goodwill. The Pelloux guidelines are the contract.
• One mental model from notebook to cluster. The same scenario object drives a quick look in a notebook, a browser visualization, a parameter sweep and a batch of replications.

Where we are going. The engine keeps one Python object per agent, which is what makes models easy to write, and moves the heavy lifting into arrays: Column attributes give the model a numpy view of every agent, continuous space answers neighbour queries for the whole population with one KD-tree, and the roadmap adds vectorised step phases and parallel replications out of the box. The performance audit records what has been done and what is next.

Why Modelly

Modelly gives you the boring, load-bearing parts as small composable objects, so your model file reads like the description of the system instead of the plumbing around it:

No global state, no hidden step order, no bespoke loops: reproducibility is the default.

Install

Modelly requires Python 3.12+ and is published on PyPI as modelly-abm.

python -m venv .venv && source .venv/bin/activate
pip install modelly-abm

Add extras for what you need:

pip install "modelly-abm[viz]"       # + solara, matplotlib, altair
pip install "modelly-abm[network]"   # + networkx
pip install "modelly-abm[rec]"       # network + viz: what the bundled examples need

To work on Modelly itself, install from a clone instead: see Development.

To depend on Modelly from your own project, add it to pyproject.toml (the distribution is modelly-abm, the import is modelly):

dependencies = ["modelly-abm>=1.2"]

The full walkthrough, from an empty folder to a tested and replicated model, is docs/using_modelly_in_your_project.md.

A model in 30 seconds

Agents wander a grid and hand one unit of wealth to a random cellmate. Inequality emerges. The same code ships as example.py.

from modelly import Model
from modelly.space import CellAgent, OrthogonalMooreGrid
from modelly.scenarios import Scenario


class WealthScenario(Scenario):
    """Everything that can vary between runs lives here."""

    n: int = 120
    width: int = 12
    height: int = 12


class MoneyAgent(CellAgent):
    def __init__(self, model, cell):
        super().__init__(model)
        self.cell = cell
        self.wealth = 1

    def step(self):
        self.cell = self.cell.neighborhood.select_random_cell()
        cellmates = [a for a in self.cell.agents if a is not self]
        if self.wealth > 0 and cellmates:
            self.random.choice(cellmates).wealth += 1
            self.wealth -= 1


class WealthModel(Model):
    def __init__(self, scenario: WealthScenario = WealthScenario):
        super().__init__(scenario=scenario)
        self.grid = OrthogonalMooreGrid(
            (scenario.width, scenario.height), random=self.random
        )
        MoneyAgent.create_agents(
            self,
            scenario.n,
            self.random.choices(self.grid.all_cells.cells, k=scenario.n),
        )

    def step(self):
        self.agents.shuffle_do("step")  # every agent, in random order

    @property
    def gini(self):
        x = sorted(a.wealth for a in self.agents)
        n = len(x)
        weighted = sum(xi * (n - i) for i, xi in enumerate(x))
        return 1 + 1 / n - 2 * weighted / (n * sum(x))


model = WealthModel()
for _ in range(100):
    model.step()

print(model.gini)  # 0.0 at the start, about 0.6 after 100 ticks

Three pieces, and nothing else: a scenario of inputs, agents that know one thing each, and a model that owns the world and advances it.

Record it, then look at it

from modelly.data.collector import DataCollector


class WealthModel(Model):
    def __init__(self, scenario: WealthScenario = WealthScenario):
        super().__init__(scenario=scenario)
        # ... grid and agents as above ...
        self.datacollector = DataCollector(
            model_reporters={"Gini": "gini"},  # anything reachable from the model
            agent_reporters={"Wealth": "wealth"},  # anything on each agent
        )

    def step(self):
        self.agents.shuffle_do("step")
        self.datacollector.collect(self)  # one row per tick

model_vars = model.datacollector.get_model_vars_dataframe()  # Gini per tick
agent_vars = model.datacollector.get_agent_vars_dataframe()  # wealth per agent per tick
agent_vars.groupby("Step")["Wealth"].mean().plot()

Both frames are plain pandas, so everything you already know how to do keeps working. Attribute reporters are gathered in C (operator.attrgetter), so a string reporter is the fast path, not just the convenient one.

Vectorise the bulk work

An agent-based model has two kinds of work: what one agent does in its step, which is Python by nature, and what the model does to all agents at once (aggregate, filter, record, update), which should be numpy. Declare a Column and the attribute lives in a model-owned array: the agent keeps reading and writing it as before, and the model gets a zero-copy view of everyone.

import numpy as np
from modelly import Agent, Column, Model


class MoneyAgent(Agent):
    wealth = Column(int, default=1)  # one numpy array for the whole class

    def step(self):
        other = self.random.choice(self.model.agents.to_list())
        if self.wealth > 0:  # per-agent access works as before
            other.wealth += 1
            self.wealth -= 1


class WealthModel(Model):
    @property
    def gini(self):
        x = np.sort(self.columns[MoneyAgent].wealth)  # view, no copy
        n = len(x)
        return 1 + 1 / n - 2 * np.sum(x * (n - np.arange(n))) / (n * x.sum())

    def tax(self):
        w = self.columns[MoneyAgent].wealth
        w[w > 10] -= 1  # bulk update, in place

    def rich(self):
        table = self.columns[MoneyAgent]
        return table.where(table.wealth > 10)  # an AgentSet

Nothing else changes: model.agents, shuffle_do, DataCollector and the examples work the same, and attribute reporters on a column are recorded straight from the array. Measured on 10,000 agents:

The last row is the trade-off: use columns for attributes you aggregate, filter, record or update in bulk; a plain attribute is still the cheapest thing to touch inside step. In the Boltzmann example the object loop is unchanged within noise while the model-level work is 30x cheaper.

The whole population at once

Two more operations run over everyone in one call, so a model can move its population-wide phases out of the per-agent loop:

# A whole-population step for the sheep: decrement, die, reproduce, no per-agent loop.
table = self.columns[Sheep]
table.energy -= 1
table.remove_where(table.energy < 0)
table.do_where(table.draw(0.04), "spawn_offspring")  # one seeded draw per sheep

# Continuous space: one KD-tree answers the whole flock, same snapshot for all.
lists = self.space.neighbors_within(radius=5.0)
for boid in self.agents:
    boid.neighbors = lists[boid]

draw uses the model's seeded numpy generator, so the run stays reproducible. neighbors_within is O(n log n) for the whole flock instead of one O(n) scan per agent, is periodic on a torus, and is cached while no position changes. The Boids example uses it: 2,000 boids go from 98 ms to 42 ms per step.

Replications in parallel

from modelly.scenarios import RunConfiguration, run_scenarios

scenarios = WealthScenario(n=5000, rng=1).spawn_replications(32)  # 32 independent seeds
store = run_scenarios(scenarios, RunConfiguration(WealthModel, until=200), workers=8)

Each replication carries its own seed derived from the base scenario, so the sweep is reproducible; workers= spreads it over processes.

For a plain factorial experiment, run_grid is the one-call version: every combination times the replicates, each run with its own seed, results in design order whatever the number of workers, so the DataFrame is identical to the sequential loop's.

from modelly import run_grid


def season(task):  # a notebook function works: on Linux the workers are forked
    model = Orchard(budget=task["budget"], invasion=task["invasion"], rng=task["seed"])
    model.run_for(100)
    return {"harvested": model.harvested, "rotten": model.rotten}


results = run_grid(
    season, {"budget": [0, 150, 300, 600], "invasion": [3, 10, 30]}, replicates=3
)

Populations as cohorts

When individuals in the same state face the same probabilities (an insect's stage, age and sex), one row with a count replaces them all, and each per-individual draw becomes one binomial draw per row with exactly the same law. CohortTable holds such a population with no agent objects; the stage-structured playbook runs 213x faster than its individual Mesa version and agrees with it statistically.

from modelly import CohortTable

insects = CohortTable(model.rng, stage=np.int8, age=np.int16, female=bool)
insects.add(500, stage=EGG)
insects.thin(daily_survival[insects["stage"]])  # Binomial(count, s) per row
insects.split(0.5, where=emerging, stage=ADULT, female=True)  # sex at emergence
eggs = insects.draw(lay_prob, where=mature_females).sum() * clutch

Modelly, Mesa, NetLogo or Agents.jl?

Pick Modelly when you want Mesa's authoring model with numpy underneath, measured performance, and a scenario object that makes every run reproducible. Pick NetLogo for teaching and its GUI, Agents.jl when the rest of your stack is Julia.

Coming from Mesa

Modelly's authoring model is the one Mesa 3 users know (Model, Agent, AgentSet, DataCollector), with one grid system and no schedulers. A codemod does the mechanical part of a move and reports the rest, each line pointing at a section of the guide:

python -m modelly.migrate path/to/your/model/          # dry run: diff plus report
python -m modelly.migrate path/to/your/model/ --write  # apply the rewrites

It rewrites imports to the domain-package paths (modelly.space, modelly.time, modelly.data, modelly.batch, modelly.viz), agent constructors and scheduler attributes, and flags scheduler classes, legacy grid calls, batch_run, simulators and seed= for you to decide. The construct-by-construct map, for Mesa 2.x and 3.x, is docs/migrating_from_mesa.md.

Checking a model

A static check finds the bugs that break reproducibility (random draws outside the model's generators, wall-clock values, a missing super().__init__, loops over sets) and the loops that make a step O(N²) (an agent scanning self.model.agents, nested population loops):

python -m modelly.lint path/to/your/model/   # exits 1 on findings, so it works in CI
python -m modelly.lint --explain MDL101      # why a rule matters, with a fix

Every tool is also one command: python -m modelly --help (or modelly --help once installed) lists them, and modelly lint src/ is python -m modelly.lint src/. Every rule, with the fix, is in docs/lint.md.

Its runtime companion runs the model and shows where each step's time goes: every AgentSet.do / shuffle_do call by agent class and method, with its cost per agent, DataCollector.collect, scheduled events, births and deaths, plus hints that point at lint codes:

python -m modelly.profile path/to/model.py:MyModel --steps 100 --param n=5000

From Python, with modelly.profile.Profiler(model) as prof: model.run_for(100), then prof.report() or prof.to_dataframe(). See docs/profile.md.

Checkpoints

A long run can be saved and resumed bit for bit, in the same process or a new one:

model.run_for(50)
model.save("run.ckpt")  # agents, spaces, events, data, both generators
model = WolfSheep.load("run.ckpt")  # only load files you trust: it is a pickle
model.run_for(50)  # identical to running 100 steps in one go
model.checkpoint_every(100, "run-{time:05.0f}.ckpt")

See docs/checkpoints.md.

Architecture

• Scenario to Model. Inputs enter through one typed object; the model owns state, seed, RNG and time.
• Model to AgentSet / Space / Time. Agents live in sets, act inside some space, and are driven by the scheduler.
• Model to Dataset. Reporters sample the model and its agents on intervals you choose.
• Dataset to Visualize / Analyze / Reproduce. Same data, three exits: a browser app, a dataframe, or a seeded re-run.

Package layout

One package per domain; each __init__.py lists its public names in __all__.

The top-level names (modelly.Agent, modelly.Model, modelly.DataCollector, modelly.Column, modelly.CohortTable, modelly.FastRandom, modelly.run_batch, modelly.run_grid) import from modelly directly.

How the engine stays fast

The data structures are chosen for the operations a simulation actually performs, and each choice is backed by a measurement in docs/performance.md.

Benchmarks

Two questions, two methods, both in the repository.

Same code on both frameworks. A research notebook written for Mesa 2.3, ported with the codemod and nothing else changed, identical seeds, outputs checked bit-identical, CPU time pinned and alternating: with its compiled random core Modelly is 12% faster than Mesa 2.3 (paired runs at 0.877 to 0.884 of Mesa's time, identical output in every chunk). With the pure-Python FastRandom it is 1.3 to 3.8% faster, and 1.5 to 2% behind with the standard library's generator. The method and every round are in docs/performance.md.

Same model, each framework's own idiom. benchmarks/playbooks/ holds eight models written twice: for Mesa 2.3 the way its API intends, and for Modelly with columns, vectorised phases, CellIndex and one KD-tree per step. The runner executes both in their own environments, pinned to one core, alternating rounds, checks that the implementations agree in distribution (Welch's t-test over shared seeds, every statistic) and that each is deterministic. CPU seconds of the steps at the large size, median of three rounds, this machine:

Where Modelly keeps Mesa's data structure (agents held in cell lists, modelly-cells in the results) the gap closes to 1.4 to 1.9x on the epidemic and predator-prey models: the layout is where the time is, not the interpreter. (Schelling and Sugarscape with cell lists stay 15x and 6.3x ahead, from the O(1) empty-cell index and cached neighbourhoods.) Every vectorised phase rests on a stated equivalence argument, in docs/vectorised_phases.md; the full tables with the agreement checks are in benchmarks/playbooks/results/README.md.

Future roadmap

What is shipped: columns, vectorised step phases (draw, do_where, remove_where), one KD-tree query for a whole continuous population, an O(1) empty-cell index on every discrete space, process-pool replications, incremental data frames, and compiled do / shuffle_do loops and neighbourhood walk (modelly/_native/fastloop.c). What comes next, in order of expected impact; each item keeps today's authoring model, you still write a Model, an Agent subclass and a Scenario:

1. Vectorised movement on grids. A coordinate column plus a vectorised neighbourhood lookup, so a grid model can move its whole population in one numpy operation.
2. Shared-memory replications. Fan a sweep over one large model out to processes without copying the column store.
3. Compiled cell moves. An optional compiled path for the cell move, the last Python-bound cost of a per-agent step now that the agent-set loops and the neighbourhood walk are compiled.
4. Live dashboards. The incremental data frame is the first piece; a streaming view that updates per tick without re-reading history is the next.

Built-in examples

Real, runnable models that ship with the package, good reading material for the patterns above.

Run one:

solara run modelly/examples/basic/boltzmann_wealth_model/app.py   # browser UI

Documentation

The tutorials are executable: open them locally, in Colab, or through Binder (links at the top of each notebook).

Development

git clone https://github.com/RemiPelloux/Modelly.git && cd Modelly
pip install -e ".[dev]"
bash scripts/ci-local.sh          # lint, format, tests, size audit: the same gate as CI
bash scripts/ci-local.sh --list   # stage names, run a subset with: ci-local.sh lint test
bash scripts/build-native.sh      # compile modelly/_native in place; MODELLY_PURE_PYTHON=1 forces the Python twins

The coverage badge at the top of this page is produced by that gate: the test stage measures coverage and rewrites docs/images/badges/coverage.svg, so commit the badge with your change.

Code discipline is written down in pelloux-guidelines.md: small files, short functions, surgical changes, conventional commits. scripts/audit-pelloux.sh enforces the size limits against pelloux-baseline.json; legacy oversized files are listed there and may shrink but never grow. The repository layout and how the brand assets are generated are in CONTRIBUTING.md.

Contributing

Issues, ideas and pull requests are welcome on the issue tracker. If you are adding a feature, opening a ticket first is the fastest route: it keeps the patch small and reviewable.

Everything you need is in CONTRIBUTING.md: local setup, tests, the lint and format commands CI runs, docs, and how a pull request is reviewed. By taking part you agree to our Code of Conduct.

Citing

If Modelly contributes to a publication, cite it with the metadata in CITATION.cff (GitHub shows a "Cite this repository" button that formats it for you).

License

Modelly is released under the Apache License 2.0. Third-party attribution is recorded in NOTICE.

_{Modelly: build the system, run the world, watch what emerges.}