Struct StandardModel 

pub struct StandardModel<S, A, Store, Props, R, Sch>
where
    A: Agent,
    S: Space,
    Store: AgentStore<A>,
    R: RngCore,
{ /* private fields */ }

Discrete-time agent-based model.

This is the main model type for tick-based simulations. It stores agents in an AgentStore, uses a Scheduler to determine activation order, and calls user-provided step functions each tick.

Type Parameters

• S - space type (e.g. NothingSpace, Grid2D)
• A - agent type implementing Agent
• Store - agent container implementing AgentStore<A>
• Props - user-defined model properties (use () if unused)
• R - RNG type (e.g. StdRng)
• Sch - scheduler type (e.g. Fastest, Randomly)

Example

type MyModel = StandardModel<NothingSpace, Particle, HashMapStore<Particle>, (), StdRng, Fastest>;

let mut model = MyModel::new(store, space, Fastest::new(), (), rng, Some(Box::new(step_fn)), None, true);
model.step_n(100);

Implementations

impl<S, A, Store, Props, R, Sch> StandardModel<S, A, Store, Props, R, Sch>

where A: PositionedAgent, S: SpaceInteraction<A>, Store: AgentStore<A>, R: RngCore, Sch: Scheduler<Self>,

pub fn insert_positioned_agent( &mut self, agent: A, ) -> Result<(), InteractionError<S::Error>>

Insert a positioned agent into both the store and the space atomically.

pub fn remove_positioned_agent( &mut self, id: AgentId, ) -> Result<Option<A>, InteractionError<S::Error>>

Remove a positioned agent from both the store and the space atomically.

pub fn move_positioned_agent( &mut self, id: AgentId, new_position: A::Position, ) -> Result<(), InteractionError<S::Error>>

Move a positioned agent, updating both the agent value and spatial index.

pub fn validate_space_index(&self) -> Result<(), InteractionError<S::Error>>

Validate that all stored agents are represented by the spatial index.

pub fn step_spatial(&mut self) -> Result<(), InteractionError<S::Error>>

Advance one tick while applying deferred add/remove actions to both the agent store and the spatial index.

pub fn run_spatial( &mut self, steps: usize, ) -> Result<(), InteractionError<S::Error>>

Advance n spatially-consistent ticks.

impl<S, A, Store, Props, R, Sch> StandardModel<S, A, Store, Props, R, Sch>

where A: Agent, S: Space, Store: AgentStore<A>, R: RngCore, Sch: Scheduler<Self>,

pub fn new( agents: Store, space: S, scheduler: Sch, properties: Props, rng: R, agent_step_ctx: Option<AgentStepFn<S, A, Props, R, Sch>>, model_step: Option<fn(&mut Self)>, agents_first: bool, ) -> Self

Create a new StandardModel.

Arguments

• agents - pre-populated agent store.
• space - the simulation space.
• scheduler - controls agent activation order.
• properties - user-defined model properties.
• rng - seeded random number generator.
• agent_step_ctx - optional per-agent step function.
• model_step - optional per-tick model step function.
• agents_first - if true, agent steps run before the model step.

pub fn new_base( agents: Store, space: S, scheduler: Sch, properties: Props, rng: R, ) -> Self

Create a model with no step functions configured yet.

This is the most ergonomic starting point for external consumers who want to configure the model via builder-style methods.

Defaults:

• no agent_step_ctx
• no model_step
• agents_first = true

pub fn new_with_agent_step( agents: Store, space: S, scheduler: Sch, properties: Props, rng: R, agent_step_ctx: impl for<'a> FnMut(&mut A, &mut StepContext<'a, S, A, Props, R, Sch>) + 'static, agents_first: bool, ) -> Self

Create a model with an agent step configured and no model step.

This avoids Some(Box::new(...)) boilerplate in the common case of a purely agent-driven simulation.

pub fn new_with_model_step( agents: Store, space: S, scheduler: Sch, properties: Props, rng: R, model_step: fn(&mut Self), agents_first: bool, ) -> Self

Create a model with a model step configured and no agent step.

