Skip to main content

Crate ixa

Crate ixa 

Source
Expand description

A framework for building discrete-event simulations

Ixa is a framework designed to support the creation of large-scale discrete event simulations. The primary use case is the construction of agent-based models for disease transmission, but the approach is applicable in a wide array of circumstances.

The central object of an Ixa simulation is the Context that is responsible for managing all the behavior of the simulation. All of the simulation-specific logic is embedded in modules that rely on the Context for core services such as:

  • Maintaining a notion of time for the simulation
  • Scheduling events to occur at some point in the future and executing them at that time
  • Holding module-specific data so that the module and other modules can access it

In practice, a simulation usually consists of a set of modules that work together to provide all of the functions of the simulation. For instance, a simple disease transmission model might consist of the following modules:

  • A population loader that initializes the set of people represented by the simulation.
  • An infection seeder that introduces the pathogen into the population.
  • A disease progression manager that transitions infected people through stages of disease until recovery.
  • A transmission manager that models the process of an infected person trying to infect susceptible people in the population.

§Features

  • logging: enables structured logging for native and wasm targets.
  • profiling: enables collection and reporting of execution profiling statistics. Disabled by default.

§Events

Event types can derive IxaEvent with the same import used for the trait:

use ixa::IxaEvent;

#[derive(IxaEvent)]
struct MyEvent;

fn assert_event<E: IxaEvent>() {}
assert_event::<MyEvent>();

§Command Line Usage

This document contains the help content for the ixa command-line program.

§ixa

Default cli arguments for Ixa runner

Usage: ixa [OPTIONS]

§Options:
  • -r, --random-seed <RANDOM_SEED> — Random seed

    Default value: 0

  • -c, --config <CONFIG> — Optional path for a global properties config file

  • -o, --output <OUTPUT_DIR> — Optional path for report output

  • --prefix <FILE_PREFIX> — Optional prefix for report files

  • -f, --force-overwrite — Overwrite existing report files?

  • -l, --log-level <LOG_LEVEL> — Enable logging

  • -v, --verbose — Increase logging verbosity (-v, -vv, -vvv, etc.)

    LevelERRORWARNINFODEBUGTRACE
    Default✓
    -v✓✓✓
    -vv✓✓✓✓
    -vvv✓✓✓✓✓
  • --warn — Set logging to WARN level. Shortcut for --log-level warn

  • --debug — Set logging to DEBUG level. Shortcut for --log-level DEBUG

  • --trace — Set logging to TRACE level. Shortcut for --log-level TRACE

  • --no-stats — Suppresses the printout of summary statistics at the end of the simulation

Re-exports§

pub use context::Context;
pub use context::ContextBase;
pub use context::EventListenerId;
pub use context::ExecutionPhase;
pub use context::IxaEvent;
pub use calendar::ContextCalendarExt;
pub use error::IxaError;
pub use global_properties::ContextGlobalPropertiesExt;
pub use global_properties::GlobalProperty;
pub use network::ContextNetworkExt;
pub use network::Edge;
pub use network::EdgeType;
pub use plan_queue::PlanId;
pub use random::ContextRandomExt;
pub use random::RngId;
pub use report::ConfigReportOptions;
pub use report::ContextReportExt;
pub use report::Report;
pub use runner::run_with_args;
pub use runner::run_with_custom_args;
pub use runner::run_with_merged_args;
pub use runner::BaseArgs;
pub use runner::RunnerArgs;
pub use log::disable_logging;
pub use log::enable_logging;
pub use log::set_log_level;
pub use log::set_module_filter;
pub use log::set_module_filters;
pub use crate::hashing::HashMapExt;
pub use crate::hashing::HashSetExt;
pub use entity::ContextEntitiesExt;
pub use entity::EntityPropertyTuple;
pub use csv;
pub use ctor;
pub use paste;
pub use rand;
pub use rkyv;

Modules§

