Getting started with PyExtal

What you need

• Linux on an Intel or AMD (x86_64) computer. On Windows, use WSL (Windows Subsystem for Linux), which runs Linux inside Windows; open the “Ubuntu” terminal it installs and follow the Linux instructions below. macOS and ARM computers are not supported yet.

• Python 3.11, 3.12, 3.13 or 3.14. Check with python3 --version in a terminal. If Python is missing or older, install a newer one with your system’s package manager, conda, or uv (see Using uv or conda instead).

You do not need a compiler: PyExtal is installed as a ready-built package that already contains its compiled simulation engine.

Installation

1. Create a virtual environment

A virtual environment is a private folder of Python packages for one project. It keeps PyExtal and its dependencies separate from everything else on your computer, so installing or upgrading them cannot break other software. Create one once:

python3 -m venv ~/pyextal-env

and activate it in every new terminal before using PyExtal:

source ~/pyextal-env/bin/activate

The prompt then starts with (pyextal-env). Inside the environment, python and pip refer to the environment’s own copies. Leave it with deactivate.

2. Choose what to install

PyExtal comes in three variants. They all contain the same simulation and refinement code; the bigger ones add the JAX library, which some of the refinement tools need.

Install command	What you get	Download size	Choose it if
pip install pyextal	Bloch-wave simulation of CBED and LARBED patterns, coarse and fine refinement, LARBED extraction, symmetry and structure-factor tools. Runs on the CPU.	small	you are starting out, or follow the example notebooks
pip install "pyextal[jax]"	everything above, plus the gradient-based refinement tools (pyextal.jaxEngine, jaxGeo, jaxJoint, jaxMultipole) and their command lines (jaxgeo-refine, …). JAX runs on the CPU.	about 100 MB more	you want the JAX refinement and have no NVIDIA GPU, or just want to try it
pip install "pyextal[cuda]"	the same as [jax], but JAX runs on an NVIDIA GPU, which makes the JAX refinement much faster on large datasets	several GB more	you have an NVIDIA graphics card and use the JAX refinement

[jax] and [cuda] only change how the JAX refinement tools run. The ordinary simulation and refinement run on the CPU in every variant. You can start with pip install pyextal and add the others later by running their install command; nothing needs to be removed first.

Keep the quotes around "pyextal[jax]" and "pyextal[cuda]": some terminals (for example zsh, the default on newer systems) otherwise read the square brackets as a file pattern and report no matches found.

For [cuda] you need an NVIDIA GPU and a recent NVIDIA driver (version 525 or newer, which supports CUDA 12). You do not need to install CUDA itself: the required CUDA libraries are downloaded by pip. On WSL, install the normal NVIDIA driver in Windows (from the NVIDIA website or the GeForce/NVIDIA app) and do not install a Linux NVIDIA driver inside WSL. Check that the driver is visible with nvidia-smi.

3. Check the installation

python -c "import pyextal; print(pyextal.__version__)"

prints the installed version. With [jax] or [cuda], also check where JAX runs:

python -c "import jax; print(jax.devices())"

This prints [CpuDevice(id=0)] for [jax], and a CudaDevice entry for [cuda]. If [cuda] still shows only CpuDevice, JAX did not find the GPU; check nvidia-smi and the driver version above.

Upgrading and uninstalling

With the environment activated:

pip install --upgrade pyextal          # or --upgrade "pyextal[jax]", "pyextal[cuda]"
pip uninstall pyextal

Deleting the environment folder (rm -rf ~/pyextal-env) removes PyExtal and everything installed with it.

Jupyter notebooks

The examples are Jupyter notebooks. Install Jupyter into the same environment and start it from there, so the notebooks use this environment’s PyExtal:

pip install jupyterlab
jupyter lab

Using uv or conda instead

With uv, which also installs Python for you:

uv venv --python 3.12 ~/pyextal-env
source ~/pyextal-env/bin/activate
uv pip install pyextal                 # or "pyextal[jax]", "pyextal[cuda]"

In a uv project, uv add pyextal adds it as a dependency instead.

With conda, create an environment for the Python version and install PyExtal into it with pip (PyExtal is not on the conda channels):

conda create -n pyextal python=3.12
conda activate pyextal
pip install pyextal

Installation problems

• ERROR: No matching distribution found for pyextal: there is no ready-built package for your computer. Check that you are on Linux or WSL (not macOS or native Windows), on an x86_64 machine (uname -m prints x86_64), and that python --version is 3.11 to 3.14.

• pip: command not found, or packages install but import pyextal fails: the environment is not active. Run source ~/pyextal-env/bin/activate and try again.

• no matches found: pyextal[jax]: add the quotes, pip install "pyextal[jax]".

FAQ

1. matplotlib qt5 backend error

   qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
   This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
   
   Available platform plugins are: eglfs, minimal, minimalegl, offscreen, vnc, webgl, xcb.
   
   Aborted (core dumped)
   

   This is probably a WSL issue. You can either use another backend, e.g. tk, or try to install PyQt5 dependences with running the following command:

   sudo apt-get install '^libxcb.*-dev' libx11-xcb-dev libglu1-mesa-dev libxrender-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev
   

2. RuntimeWarning: threadpoolctl is not installed

   The simulation engine needs threadpoolctl to limit BLAS to one thread per worker. Without it the engine still runs but oversubscribes the CPU and can be several times slower. It is a dependency of pyextal, so this only happens if it was uninstalled; reinstall it with pip install threadpoolctl.