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//! - **`debugger`**: enables the interactive debugger, an interactive console-based REPL
33//!   (Read-Eval-Print Loop) that allows you to pause simulation execution, inspect state, and
34//!   control simulation flow through commands like breakpoints, population queries, and
35//!   step-by-step execution.
36//! - **`web_api`**: enables the web API, an HTTP-based remote control interface that allows
37//!   external applications to monitor simulation state, control execution, and query data through
38//!   REST endpoints. This feature implies the `debugger` feature.
39
40#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/docs/book/src/cli-usage.md"))]
41
42pub mod context;
43pub use context::{Context, ContextBase, ExecutionPhase, IxaEvent};
44
45mod plugin_context;
46pub use plugin_context::PluginContext;
47
48mod data_plugin;
49pub use data_plugin::*;
50
51pub mod error;
52pub use error::IxaError;
53
54pub mod global_properties;
55pub use global_properties::{ContextGlobalPropertiesExt, GlobalProperty};
56
57pub mod network;
58pub use network::{ContextNetworkExt, Edge, EdgeType};
59
60pub mod macros;
61//pub use macros::*;
62
63pub mod people;
64pub use people::{
65    ContextPeopleExt, PersonCreatedEvent, PersonId, PersonProperty, PersonPropertyChangeEvent,
66};
67
68pub mod plan;
69pub mod random;
70pub use random::{ContextRandomExt, RngId};
71
72pub mod tabulator;
73pub use tabulator::Tabulator;
74
75pub mod report;
76pub use report::{ConfigReportOptions, ContextReportExt, Report};
77
78pub mod runner;
79pub use runner::{run_with_args, run_with_custom_args, BaseArgs};
80
81#[cfg(feature = "debugger")]
82pub mod debugger;
83
84pub mod log;
85pub use log::{
86    debug, disable_logging, enable_logging, error, info, set_log_level, set_module_filter,
87    set_module_filters, trace, warn, LevelFilter,
88};
89
90#[cfg(feature = "progress_bar")]
91pub mod progress;
92
93#[cfg(feature = "debugger")]
94pub mod external_api;
95pub mod hashing;
96pub mod numeric;
97
98#[cfg(feature = "web_api")]
99pub mod web_api;
100
101// Re-export for macros
102pub use ixa_derive::{impl_make_canonical, sorted_tag, sorted_value_type};
103pub use {bincode, csv, ctor, paste, rand};
104
105// Deterministic hashing data structures
106pub use crate::hashing::{HashMap, HashMapExt, HashSet, HashSetExt};
107
108// Preludes
109pub mod prelude;
110
111pub mod prelude_for_plugins {
112    pub use ixa_derive::IxaEvent;
113
114    pub use crate::context::{ContextBase, IxaEvent};
115    pub use crate::define_data_plugin;
116    pub use crate::error::IxaError;
117    pub use crate::prelude::*;
118}
119
120pub mod execution_stats;
121
122#[cfg(all(target_arch = "wasm32", feature = "debugger"))]
123compile_error!(
124    "Target `wasm32` and feature `debugger` are mutually exclusive — enable at most one."
125);
126
127#[cfg(all(target_arch = "wasm32", feature = "progress_bar"))]
128compile_error!(
129    "Target `wasm32` and feature `progress_bar` are mutually exclusive — enable at most one."
130);
131
132// The following is a workaround for an ICE involving wasm-bindgen:
133// https://github.com/CDCgov/ixa/actions/runs/16283417455/job/45977349528?pr=464
134#[cfg(target_family = "wasm")]
135use wasm_bindgen::prelude::wasm_bindgen;
136
137// See: https://github.com/rustwasm/wasm-bindgen/issues/4446
138#[cfg(target_family = "wasm")]
139mod wasm_workaround {
140    extern "C" {
141        pub(super) fn __wasm_call_ctors();
142    }
143}
144
145// See: https://github.com/rustwasm/wasm-bindgen/issues/4446
146#[cfg(target_family = "wasm")]
147#[wasm_bindgen(start)]
148fn start() {
149    // fix:
150    // Error: Read a negative address value from the stack. Did we run out of memory?
151    #[cfg(target_family = "wasm")]
152    unsafe {
153        wasm_workaround::__wasm_call_ctors()
154    };
155}
ixa/lib.rs

ixa/
lib.rs
