Modelarium

Modelarium is a modular, extensible, and multithreaded agent-based modelling (ABM) framework for Java. It provides a flexible architecture for defining agents, environments, and behaviours using composable attributes, and supports high-performance simulation with optional cross-thread coordination.

Highlights

• Attribute-based modelling of agents and environments, with properties, events, and routines
• Functional attribute variants, so behaviours can be defined with lambdas rather than subclassing
• Multi-core execution with optional lockstep synchronisation through a co-ordinator thread
• Pluggable schedulers (in-order, random order, or custom)
• Configurable results recording to memory or SQLite
• Seeded, reproducible randomness threaded through the whole model
• Java 21, with a stable automatic module name for module-path compatibility

Repository structure

This repository contains two Maven modules, built together by a thin aggregator pom.xml at the root:

• modelarium/ - the library itself, published to Maven Central as dev.modelarium:modelarium. See the library README for concepts, a quickstart, and the full configuration reference.
• modelarium-examples/ - worked example models built against the library. These are compiled and smoke-tested on every build, so they always reflect the current API, and they are never published. See the examples README for how to run them.

Examples

The examples module contains five complete models. They progress from a conventional compartmental epidemic model to published classic agent-based models and replication experiments:

Example	What it demonstrates	Original literature
SIR epidemic	Agent properties and events, spatial contact, an environment-level prevalence summary, seeded randomness, and multi-core execution.	—
Schelling segregation	A spatial grid, agent relocation, neighbourhood queries, cross-agent interaction, and aggregate segregation measures.	—
El Farol Bar	Adaptive decision-making, agent-specific predictor sets, shared attendance history, and environment feedback.	—
Epstein-Axtell Sugarscape	A suite of replication experiments using a custom scheduler, resource landscapes, death and replacement, and experiment-level CSV output.	Epstein and Axtell (1996)
Axelrod cultural dissemination	An event-driven replication study, spatial cultural interaction, absorbing-state detection, repeated seeded runs, and summary statistics.	Axelrod (1997)

Build all modules, then run an example from the repository root:

mvn -B verify
mvn -pl modelarium-examples exec:java \
  -Dexec.mainClass=dev.modelarium.examples.sir.SIRMain

Each example reads its default settings from modelarium-examples/src/main/resources, prints or exports a summary, and writes detailed results beneath modelarium-examples/output/. See the examples README for every main class, configuration file, expected output, and shorter smoke-test commands.

Documentation

• Library guide and quickstart
• Worked examples
• API reference (Javadoc)
• Supported public API policy

Installation (Maven Central)

Modelarium is published to Maven Central. Add it to your pom.xml:

<dependency>
  <groupId>dev.modelarium</groupId>
  <artifactId>modelarium</artifactId>
  <version>2.0.0</version>
</dependency>

Requirements

• Java 21
• Maven

Building from source

Build and test everything (library, examples, and the smoke tests) from the repository root:

mvn -B verify

To work on the library module alone:

mvn -B test --file modelarium/pom.xml

Install the library to your local Maven repository:

mvn -B install --file modelarium/pom.xml

License

MIT - see LICENSE.