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 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::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 entity::ContextEntitiesExt;

pub use entity::EntityPropertyTuple;

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

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

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.

macros

network

A module for modeling contact networks.

numeric

Vendored from [email protected] (prec.rs), convenience wrappers around methods from the approx crate. Provides utility functions for working with floating point precision.

plan

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

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:

progress

Provides functions to set up and update a progress bar.

random

report

runner

Macros

__define_data_plugin

Helper for define_data_plugin

all

Creates a query matching all entities of a given type, optionally filtered by properties.

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_make_canonical

impl_people_make_canonical

impl_property

Implements the Property trait for the given property type and entity.

info

Logs a message at the info level.

reorder_closure

sorted_tag

sorted_value_type

trace

Logs a message at the trace level.

unreorder_closure

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.