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

• logging: enables structured logging for native and wasm targets.
• progress_bar: enables the timeline progress bar for long-running simulations.
• profiling: enables collection and reporting of execution profiling statistics.

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

• -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

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.

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

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.

with

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

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.