Module messaging 

Inter-agent messaging system inspired by FlameGPU2.

FlameGPU2 achieves massive GPU throughput by decoupling agent communication from direct neighbor queries. Agents output messages in one phase, then read messages in the next. This two-phase approach eliminates data races and enables efficient GPU-side spatial indexing.

rustsim mirrors this with a CPU-first messaging layer that can be backed by GPU buffers when CUDA is available.

Message Types

Type	Description	FlameGPU2 equivalent
BruteForceMessages	All-to-all; every agent reads every message	MessageBruteForce
SpatialMessages2D	Spatial-hashing 2D; agents read messages within a radius	MessageSpatial2D
SpatialMessages3D	Spatial-hashing 3D; agents read messages within a radius	MessageSpatial3D

Two-Phase Pattern

// Phase 1: agents output messages
for id in agent_ids {
    let agent = store.get(id);
    messages.output(MyMessage { x: agent.x, y: agent.y, vx: agent.vx });
}
messages.finalize(); // build spatial index

// Phase 2: agents read messages and update
for id in agent_ids {
    let mut agent = store.get_mut(id);
    for msg in messages.read_nearby(agent.x, agent.y, radius) {
        // accumulate forces, etc.
    }
}
messages.clear();

Structs

BruteForceMessages

Brute-force message list – every agent can read every message.

SpatialIter2D

Iterator over spatially-nearby messages.

SpatialIter3D

Iterator over spatially-nearby 3D messages.

SpatialMessages2D

2D spatial message list with spatial-hashing neighbor lookup.

SpatialMessages3D

3D spatial message list with spatial-hashing neighbor lookup.

Enums

MessageConfigError

Errors returned by messaging configuration validation.

MessagePhaseError

Errors returned when a message buffer is used outside its valid phase.

Traits

Message

A message that can be exchanged between agents.