SSMS: Sequential Sampling Model Simulators

PyPI

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.

At a Glance

Need	Use ssms for
Simulate behavior	Generate response-time and choice data from a broad SSM library.
Train likelihood networks	Produce LAN/LANfactory-style training data with configurable simulators and KDE estimators.
Prototype models	Combine registered model configs, custom drift/boundary functions, parameter transforms, and Cython extensions.
Work with RLSSMs	Simulate trial-wise learning models, response-only choice models, and posterior predictive functions for RL workflows.

Core links:

Documentation: https://lnccbrown.github.io/ssm-simulators/
API reference: https://lnccbrown.github.io/ssm-simulators/api/ssms/
RLSSM API: https://lnccbrown.github.io/ssm-simulators/api/rlssm/
Issues and feature requests: https://github.com/lnccbrown/ssm-simulators/issues

Model Coverage

Family	Examples
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 models	aDDM with observed or self-sampled fixations, continuation strategies, and optional trajectory metadata.
Reinforcement-learning SSMs	Rescorla-Wagner learning rules, RT + choice RLSSMs, inverse-temperature softmax choice-only models, and response-only posterior predictive workflows.

Choice-only RL support includes inverse-temperature softmax decision processes for two-, three-, and four-choice settings. Built-in RL presets currently cover two- and three-armed Rescorla-Wagner bandits: 2AB_RW_InvTempSoftmax and 3AB_RW_InvTempSoftmax.

Where ssms Fits

ssm-simulators is the simulator and data-generation layer of the HSSM ecosystem.

Package	Relationship
HSSM	Builds Bayesian inference workflows around simulator-defined model configurations, including ssms-defined RLSSMs.
LANfactory	Trains likelihood approximation networks from ssms-generated simulation data.
LAN_pipeline_minimal	Orchestrates simulation and LAN training pipelines.

The RLSSM path is ssms-first: ssms owns the learning rule, task environment, response mapping, and simulator/PPC behavior; HSSM consumes the assembled model contract through hssm.rl.RLSSMConfig.from_ssms_model(...) for inference.

Installation

pip install ssm-simulators

Install the optional JAX backend for differentiable RLSSM learning processes:

pip install "ssm-simulators[jax]"

[!NOTE] Multi-threaded simulation with n_threads > 1 requires OpenMP and GSL. Install system dependencies first:
# macOS
brew install libomp gsl

# Ubuntu/Debian
sudo apt-get install build-essential libgsl-dev
Then reinstall with pip install --force-reinstall ssm-simulators. Without these dependencies, the package still works in single-threaded mode.

Building from source or developing this package requires a C compiler. Most users installing from PyPI wheels do not need to install GCC manually.

Quick Starts

Classic SSM Simulation

The Simulator class is the recommended user-facing API for direct simulation:

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 Simulation

RLSSMs combine a trial-wise learning process, a task environment, and an SSM or choice-only decision process:

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()

For choice-only models, the simulator keeps rt=-1.0 only as a compatibility placeholder in generative output. HSSM inference and ssms PPC use response-only data.

Tutorials

Start here:

Training Data CLI

The package exposes generate for creating training data from a YAML configuration file:

generate [--config-path <path/to/config.yaml>] --output <output/directory> [--log-level INFO]

Common options:

Option	Meaning
`--config-path`	YAML configuration path. Uses the default config if omitted.
`--output`	Output directory for generated data.
`--n-files`	Number of data files to generate.
`--estimator-type`	Likelihood estimator override, such as `kde` or `pyddm`.
`--log-level`	Logging level.

Minimal YAML example:

MODEL: "ddm"
GENERATOR_APPROACH: "lan"

PIPELINE:
  N_PARAMETER_SETS: 100
  N_SUBRUNS: 20

SIMULATOR:
  N_SAMPLES: 2000
  DELTA_T: 0.001

TRAINING:
  N_SAMPLES_PER_PARAM: 200

ESTIMATOR:
  TYPE: "kde"

Parallel Execution

When using n_threads > 1, ssms uses GSL's validated Ziggurat algorithm for Gaussian random number generation. The maximum supported number of threads is 256.

from ssms.basic_simulators import Simulator

theta = {"v": 1.0, "a": 1.5, "z": 0.5, "t": 0.2}

sim = Simulator("ddm")
single_thread = sim.simulate(theta=theta, n_samples=10000, n_threads=1)
multi_thread = sim.simulate(theta=theta, n_samples=10000, n_threads=8)

