Installation

quantem.widget is currently published on TestPyPI (pre-release). Install it from there, with PyPI as the extra index so its dependencies (numpy, torch, …) resolve normally:

pip install -i https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    quantem.widget

That works on every backend; the widget picks the fastest path it finds at runtime. Requires Python 3.11 or newer.

To upload or download shared datasets through the Hugging Face helpers (quantem.widget.io.upload / download — see Load and I/O), add the [hub] extra, which pulls in quantem.data:

pip install -i https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    "quantem.widget[hub]"

Widget tutorial fixtures live under widget-tutorials/ on bobleesj/quantem-data. Upload and download commands are on that dataset card.

Google Colab

Each tutorial notebook can open directly in Colab from the badge at the top of the notebook. Colab uses the same files that build these docs, so there is no separate Colab copy to maintain.

Each Colab-ready tutorial has one collapsed Install QuantEM cell. Its two plain steps download and run the shared scripts/install_colab.py installer, which resolves only the newest quantem.widget and quantem.gpu wheel URLs from TestPyPI. Normal dependencies still come from PyPI, and Colab’s loaded NumPy and Numba versions are preserved. After installation, the cell calls quantem.widget.profile() automatically so the notebook records the installed QuantEM versions and active compute environment. Do not use TestPyPI as Colab’s package index or upgrade NumPy inside the running kernel: either can leave the process with incompatible compiled extension modules.

Show4DSTEM also selects its kernel-backed compute path in Colab because Colab’s output iframe does not expose WebGPU. When that iframe mounts, the widget asks the kernel for its first diffraction and virtual-image buffers again. The tutorial can therefore use the normal, final viewer expression without special display calls, sleeps, or state-resend code. Other notebook and exported-HTML contexts keep the browser-compute path.

Common entry points:

Tutorial	Colab	Source notebook
Example Data	Open in Colab	GitHub
Show1D	Open in Colab	GitHub
Show2D	Open in Colab	GitHub
Show3D	Open in Colab	GitHub
Show3DSlices	Open in Colab	GitHub
Show4DSTEM	Open in Colab	GitHub
ShowDiffraction	Open in Colab	GitHub
Choose Lattice	Open in Colab	GitHub
ShowFolder	Open in Colab	GitHub
IO/GPU	Open in Colab	GitHub
HTML and file export	Open in Colab	GitHub

Backends

• NVIDIA CUDA - the universal Torch viewer runs on GPU. The integer-reduction detector path uses CuPy. We do not pin a CuPy wheel (a fixed cuda12x/cuda13x would collide with one your environment already ships); a real CUDA workflow already has the matching CuPy installed.

• Apple Silicon (Metal / MPS) - a dedicated raw-Metal viewer powers Show4DSTEM on the MacBook, with full-resolution CBED and a fast virtual-image path. The tiny pyobjc-framework-Metal wheel installs automatically on macOS.

• CPU - everything still runs, just slower. This is the path used to build these docs.

Verify

import quantem.widget as qw

qw.profile()