Crate syren 

Syren

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 is the API reference. For a task-oriented introduction, worked examples, and the reproducibility guarantees, see the guide at https://ashvinperera.github.io/Syren-ABM-Framework/.

Installation

Syren has no default features; enable the ones your model needs:

[dependencies]
syren = { version = "0.6.0", features = ["model"] }

Features

• agents, environment — agent templates and typed model-wide values.
• model — the ModelBuilder layer (implies agents and environment).
• messaging — the four message specialisations.
• gpu, messaging_gpu — GPU state mirroring and compute dispatch.
• profiling — tracing spans and Chrome Trace output.

Getting started

The first_model example is the smallest complete model: register a component, build a population with ModelBuilder, run a system whose access is derived from its query, draw per-entity randomness from the run context with DetRng, and summarise with a Welford reduction. Run it with cargo run --example first_model --features model.

Determinism

A model run with the same version, features, seed, and initial state produces the same trajectory regardless of thread count. Draw randomness through DetRng::from_context, keyed on the run context and a salt, and set the model seed with ModelBuilder::with_seed. See the guide’s reproducibility chapter for the model author’s obligations.

Stability

Syren is pre-1.0: patch releases keep the public API; minor releases may break it with migration notes. Lower-level building blocks live in the advanced module and may change with less notice.

Modules

advanced

Advanced extension APIs that expose storage and scheduling internals.

agents

Domain-facing agent API layered over the raw ECS.

environment

Simulation-wide typed parameter store.

gpu

GPU Execution Backend

messaging

Typed, per-tick messaging for agent-based simulations.

model

Top-level model composition API.

prelude

Commonly used ECS types.

space

First-class agent spaces: discrete grids and continuous 2-D space.

Structs

AccessSets

Declares the component access set of a system.

AgentTemplateId

Compact identifier for an agent template registered in an agent registry.

BatchColumn

One component column in a dynamically-typed spawn batch.

BoundaryChannelProfile

Backend profile for one channel at a scheduler boundary.

BoundaryContext

Engine-side surfaces a BoundaryResource may interact with during a lifecycle hook.

BoundaryHandle

Short-lived typed reference to a boundary resource.

BuiltQuery

An immutable, fully constructed ECS query description.

Bundle

Concrete implementation of a dynamic component bundle.

ChannelSet

Bitset of ChannelIDs for non-component scheduling dependencies.

ComponentDesc

Describes a registered component type.

ComponentRegistry

Mapping between Rust component types and compact ComponentID values.

Count

Accumulator that counts the number of entities processed.

DetRng

Deterministic pseudo-random generator keyed by simulation coordinates.

DotExport

Display wrapper that renders a compiled scheduler plan as a Graphviz DOT graph.

ECSManager

Thread-safe entry point to the ECS world.

ECSReference

A non-owning handle granting access to ECS data.

Entity

Opaque, versioned identifier for an ECS entity.

EntityLocation

Physical storage location of an entity within archetype storage.

FnSystem

A concrete System backed by a function or closure.

MinMax

Accumulator that tracks minimum and maximum values.

PlanDisplay

Display wrapper that renders a compiled scheduler plan as a text table.

QueryBuilder

Builder for constructing ECS query descriptions.

QueryComponent

One component column declared by a query.

QuerySignature

Component signature used for query matching.

Read

Marker for a read-only component parameter in a tuple-based query.

RunContext

Deterministic execution context for the system currently running on this thread.

Scheduler

Stores systems, compiles them into conflict-free execution stages, and executes stages with Rayon parallelism.

Signature

Bitset representing a set of components.

SpanGuard

A RAII guard that records a Chrome Trace complete event on drop.

SpanName

A span name; accepts &'static str, String, or Cow<'static, str>.

SpawnBatch

Dynamically-typed batch payload for spawning many entities with one signature.

Stage

A logical execution stage used by Scheduler during planning.

Sum

Accumulator that computes a floating-point sum.

Welford

Accumulator implementing Welford’s online algorithm for mean and variance.

Write

Marker for a mutable component parameter in a tuple-based query.

Enums

ActivationOrder

Controls the order in which entities are visited by a system’s iteration.

Arg

Argument value for profiling spans.

AttributeError

Aggregate error for attribute (component column) operations.

BoundaryAccessFailure

Reason a boundary-resource access failed.

ChannelOrder

Directional ordering constraint derived from channel produces/consumes.

Command

Represents a deferred ecs mutation command.

ECSError

Unified error type for the public ECS API.

ExecutionError

Errors that occur during ECS execution and iteration.

GPUAccessMode

Declares how a component buffer is accessed during GPU execution.

MoveError

Errors that can occur while moving an entity between archetypes.

ProfilingError

Errors returned by try_init.

RegistryError

Errors from the global component registry and its factories.

SpawnError

High-level error for entity spawning.

SystemBackend

Execution backend for a system.

Constants

CHUNK_CAP

Maximum number of rows per chunk.

Traits

BoundaryResource

Trait for tick-lifecycle resources owned by ECSManager.

DynamicBundle

Type-erased container for component values.

EntityQueryParam

Entity-aware variant of QueryParam.

GPUPod

Marker trait for component types that are safe to transfer to and from the GPU.

GpuSystem

GPU capability trait (feature-gated). A GPU system is still a System, but additionally provides WGSL.

QueryParam

Trait implemented by query parameter markers (Read<T>, Write<T>) and tuples thereof to enable a single generic for_each entry point.

System

A unit of executable logic operating on the ECS world.

Functions

flush_thread

Flush this thread’s local event buffer into the global collected_events store.

init

Initialize the profiler and ignore repeated initialization attempts.

max_workers

Returns Rayon’s current pool size.

next_arg

Add an argument to the next span created on this thread.

register_gpu_component

Registers a component type as GPU-safe and eligible for GPU execution.

shutdown

Shut down the profiler and write the Chrome Trace JSON.

span

Create a profiling span.

span_fmt

Create a profiling span using format_args without forcing the caller to allocate manually.

thread_name

Assign a human-friendly thread name (shown in Perfetto/Chrome tracing).

try_init

Initialize the profiler and set output path.

worker_id

Returns the stable worker identifier for the calling thread.

Type Aliases

ArchetypeID

Unique identifier for an archetype.

BoundaryID

Opaque identifier for a boundary resource registered on ECSManager.

ChannelID

Opaque identifier for a non-component scheduling channel.

ChunkID

Chunk index within an archetype.

ComponentID

Unique identifier for a component type.

ECSResult

Result type used by the ECS engine.

EntityID

Globally unique entity identifier encoded as a packed 64-bit value.

GPUResourceID

Unique identifier for a GPU resource.

SystemID

Unique identifier for a system.