Check your installation's parallel capabilities:

from cssm._openmp_status import print_status

print_status()

Development

This project uses uv for dependency management:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --all-groups

Rebuild Cython extensions after source changes:

uv pip install --python .venv/bin/python -e . --reinstall

Run the main local checks:

uv run pytest tests/
uv run ruff check .
uv run ruff format --check .
uv run --extra docs mkdocs build

Contributing

Contributions are welcome, including new models, documentation improvements, bug fixes, and simulator validation work.

Add a model: https://lnccbrown.github.io/ssm-simulators/contributing/add_models/
Add a parameter adapter: https://lnccbrown.github.io/ssm-simulators/contributing/add_parameter_adapters/
Open an issue: https://github.com/lnccbrown/ssm-simulators/issues
Open a pull request: https://github.com/lnccbrown/ssm-simulators/pulls

Citation

Please cite ssm-simulators with the Zenodo DOI: https://doi.org/10.5281/zenodo.17156205.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ssm_simulators-0.13.0.tar.gz (2.7 MB view details)

Uploaded Jul 10, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ssm_simulators-0.13.0-cp314-cp314-win_amd64.whl (4.1 MB view details)

Uploaded Jul 10, 2026 CPython 3.14Windows x86-64

ssm_simulators-0.13.0-cp314-cp314-musllinux_1_2_x86_64.whl (12.8 MB view details)

Uploaded Jul 10, 2026 CPython 3.14musllinux: musl 1.2+ x86-64

ssm_simulators-0.13.0-cp314-cp314-musllinux_1_2_aarch64.whl (12.3 MB view details)

Uploaded Jul 10, 2026 CPython 3.14musllinux: musl 1.2+ ARM64

ssm_simulators-0.13.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (12.8 MB view details)

Uploaded Jul 10, 2026 CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

ssm_simulators-0.13.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (12.4 MB view details)

Uploaded Jul 10, 2026 CPython 3.14manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

ssm_simulators-0.13.0-cp314-cp314-macosx_11_0_arm64.whl (4.1 MB view details)

Uploaded Jul 10, 2026 CPython 3.14macOS 11.0+ ARM64

ssm_simulators-0.13.0-cp314-cp314-macosx_10_15_x86_64.whl (4.2 MB view details)

Uploaded Jul 10, 2026 CPython 3.14macOS 10.15+ x86-64

ssm_simulators-0.13.0-cp313-cp313-win_amd64.whl (4.0 MB view details)

Uploaded Jul 10, 2026 CPython 3.13Windows x86-64

ssm_simulators-0.13.0-cp313-cp313-musllinux_1_2_x86_64.whl (12.9 MB view details)

Uploaded Jul 10, 2026 CPython 3.13musllinux: musl 1.2+ x86-64

ssm_simulators-0.13.0-cp313-cp313-musllinux_1_2_aarch64.whl (12.3 MB view details)

Uploaded Jul 10, 2026 CPython 3.13musllinux: musl 1.2+ ARM64

ssm_simulators-0.13.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (12.9 MB view details)

Uploaded Jul 10, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

ssm_simulators-0.13.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (12.4 MB view details)

Uploaded Jul 10, 2026 CPython 3.13manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

ssm_simulators-0.13.0-cp313-cp313-macosx_11_0_arm64.whl (4.1 MB view details)

Uploaded Jul 10, 2026 CPython 3.13macOS 11.0+ ARM64

ssm_simulators-0.13.0-cp313-cp313-macosx_10_13_x86_64.whl (4.1 MB view details)

Uploaded Jul 10, 2026 CPython 3.13macOS 10.13+ x86-64

ssm_simulators-0.13.0-cp312-cp312-win_amd64.whl (4.0 MB view details)

Uploaded Jul 10, 2026 CPython 3.12Windows x86-64

ssm_simulators-0.13.0-cp312-cp312-musllinux_1_2_x86_64.whl (12.9 MB view details)

Uploaded Jul 10, 2026 CPython 3.12musllinux: musl 1.2+ x86-64

ssm_simulators-0.13.0-cp312-cp312-musllinux_1_2_aarch64.whl (12.4 MB view details)

Uploaded Jul 10, 2026 CPython 3.12musllinux: musl 1.2+ ARM64

ssm_simulators-0.13.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (12.9 MB view details)

Uploaded Jul 10, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

ssm_simulators-0.13.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (12.5 MB view details)

Uploaded Jul 10, 2026 CPython 3.12manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

