Installation#

This section provides instructions on how to install the tme library. Depending on your preferred method or system setup, you can choose between the installation with Conda, PyPI, or from source. Click on the tabs below to view the instructions for each method.

Conda

Conda provides an isolated environment, helps avoid conflicts with other packages, and installs necessary dependencies.

Create a New Conda Environment and Install Dependencies:

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

Activate the Environment:
```
conda activate pytme
```
Install from Source:

The following will download and install the newest version of tme.
```
pip install git+https://github.com/KosinskiLab/pyTME.git
```

PyPI

Pip will fetch the required packages from PyPI and install them on your system.

Prerequisite:

Ensure you have Python 3.11 or higher installed on your system:

python --version

Install from PyPI:

Once available on PyPI, the installation is a single command.
```
pip install pytme
```

Note

The Python Package Index (PyPI) provides a simple and convenient way to install tme. However, installing from Conda or source fetches the most recent version of the code base.

Source

Installing from source is ideal for developers and contributors who need access to the latest, unreleased changes and plan to modify the code. This method involves cloning the repository and setting up a local development environment.

For detailed information on contributing to the project, see our Contributor’s Guide.

Prerequisite:

Ensure you have Python 3.11 or higher and Git installed on your system:
```
python --version
git --version
```
Clone the Repository:

First, clone the tme repository and navigate into it:
```
git clone https://github.com/KosinskiLab/pyTME.git
cd pyTME
```
Set Up a Development Environment:

It’s recommended to create a virtual environment:
```
python -m venv pytme
source pytme/bin/activate
```
Install the Package in Editable Mode:

Install the library in editable mode with pip. This allows you to modify the source code and see changes immediately:
```
pip install -e .
```
This will automatically install all required dependencies for tme. Remember to navigate out of the source directory before using tme. This ensures the built extensions are properly loaded from the installed library, avoiding potential issues.

Note

The above method is suited for development purposes. If you simply want to install the latest version of the package without cloning, you can use:

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

This method installs the package directly from the repository without the need for cloning and is suitable for users who don’t plan to modify the source code.

Optional GUI Setup#

If you installed tme using Conda, you will only need to execute the following to use the preprocessing GUI:

pip install git+https://github.com/maurerv/napari-density-io.git

Otherwise, you also have to install the remaining GUI dependencies:

pip install napari magicgui PyQt5

GPU Support#

To enable GPU support in tme, install one of the following GPU-accelerated libraries: PyTorch or CuPy. While both are supported, CuPy is the recommended choice.

Check Your CUDA Version:

Use the nvidia-smi command to get information about your NVIDIA driver and GPU:

nvidia-smi

Look for the CUDA version in the output; it’s usually displayed in the top right corner. After determining your CUDA version, you can proceed to install one of the supported GPU-accelerated libraries.

CuPy (Recommended)

If you have CUDA version 12 or upwards, install CuPy using:

pip install cupy-cuda12x

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

PyTorch

Alternatively, you can use PyTorch for GPU computations:

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.

Testing the Installation#

To verify that tme has been installed correctly, you can run the test suite provided with the project as follows:

git clone https://github.com/KosinskiLab/pyTME.git
cd pyTME
pytest

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

Troubleshooting#

The installation of pyFFTW via pip has been troublesome in the past. Consider using the installation method 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

Support#

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