Crate ixa

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

• debugger: enables the interactive debugger, an interactive console-based REPL (Read-Eval-Print Loop) that allows you to pause simulation execution, inspect state, and control simulation flow through commands like breakpoints, population queries, and step-by-step execution.
• web_api: enables the web API, an HTTP-based remote control interface that allows external applications to monitor simulation state, control execution, and query data through REST endpoints. This feature implies the debugger feature.

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.)

  Level	ERROR	WARN	INFO	DEBUG	TRACE
  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

• -d, --debugger <DEBUGGER> — Set a breakpoint at a given time and start the debugger. Defaults to t=0.0

• -w, --web <WEB> — Enable the Web API at a given time. Defaults to t=0.0

• -t, --timeline-progress-max <TIMELINE_PROGRESS_MAX> — Enable the timeline progress bar with a maximum time

• --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::ExecutionPhase;

pub use context::IxaEvent;

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 people::ContextPeopleExt;

pub use people::PersonCreatedEvent;

pub use people::PersonId;

pub use people::PersonProperty;

pub use people::PersonPropertyChangeEvent;

pub use random::ContextRandomExt;

pub use random::RngId;

pub use tabulator::Tabulator;

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::BaseArgs;

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 bincode;

pub use csv;

pub use ctor;

pub use paste;

pub use rand;

Modules

context

A manager for the state of a discrete-event simulation

debugger

error

Provides IxaError and wraps other errors.

execution_stats

external_api

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.

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.

people

A generic mechanism for representing people and associated data.

plan

A priority queue that stores arbitrary data sorted by time and priority

prelude

prelude_for_plugins

progress

Provides functions to set up and update a progress bar.

random

report

runner

tabulator

Macros

__define_data_plugin

Helper for define_data_plugin

__define_derived_property_common

Defines a derived person property with the following parameters:

__define_person_property_common

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

Defines a derived person property with the following parameters:

define_edge_type

Define a new edge type for use with network.

define_global_property

Defines a global property with the following parameters:

define_multi_property

define_person_property

Defines a person property with the following parameters:

define_person_property_with_default

Defines a person property with the following parameters:

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 .get_rng.

error

Logs a message at the error level.

impl_make_canonical

info

Logs a message at the info level.

sorted_tag

sorted_value_type

trace

Logs a message at the trace level.

warn

Logs a message at the warn level.

Enums

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

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.