Active-learning-driven adaptive experimentation in psychophysics

Installation | Documentation | Examples | Contributing

Overview

psyphy is an open-source, JAX-based package for psychophysics research. It fits Bayesian models of perceptual discrimination, currently the Wishart Process Psychophysical Model (WPPM), on CPU or GPU. A fit gives either a single maximum a posteriori (MAP) estimate or samples from the full posterior with the No-U-Turn Sampler (NUTS). The aim is to use that posterior to choose the next trial in an adaptive experiment.

The examples so far are on human color perception, but the model applies to any stimulus space where discrimination noise varies smoothly.

The package is under active development, and we welcome contributions.

Install

psyphy supports Python 3.10 and later. We recommend installing psyphy under a virtual environment. Once you've created a virtual environment for psyphy and activated it, you can install psyphy using pip:

pip install psyphy

If you're a developer or want the latest features, install from GitHub:

git clone https://github.com/flatironinstitute/psyphy.git
cd psyphy
pip install -e .

Contributors can also use uv, which installs from the committed uv.lock for a reproducible environment instead of resolving the loose ranges above fresh each time; see CONTRIBUTING.md for the uv-based workflow.

GPU support

The commands above install a CPU-only jax. For an NVIDIA/CUDA GPU (including the Flatiron cluster), install the cuda extra instead:

pip install "psyphy[cuda]"     # from PyPI
pip install -e ".[cuda]"       # from a clone

This pulls in JAX's own cuda12 extra, which bundles a matching CUDA/cuDNN runtime as pip packages — no system CUDA module needs to be loaded alongside it.

Apple Silicon (M-series) GPUs are not supported. JAX's Metal backend cannot do float64, which some psyphy examples require for published-precision comparisons (Apple/Google's own jax-metal package is also no longer maintained). On a Mac, psyphy runs on CPU.

Quickstart

• Go here for a light-weight tutorial that demonstrates how to instantiate, evaluate and fit a model quickly. You should be able to run the underlying script on your CPU.
• Go here for a more comprehensive example visualizing a spatially varying covariance field, also explaining the underlying math. The underlying script for this tutorial requires a GPU.

Contributing

For contributors, see CONTRIBUTING.md for full doc guidelines and NumPy-style docstrings.