Crate simvar_harness 

Deterministic simulation test harness for concurrent systems.

This crate provides a framework for running deterministic simulations of distributed systems and concurrent applications. It allows you to test complex scenarios involving multiple actors (hosts and clients) with controlled timing, randomness, and networking.

Features

• Deterministic execution - Same seed produces identical simulation results
• Host and client actors - Model persistent services (hosts) and ephemeral clients
• Simulation lifecycle hooks - Customize behavior at key points via SimBootstrap
• Built-in TUI - Optional terminal UI for monitoring simulation progress
• Parallel execution - Run multiple simulation runs concurrently
• Cancellation support - Graceful shutdown with Ctrl-C handling

Example

struct MyBootstrap;

impl SimBootstrap for MyBootstrap {
    fn build_sim(&self, config: SimConfig) -> SimConfig {
        config
    }

    fn on_start(&self, sim: &mut impl Sim) {
        // Spawn a host actor
        sim.host("server", || async {
            // Server logic here
            Ok(())
        });

        // Spawn a client actor
        sim.client("client", async {
            // Client logic here
            Ok(())
        });
    }
}

let results = run_simulation(MyBootstrap)?;

Environment Variables

• SIMULATOR_RUNS - Number of simulation runs to execute (default: 1)
• SIMULATOR_MAX_PARALLEL - Maximum parallel runs (default: number of CPUs)
• SIMULATOR_SEED - Fixed random seed for deterministic runs
• SIMULATOR_EPOCH_OFFSET - Fixed epoch offset override (when time feature is enabled)
• SIMULATOR_EPOCH_MIN / SIMULATOR_EPOCH_MAX - Bounded random epoch offset (inclusive)
• SIMULATOR_EPOCH_RANGE_PROFILE - Epoch profile (low, wide, full)
• NO_TUI - Disable terminal UI when set

Re-exports

pub use simvar_utils as utils;

pub use switchy;

Modules

client

Client actor types and utilities.

formatting

Time formatting utilities.

host

Host actor types and utilities.

plan

Interaction planning utilities.

Structs

SimConfig

Configuration for a simulation run.

SimProperties

Properties describing a simulation run.

SimRunProperties

Runtime metrics from a simulation run.

Enums

Error

Errors that can occur during simulation execution.

SimResult

Result of a simulation run.

Traits

Sim

Interface for managing simulation actors (hosts and clients).

SimBootstrap

Trait for bootstrapping and configuring simulations.

Functions

end_sim

Signals all running simulations to stop.

run_simulation

Executes one or more simulation runs using the provided bootstrap implementation.