Skip to content

Installation

Prerequisites

COFOLDER requires:

  • Python 3.11 or 3.12
  • CUDA-compatible GPU (for Boltz)
  • Git (for installation from source)

Installation from Source

The recommended method is to install directly from GitHub:

# Clone the repository
git clone https://github.com/CDDLeiden/COFOLDER.git
cd COFOLDER

# Install the base package
pip install -e .

This installs the base COFOLDER package and its core dependencies, including:

  • rdkit - For molecular structure handling
  • numpy and pandas - For core numerical and tabular data handling
  • biopython and gemmi - For sequence and structure input handling

Install the analysis extra for IFP clustering, affinity statistics, ProLIF/pdb2pqr interaction processing, and plotting:

pip install -e ".[analysis]"

If one of these features is requested without its dependency, COFOLDER raises an error naming the feature and recommends installing cofolder[analysis]; it does not silently omit the requested metric or artifact.

Backend runners are installed separately through optional extras:

# Boltz 1 runner
pip install -e ".[boltz1]"

# Boltz 2 runner
pip install -e ".[analysis,boltz2]"

# Boltz Community runner
pip install -e ".[boltz-community]"

# OpenFold3 runner
pip install -e ".[openfold3]"

The initial release supports Boltz 1.0.0 for the boltz1 runner, Boltz >=2.0.0,<3 for boltz2, and Boltz Community 2.10.12. Boltz 1 and Boltz 2 require Python below 3.13; use Python 3.11 or 3.12 as listed above. Install each Boltz-family backend in its own environment because the distributions provide the same boltz command and Python package namespace. COFOLDER reports an explicit compatibility error when it detects an unsupported version, Python version, or mixed Boltz-family environment.

The integrated openfold3 runner still has a second setup step after installation because the upstream model cache, checkpoints, and CCD need to be prepared:

# Install the COFOLDER package with the OpenFold3 backend extra
pip install -e ".[openfold3]"

# Keep the downloaded cache, parameters, and CCD in the repository cache folder
export OPENFOLD_CACHE="$PWD/cache/.openfold3-cache"
cofolder-tools setup-openfold3

Notes for OpenFold3:

  • The COFOLDER openfold3 extra installs the upstream openfold3 package.
  • The example above sets OPENFOLD_CACHE to the gitignored cache/.openfold3-cache directory. If the variable is omitted, cofolder-tools setup-openfold3 retains the upstream ~/.openfold3 default.
  • cofolder-tools setup-openfold3 also answers the standard upstream setup prompts explicitly: it uses OPENFOLD_CACHE for both cache/checkpoint-root questions, selects parameter download choice 1, and declines forced redownloads by default. Set OPENFOLD3_FORCE_DOWNLOAD_PARAMETERS=yes only when you intentionally want to replace an existing checkpoint.
  • The tool answers the upstream integration-test prompt with no by default so bootstrap does not hang in an unexpected interactive test path. If you intentionally want those tests, run OPENFOLD3_RUN_INTEGRATION_TESTS=yes cofolder-tools setup-openfold3.
  • If you want all published checkpoints instead of the default checkpoint only, run OPENFOLD3_PARAMETER_CHOICE=2 cofolder-tools setup-openfold3.
  • If you want a different cache root, set OPENFOLD_CACHE before running the tool, for example OPENFOLD_CACHE=/scratch/$USER/.openfold3 cofolder-tools setup-openfold3.
  • Upstream docs note that first inference can also download default model parameters into $HOME/.openfold3, but this project prefers the explicit setup script so readiness is established before prediction runs.
  • The current OpenFold3 integration is confidence-only: it exposes OpenFold3-native confidence outputs and keeps affinity groups unsupported unless a future code change intentionally widens that capability.
  • For clean-install manual acceptance in a fresh environment, see the Backend Acceptance Tutorial.

For clean-install backend acceptance in fresh environments, see the Backend Acceptance Tutorial.

Verify Installation

After installation, verify that COFOLDER is correctly installed:

cofolder --version
cofolder-tools --help

To create a local, editable copy of the packaged example bundle from any working directory:

cofolder-tools copy-examples ./cofolder-examples

You should see output showing the version number.

Optional Dependencies

Standalone Bias Workflow

The dedicated cofolder bias command does not need a cofolding backend runner. Install .[analysis] for the complete reference-overlap plotting artifact set.

With the analysis extra installed, the backend-free bias workflow supports:

  • custom-only reference inputs
  • prebuilt public protein/ligand training CSVs
  • mixed public-plus-custom reference analysis

Install mmseqs2 only if you want to build public protein bias-training data from a system definition in the same environment where you run cofolder:

conda install -c conda-forge -c bioconda mmseqs2

