Installation#

TMol supports Python 3.11 and newer. It depends on PyTorch and ships custom C++/CUDA extensions for scoring, packing, kinematics, and minimization kernels.

  • Choose a path: Use a release wheel for the shortest supported install, or build from source when developing TMol or targeting an unavailable platform combination.

  • Next step: Run the Quickstart, then choose an interactive example or a concise workflow.

  • Development setup: See Development.

Pre-built Wheels#

Pre-built wheels include ahead-of-time compiled extensions, so installing a wheel does not require nvcc.

TMol uses two distribution channels:

  • PyPI provides source distributions for pip install tmol.

  • GitHub Releases provide pre-built CPU and GPU wheels.

The most deterministic install path is an explicit wheel URL from the GitHub Releases page:

pip install "tmol @ https://github.com/uw-ipd/tmol/releases/download/vX.Y.Z/tmol-X.Y.Z+cu132torch2.14-cp313-cp313-manylinux_2_28_x86_64.whl"

Install the matching PyTorch build first:

pip install "torch==2.14.*" --index-url https://download.pytorch.org/whl/cu132

Wheel tags select Python, PyTorch, and CUDA compatibility. For example, cp313 selects Python 3.13 and +cu132torch2.14 selects the CUDA/PyTorch lane. CPU wheels are also PyTorch-minor-specific: +cputorch2.14 selects the CPU extension built against PyTorch 2.14. PyTorch 2.13 wheels remain available as the corresponding torch2.13 lanes. TMol wheels do not replace the host C++ runtime.

Release builds provide CPU wheels for Linux x86-64, Linux aarch64, and Apple Silicon. For example, after installing PyTorch 2.14, an Apple Silicon wheel is:

pip install "tmol @ https://github.com/uw-ipd/tmol/releases/download/vX.Y.Z/tmol-X.Y.Z+cputorch2.14-cp313-cp313-macosx_14_0_arm64.whl"

PyPI Source Distribution#

The simple install is:

pip install tmol

During a PyPI source-distribution build, TMol tries to fetch a matching pre-built wheel from GitHub Releases. If no compatible wheel exists, it builds locally.

Useful environment variables:

  • TMOL_DISABLE_WHEEL_FETCH=1: skip the pre-built lookup and build locally.

  • TMOL_FORCE_BUILD=1: force the local build path.

  • TMOL_ENABLE_LOCAL_FETCH=1: allow wheel fetch from a git checkout install.

  • TMOL_WHEEL_LOCAL_TAG=cu132torch2.14: pin the wheel lane.

  • TMOL_WHEEL_RELEASE_TAG=vX.Y.Z: override the GitHub release tag.

  • TMOL_WHEEL_RELEASE_BASE_URL=...: use a release mirror.

  • TMOL_WHEEL_FETCH_RETRIES=2: set HTTP retry attempts.

  • TMOL_WHEEL_FETCH_TIMEOUT_S=20: set per-request timeout.

  • TMOL_WHEEL_FETCH_BACKOFF_S=1.5: set retry backoff.

From Source#

git clone https://github.com/uw-ipd/tmol.git
cd tmol
pip install -e ".[dev]"

This builds C++/CUDA extensions through CMake. To request a CPU-only build (the normal source build on Apple Silicon), use:

pip install -e . -Ccmake.define.TMOL_ENABLE_CUDA=OFF

CMake also falls back to CPU-only when it cannot find a CUDA compiler. This path needs CMake and a compatible C++ compiler, but no nvcc. Alternatively, CPU kernels can be compiled on first use:

TMOL_USE_JIT=1 python -c "import tmol; print(tmol.__version__)"

CPU-only JIT needs a C++ compiler and ninja; nvcc is required only for CUDA kernels.

CPU source builds and release wheels are tested on Linux x86-64, Linux aarch64, and Apple Silicon. Native Windows is not currently supported; use a Linux environment such as WSL2.

Linux Runtime Notes#

Linux release wheels use manylinux_2_28 platform tags on x86_64 and aarch64. They require glibc 2.28 or newer. Apple Silicon wheels use macosx_14_0_arm64, matching the PyTorch 2.13 and 2.14 deployment target. PyTorch supplies the matching shared libraries; TMol wheels do not bundle the PyTorch or NVIDIA runtime libraries.

If import tmol fails with a GLIBCXX_* not found error, the host libstdc++ is too old for the wheel. Use one of these paths:

# Build against system libraries
TMOL_DISABLE_WHEEL_FETCH=1 pip install -e .

# Or allow just-in-time extension compilation (CPU-only needs no nvcc)
export TMOL_JIT_FALLBACK=1

Other fixes include loading a newer GCC module, installing conda-forge::libstdcxx-ng and setting LD_LIBRARY_PATH, or running in a recent container image.

Check the active Python, PyTorch, and CUDA environment with:

python -c "import sys, torch; print(f'Python {sys.version_info.major}.{sys.version_info.minor}, Torch {torch.__version__}, CUDA {torch.version.cuda}')"

Google Colab#

Colab GPU runtimes currently use PyTorch 2.11.0 with CUDA 12.8 and may provide Python 3.12 or 3.13. TMol v0.1.54 provides separate Python-ABI wheels compiled for T4 (sm_75), A100 (sm_80), and L4 (sm_89) GPUs. For Python 3.13:

pip install "tmol @ https://github.com/uw-ipd/tmol/releases/download/v0.1.54/tmol-0.1.54+cu128torch2.11-cp313-cp313-manylinux_2_28_x86_64.whl"

The tutorial bootstrap selects the wheel matching the runtime’s Python ABI and constrains pip to keep Colab’s active PyTorch. It stops with a clear compatibility error instead of attempting a long source build when Python, PyTorch, or CUDA do not match. Always confirm the active versions before installing an ABI-specific wheel URL.