ssm_simulators-0.13.0-cp312-cp312-macosx_11_0_arm64.whl (4.1 MB view details)

Uploaded Jul 10, 2026 CPython 3.12macOS 11.0+ ARM64

ssm_simulators-0.13.0-cp312-cp312-macosx_10_13_x86_64.whl (4.2 MB view details)

Uploaded Jul 10, 2026 CPython 3.12macOS 10.13+ x86-64

File details

Details for the file ssm_simulators-0.13.0.tar.gz.

File metadata

Download URL: ssm_simulators-0.13.0.tar.gz
Upload date: Jul 10, 2026
Size: 2.7 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for ssm_simulators-0.13.0.tar.gz
Algorithm	Hash digest
SHA256	`b05d706b9b365c26d26a749d64f50b24da52157f7d6ef1f1387f3ef411804123`
MD5	`c44b7d54f62c5e2296838158078c66f0`
BLAKE2b-256	`6343548b2c79fdc9db90bffe3658fe788cc120bd5ad69f8ca6dfb7b7baa8fe3c`

Algorithm	Hash digest
SHA256	`9086fe5c9ae4c279c9ac0e3dc5629bbd2546594390a72f88779b965ef5a4523d`
MD5	`7aa13a82806bbadfb41857a87ae457a9`
BLAKE2b-256	`f9e7fe07115085d82e6887f72889759cfc93850d1715e33944a70f8431048c70`

Algorithm	Hash digest
SHA256	`e05754f20cbcc237b741e41c36ed505628b514b66465ea5d6a4ed72739d233c5`
MD5	`a07027f14a2c7710922fc7e24ffd43ee`
BLAKE2b-256	`eac80c3c8e1d9a1054fde9dc048bf61d276bbe977305b9c2b64f912c938722dd`

Algorithm	Hash digest
SHA256	`0d2f330770be922ccc0b5b26504d9fdc958a9d5b9157c702377c08bfb209ea3b`
MD5	`5139e8fb8e340118b82d4e25a1f85e4d`
BLAKE2b-256	`e55570a1326fd9ff28743e31348084a11c9517f147146982934a024da043279e`

Algorithm	Hash digest
SHA256	`c1e52f4889435710127532954f8c1fb72e5d0ddd8028b07bc6835e171d3893ac`
MD5	`87aa6fd25c25e1717f25c4afb677abbc`
BLAKE2b-256	`580eda2b5a9582928a9e063c5635a36dba2385a96149863b6eaf74e81943188d`

Algorithm	Hash digest
SHA256	`f7fed607d865265e91acd09369ba049011c642d19429b1e0c851a798f0d39b12`
MD5	`00d72ecf58b9c2245058c627c0393d79`
BLAKE2b-256	`9a8ad77129500d8cf8876792302096c403af64839f745b9a2038b11be2b1256d`

Algorithm	Hash digest
SHA256	`a033090549b6939f165bd8d837f4923abfcc6326e69cfd2b22dd47c9c486d7bf`
MD5	`59811c64c483346527ae998ee60252a1`
BLAKE2b-256	`e1f75139c1d4b55d97d891d3893a26ef0e79504a1a7364222ecdcd732731e5f8`

Algorithm	Hash digest
SHA256	`15935b2e534238e2d0275e9fd65d1bf32c95f4fbac7870dd01ea9454472e7bcd`
MD5	`5fb49716f0ffa0a1a3db4303b90f1337`
BLAKE2b-256	`d45811150f825b36305841355bd1af760b8fa4db94b51b776bccf89763a60685`

Algorithm	Hash digest
SHA256	`f9b2d991e87212f16cf478ef3539f25920efb933cfea9030dc1d07469d2d8a84`
MD5	`7ad7b5754d7f75ad28bb17b9444ee1c8`
BLAKE2b-256	`496c3509e16b4fdea17fe1975ef57df2530b7b0fa971270563f11b0b1e46118f`

Algorithm	Hash digest
SHA256	`3239f1c981a8eae834e369a5f5ae35d0d1c5058bf85d120a2b157b98b8466735`
MD5	`17c7279771db4097417c8dbb8b65ed08`
BLAKE2b-256	`987b9d4901f92b5763046ec271312bdec8b2326d09db441d6dcd5d4846dddcb5`

Algorithm	Hash digest
SHA256	`c5c65f87ddf734495f25aa4626dd31ca798eea016d4b95d012cb9f2ad73a4919`
MD5	`250065267401e05371b709f211e294b2`
BLAKE2b-256	`420727a5a163e02d016a89368a71de8d1c7fe3bb002dd375e71149163cd2ee80`

