SSMS: Sequential Sampling Model Simulators

ssm-simulators provides fast C/Cython simulators for sequential sampling models used in cognitive science, neuroscience, and amortized Bayesian inference, spanning classic DDM variants, multi-choice models, attention models, and reinforcement-learning SSMs.

Installation

pip install ssm-simulators

Install the optional JAX backend for differentiable RLSSM learning processes:

pip install "ssm-simulators[jax]"

Users who need multi-threaded simulation should install OpenMP and GSL first:

# macOS
brew install libomp gsl

# Ubuntu/Debian
sudo apt-get install build-essential libgsl-dev

Quick Start

Classic SSM

from ssms.basic_simulators import Simulator

sim = Simulator("ddm")
out = sim.simulate(
    theta={"v": 1.0, "a": 1.5, "z": 0.5, "t": 0.2},
    n_samples=1000,
)

print(out["rts"].shape, out["choices"].shape)

RLSSM

import ssms.rl as rl

config = rl.preset.get("2AB_RW_InvTempSoftmax")
sim = rl.Simulator(config)

data = sim.simulate(
    theta={"rl_alpha": 0.2, "beta": 2.0},
    n_trials=200,
    n_participants=20,
    random_state=42,
)

response_only = data.drop(columns=["rt"])
config.validate_data(response_only).raise_for_errors()

Choice-only simulations emit rt=-1.0 only as a compatibility placeholder in generative output. Use response-only data for HSSM handoff and choice-only PPC.

Next Steps

• Learn the basic simulator API in the basic tutorial.
• Understand the package surface in Simulator and data-generation capabilities.
• Configure a registered model with Configure models and data generation.
• Generate LAN training data with the data generator tutorial.
• Build and simulate RLSSMs with the RLSSM tutorial.
• Learn response-only RL simulation in the choice-only RL tutorial.
• Understand native fixed-width outputs in Why structured observations exist.
• Use the API reference when integrating ssms into another package.

What ssms provides

Area	Documentation path
Direct SSM simulation	Basic tutorial, basic simulator API
Model configuration	Configuration guide, config API
Training data generation	Data-generator guide, MLflow tracking, dataset generator API
Likelihood estimation	KDE guide, PyDDM comparison, support-utils API
RLSSM simulation	RLSSM tutorial, RLSSM API
Choice-only RL models	Choice-only RL tutorial, RLSSM API
Structured observation results	Why structured observations exist, normalize legacy results, result contract
New model contributions	Contribute new models, parameter adapters

Model families

ssms covers a broad simulator surface:

• Diffusion models: DDM, full DDM, deadline variants, angle and Weibull boundaries, Levy, Ornstein-Uhlenbeck, gamma-drift, conflict, tradeoff, and shrink-spotlight variants.
• Multi-choice accumulators: race, racing diffusion, LBA, LBA4, LCA, and Poisson race models.
• Attention and fixation-conditioned models: aDDM simulators with observed or self-sampled fixation inputs, continuation strategies, and optional trajectory metadata.
• Reinforcement-learning SSMs: Rescorla-Wagner learning rules, RT + choice models, inverse-temperature softmax choice-only models, and posterior predictive functions for response-only RL workflows.

RL preset support

ssms includes inverse-temperature softmax decision processes for two-, three-, and four-choice settings, plus RT + choice race models. Built-in RL presets include Rescorla-Wagner DDM/angle/Weibull models, dual-alpha variants, choice-only inverse-temperature softmax bandits such as 2AB_RW_InvTempSoftmax, 3AB_RW_InvTempSoftmax, and 4AB_RW_InvTempSoftmax, and the four-choice RT + choice race preset 4AB_RW_RaceNoBiasAngle.

Ecosystem fit

ssm-simulators is the simulator and data-generation layer of the HSSM ecosystem: it defines the models, simulates from them, and produces the training data that likelihood networks are fitted to.

For the full map — what each package owns, how artifacts flow between them, and which versions work together — see The HSSM ecosystem.