Installation#

This section provides instructions on how to install pytme. We recommend creating an installation enviroment for a clean and isolated setup. Available options for different use cases are outlined in the tabs below.

Conda

Best for cross-platform compatibility and managing complex dependencies.

conda create \
   --name pytme \
   -c conda-forge \
   python=3.11 \
   pyfftw \
   pyqt

   napari \
   magicgui \

Venv

Python’s built-in option, suitable for simpler setups.

python3 -m venv pytme
source pytme/bin/activate

Docker

Docker is a good choice for deployment scenarios and provides the highest degree of reproducibility across different systems..

To build the Docker image

docker build -t pytme -f docker/Dockerfile_GPU .

Alternatively, you can pull the latest version from Docker Hub

docker pull dquz/pytme:latest

Tip

When using Docker, pytme will already be installed in the container. Latest corresponds to the current version of the main branch. You can also use a release version by specifiying the corresponding tag.

After setting up your environment, pytme can be installed from PyPi

pip install pytme

Alternatively, you can install the development version with the latest changes

pip install git+https://github.com/KosinskiLab/pyTME.git

CPU/GPU/TPU Support#

pytme’s backend agnostic design enables the same code to be run on practically any hardware platform using a best-of-breed approach. To enable pytme to utilize compute devices other than CPUs, install one of the libraries below. pytme defaults to CuPy for GPU applications, but expert users can decide freely between their desired backend.

CuPy (Recommended)

The following will install the CuPy dependencies of pytme

pip install "pytme[cupy]"

Alternatively, you can install CuPy directly

pip install cupy-cuda12x

If your CUDA version is lower than 12 or you encounter any issues, please refer to CuPy’s official installation guide for a version tailored to your system and detailed instructions.

PyTorch

The following will install the PyTorch dependencies of pytme

pip install "pytme[torch]"

Alternatively, you can install PyTorch directly

pip install torch torchvision

PyTorch’s installation might vary based on your system and the specific GPU in use. Consult the official PyTorch website for detailed installation options tailored for your environment.

JAX

The following will install the JAX dependencies of pytme

pip install "pytme[jax]"

Alternatively, you can install JAX directly

pip install "jax[cuda12]"

Setting up JAX might require additional attention on certain platforms. Consult the JAX documentation for tailored options.

MLX

The following will install the MLX dependencies of pytme

pip install mlx

The MLX library is only available for Apple silicone chips.

GUI Setup#

If you would like to perform interactive preprocessing and analysis of your data, you need to install the following dependencies

pip install "napari==0.4.19.post1" magicgui git+https://github.com/maurerv/napari-density-io.git

Troubleshooting#

The following presents known issues encountered during installation and outlines solutions to them.

pyFFTW#

The installation of pyFFTW via pip has been troublesome in the past. Consider using Conda for a smoother experience. Alternatively, pyFFTW can be installed from source. To compile it on my M1 MacBook running homebrew, I had to modify pyFFTW’s setup.py variable self.library_dirs to include the homebrew paths in the EnvironmentSniffer class’s __init__ method as follows

self.library_dirs = get_library_dirs()
self.library_dirs.extend(["/opt/homebrew/lib", "/opt/homebrew/opt/fftw/lib"]) # Patch

CuPy#

GPU backends often require a correct setup of CUDA libraries. CuPy expects the corresponding libraries to be in a set of standard locations and will raise Runtime/Import errors should that not be the case. Possible errors include RuntimeError: CuPy failed to load libnvrtc.so, ImportError: libcudart.so: cannot open shared object file and cupy.cuda.compiler.CompileException.

Solving this issue typically requires setting as set of environment variables and is outlined in the cupy installation faq.

Testing#

The code of pytme is automatically tested before release. Should you run into issues that are not outlined above, you can optionally verify your local installation via the provided test suite as follows

git clone https://github.com/KosinskiLab/pyTME.git
cd pyTME
ulimit -n 4096
pytest

If the tests pass without any errors, pytme has been successfully installed.

Note

Running the code above may fail when using Conda or Venv. A possible solution is to install pytme in editable mode

pip uninstall pytme
pip install -e .
python3 -m pytest tests/

Support#

For issues, questions, or contributions, please open an issue or pull request in the pytme repository.