Struct SystemState 

pub struct SystemState { /* private fields */ }

A heterogeneous collection of payloads describing one system time point.

Fields are declared by a JSON-derived SystemStateSchema. Values are addressed by those field names but stored in compact optional slots. The type-erased representation remains private; callers always insert, borrow, mutate, and extract concrete Rust types.

Implementations

impl SystemState

pub fn clone_structure_without_payloads(&self, time: SimulationTime) -> Self

Creates another empty state with the same specification and field types.

No payload is cloned. The immutable specification handle is shared, and each assembly-established concrete type contract is copied into an empty slot. A later SystemState::insert_payload must therefore use the same type even though the derived state begins without payloads.

pub const fn simulation_time(&self) -> SimulationTime

Returns this state’s temporal coordinate.

pub fn replace_simulation_time( &mut self, time: SimulationTime, ) -> SimulationTime

Replaces this state’s complete temporal coordinate.

The previous SimulationTime is returned by value. Both coordinates are small Copy values, so replacement performs no heap allocation and does not inspect, move, or clone any scientific payload.

Replacing the complete value rather than exposing its individual fields ensures that a physical coordinate can enter a state only through the finite-value validation performed by SimulationTime::from_iteration_and_physical_time.

Collection invariants

A state stored inside a time-ordered collection must not be passed as &mut SystemState to external callers: changing its time could violate collection ordering. The owning simulation may freely call this method before submitting a state or encoded sample.

pub fn advance_simulation_time( &mut self, physical_time_increment: Option<f64>, ) -> Result<SimulationTime, StateError>

Advances the iteration by one after one completed model step.

Passing None increments only the authoritative iteration and preserves the current optional physical coordinate. Passing Some(delta) additionally requires an existing physical coordinate, a finite delta, and a finite sum. Negative and zero finite deltas are valid because iteration—not physical time—defines record ordering.

On success, the new SimulationTime is stored and returned. All validation occurs before assignment, so every error leaves the original time point unchanged.

Errors

Returns:

• StateError::IterationOverflow when the current iteration is u64::MAX;
• StateError::MissingPhysicalTime when a delta is supplied but the current state has no physical coordinate;
• StateError::InvalidPhysicalAdvance when the delta or resulting coordinate is not finite.

pub const fn schema(&self) -> &SystemStateSchema

Returns the shared immutable field specification.

pub fn declared_field_count(&self) -> usize

Returns the number of fields declared by the state specification.

This count is structural and includes empty payload slots.

pub fn has_no_declared_fields(&self) -> bool

Reports whether the state specification declares no fields.

This is consistent with SystemState::declared_field_count. To test whether a non-empty layout currently carries no payloads, use SystemState::has_no_payloads.

pub fn populated_field_count(&self) -> usize

Returns the number of slots that currently contain payloads.

pub fn has_no_payloads(&self) -> bool

Reports whether every declared payload slot is empty.

pub fn field_schemas(&self) -> &[StateFieldSchema]

Returns field specifications in deterministic template order.

pub fn contains_payload(&self, key: &str) -> Result<bool, StateError>

Reports whether a declared field currently contains a payload.

Errors

Returns StateError::UnknownField when key was not declared by the JSON template.

pub fn payload_has_type<T>(&self, key: &str) -> Result<bool, StateError>

where T: Any,

Reports whether a populated field contains the exact Rust type T.

An empty declared field returns false.

Errors

Returns StateError::UnknownField when key was not declared by the JSON template.

pub fn insert_payload<T>( &mut self, key: &str, payload: T, ) -> Result<Option<T>, PayloadInsertError<T>>

where T: Serialize + Clone + Send + 'static,

Sets or replaces a payload while preserving ownership on every outcome.

payload moves into this operation and is never cloned:

• a never-populated declared slot binds itself to T, receives the payload, and returns Ok(None);
• a slot bound to exactly T receives it and returns the displaced payload as Ok(Some(previous)), or Ok(None) when currently empty;
• an undeclared key returns Err(PayloadInsertError<T>) containing the unchanged incoming payload;
• a slot bound to another concrete type remains unchanged and returns the incoming payload in PayloadInsertError<T>, even when its payload is empty.

