google-deepmind/alphaprotein-novo

google-deepmind/alphaprotein-novo

Description: AlphaProtein Novo

Language: Python

License: Apache-2.0

Stars: 70

Forks: 8

Open issues: 0

Created: 2026-10-05T14:39:58Z

Pushed: 2026-10-05T15:51:41Z

Default branch: main

Fork: no

Archived: no

README:

AlphaProtein Novo

AlphaProtein Novo (AP Novo) is a generative diffusion pipeline for *de novo* enzyme design via structural motif scaffolding.

This package includes a diffusion model which co-generates protein structures and sequences conditioned on a catalytic motif and ligand context. This is run using run_generator.py.

To form an end-to-end pipeline, the diffusion model is combined with optional sequence redesign using LigandMPNN (run_ligandmpnn.py), structure prediction using AlphaFold 3 (run_alphafold.py), and evaluation metrics (evaluate_design.py). The run_pipeline.py script runs all stages in sequence.

See the [Quickstart](#quickstart) section for a basic launch command and [Example Design Campaigns](#example-design-campaigns) for more detailed examples.

Any publication that discloses findings arising from using this source code, the model parameters, or outputs produced by those should [cite](#citing-this-work) the Designing enzymes for new-to-nature chemistry and non-natural substrates with AlphaProtein Novo paper.

:ledger: Note: Pretrained model weights are not part of this package and must be downloaded from Google Cloud Storage (see [Model Parameters](#model-parameters-weights) below). Use is subject to these [terms of use](WEIGHTS_TERMS_OF_USE.md). Scripts look for weights under ./models/apnovo_generator by default, or you can point to another directory using --apn_model_dir (for run_pipeline.py), --model_dir (for run_generator.py), or settings.model_dir in your design manifest.

Installation & Environment Setup

Two Python environments are recommended:

• Primary Environment (`alphaprotein_novo`): Contains JAX. Runs diffusion

generation, AlphaFold 3 folding, evaluation metrics, and the pipeline orchestrator.

• LigandMPNN Environment (`ligandmpnn`) [Optional]: Contains PyTorch. Used

to run LigandMPNN for sequence design.

Primary Environment (alphaprotein_novo)

# Create and activate a Python 3.12 environment
uv venv --python 3.12 .venv
source .venv/bin/activate

# Install JAX with CUDA 12 support (or CPU: uv pip install -U jax)
uv pip install -U "jax[cuda12]>=0.4.30"

# Install AlphaFold 3
uv pip install git+https://github.com/google-deepmind/alphafold3.git

# Install AP Novo in editable mode
cd /path/to/alphaprotein_novo
uv pip install -e .

# Compile AlphaFold 3 chemical component data (CCD pickle)
build_data

:ledger: Tip: `build_data` compiles `ccd.pickle` and `chemical_component_sets.pickle` required by AlphaFold 3 to parse ligands. If components.cif cannot be located, set the LIBCIFPP_DATA_DIR environment variable to its directory before running build_data.

LigandMPNN Environment (ligandmpnn) [Optional]

Only required if you plan to run optional sequence redesign with LigandMPNN:

# 1. Create and activate Python 3.11 environment
uv venv --python 3.11 .venv-ligandmpnn
source .venv-ligandmpnn/bin/activate

# 2. Clone LigandMPNN and download weights
git clone https://github.com/dauparas/LigandMPNN.git
cd LigandMPNN
bash get_model_params.sh ./model_params

# 3. Install dependencies
uv pip install -r requirements.txt
uv pip install "setuptools/projects/LigandMPNN # For example.
export LIGANDMPNN_PYTHON=/home//miniconda3/envs/ligandmpnn/bin/python # For example.

Model Parameters (Weights)

• AP Novo: Download pretrained generator weights (generator.bin.zst)

into ./models/apnovo_generator (subject to the [AP Novo Parameters Terms of Use](WEIGHTS_TERMS_OF_USE.md); or configure a directory via --apn_model_dir, --model_dir, or settings.model_dir in your manifest):

mkdir -p models/apnovo_generator
wget -P models/apnovo_generator https://storage.googleapis.com/alphaprotein_novo/generator.bin.zst

• AlphaFold 3 Leaving Atom (AF3-LA): Download neural network weights

(af3_leaving_atom.bin.zst) into ./models/af3_la (subject to the AlphaFold 3 Parameters Terms of Use). Structure prediction uses these by default, because AF3-LA is fine-tuned for leaving atom handling and therefore models the covalent intermediates common in AP Novo designs:

mkdir -p models/af3_la
wget -P models/af3_la https://storage.googleapis.com/alphafold3/af3_leaving_atom.bin.zst

Alternatively, stock AlphaFold 3 weights (af3.bin.zst) can be used, subject to the same terms of use. Pass --model_dir=./models/af3 (or --af3_model_dir=./models/af3 to run_pipeline.py) to select them:

mkdir -p models/af3
wget -P models/af3 https://storage.googleapis.com/alphafold3/af3.bin.zst

Quickstart

The standard way to run AP Novo is via run_pipeline.py. It executes design generation, sequence design, folding, and metrics calculation end-to-end from a single "manifest" file containing configuration settings:

# Ensure the primary environment is active
source .venv/bin/activate

python run_pipeline.py \
--manifest=examples/kemp_eliminase/kemp_manifest.json \
--output_dir=./kemp_campaign \
--af3_model_dir=./models/af3_la \
--ligandmpnn_dir=/path/to/LigandMPNN \
--ligandmpnn_python="/path/to/ligandmpnn/.venv-ligandmpnn/bin/python"

:ledger: Tip: To quickly verify your installation without waiting for a full-length diffusion trajectory, swap in `examples/kemp_eliminase/kemp_test_manifest.json`, which runs the same Kemp eliminase benchmark with reduced sampling steps.

Outputs are organized into stage-specific subdirectories under --output_dir (see [Generated Artifacts & Reports](#generated-artifacts--reports) below). By default, re-running the pipeline resumes interrupted campaigns by skipping completed designs; you can also force a full rerun or execute individual stages (see [Modular Stage Execution](#modular-stage-execution)).

Design Manifests

Campaigns are configured using a JSON manifest describing the design problem, motif conditioning, and downstream processing.

Here is an example based on examples/kemp_eliminase/kemp_manifest.json:

{
"settings": {
"model_dir": "./models/apnovo_generator"
},
"defaults": {...