Helico

Protein contact maps → 3D structures. Helico takes an amino acid sequence and a residue–residue contact map and predicts all-atom coordinates, without a multiple sequence alignment (MSA). It also gives you a way to score candidate contact maps by evaluating the structures they produce.

More contacts, same sequence. Independent Helico predictions for the SH3-like domain 8B2G, chain A, with increasing subsets of contacts from its known structure. Each step keeps the previous contacts and adds more; all other settings stay fixed. This is an illustrative example using ground-truth contacts, not an end-to-end prediction benchmark. Static view, predictions, and reproduction details.

• Fold from contacts. Supply contacts from a predictor such as MarinFold, or your own contact hypotheses. Get atom coordinates, a PDB file, and per-atom confidence.
• Compare contact maps. Fold the same sequence with different maps and compare the resulting structure confidence. When a reference structure is available, measure accuracy with lDDT, TM-score, or RMSD.
• Study how contacts affect folding. Vary the number or quality of supplied contacts while keeping the sequence and model fixed. Partial maps are supported; unlisted pairs remain unknown.

Helico predicts coordinates from contacts. The contact predictions themselves come from an upstream model or another source. The released checkpoint is contacts-msafree-01-step6000.pt at timodonnell/helico.

The Colab notebook walks through folding and visualizing a protein under several contact conditions. For local inference, use Python 3.10+ and an NVIDIA CUDA GPU:

git clone https://github.com/Open-Athena/helico.git
cd helico
uv venv --python 3.10
uv pip install -e .
source .venv/bin/activate

Start with the animation's inputs: a 74-residue sequence and 59 contacts derived from its known structure. Copy these demo files into the repository root:

cp docs/images/contact_sweep/sequence.txt sequence.txt
cp docs/images/contact_sweep/contacts.txt contacts.txt

For your own protein, replace sequence.txt with a single amino acid sequence (no FASTA header) and contacts.txt with one pair of zero-based residue positions per line. For example, the demo contact list starts with:

21 53
40 46

Use positions within the supplied sequence. The demo uses ground-truth contacts; for prediction, supply contacts from your predictor or other source.

from pathlib import Path
from helico.inference import contacts_from_pairs, fold, load_model

sequence = "".join(Path("sequence.txt").read_text().split())
pairs = [
    tuple(map(int, line.split()))
    for line in Path("contacts.txt").read_text().splitlines()
    if line.strip()
]

model = load_model()  # downloads the released Helico checkpoint on first use
contacts = contacts_from_pairs(pairs, seq_len=len(sequence), strict=True)
result = fold({"A": sequence}, contacts=contacts, model=model, n_samples=5, seed=0)

result.write_pdb("prediction.pdb")
print(result.coords.shape)  # (number of atoms, 3), coordinates in angstroms
print(result.mean_plddt)    # model confidence, on a 0–100 scale

The checkpoint and chemical component dictionary download automatically and are cached. fold() returns the best of n_samples by the model's ranking score. The PDB's B-factor column contains per-atom pLDDT.

hf download timodonnell/helico contacts-msafree-01-step6000.pt --local-dir checkpoints
helico-infer \
  --checkpoint checkpoints/contacts-msafree-01-step6000.pt \
  --sequences "A:$(tr -d '[:space:]' < sequence.txt)" \
  --contacts contacts.txt \
  --output prediction.pdb

A useful contact map should lead to a plausible, accurate structure. Helico lets you evaluate that downstream outcome in two ways:

To compare maps without a reference, reuse the loaded model and sequence from the example above. Build each candidate matrix with contacts_from_pairs:

candidate_maps = {
    "sparse": contacts_from_pairs(pairs[:10], seq_len=len(sequence), strict=True),
    "full_list": contacts_from_pairs(pairs, seq_len=len(sequence), strict=True),
}
scores = {}
for name, contact_map in candidate_maps.items():
    prediction = fold(
        {"A": sequence}, contacts=contact_map, model=model, n_samples=5, seed=0
    )
    scores[name] = prediction.mean_plddt

print(sorted(scores.items(), key=lambda item: item[1], reverse=True))

For your own data, compare cutoffs of a ranked contact list or substitute maps from different predictors. Keep the sequence, checkpoint, seed, and sampling budget fixed. Confidence is a proxy for map quality, not a calibrated contact precision or a guarantee of correctness. Measured lDDT requires a reference; predicted lDDT (pLDDT) does not.

The model uses a symmetric, three-state matrix: present / absent / unknown. For a standard protein, each row and column corresponds to one residue.

• contacts_from_pairs(...) marks the listed pairs present and leaves every other pair unknown. A pair missing from a truncated list is not evidence that the residues do not contact.
• Positions are zero-based by default; pass one_indexed=True for one-based input. Same-chain pairs fewer than six positions apart are excluded. With strict=True, invalid or too-close pairs raise an error.
• For complexes, use (chain_a, position_a, chain_b, position_b) tuples and pass tokenized= built from the same chains. See the API and notebook.
• contacts_from_structure(...) derives a map from a known structure using pyconfind. It is an oracle input for experiments, because it uses the answer.

Contacts follow the side-chain contact definition used by MarinFold's contacts-v1, rather than a generic Cα distance threshold. See contacts.py for the exact parameters.

On the 210 eval-test monomers with results for all compared methods in experiment 14:

Here L is the protein length; top-L keeps that many ranked contacts. The MarinFold row uses the decontaminated exp232 checkpoint at step 363,000. All Helico rows use contacts-msafree-01 step 6,000 without an MSA. Oracle contacts show what the model can do when given the correct map; they are not a prediction result. Real predicted contacts improve on Helico without contacts and on single-sequence Protenix, while ESMFold and ESMFold2 remain stronger on this set.

See the source table, experiment settings and analysis, and contact-conditioning results. The structure viewer lets you inspect individual predictions without a GPU.

Helico builds on Protenix. A learned projection embeds the three contact states into the pair representation before the Pairformer and diffusion modules predict coordinates. The released model disables both the MSA module and alignment-derived input features, so it needs no alignment search.

Training exposes the model to complete, partial, noisy, and missing contact maps. The conditioning mechanism and training recipe are documented in TRAINING.md.

The full test suite also checks Protenix weight loading and benchmark scoring. Install both sets of test dependencies and download the Protenix test checkpoint:

uv sync --python 3.10 --extra dev --extra bench
source .venv/bin/activate
mkdir -p checkpoints
curl -fL https://protenix.tos-cn-beijing.volces.com/checkpoint/protenix_base_default_v1.0.0.pt \
  -o checkpoints/protenix_base_default_v1.0.0.pt
pytest

• Training guide: data preparation, local and Modal training, and contact conditioning.
• Experiments and W&B runs: runs, comparisons, and results.
• Model weights and datasets.
• Published benchmark artifacts: predicted structures, scores, and run manifests.
• helico-bench --help: FoldBench evaluation. Install benchmark dependencies with uv sync --python 3.10 --extra bench; benchmark data downloads on first use.

Apache 2.0.