Returning a previous payload is deliberate assignment behavior. A caller that does not need that owner should discard it explicitly:

let mut state = spec.create_empty_state(SimulationTime::from_iteration(0));
drop(state.insert_payload("population", vec![1_u64, 2, 3])?);

Type-contract validation occurs before the slot is changed. Consequently, rejection cannot discard or temporarily remove an existing scientific value, and take or clear cannot reopen a field for a different type.

Errors

Returns PayloadInsertError containing:

• StateError::UnknownField when key is undeclared;
• StateError::TypeMismatch when the slot is bound to a different concrete Rust type.

In both cases PayloadInsertError::into_parts recovers the unchanged incoming T without cloning it.

pub fn payload<T>(&self, key: &str) -> Result<&T, StateError>

where T: Any,

Borrows a populated field as the exact Rust type T.

Errors

Returns StateError::UnknownField for an undeclared key, StateError::MissingPayload for an empty slot, or StateError::TypeMismatch when the stored concrete type differs from T.

pub fn payload_mut<T>(&mut self, key: &str) -> Result<&mut T, StateError>

where T: Any,

Mutably borrows a populated field as the exact Rust type T.

Mutation occurs in place and does not clone the payload.

Errors

Returns StateError::UnknownField for an undeclared key, StateError::MissingPayload for an empty slot, or StateError::TypeMismatch when the stored concrete type differs from T.

pub fn borrow_payloads<'state, Q>( &'state self, keys: Q::Keys<'_>, ) -> Result<Q::Refs<'state>, StateError>

where Q: PayloadTuple,

Borrows several distinct populated fields as concrete immutable types.

Q is a tuple of expected payload types, while keys is the equally sized tuple of field names. Tuple positions correspond exactly. The supported arities are two through eight; single-field callers should use SystemState::payload. The sealed tuple implementation is internal and requires no user-defined selector, query object, or macro invocation.

Errors

Validation proceeds from left to right and completes before references are returned. The method reports an unknown field, repeated field, retained type mismatch, or missing payload through StateError. An error leaves every slot unchanged.

pub fn borrow_payloads_mut<'state, Q>( &'state mut self, keys: Q::Keys<'_>, ) -> Result<Q::RefsMut<'state>, StateError>

where Q: PayloadTuple,

Borrows several distinct populated fields as concrete mutable types.

Q is a tuple of expected payload types, while keys is the equally sized tuple of field names. All names, duplicate indices, retained type contracts, and payload presence are validated before any mutable reference is produced. Payloads remain owned by this state and are not cloned, moved, serialized, locked, or temporarily removed.

One call should normally surround a complete coupled kernel or sweep so name lookup and dynamic type validation occur once outside its inner loop. Supported arities are two through eight; single-field callers should use SystemState::payload_mut.

Errors

Returns the same deterministic validation errors as SystemState::borrow_payloads. A failure leaves the state unchanged and grants no partial borrow.

pub fn take_payload<T>(&mut self, key: &str) -> Result<T, StateError>

where T: Any + Send,

Removes and returns the payload from a declared field.

A successful call moves the original concrete T out of its internal box and leaves the field slot empty while retaining its type contract. It does not invoke Clone. Type and presence validation occurs before the payload owner is removed.

Errors

Returns StateError::UnknownField for an undeclared key, StateError::MissingPayload for an empty slot, or StateError::TypeMismatch when the stored concrete type differs from T.

pub fn clear_payload(&mut self, key: &str) -> Result<bool, StateError>

Drops the payload stored in one declared field.

Returns true when a payload was present and dropped, or false when the declared slot was already empty.

Errors

Returns StateError::UnknownField when key was not declared by the JSON template.

pub fn clear_all_payloads(&mut self)

Drops every payload while retaining layout, type contracts, and time.

Trait Implementations

impl Clone for SystemState

fn clone(&self) -> Self

Shares the immutable specification and deep-clones populated payloads.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SystemState

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

Formats structural metadata without formatting scientific payloads.