calendar
Calendar dates for parameters. Model times are f64 days from day 0; given a start date, a document may write a day as a YYYY-MM-DD date, a YYYY-Www week, or days with units such as 2w. The #[calendar] attribute marks those fields:
context
A manager for the state of a discrete-event simulation
data_structures
entity
A “person” is represented by a PersonId and has multiple PersonProperty values associated with it. Entities generalize this: An Entity is analogous to a table in a relationship database, and the properties of an entity are analogous to the columns that exist on the table. A row in the table is addressable with an EntityId<Entity> (implemented as a newtype of a usize). In this new paradigm, Person is a particular entity, possibly one of several, and PersonId is a type alias for EntityId<Person>.
error
Provides IxaError and wraps other errors.
execution_stats
global_properties
A generic mechanism for storing context-wide data.
hashing
This module provides a deterministic hasher and HashMap and HashSet variants that use it. The hashing data structures in the standard library are not deterministic:
log
The log module defines an interface to Ixa’s internal logging facilities. Logging messages about internal behavior of Ixa. This is not to be confused with reporting, which is model-level concept for Ixa users to record data about running models.
macros
network
A module for modeling contact networks.
numeric
Vendored from statrs@0.18.0 (prec.rs), convenience wrappers around methods from the approx crate. Provides utility functions for working with floating point precision.
planDeprecated
Compatibility re-exports for plan-related public API.
plan_queue
Implementation details for Ixa’s plan queues.
prelude
prelude_for_plugins
profiling
This module provides a lightweight, feature-gated profiling interface for simulations. It tracks event counts and measures elapsed time for named operations (“spans”), and can export the results to the console and to a JSON file together with execution statistics. It supports:
random
report
runner
triggers
Trigger criteria that emit user-defined events.

Macros§

__define_data_plugin
Helper for define_data_plugin
assert_almost_eq
debug
Logs a message at the debug level.
define_data_plugin
Defines a new type for storing data in Context.
define_derived_property
The “derived” variant of define_property! for defining simple derived property types. Defines a struct or enum with a standard set of derives and automatically invokes impl_derived_property! for it.
define_edge_type
define_entity
Defines a zero-sized struct with the right derived traits and implements the Entity trait. If you already have a type defined (struct, enum, etc.), you can use the impl_entity! macro instead.
define_global_property
Defines a global property with the following parameters:
define_multi_property
Defines a derived property consisting of a (named) tuple of other properties. The primary use case is for indexing and querying properties jointly.
define_property
Defines a struct or enum with a standard set of derives and automatically invokes impl_property! for it. This macro provides a concise shorthand for defining simple property types that follow the same derive and implementation pattern.
define_report
Use this macro to define a unique report type
define_rng
Use this to define a unique type which will be used as a key to retrieve an independent rng instance when calling Context::get_rng.
error
Logs a message at the error level.
impl_derived_property
Implements the Property trait for an existing type as a derived property.
impl_edge_type
impl_entity
Implements the Entity trait for the given existing type and defines a type alias of the form MyEntityId = EntityId<MyEntity>. For simple zero-sized types, use the define_entity! macro instead, which will define the struct and derive all the super traits.
impl_property
Implements the Property trait for the given property type and entity.
impl_property_eq
Implements PartialEq and Eq for a property type using Ixa’s generated byte-based equality behavior.
impl_property_eq_hash
Implements PartialEq, Eq, and Hash for a property type using Ixa’s generated byte-based equality and hashing behavior.
impl_property_hash
Implements Hash for a property type using Ixa’s generated byte-based hashing behavior.
info
Logs a message at the info level.
log_enabled
Determines if a message logged at the specified level in that module will be logged.
output
Writes one plain, newline-terminated message to the user-facing output.
schedule_relative
Schedules an action after a delay relative to the context’s current time.
trace
Logs a message at the trace level.
track_periodic_value_change_counts
Tracks periodic value change counts with concise entity, property, and strata syntax.
warn
Logs a message at the warn level.
with
Creates an entity-scoped bundle of property values for queries and entity initialization.

Enums§

Level
An enum representing the available verbosity levels of the logger.
LevelFilter
An enum representing the available verbosity level filters of the logger.

Traits§

DataPlugin
A trait for objects that can provide data containers to be held by Context. Do not implement this trait manually; define data plugins with define_data_plugin!.
PluginContext
A supertrait that exposes useful methods from Context for plugins implementing Context extensions.

Functions§

add_data_plugin_to_registry
get_data_plugin_count
get_data_plugin_ids
initialize_data_plugin_index
Acquires a global lock on the next available plugin index, but only increments it if we successfully initialize the provided index. (Must be pub, as it’s called from within a macro.)

Type Aliases§

HashMap
Type alias for a hash map that uses the Fx hashing algorithm.
HashSet
Type alias for a hash set that uses the Fx hashing algorithm.

Attribute Macros§

calendar
Marks a struct’s calendar day fields; see ixa::calendar.

Derive Macros§

IxaEvent