Quickstart Guide

This guide demonstrates how to instantiate a simulator from a built-in domain preset, generate multi-agent sequences, and inspect the resulting pandas DataFrame.

Your First Simulation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from behaviorsim import Simulator

# 1. Instantiate from the built-in finance preset
sim = Simulator.from_preset("finance")

# 2. Generate 50 interactions across 5 distinct sequence trajectories
df = sim.generate(
    num_interactions=50,
    num_sequences=5,
    seed=42
)

# 3. Print the first few rows
print(df.head())

Understanding the Code

• Simulator.from_preset("finance"): Constructs a pre-calibrated simulator with states (Stable, Active, Volatile, Drawdown, Recovered, Closed), transition matrices, and feature emission rules.
• sim.generate(...): Executes the simulation loop.
  • num_interactions: Number of steps per sequence (default: 100).
  • num_sequences: Number of independent agent trajectories (default: 1).
  • seed: Integer random seed for bitwise reproducibility.

Inspecting Output Traces

The returned object is a standard pandas.DataFrame containing:

Deterministic Reproducibility

Running the script above with seed=42 will always generate the exact same values on any machine, making test cases and benchmark evaluations completely reliable.