Alternative without conda-forge:

cofolder-tools install-mmseqs
export COFOLDER_MMSEQS_BIN="$HOME/.cofolder/vendor/mmseqs/bin/mmseqs"

COFOLDER accepts only a regular, executable MMseqs file. Resolution checks an explicit --mmseqs_bin value first, then COFOLDER_MMSEQS_BIN, the managed user installation above, checkout-local vendor/mmseqs locations when running from a source checkout, and finally mmseqs on PATH. Missing or non-executable candidates are included in required-command diagnostics.

Verify:

which mmseqs
mmseqs --version

Bias-only setup after installing .[analysis] is described in full in Providing bias training data. The commands below document the retained legacy CSV route:

# 1) Optional: fetch CCD + mmseqs DB if you want to build public training CSVs
cofolder-tools fetch-bias-training-data \
  --output_root /path/to/training_data \
  --overwrite

# 2) Optional: build public protein/ligand training CSVs
cofolder-tools build-bias-training-data \
  --system_path /path/to/system.yaml \
  --components_cif /path/to/training_data/ccd/components.cif \
  --output_protein_csv /path/to/training_data/protein_training_data.csv \
  --output_ligand_csv /path/to/training_data/ligand_training_data.csv \
  --release_cutoff 2023-06-01 \
  --overwrite

# 3a) Run standalone bias from prebuilt public references
cofolder bias \
  --system_path /path/to/system.yaml \
  --wrk_dir /path/to/bias_run \
  --protein_training_data_path /path/to/training_data/protein_training_data.csv \
  --ligand_training_data_path /path/to/training_data/ligand_training_data.csv

# 3b) Or run standalone bias from custom-only references
cofolder bias \
  --system_path /path/to/system.yaml \
  --wrk_dir /path/to/bias_run \
  --custom_protein_reference_path /path/to/custom_protein.csv \
  --custom_ligand_reference_path /path/to/custom_ligand.csv

When the builder writes bias_training_data.csv, its sequence_similarity values are MMseqs pident percentages. The accompanying sequence_similarity_method column is mmseqs_pident when a hit exists and unavailable when MMseqs returned no result; an unavailable protein similarity is left empty so it cannot pass a protein-similarity threshold. The configured threshold filters the standalone protein_training_data.csv but does not discard MMseqs hits needed to annotate PDBs in the combined table.

Downstream bias analysis never puts a PairwiseAligner result in sequence_similarity. When PairwiseAligner is used for sequence-only custom references, its percentage is written to sequence_similarity_pairwise, with method pairwise_aligner; the MMseqs column remains empty.

cofolder bias writes diagnostic artifacts under <wrk_dir>/results/bias_train/. These are reference-overlap outputs for pre-cofolding decision support. They are not binding-affinity predictions, model-confidence scores, or guarantees of cofolding success.

If you want the same bias diagnostics attached to a runner-backed validation run, use validate --assess_bias with the same public reference CSVs:

cofolder validate ... \
  --assess_bias \
  --protein_training_data_path /path/to/training_data/protein_training_data.csv \
  --ligand_training_data_path /path/to/training_data/ligand_training_data.csv

Documentation Tools

To build the documentation locally:

pip install -e ".[docs]"

This installs:

  • MkDocs with Material theme
  • mkdocstrings for API reference generation

Tutorial Notebooks

To run the interactive marimo tutorials:

pip install -e ".[analysis,tutorials]"

Then launch a tutorial notebook, for example:

marimo edit tutorials/bias.py

Development Installation

For development work, install with all optional dependencies:

pip install -e ".[analysis,docs,test,development]"

Add the backend extra you need in the same environment, for example:

pip install -e ".[analysis,boltz2]"

If you are developing against OpenFold3 instead, keep the same development environment and install the matching COFOLDER backend extra plus the setup script:

pip install -e ".[analysis,openfold3]"
cofolder-tools setup-openfold3

Troubleshooting

CUDA Issues

If you encounter CUDA-related errors, ensure:

  1. You have a CUDA-compatible GPU
  2. CUDA drivers are properly installed
  3. PyTorch is installed with CUDA support

RDKit Issues

If RDKit installation fails, try installing via conda:

conda install -c conda-forge rdkit

Optional Analysis Dependency Errors

If clustering, affinity correlation statistics, plotting, ProLIF, or pdb2pqr reports that an optional dependency is unavailable, install the complete supported analysis set:

python -m pip install -e ".[analysis]"

Combine it with exactly one backend extra when prediction is also required, for example python -m pip install -e ".[analysis,boltz2]".

Next Steps

Once installed, proceed to the Quick Start Guide to begin using COFOLDER. For runtime failures, use the consolidated Troubleshooting guide.