simulation

simulation

The simulation module (std::core::simulation) provides domain-agnostic simulation primitives for event-driven state machines over time series. Finance, IoT, and physics modules build on these primitives.

Import

from std::core::simulation use {
    signal_mode_config, full_mode_config, state_only_config,
    get_results, get_final_state, get_processed_count, replay
}

Core Concept

simulate() is a method on data tables that runs a state machine over each row. The handler function receives (row, state, index) and returns either:

• The new state directly (no result collected)
• { state: newState, result: value } to collect a result

let result = prices.simulate(
    |row, state, idx| {
        if row.close > state.threshold {
            { state: { ...state, position: 1 }, result: "buy" }
        } else {
            state
        }
    },
    { initial_state: { position: 0, threshold: 100.0 } }
)

Types

SimulationConfig

Field	Type	Description
initial_state	object	Starting state for the state machine
mode	string	"full" for row access, "signal" for numeric values
collect_results	bool	Whether to accumulate results
collect_event_log	bool	Whether to collect event log for replay

SimulationResult

Field	Type	Description
final_state	object	State after processing all rows
results	array	Collected results from handler
elements_processed	int	Number of rows processed

Configuration Helpers

• signal_mode_config(initial_state?) — Config optimized for pre-computed SIMD signals.
• full_mode_config(initial_state?) — Config with full row access.
• state_only_config(initial_state?) — Config that skips result collection (saves memory).

Result Utilities

• get_results(sim_result) — Extract the collected results array.
• get_final_state(sim_result) — Extract the final state.
• get_processed_count(sim_result) — Get count of processed elements.

Multi-Table Simulation

simulate_correlated() runs a state machine over multiple aligned series. The handler receives (context, state, index) where context maps series names to current values.

let result = simulate_correlated(
    { spy: spy_prices, vix: vix_prices },
    |ctx, state, idx| {
        let spread = ctx.spy - ctx.vix * 10
        if spread > 50 && state.position == 0 {
            { state: { position: 1 }, result: "enter_long" }
        } else {
            state
        }
    },
    { initial_state: { position: 0 } }
)

All series must have the same length (aligned timestamps).

Replay

replay(table, handler, config)

Re-run a simulation with event log collection enabled, useful for debugging simulation behavior deterministically.

let debug_result = replay(prices, my_handler, my_config)
// debug_result includes event_log array

See Also

• Finance — financial backtesting built on simulation
• IoT — device monitoring built on simulation