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.

Crystal and volume demos

Follow the interactive demo route for ShowCIF, PlanPtycho, Show3D, and Show3DSlices. Crystal inspection and planning require ASE, abTEM, and spglib through the crystal extra:

python -m pip install -i https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ 'quantem.widget[crystal]'

Check that the installed build includes the API you want to demonstrate; the new ShowCIF notebook requires a revision containing ShowCIF. For an unpublished source revision, use the developer setup and install '.[crystal]', then build the JavaScript with npm run build. Use the same Python environment for installation and the notebook kernel.

Google Colab

Tutorials with a Colab badge can open directly in Colab. The new crystal demo can also be run from a local source checkout as described above. 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
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) - quantem.gpu.io.load keeps 4D-STEM acquisitions encoded on the Apple GPU, and Show4DSTEM opens them with the same viewer as on CUDA, at full detector resolution. 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()