Transitions & Dynamics

Stationary transition probability matrices and dynamic rule evaluation.

Transitions dictate how agents migrate between states at each interaction step.

Transition Probability Matrices

A stationary transition matrix is represented as a 2D NumPy array of shape (K, K), where each row must sum to 1.0:

matrix_example.py

import numpy as np
from behaviorsim import Simulator, State, Profile, FeatureDistribution

states = [State("A", description="State A"), State("B", description="State B")]

# Transition probability matrix (rows must sum to 1.0)
# Row 0: Transitions from A -> [A (80%), B (20%)]
# Row 1: Transitions from B -> [A (10%), B (90%)]
matrix = np.array([
    [0.8, 0.2],
    [0.1, 0.9]
])

# Profile defines transitions and emitted feature distributions
profile = Profile(
    name="dynamic_agent",
    transition_matrix=matrix,
    state_emissions={
        "A": {"latency": FeatureDistribution("normal", {"loc": 100.0, "scale": 15.0})},
        "B": {"latency": FeatureDistribution("exponential", {"scale": 250.0})},
    }
)

sim = Simulator(states=states, profile=profile)
df = sim.generate(num_interactions=50, seed=42)
print(df[["interaction_id", "state", "latency"]].head())

Dynamic Transition Rules

Real behaviors are frequently non-stationary: an agent transitions only when a metric crosses a threshold. BehaviorSim supports TransitionRule objects that evaluate conditions over historical feature values.

Supported Operators & Aggregations

Comparison Operators

<, <=, >, >=, ==, !=

Historical Aggregations

last, sum, max, mean, min

PreviousBehavioral States

NextEngine Overview