Skip to content

SSMS: Sequential Sampling Model Simulators

DOI PyPI Downloads GitHub pull requests Python Version Run tests Ruff License: MIT codecov

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.

What ssms Provides

Area Documentation path
Direct SSM simulation Basic tutorial, basic simulator API
Model configuration Configuration systems, config API
Training data generation Data generators, dataset generator API
RLSSM simulation RLSSM tutorial, RLSSM API
Choice-only RL models Choice-only RL tutorial, RLSSM API
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.

Package Role
HSSM Consumes simulator-defined model contracts for Bayesian inference, including ssms-defined RLSSMs.
LANfactory Trains likelihood approximation networks from ssms-generated data.
LAN_pipeline_minimal Runs data-generation and LAN-training pipelines.

For RLSSMs, ssms owns the learning rule, task environment, response mapping, simulation loop, and posterior predictive behavior. HSSM consumes the assembled ssms model through hssm.rl.RLSSMConfig.from_ssms_model(...).

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.

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

Next Steps