The Syren Guide

Syren is a parallel Rust framework for agent-based models. It stores agents in an archetype entity-component-system (ECS), runs systems over them through a deterministic stage scheduler on top of Rayon, and adds agent, environment, messaging, and optional GPU layers behind Cargo features.

This guide is the user and contributor manual. The Rust API reference lives on docs.rs; this guide explains how the pieces fit together and how to use them.

Who this is for

Syren is for researchers and engineers who write agent-based models in Rust and care about reproducibility and scale. You should be comfortable with Rust and Cargo. There is no separate model-definition language: a model is a Rust program that uses the library.

What the framework provides

• Archetype-ECS storage — components stored in chunked, columnar arrays, iterated over contiguous memory.
• Deterministic scheduling — systems declare their data access; the scheduler packs non-conflicting systems into parallel stages and preserves a reproducible activation order.
• Query-derived access — a system's read/write set is derived from the queries it runs, so the declared access cannot drift from what it touches.
• Deterministic randomness — DetRng keys draws on the run context and a salt, so results do not depend on which worker thread visits which rows.
• Model layer (model feature) — ModelBuilder, agent templates, environments, sub-schedulers, and nested models.
• Messaging (messaging feature) — four message specialisations (brute-force, bucketed, spatial, targeted).
• Optional GPU execution (gpu feature) — mirror component columns to the GPU and dispatch compute systems through wgpu.

How to read this guide

• Getting started takes you from an empty project to a running model.
• Core concepts explains each part of the framework and how it relates to the source.
• How-to gives task-focused recipes.
• Reproducibility covers the reproducibility guarantees, verification, provenance, and citation.
• Reference collects the feature matrix, compatibility policy, error model, performance methodology, and a glossary.
• Contributing documents the engine internals and the development process.