pub fn with_agent_step_ctx( self, agent_step_ctx: impl for<'a> FnMut(&mut A, &mut StepContext<'a, S, A, Props, R, Sch>) + 'static, ) -> Self

Builder-style method to set or replace the agent step function.

pub fn with_model_step(self, model_step: fn(&mut Self)) -> Self

Builder-style method to set or replace the model step function.

pub fn with_agents_first(self, agents_first: bool) -> Self

Builder-style method to configure whether agent steps run before model steps.

pub fn time(&self) -> Time

Current simulation time.

pub fn rng_mut(&self) -> RefMut<'_, R>

Mutable access to the model’s RNG (via RefCell).

pub fn space(&self) -> &S

Immutable reference to the simulation space.

pub fn space_mut(&mut self) -> &mut S

Mutable reference to the simulation space.

pub fn properties(&self) -> &Props

Immutable reference to user-defined properties.

pub fn properties_mut(&mut self) -> &mut Props

Mutable reference to user-defined properties.

pub fn agent(&self, id: AgentId) -> Option<Ref<'_, A>>

Borrow an agent immutably by ID.

pub fn agent_mut(&self, id: AgentId) -> Option<RefMut<'_, A>>

Borrow an agent mutably by ID.

pub fn insert_agent(&mut self, agent: A) -> Result<(), A>

Insert an agent into the store.

Returns Err(agent) if an agent with the same ID already exists (the agent is returned back to the caller).

pub fn remove_agent(&mut self, id: AgentId) -> Option<A>

Remove an agent by ID, returning it if found.

pub fn next_id(&mut self) -> AgentId

Generate the next unused agent ID (monotonically increasing).

pub fn step(&mut self)

Advance the simulation by one time step.

Runs agent steps and model step in the order determined by agents_first, then increments time by 1.

pub fn step_n(&mut self, n: usize)

Advance the simulation by n time steps.

pub fn run(&mut self, steps: usize)

Alias for step_n.

pub fn agents(&self) -> impl Iterator<Item = Ref<'_, A>>

Iterator over all agents in the store.

Returns borrowed references. The order depends on the store implementation and must not be treated as a stable replay contract unless the store explicitly guarantees it.

pub fn agents_len(&self) -> usize

Number of agents currently in the store.

Trait Implementations

impl<S, A, Store, Props, R, Sch> HasAgentIds for StandardModel<S, A, Store, Props, R, Sch>

where A: Agent, S: Space, Store: AgentStore<A>, R: RngCore,

fn agent_ids(&self) -> Vec<AgentId>

Collect all agent IDs into a new Vec.

fn agent_ids_into(&self, buf: &mut Vec<AgentId>)

Append all agent IDs into buf (does not clear it first).

impl<S, A, Store, Props, R, Sch> Model for StandardModel<S, A, Store, Props, R, Sch>

where A: Agent, S: Space, Store: AgentStore<A>, R: RngCore,

type Agent = A

The agent type stored in this model.

type Space = S

The space type used by this model.

type Properties = Props

User-defined model properties (can be () if unused).

type Rng = R

The random number generator type.

type AgentRef<'a> = Ref<'a, A> where Self: 'a

Borrowed reference to an agent (may be Ref<'a, A> for RefCell-based stores).

type AgentRefMut<'a> = RefMut<'a, A> where Self: 'a

Mutably borrowed reference to an agent (may be RefMut<'a, A>).

fn time(&self) -> Time

Current simulation time.

fn rng_mut(&self) -> impl DerefMut<Target = Self::Rng> + '_

Mutable access to the model’s RNG.

fn space(&self) -> &Self::Space

Immutable reference to the simulation space.

fn properties(&self) -> &Self::Properties

Immutable reference to user-defined properties.

fn properties_mut(&mut self) -> &mut Self::Properties

Mutable reference to user-defined properties.

fn agent(&self, id: AgentId) -> Option<Self::AgentRef<'_>>

Look up an agent by ID, returning a borrowed reference.

fn agent_mut(&self, id: AgentId) -> Option<Self::AgentRefMut<'_>>

Look up an agent by ID, returning a mutably borrowed reference.

fn has_id(&self, id: AgentId) -> bool

Check whether an agent with the given ID exists.