Modelarium 2.0.0 API

Modelarium API

Modelarium is a modular, extensible, and multithreaded agent-based modelling framework for Java 21. Models are assembled from agents, one environment, and composable property, event, and routine attributes.

Starting a model

1. Create agent and environment attributes and group them into named attribute sets.
2. Provide agent and environment generators.
3. Build a Config and pass it to Model.
4. Call Model.run().
5. Inspect or export the ReadOnlyResults returned by Model.getResults().

Main extension points

• modelarium.entities.attributes and its subpackages define properties, events, routines, and their functional variants.
• modelarium.entities.generators controls population and environment construction.
• modelarium.scheduler controls local agent execution order.
• modelarium.entities.logging.databases.factories selects memory- or disk-backed log storage.

Concurrency

Synchronised runs advance worker threads in lockstep, support cross-worker population access, and run environment behaviour at tick boundaries. Unsynchronised runs avoid co-ordination but do not support cross-worker lookups and do not run environment attributes. Configure this behaviour through Config.ConfigBuilder; the multithreading implementation packages are not application extension points.

API status

Packages annotated with PublicApi form the supported API unless a type or member is marked @Internal. Internal elements may remain Java-public for framework integration but are not covered by semantic-versioning compatibility guarantees.

Packages

Package	Description
modelarium	Provides Modelarium's primary configuration and execution API.
modelarium.api	Defines annotations used to identify Modelarium's supported public API.
modelarium.clock	Provides read-only access to simulation time.
modelarium.entities	Defines the agents and environment which make up a Modelarium simulation.
modelarium.entities.agentsets	Provides mutable and read-only collections of agents.
modelarium.entities.attributes	Defines the common API for Modelarium attributes.
modelarium.entities.attributes.events	Provides conditional event attributes for agents and environments.
modelarium.entities.attributes.events.functional	Provides functional interfaces and lambda-backed implementations of event attributes.
modelarium.entities.attributes.properties	Provides typed state-bearing properties for agents and environments.
modelarium.entities.attributes.properties.functional	Provides functional interfaces and lambda-backed implementations of property attributes.
modelarium.entities.attributes.routines	Provides unconditional per-tick routines for agents and environments.
modelarium.entities.attributes.routines.functional	Provides functional interfaces and lambda-backed implementations of routine attributes.
modelarium.entities.attributes.sets	Provides named, ordered collections of agent and environment attributes.
modelarium.entities.attributes.sets.readonly	Provides read-only views of agent and environment attribute sets.
modelarium.entities.contexts	Defines the simulation views supplied to attribute behaviour.
modelarium.entities.generators	Provides extension points for constructing a model's agents and environment.
modelarium.entities.logging	Provides logs which associate an entity and attribute set with recorded attribute series.
modelarium.entities.logging.databases	Provides memory- and disk-backed storage for attribute log series.
modelarium.entities.logging.databases.factories	Provides factories which select and create the logging backend used by a model run.
modelarium.entities.readonly	Provides read-only views of agents, environments, and their common entity state.
modelarium.exceptions	Defines Modelarium-specific failures for model execution, entity lookup, attribute access, coordination, timeouts, interruption, and missing functional behaviour.
modelarium.multithreading	Implements Modelarium's worker and co-ordinator runtime.
modelarium.results.readonly	Provides immutable access to completed model results and result export.
modelarium.scheduler	Provides policies for ordering local agent execution on each tick.
modelarium.scheduler.functional	Provides a lambda-backed scheduler and its tick function interface.
modelarium.utils	Provides small public utility types used by Modelarium extension points.