psyphy 0.0.5

Active-learning-driven adaptive experimentation in psychophysics

Installation | Documentation | Examples | Contributing

Overview

psyphy is an open-source, JAX-based framework for psychophysics research. It leverages GPU acceleration and efficient approximate inference to power Bayesian, active-learning-driven adaptive experiments.

Designed to be modular and extensible, psyphy accelerates research workflows and enables real-time adaptive experiments. While currently focused on human color perception, it can be adapted to other perceptual modalities.

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

Install

psyphy only supports python 3.10+. 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 developer or want to use the latest features, you can install from GitHub using:

git clone https://flatironinstitute.github.io/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.