Struct Context 

pub struct Context { /* private fields */ }

A manager for the state of a discrete-event simulation

Provides core simulation services including

• Maintaining a notion of time
• Scheduling events to occur at some point in the future and executing them at that time
• Holding data that can be accessed by simulation modules

Simulations are constructed out of a series of interacting modules that take turns manipulating the Context through a mutable reference. Modules store data in the simulation using the DataPlugin trait that allows them to retrieve data by type.

The future event list of the simulation is a queue of Callback objects - called plans - that will assume control of the Context at a future point in time and execute the logic in the associated FnOnce(&mut Context) closure. Modules can add plans to this queue through the Context.

The simulation also has a separate callback mechanism. Callbacks fire before the next timed event (even if it is scheduled for the current time). This allows modules to schedule actions for immediate execution but outside of the current iteration of the event loop.

Modules can also emit ‘events’ that other modules can subscribe to handle by event type. This allows modules to broadcast that specific things have occurred and have other modules take turns reacting to these occurrences.

Implementations

impl Context

pub fn new() -> Context

Create a new empty Context

pub fn subscribe_to_event<E: IxaEvent>( &mut self, handler: impl Fn(&mut Context, E) + 'static, ) -> EventListenerId<E>

Register to handle emission of events of type E

Handlers will be called upon event emission in order of subscription as queued Callbacks with the appropriate event.

pub fn unsubscribe_from_event<E: IxaEvent>( &mut self, listener_id: &EventListenerId<E>, ) -> bool

Unsubscribe a previously registered event listener.

Returns true if a listener was unsubscribed and false if the token is unknown, already unsubscribed, or otherwise absent.

pub fn emit_event<E: IxaEvent>(&mut self, event: E)

Emit an event of type E to be handled by registered receivers

Receivers will handle events in the order that they have subscribed and are queued as callbacks

pub fn add_plan( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, ) -> PlanId

Add a plan to the future event list at the specified time in the normal phase

The supplied time is converted to f64 before validation.

use ixa::Context;

struct ModelTime(f64);

impl From<ModelTime> for f64 {
    fn from(time: ModelTime) -> Self {
        time.0
    }
}

let mut context = Context::new();
context.add_plan(ModelTime(1.0), |_| {});

Returns a PlanId for the newly-added plan that can be used to cancel it if needed.

Panics

Panics if time is in the past, infinite, or NaN.

pub fn add_plan_with_phase( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, phase: ExecutionPhase, ) -> PlanId

Add a plan to the future event list at the specified time and with the specified phase (first, normal, or last among plans at the specified time)

The supplied time is converted to f64 before validation.

Returns a PlanId for the newly-added plan that can be used to cancel it if needed.

Panics

Panics if time is in the past, infinite, or NaN.

pub fn add_passive_plan( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, ) -> PlanId

Add a passive plan to the future event list at the specified time in the normal phase.

Passive plans execute like regular plans but do not keep the simulation timeline alive.

The supplied time is converted to f64 before validation.

Returns a PlanId for the newly-added plan that can be used to cancel it if needed.

Panics

Panics if time is in the past, infinite, or NaN.

pub fn schedule_shutdown(&mut self, time: f64) -> PlanId

Schedule Context::shutdown at the specified maximum simulation time.

The shutdown request is scheduled through Context::add_passive_plan, so it does not keep the simulation timeline alive when non-passive work is exhausted before time. If execution reaches time, normal shutdown finishes queued callbacks and regular plans at that time before running shutdown-time plans. If execution ends earlier, the future passive shutdown plan remains queued like any other future passive plan.

This schedules the shutdown request itself. Use Context::add_shutdown_plan to schedule work that should run during normal shutdown.

Returns a PlanId that can be passed to Context::cancel_plan.

Examples

use ixa::Context;

let mut context = Context::new();
context.schedule_shutdown(10.0);
context.add_plan(20.0, |_| {});

context.execute();
assert_eq!(context.get_current_time(), 10.0);

Panics

Panics if time is in the past, infinite, or NaN.

pub fn add_passive_plan_with_phase( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, phase: ExecutionPhase, ) -> PlanId

Add a passive plan to the future event list at the specified time and with the specified phase.

Passive plans execute like regular plans but do not keep the simulation timeline alive.

The supplied time is converted to f64 before validation.

Returns a PlanId for the newly-added plan that can be used to cancel it if needed.

Panics

Panics if time is in the past, infinite, or NaN.

pub fn add_shutdown_plan( &mut self, callback: impl FnOnce(&mut Context) + 'static, ) -> PlanId

Add a plan to execute during shutdown-time in the normal phase.

Shutdown-time plans execute after regular plans at the current simulation time are exhausted during normal shutdown, and after natural exhaustion of the regular plan queue.

Returns a PlanId for the newly-added plan that can be used to cancel it if needed.

pub fn add_shutdown_plan_with_phase( &mut self, callback: impl FnOnce(&mut Context) + 'static, phase: ExecutionPhase, ) -> PlanId

Add a plan to execute during shutdown-time with the specified phase.

Shutdown-time plans have no simulation time. They are ordered by phase and insertion order.

Returns a PlanId for the newly-added plan that can be used to cancel it if needed.

pub fn add_periodic_plan_with_phase( &mut self, period: impl Into<f64>, callback: impl Fn(&mut Context) + 'static, phase: ExecutionPhase, )

Add a passive periodic plan with specified priority to the future event list.

Periodic plans reschedule themselves after every run. They do not keep the simulation timeline alive: when no non-passive plans remain, normal shutdown begins, and only passive plans at the final current time can still run during that execution pass. Future passive periodic plans remain queued and may run if later non-passive work is scheduled.

The supplied period is converted to f64 before validation.

Notes:

• The first periodic plan is scheduled at time 0.0. If set_start_time was set to a positive value, this will currently panic because the first plan occurs before the start time (see issue #634 for future behavior).

Panics

Panics if plan period is negative, infinite, or NaN.

pub fn cancel_plan(&mut self, plan_id: &PlanId)

Cancel a plan that has been added to the queue

Panics

This function panics if you cancel a plan which has already been cancelled or executed.

pub fn queue_callback(&mut self, callback: impl FnOnce(&mut Context) + 'static)

Add a Callback to the queue to be executed before the next plan

pub fn get_data_mut<T: DataPlugin>( &mut self, _data_plugin: T, ) -> &mut T::DataContainer

Retrieve a mutable reference to the data container associated with a DataPlugin

If the data container has not been already added to the Context then this function will use the DataPlugin::init method to construct a new data container and store it in the Context.

Returns a mutable reference to the data container

pub fn get_data<T: DataPlugin>(&self, _data_plugin: T) -> &T::DataContainer

Retrieve a reference to the data container associated with a DataPlugin

Returns a reference to the data container if it exists or else None

pub fn shutdown(&mut self)

Request normal shutdown.

Normal shutdown stops simulation time from advancing. Execution continues through queued callbacks, regular plans at the current time, and then shutdown-time plans. Calling shutdown during shutdown-time execution does not return execution to regular current-time plans.

pub fn abort(&mut self)

Stop the current event loop immediately.

Abort only stops the current execute loop. The stopped status is cleared when execute is called again.

pub fn get_current_time(&self) -> f64

Get the current simulation time

Returns the current time in the simulation. The behavior depends on execution state:

• During execution: returns the time of the currently executing plan or callback
• Before execution: returns the start time (if set via Context::set_start_time), or 0.0

The time can be negative if a negative start time was set before execution.

pub fn set_start_time(&mut self, start_time: impl Into<f64>)

Set the start time for the simulation. Must be finite.

The supplied start time is converted to f64 before validation.

• Call before Context.execute().
• start_time must be finite (not NaN or infinite).
• May be called only once.
• If plans are already scheduled, start_time must be earlier than or equal to the earliest scheduled plan time.

Panics

Panics if:

• start_time is NaN or infinite.
• the start time was already set.
• Context::execute() has been called.
• start_time is later than the earliest scheduled plan time.

pub fn get_start_time(&self) -> Option<f64>

Get the start time that was set via set_start_time, or None if not set.

pub fn execute(&mut self)

Execute the simulation until callbacks and plans are exhausted and shutdown work is complete.

pub fn execute_single_step(&mut self)

Executes a single callback, plan, or shutdown status transition.

pub fn get_execution_statistics(&mut self) -> ExecutionStatistics

Trait Implementations

impl ContextBase for Context

fn subscribe_to_event<E: IxaEvent>( &mut self, handler: impl Fn(&mut Context, E) + 'static, ) -> EventListenerId<E>

fn unsubscribe_from_event<E: IxaEvent>( &mut self, listener_id: &EventListenerId<E>, ) -> bool

fn emit_event<E: IxaEvent>(&mut self, event: E)

fn add_plan( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, ) -> PlanId

fn add_plan_with_phase( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, phase: ExecutionPhase, ) -> PlanId

fn add_passive_plan( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, ) -> PlanId

fn add_passive_plan_with_phase( &mut self, time: impl Into<f64>, callback: impl FnOnce(&mut Context) + 'static, phase: ExecutionPhase, ) -> PlanId

fn add_shutdown_plan( &mut self, callback: impl FnOnce(&mut Context) + 'static, ) -> PlanId

fn add_shutdown_plan_with_phase( &mut self, callback: impl FnOnce(&mut Context) + 'static, phase: ExecutionPhase, ) -> PlanId

fn add_periodic_plan_with_phase( &mut self, period: impl Into<f64>, callback: impl Fn(&mut Context) + 'static, phase: ExecutionPhase, )

fn cancel_plan(&mut self, plan_id: &PlanId)

fn queue_callback(&mut self, callback: impl FnOnce(&mut Context) + 'static)

fn get_data_mut<T: DataPlugin>(&mut self, plugin: T) -> &mut T::DataContainer

fn get_data<T: DataPlugin>(&self, plugin: T) -> &T::DataContainer

fn get_current_time(&self) -> f64

fn get_execution_statistics(&mut self) -> ExecutionStatistics

fn abort(&mut self)

fn schedule_shutdown(&mut self, time: f64) -> PlanId

Schedule normal shutdown as a passive plan at the specified maximum time.

impl ContextEntitiesExt for Context

fn add_entity<E: Entity, PL: PropertyInitializationList<E>>( &mut self, property_list: PL, ) -> Result<EntityId<E>, IxaError>

fn get_property<E: Entity, P: Property<E>>(&self, entity_id: EntityId<E>) -> P

Fetches the property value set for the given entity_id.

fn set_property<E: Entity, P: Property<E>>( &mut self, entity_id: EntityId<E>, property_value: P, )

Sets the value of the given property. This method unconditionally emits a PropertyChangeEvent.

fn index_property<E: Entity, P: IndexableProperty<E>>(&mut self)

Enables full indexing of property values for the property P.

fn index_property_counts<E: Entity, P: IndexableProperty<E>>(&mut self)

Enables value-count indexing of property values for the property P.

fn track_periodic_value_change_counts<E, PL, P, F>( &mut self, period: impl Into<f64>, handler: F, )

where E: Entity, PL: PropertyList<E> + Eq + Hash, P: IndexableProperty<E>, F: Fn(&mut Context, &mut StratifiedValueChangeCounter<E, PL, P>) + 'static,

Tracks periodic value change counts for a newly created counter.

fn with_query_results<'a, E: Entity, Q: Query<E>>( &'a self, query: Q, callback: &mut dyn FnMut(EntitySet<'a, E>), )

This method gives client code direct access to the query result as an EntitySet. This is especially efficient for indexed queries, as this method can reduce to wrapping a single indexed source.

fn query_entity_count<E: Entity, Q: Query<E>>(&self, query: Q) -> usize

Gives the count of distinct entity IDs satisfying the query. This is especially efficient for indexed queries.

fn sample_entity<E, Q, R>(&self, rng_id: R, query: Q) -> Option<EntityId<E>>

where E: Entity, Q: Query<E>, R: RngId + 'static, R::RngType: Rng,

Sample a single entity uniformly from the query results. Returns None if the query’s result set is empty.

fn count_and_sample_entity<E, Q, R>( &self, rng_id: R, query: Q, ) -> (usize, Option<EntityId<E>>)

where E: Entity, Q: Query<E>, R: RngId + 'static, R::RngType: Rng,

Count query results and sample a single entity uniformly from them.

fn sample_entities<E, Q, R>( &self, rng_id: R, query: Q, n: usize, ) -> Vec<EntityId<E>>

where E: Entity, Q: Query<E>, R: RngId + 'static, R::RngType: Rng,

Sample up to requested entities uniformly from the query results. If the query’s result set has fewer than requested entities, the entire result set is returned.

fn get_entity_count<E: Entity>(&self) -> usize

Returns a total count of all created entities of type E.

fn get_entity_iterator<E: Entity>(&self) -> PopulationIterator<E>

Returns an iterator over all created entities of type E.

fn query<E: Entity, Q: Query<E>>(&self, query: Q) -> EntitySet<'_, E>

Generates an EntitySet representing the query results.

fn query_result_iterator<E: Entity, Q: Query<E>>( &self, query: Q, ) -> EntitySetIterator<'_, E>

Generates an iterator over the results of the query.

fn match_entity<E: Entity, Q: Query<E>>( &self, entity_id: EntityId<E>, query: Q, ) -> bool

Determines if the given person matches this query.

fn filter_entities<E: Entity, Q: Query<E>>( &self, entities: &mut Vec<EntityId<E>>, query: Q, )

Removes all EntityIds from the given vector that do not match the given query.

impl ContextGlobalPropertiesExt for Context

fn set_global_property_value<T: GlobalProperty + 'static>( &mut self, _property: T, value: T::Value, ) -> Result<(), IxaError>

Set the value of a global property of type T

fn get_global_property_value<T: GlobalProperty + 'static>( &self, _property: T, ) -> Option<&T::Value>

Return value of global property T

fn load_global_properties(&mut self, file_name: &Path) -> Result<(), IxaError>

Load global properties from a JSON file.

fn load_parameters_from_json<T: 'static + Debug + DeserializeOwned>( &mut self, file_name: &Path, ) -> Result<T, IxaError>

Given a file path for a valid json file, deserialize parameter values for a given struct T

impl ContextNetworkExt for Context

fn add_edge<E: Entity, ET: EdgeType<E>>( &mut self, entity_id: EntityId<E>, neighbor: EntityId<E>, weight: f32, inner: ET, ) -> Result<(), IxaError>

Add an edge of type ET between entity_id and neighbor with a given weight.

fn add_edge_bidi<E: Entity, ET: EdgeType<E>>( &mut self, entity1: EntityId<E>, entity2: EntityId<E>, weight: f32, inner: ET, ) -> Result<(), IxaError>

Add a pair of edges of type ET between entity1 and entity2 with a given weight, one edge in each direction. This is syntactic sugar for calling add_edge twice.

fn remove_edge<E: Entity, ET: EdgeType<E>>( &mut self, entity_id: EntityId<E>, neighbor: EntityId<E>, ) -> Option<Edge<E, ET>>

Remove the edge of type ET from entity_id to neighbor and return it, or None if the edge does not exist.

fn get_edge<E: Entity, ET: EdgeType<E>>( &self, entity_id: EntityId<E>, neighbor: EntityId<E>, ) -> Option<&Edge<E, ET>>

Get an edge of type ET from entity_id to neighbor if one exists.

fn get_edges<E: Entity, ET: EdgeType<E>>( &self, entity_id: EntityId<E>, ) -> Vec<Edge<E, ET>>

Get all outgoing edges of type ET from entity_id.

fn get_matching_edges<E: Entity, ET: EdgeType<E>>( &self, entity_id: EntityId<E>, filter: impl Fn(&Self, &Edge<E, ET>) -> bool, ) -> Vec<Edge<E, ET>>

Get all edges of type ET from entity_id that match the predicate provided in filter.

fn find_entities_by_degree<E: Entity, ET: EdgeType<E>>( &self, degree: usize, ) -> Vec<EntityId<E>>

Find all entities who have an edge of type ET and degree degree.

fn select_random_edge<E: Entity, ET: EdgeType<E>, R: RngId + 'static>( &self, rng_id: R, entity_id: EntityId<E>, ) -> Result<Edge<E, ET>, IxaError>

where R::RngType: Rng,

Select a random outgoing edge of type ET from entity_id, weighted by the edge weights.

impl ContextRandomExt for Context

fn init_random(&mut self, base_seed: u64)

Initializes the RngPlugin data container to store rngs as well as a base seed. Note that rngs are created lazily when get_rng is called.

fn sample<R: RngId + 'static, T>( &self, _rng_type: R, sampler: impl FnOnce(&mut R::RngType) -> T, ) -> T

Gets a random sample from the random number generator associated with the given RngId by applying the specified sampler function. If the Rng has not been used before, one will be created with the base seed you defined in set_base_random_seed. Note that this will panic if set_base_random_seed was not called yet.

fn debug_rng_state<R: RngId + 'static>(&self, _rng_id: R) -> u64

where R::RngType: Clone + Rng,

Returns a deterministic debug fingerprint for the current position of the random number generator associated with the given RngId.

fn sample_distr<R: RngId + 'static, T>( &self, _rng_type: R, distribution: impl Distribution<T>, ) -> T

where R::RngType: Rng,

Gets a random sample from the specified distribution using a random number generator associated with the given RngId. If the Rng has not been used before, one will be created with the base seed you defined in set_base_random_seed. Note that this will panic if set_base_random_seed was not called yet.

fn sample_range<R: RngId + 'static, S, T>(&self, rng_id: R, range: S) -> T

where R::RngType: Rng, S: SampleRange<T>, T: SampleUniform,

Gets a random sample within the range provided by range using the generator associated with the given RngId. Note that this will panic if set_base_random_seed was not called yet.

fn sample_bool<R: RngId + 'static>(&self, rng_id: R, p: impl Into<f64>) -> bool

where R::RngType: Rng,

Gets a random boolean value which is true with probability p using the generator associated with the given RngId. The supplied probability is converted to f64 before sampling.

fn sample_weighted<R: RngId + 'static, T>( &self, _rng_id: R, weights: &[T], ) -> usize

where R::RngType: Rng, T: Clone + Default + SampleUniform + for<'a> AddAssign<&'a T> + PartialOrd + Weight,

Draws a random entry out of the list provided in weights with the given weights using the generator associated with the given RngId. Note that this will panic if set_base_random_seed was not called yet.

impl ContextReportExt for Context

fn generate_filename(&mut self, short_name: &str) -> PathBuf

fn add_report_by_type_id( &mut self, type_id: TypeId, short_name: &str, ) -> Result<(), IxaError>

Add a report file keyed by a TypeId. The short_name is used for file naming to distinguish what data each output file points to.

fn add_report<T: Report + 'static>( &mut self, short_name: &str, ) -> Result<(), IxaError>

Call add_report with each report type, passing the name of the report type. The short_name is used for file naming to distinguish what data each output file points to.

fn get_writer(&self, type_id: TypeId) -> RefMut<'_, Writer<File>>

fn send_report<T: Report>(&self, report: T)

Write a new row to the appropriate report file

fn report_options(&mut self) -> &mut ConfigReportOptions

Returns a ConfigReportOptions object which has setter methods for report configuration

impl ContextTriggersExt for Context

fn register_trigger<T: TriggerSpec>(&mut self, trigger: T)

impl Default for Context

fn default() -> Self

Returns the “default value” for a type.

impl ProfilingContextExt for Context

fn print_execution_statistics(&mut self, include_profiling_data: bool)

Prints the execution statistics for this context to the console.

fn write_profiling_data(&mut self)

Writes the execution statistics for the context and all profiling data to a JSON file.

impl PluginContext for Context