ALF Installation Guide¶

Package Installation¶

Use this when you want to use ALF in your own projects. This is what most users need.

Prerequisites¶

Python 3.12 or higher

Install Packages¶

# Install the core package only (minimal dependencies, no PyTorch required)
pip install alf-core

# Install the tools package (includes PyTorch, models, and datasets)
pip install alf-tools

What each package provides:

alf_core: Core data structures, tasks, and utilities. No PyTorch required.
alf_tools: Machine learning models (CNNModel, GP, ESM-2, etc.), datasets, and acquisition functions. Requires PyTorch.

Optional Extras¶

Heavy ML dependencies (transformers, rdkit, chemprop) are not installed by default. Install only what a given model needs via per-model extras, or grab a whole workflow at once with a workflow umbrella:

Extra	Installs	For
`esm2`	`transformers`	`ESM2Model`
`esmfold`	`transformers`, `accelerate`	`ESMFoldModel`
`chemprop`	`chemprop`	`ChempropModel`
`guacamol`	`rdkit`	GuacaMol dataset/scoring
`protein`	`esm2` + `esmfold`	protein workflow
`molecule`	`chemprop` + `guacamol`	small-molecule workflow

# ESM2 — protein language model (for ESM2Model)
pip install "alf-tools[esm2]"

# Chemprop — small-molecule MPNN (for ChempropModel)
pip install "alf-tools[chemprop]"

# Whole protein workflow (esm2 + esmfold)
pip install "alf-tools[protein]"

# Several extras together
pip install "alf-tools[esm2,chemprop]"

GPU Support¶

By default, alf_tools installs CPU-optimised PyTorch. To use a GPU build:

pip install alf-tools
pip install torch --index-url https://download.pytorch.org/whl/cu128

Note: Install alf_tools first, then override torch separately. Installing both in a single step causes an index conflict since alf_tools pins torch to the CPU index.

Development Setup¶

Use this when you want to develop or modify ALF itself.

Prerequisites¶

Python 3.12 or higher
uv package manager
SSH key configured for GitHub

Quick Start¶

# Clone the repository
git clone git@github.com:instadeepai/alf.git
cd alf

# Install all packages with development dependencies
uv sync

# Verify installation
uv run python -c "from alf_tools.models import CNNModel; print('ALF installed successfully')"

This installs all ALF packages (alf_core, alf_tools, alf_tutorials) with CPU-optimised PyTorch by default.

GPU Support (Optional)¶

If you have an NVIDIA GPU with CUDA 12.8:

Option A — Temporary override (no file changes):

uv sync
uv pip install torch --index-url https://download.pytorch.org/whl/cu128 --reinstall

To revert to CPU, run uv sync.

Option B — Persistent change:

Edit tools/pyproject.toml to change the torch source index from pytorch-cpu to pytorch-gpu, then run uv sync. Revert this before committing.

[tool.uv.sources]
torch = [
  { index = "pytorch-gpu" },
]

Note: After installing the GPU variant, avoid running uv sync or uv run (which auto-syncs) as both will revert torch to the CPU build. To run scripts without triggering a sync, use uv run --no-sync python script.py or activate the virtualenv directly.

Optional Extras (Development)¶

In the cloned repository the alf_tools extras are re-exposed as dependency groups, so install them with --group (not --extra):

uv sync --group esm2
uv sync --group chemprop
uv sync --group protein              # esm2 + esmfold
uv sync --group molecule             # chemprop + guacamol
uv sync --group esm2 --group chemprop