Struct ObsPlan 

pub struct ObsPlan { /* private fields */ }

Compiled observation plan: either Simple or Standard class.

Simple (all Fixed regions): pre-computed gather indices, branch-free loop, zero spatial computation at runtime. Use execute.

Standard (any agent-relative region): template-based gather with interior/boundary dispatch. Use execute_agents.

Implementations

impl ObsPlan

pub fn compile( spec: &ObsSpec, space: &dyn Space, ) -> Result<ObsPlanResult, ObsError>

Compile an ObsSpec against a Space.

Detects whether the spec contains agent-relative regions and dispatches to the appropriate plan class:

• All Fixed → Simple (pre-computed gather)
• Any AgentDisk/AgentRect → Standard (template-based)

pub fn compile_bound( spec: &ObsSpec, space: &dyn Space, generation: WorldGenerationId, ) -> Result<ObsPlanResult, ObsError>

Compile with generation binding for PLAN_INVALIDATED detection.

Same as compile but records the snapshot’s world_generation_id for later validation in ObsPlan::execute.

pub fn output_len(&self) -> usize

Total number of f32 elements in the output tensor.

pub fn mask_len(&self) -> usize

Total number of bytes in the validity mask.

pub fn compiled_generation(&self) -> Option<WorldGenerationId>

The generation this plan was compiled against, if bound.

pub fn execute( &self, snapshot: &dyn SnapshotAccess, engine_tick: Option<TickId>, output: &mut [f32], mask: &mut [u8], ) -> Result<ObsMetadata, ObsError>

Execute the observation plan against a snapshot.

Fills output with gathered and transformed field values, and mask with validity flags (1 = valid, 0 = padding). Both buffers must be pre-allocated to output_len and mask_len respectively.

engine_tick is the current engine tick for computing ObsMetadata::age_ticks. Pass None in Lockstep mode (age is always 0). In RealtimeAsync mode, pass the current engine tick so age reflects snapshot staleness.

Returns ObsMetadata on success.

Errors

• ObsError::PlanInvalidated if bound and generation mismatches.
• ObsError::ExecutionFailed if a field is missing from the snapshot.

pub fn execute_batch( &self, snapshots: &[&dyn SnapshotAccess], engine_tick: Option<TickId>, output: &mut [f32], mask: &mut [u8], ) -> Result<Vec<ObsMetadata>, ObsError>

Execute the plan for a batch of N identical environments.

Each snapshot in the batch fills output_len() elements in the output buffer, starting at batch_idx * output_len(). Same for masks. This is the primary interface for vectorized RL training.

Returns one ObsMetadata per snapshot.

pub fn execute_agents( &self, snapshot: &dyn SnapshotAccess, space: &dyn Space, agent_centers: &[Coord], engine_tick: Option<TickId>, output: &mut [f32], mask: &mut [u8], ) -> Result<Vec<ObsMetadata>, ObsError>

Execute the Standard plan for N agents in one environment.

Each agent gets output_len() elements starting at agent_idx * output_len(). Fixed entries produce the same output for all agents; agent-relative entries are resolved per-agent using interior/boundary dispatch.

Interior agents (~49% for 20×20 grid, radius 3) use a branchless fast path with stride arithmetic. Boundary agents fall back to per-cell bounds checking.

pub fn is_standard(&self) -> bool

Whether this plan requires execute_agents (Standard) or execute (Simple).

Trait Implementations

impl Debug for ObsPlan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.