ixa/
lib.rs

1//! A framework for building discrete-event simulations
2//!
3//! Ixa is a framework designed to support the creation of large-scale
4//! discrete event simulations. The primary use case is the construction of
5//! agent-based models for disease transmission, but the approach is applicable
6//! in a wide array of circumstances.
7//!
8//! The central object of an Ixa simulation is the `Context` that is
9//! responsible for managing all the behavior of the simulation. All of the
10//! simulation-specific logic is embedded in modules that rely on the `Context`
11//! for core services such as:
12//! * Maintaining a notion of time for the simulation
13//! * Scheduling events to occur at some point in the future and executing them
14//!   at that time
15//! * Holding module-specific data so that the module and other modules can
16//!   access it
17//!
18//! In practice, a simulation usually consists of a set of modules that work
19//! together to provide all of the functions of the simulation. For instance,
20//! a simple disease transmission model might consist of the
21//! following modules:
22//! * A population loader that initializes the set of people represented
23//!   by the simulation.
24//! * An infection seeder that introduces the pathogen into the population.
25//! * A disease progression manager that transitions infected people through
26//!   stages of disease until recovery.
27//! * A transmission manager that models the process of an infected
28//!   person trying to infect susceptible people in the population.
29//!
30//! ## Features
31//!
32//! - **`logging`**: enables structured logging for native and wasm targets.
33//! - **`progress_bar`**: enables the timeline progress bar for long-running simulations.
34//! - **`profiling`**: enables collection and reporting of execution profiling statistics. Disabled by default.
35
36#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/docs/book/src/cli-usage.md"))]
37
38pub mod context;
39pub use context::{Context, ContextBase, ExecutionPhase, IxaEvent};
40
41mod plugin_context;
42pub use plugin_context::PluginContext;
43
44mod data_plugin;
45pub use data_plugin::*;
46
47pub mod error;
48pub use error::IxaError;
49
50pub mod global_properties;
51pub use global_properties::{ContextGlobalPropertiesExt, GlobalProperty};
52
53pub mod network;
54pub use network::{ContextNetworkExt, Edge, EdgeType};
55
56pub mod macros;
57
58pub mod plan;
59pub mod random;
60pub use random::{ContextRandomExt, RngId};
61
62pub mod report;
63pub use report::{ConfigReportOptions, ContextReportExt, Report};
64
65pub mod runner;
66pub use runner::{run_with_args, run_with_custom_args, BaseArgs};
67
68pub mod log;
69pub use log::{
70    debug, disable_logging, enable_logging, error, info, set_log_level, set_module_filter,
71    set_module_filters, trace, warn, LevelFilter,
72};
73
74#[cfg(feature = "progress_bar")]
75pub mod progress;
76
77pub mod hashing;
78pub mod numeric;
79
80// Re-export for macros
81pub use bincode;
82pub use csv;
83pub use ctor;
84pub use ixa_derive::{
85    impl_make_canonical, impl_people_make_canonical, reorder_closure, sorted_tag,
86    sorted_value_type, unreorder_closure,
87};
88pub use paste;
89pub use rand;
90
91// Deterministic hashing data structures
92pub use crate::hashing::{HashMap, HashMapExt, HashSet, HashSetExt};
93
94// Preludes
95pub mod prelude;
96
97pub mod prelude_for_plugins {
98    pub use ixa_derive::IxaEvent;
99
100    pub use crate::context::{ContextBase, IxaEvent};
101    pub use crate::define_data_plugin;
102    pub use crate::error::IxaError;
103    pub use crate::prelude::*;
104}
105
106pub mod entity;
107pub use entity::{ContextEntitiesExt, EntityPropertyTuple};
108
109pub mod execution_stats;
110pub mod profiling;
111mod value_vec;
112
113#[cfg(all(target_arch = "wasm32", feature = "progress_bar"))]
114compile_error!(
115    "Target `wasm32` and feature `progress_bar` are mutually exclusive — enable at most one."
116);
117
118// The following is a workaround for an ICE involving wasm-bindgen:
119// https://github.com/CDCgov/ixa/actions/runs/16283417455/job/45977349528?pr=464
120#[cfg(target_family = "wasm")]
121use wasm_bindgen::prelude::wasm_bindgen;
122
123// See: https://github.com/rustwasm/wasm-bindgen/issues/4446
124#[cfg(target_family = "wasm")]
125mod wasm_workaround {
126    extern "C" {
127        pub(super) fn __wasm_call_ctors();
128    }
129}
130
131// See: https://github.com/rustwasm/wasm-bindgen/issues/4446
132#[cfg(target_family = "wasm")]
133#[wasm_bindgen(start)]
134fn start() {
135    // fix:
136    // Error: Read a negative address value from the stack. Did we run out of memory?
137    #[cfg(target_family = "wasm")]
138    unsafe {
139        wasm_workaround::__wasm_call_ctors()
140    };
141}
ixa/lib.rs

ixa/
lib.rs