Algorithm	Hash digest
SHA256	`8e9d70b9772a5d72bb5067dac58764ee752a348c667282e5697071d49a849fe3`
MD5	`66526f8f5a0bcd79da5769ca26b7cc59`
BLAKE2b-256	`21a1f0d85b8b7d661097448c0e8e0f81e6c625935517f3558b735d6f9defcbc1`

Algorithm	Hash digest
SHA256	`eaecbb5b7bec78aa03ba2a33a86249365ee8fe85f2e14dbe2c367ff6fcb6ddaf`
MD5	`16046b503b442c01e950b0cb1197334f`
BLAKE2b-256	`b4d8292090436cbd9801d4a6d3f4db41f39069bd387eaad5de356c339b894135`

Algorithm	Hash digest
SHA256	`be2c48415cd8cec47748517d8657ed8a84003543d3ad984c11299eec714f8a19`
MD5	`4b24809593d57a7a29ed785acb42457e`
BLAKE2b-256	`dae62ab414484e58a6b41607c2712c2befdcaeeb4a600c85fc4a26becd6fd33a`

Algorithm	Hash digest
SHA256	`48ff12e2fc08da1bb30d04f8ee010518a604fecffbf62ab188681f513f87281e`
MD5	`11885e96c5c28d586ec6f517b29fd426`
BLAKE2b-256	`3dfa11794142a721be0f74ef8530276fc56c8a21394f6cfd5b07f252f636465a`

Algorithm	Hash digest
SHA256	`fb4da2609b8ddc1797c9fca5773356a2c7025b56763b9202e269c6356745b46f`
MD5	`8a4b1ae00d4027afda12cca60372851b`
BLAKE2b-256	`65c4dd59b015e3cafe92dd4055b127ced432a2b58fb946e7ebfb27436d4906a5`

Algorithm	Hash digest
SHA256	`45ad31d14603541fac47399fa2f21af05f70035ebaf5e19eccaf91f2f146b456`
MD5	`94f91b2da2d9d6667822285f72b3c974`
BLAKE2b-256	`62f618e45f31b0444100afbe2681a080d14636b881a2004d6eb58dc88ca2f4a6`

Algorithm	Hash digest
SHA256	`72f5c4b4ebffc97302dea85f2b67ab9e10f2144e684c300004238a29c69559dc`
MD5	`1c635747af1d71344f81da7aa76f17a5`
BLAKE2b-256	`540f157df50f009bb0e7cb4e332775d3ef25b5eb1f900fe42911d2b6959d41ad`

Algorithm	Hash digest
SHA256	`d51f0ba2b95a12d9eb4b728db88e288676ff5b89d1780fca4293514e8d42d74a`
MD5	`50999e427af80d940b307657b7b9d7fe`
BLAKE2b-256	`3c377fbbac66b2e0c9d9cc4a891af59f70d5b6907aa71d385e29cd9c0c688b0b`

Algorithm	Hash digest
SHA256	`b5aad86f98fb163b4c87eb703d4be12fbda06f116431cbd43cd15233d67325c7`
MD5	`c4f85719b65dec65bff148e4b02944bb`
BLAKE2b-256	`d859ce8a0ad8a82373c206ac143df4acc4e96433c6268c3c9ad71beaf1ca4c23`

Algorithm	Hash digest
SHA256	`1ff39689aab68becb6e84a9d970c6f5b36c76e4f619e7f89bb6a2d407379c9db`
MD5	`4e5ecc94b0a1755e717a0fd8da5c045f`
BLAKE2b-256	`242e1b31ec3918b77226a099697920e81bcfb39c4e3041c0894aff1c8f8ea42c`

ssm-simulators 0.13.0

SSMS: Sequential Sampling Model Simulators

At a Glance

Model Coverage

Where ssms Fits

Installation

Quick Starts

Classic SSM Simulation

RLSSM Simulation

Tutorials

Training Data CLI

Parallel Execution

Development

Contributing

Citation

Project links

Key dates

1 maintainer

Credits

License

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

Algorithm	Hash digest
SHA256	`c15a975b464b384f60951adb91ae46ba69ace550e7f9b919da009810f9740435`
MD5	`1aabc0bf248c16b7e83a59c61ad23d53`
BLAKE2b-256	`a4da9f090d70c185444269945b7638651a256e8f2b96b35417e24497ed43869b`