Modern structure prediction

Version Compatibility

Reference examples tested with: fair-esm 2.0+, biopython 1.83+, numpy 1.26+, requests 2.31+, chai_lab 0.6+, boltz 2.0+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Modern Structure Prediction

"Predict the structure of my protein" -> Map an amino-acid (and optionally ligand/nucleic-acid) sequence to a single 3D model plus per-residue and pairwise confidence.

• Python: ESMFold local via esm.pretrained.esmfold_v1() (no MSA); ColabFold/AlphaFold via MMseqs2 MSA; AlphaFold3/Chai-1/Boltz for complexes and ligands.

Governing Principle: a prediction is a hypothesis, and the predictor is chosen by the input and the question

The trap is treating a prediction as an answer and picking a model by novelty. Two facts govern every decision here. First, MSA depth is the dominant accuracy determinant for the coevolution-based models (AlphaFold2/3, Chai-1, Boltz): quality tracks how well-represented the sequence's family is, not how hard the biology is, so these models excel on deep-MSA families and degrade on orphan, fast-evolving, viral, or de-novo-designed sequences (Jumper 2021 Nature 596:583; Lin 2023 Science 379:1123). ESMFold is single-sequence with no MSA, so it is fast enough for metagenomic scale but is lower-accuracy on average and degrades hardest exactly where evolutionary signal is thin. Second, a default prediction is ONE dominant conformer, not an ensemble: it does not give apo vs holo, allosteric states, or fold switches, and it carries no Boltzmann populations. MSA subsampling and AF-Cluster sample some alternate states but are unreliable, seed-sensitive hypotheses (Wayment-Steele 2024 Nature 625:832), a generality directly challenged by a Matters Arising (Schafer & Porter 2025 Nature 638:E8-E12).

Three category errors follow and must be avoided. (1) These are not variant-effect, ddG, or stability engines: a single point mutation barely changes a deep MSA, so wild-type vs mutant predictions come back near-identical with near-identical pLDDT, and the model is insensitive to the mutation by construction (Buel & Walters 2022 Nat Struct Mol Biol 29:1; Pak 2023 PLoS ONE 18:e0282689). Use AlphaMissense, FoldX/Rosetta ddG, or ESM/EVE variant scores instead. (2) No co-folder gives a trustworthy Kd from geometry: a plausible complex or ligand pose is not evidence of binding or affinity, and CASP16 assessors found co-fold affinity ranking essentially unreliable; Boltz-2's affinity module is a screening prior only, not a measured constant. (3) AF3-class diffusion models can hallucinate confident-looking order in genuinely disordered regions and have measurable chirality violations (~4.4% on PoseBusters) and atom clashes (Abramson 2024 Nature 630:493), so every ligand pose needs a physical-validity check. A confident prediction is a starting hypothesis with spatially varying reliability; validate it against experiment before believing any part of it.

Decision: which predictor for the job

Job	Preferred	Why / caveat
Single-domain monomer, MAX accuracy	AlphaFold2 (LocalColabFold) or AlphaFold3	Deep MSA = best accuracy; AF2 mature and well-understood
Monomer, deep MSA, fast and free	ColabFold (MMseqs2 MSA)	40-60x faster search, near-AF2 accuracy (Mirdita 2022)
Metagenomic / genome-scale / triage	ESMFold	Fastest (no MSA); lower accuracy, weak on large/low-family proteins
Single-sequence when no homologs exist	ESMFold or Chai-1 (single-seq mode)	Both skip MSA; expect reduced accuracy, sanity-check hard
Protein-protein COMPLEX	AF-Multimer / AF3 / Boltz / Chai-1	Gate on ipTM + inter-chain PAE, NOT per-chain pLDDT
Complex WITH ligand/ion/nucleic acid/PTM	AF3, Boltz-1/2, or Chai-1	Co-folders; validate the POSE (PoseBusters), NOT affinity
Binding-affinity PRIOR for screening	Boltz-2 (affinity module)	Screening prior only; a relative affinity score, not a trusted Kd
Commercial / on-prem deployment	Boltz-1/2 or Chai-1 (both Apache-2.0/MIT, commercial OK)	AF3 weights are non-commercial (Google terms)
Alternative conformational states	AF2 + MSA subsampling / AF-Cluster	UNRELIABLE; hypotheses only, not ensembles or populations
Variant effect / stability / pathogenicity	NOT these tools	Insensitive to point mutations; use AlphaMissense/FoldX/ESM

Licenses drift; verify before deploying. AF2 code Apache-2.0, weights CC-BY-4.0 (permissive). AF3 code Apache-2.0, weights under the non-commercial "AlphaFold 3 Model Parameters Terms of Use", granted on request to non-commercial orgs and received directly from Google (open, not open-source). Boltz-1 and Boltz-2 are MIT (code + weights, commercial use permitted). Chai-1 was relicensed to Apache-2.0 for both code and weights in November 2024 (commercial use, including drug discovery, permitted; it launched Sept 2024 under a restrictive non-commercial license, so older notes may say otherwise - verify terms). ESMFold code/weights are MIT.

Decision: which confidence metric answers which question

Metric	Scope	Answers	Read it for
pLDDT (0-100)	Per-residue, LOCAL	How well-placed is this residue's local environment	Trimming; a long <50 stretch usually flags an intrinsically disordered region, not an error
PAE (Angstrom)	Residue-pair	Expected error at j when aligned on i	Domain packing, linker geometry, inter-chain arrangement
pTM (0-1)	Whole model, GLOBAL	Estimated TM-score of the overall fold	Is the topology plausible (>~0.5)
ipTM (0-1)	Interface	Accuracy of relative subunit positioning	Complex interface reliability (>~0.8 likely, <~0.6 unreliable)

The load-bearing reads: high per-residue pLDDT with a high inter-domain PAE block means each domain is confident internally but their relative arrangement is unknown - do not trust the linker or domain-domain interface. For a complex, judge the interface on ipTM plus the inter-chain PAE block; a complex can have high pLDDT on both chains and still be a garbage interface. AF-Multimer ranks models by 0.8ipTM + 0.2pTM, deliberately weighting the interface. All these metrics are self-reported and can be confidently wrong together on out-of-distribution inputs.

Predict a monomer with ESMFold (fast, no MSA)

Goal: Get a single-chain model in seconds without building an MSA, and read pLDDT off the B-factor column.

Approach: Run ESMFold locally with esm.pretrained.esmfold_v1(); the hosted esmatlas API is intermittently down (SSL/internal-server errors) so local is the reliable path. pLDDT rides in the B-factor column but is confidence, not a temperature factor.

import torch
import esm

model = esm.pretrained.esmfold_v1().eval().to('cuda')  # needs ~16 GB GPU for typical proteins

sequence = 'MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH'
with torch.no_grad():
    pdb_text = model.infer_pdb(sequence)  # returns a PDB string with pLDDT in B-factor column
with open('esmfold.pdb', 'w') as f:
    f.write(pdb_text)

Hosted-API fallback (only when no GPU and the endpoint is up):

import requests

url = 'https://api.esmatlas.com/foldSequence/v1/pdb/'
resp = requests.post(url, data=sequence, timeout=300)  # 300 s: long sequences take minutes
resp.raise_for_status()
pdb_text = resp.text

Read per-residue confidence

Goal: Summarize where a prediction is trustworthy so downstream use is restricted to confident cores.

Approach: pLDDT sits in the B-factor column of every prediction (ESMFold, AlphaFold, co-folders). Band it into the standard cutoffs; a contiguous very-low band usually marks a disordered region, not a failure.

from Bio.PDB import PDBParser

parser = PDBParser(QUIET=True)
structure = parser.get_structure('pred', 'esmfold.pdb')
plddt = {res.id[1]: res['CA'].get_bfactor() for res in structure[0].get_residues() if 'CA' in res}

# Bands from the AlphaFold/EBI convention: >90 very high, 70-90 confident, 50-70 low, <50 very low.
very_high = [r for r, s in plddt.items() if s > 90]
confident = [r for r, s in plddt.items() if 70 <= s <= 90]
very_low = [r for r, s in plddt.items() if s < 50]  # likely intrinsically disordered, not wrong
print(f'mean pLDDT {sum(plddt.values())/len(plddt):.1f}; {len(very_low)} very-low residues')

Predict a complex and gate on the interface

Goal: Model a protein-protein or protein-ligand complex and decide whether to believe the interface.

Approach: Use a co-folder (Chai-1 or Boltz), then accept the interface only if ipTM and the inter-chain PAE block agree. Chai-1 and Boltz run from the CLI; both default to no MSA and can call an MSA server. Verify the exact CLI with --help since these packages evolve fast.

import subprocess

# Chai-1: one FASTA with a header per chain; '--use-msa-server' fetches an MSA (improves accuracy).
# Reference invocation - confirm with `chai-lab fold --help`.
subprocess.run(['chai-lab', 'fold', '--use-msa-server', 'complex.fasta', 'chai_out/'], check=True)

# Boltz: FASTA or YAML input; YAML is required to request the Boltz-2 affinity module.
# Reference invocation - confirm with `boltz predict --help`.
subprocess.run(['boltz', 'predict', 'complex.fasta', '--use_msa_server'], check=True)

Goal: Gate the predicted interface before trusting any cross-chain distance.

Approach: Read ipTM and pTM from the confidence JSON the co-folder writes, and band the interface on ipTM. Below ~0.6 the interface is unreliable or the chains likely do not interact; 0.6-0.8 is uncertain and the inter-chain PAE block decides; a confident interface wants ipTM > ~0.8.

import json

with open('chai_out/scores.model_idx_0.json') as f:  # exact filename varies by tool/version
    conf = json.load(f)
iptm = conf.get('iptm')
ptm = conf.get('ptm')
if iptm is None or iptm < 0.6:        # <0.6: unreliable or chains likely do not interact
    print(f'interface NOT reliable (ipTM={iptm}); inspect inter-chain PAE before any claim')
elif iptm < 0.8:                      # 0.6-0.8: uncertain - the inter-chain PAE block decides
    print(f'interface UNCERTAIN (ipTM={iptm:.2f}); gate on the inter-chain PAE block')
else:
    ptm_str = f'{ptm:.2f}' if ptm is not None else 'NA'  # some score files omit pTM
    print(f'interface confident (ipTM={iptm:.2f}, pTM={ptm_str}); still confirm with inter-chain PAE')

Prepare an AlphaFold3 server job

Goal: Submit a monomer or complex to the AlphaFold Server without local weights.

Approach: The server takes a JSON job listing entities and seeds; multiple seeds sample the diffusion head, so request several and inspect the spread rather than trusting one sample.

import json

def af3_job(sequences, name='prediction', seeds=(1, 2, 3)):
    entities = [{'proteinChain': {'sequence': s, 'count': 1}} for s in sequences]
    return json.dumps([{'name': name, 'modelSeeds': list(seeds), 'sequences': entities}], indent=2)

job_json = af3_job(['MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH'])

Reconcile multiple predictions

Goal: Compare models from different predictors and locate the regions they agree on.

Approach: Superimpose on a fixed CA correspondence and report pairwise RMSD, but treat RMSD as fold-agreement only where the aligned selection is stated; prefer a length-normalized fold metric (TM-score) for cross-method fold claims. See geometric-analysis for TM-score and superposition caveats.

from Bio.PDB import PDBParser, Superimposer

def ca_rmsd(pdb_a, pdb_b):
    parser = PDBParser(QUIET=True)
    a = [r['CA'] for r in parser.get_structure('a', pdb_a)[0].get_residues() if 'CA' in r]
    b = [r['CA'] for r in parser.get_structure('b', pdb_b)[0].get_residues() if 'CA' in r]
    n = min(len(a), len(b))  # Superimposer needs an equal-length ordered atom correspondence
    sup = Superimposer()
    sup.set_atoms(a[:n], b[:n])
    return sup.rms

print(f'ESMFold vs AF3 CA-RMSD: {ca_rmsd("esmfold.pdb", "af3.pdb"):.2f} Angstrom')

Common Errors

Symptom	Cause	Fix
Mutant and wild-type predictions look identical	A point mutation barely changes a deep MSA; the model is insensitive to it	Do not read structure/pLDDT deltas as variant effect; use AlphaMissense, FoldX, or ESM
Confident model but wrong in the lab	Prediction is one dominant conformer, not an ensemble; no apo/holo/allosteric states	Treat as a hypothesis; sample states cautiously (MSA subsampling) and validate experimentally
Complex accepted on high per-chain pLDDT	pLDDT is intra-chain local confidence, blind to the interface	Gate on ipTM + inter-chain PAE block; reject interface if ipTM < ~0.6 (0.6-0.8 uncertain)
Long low-pLDDT stretch treated as an error	Low pLDDT correlates with intrinsic disorder	Read <50 regions as likely IDRs (biologically real flexibility), not modeling failures
Two domains confident but arrangement wrong	High intra-domain pLDDT with high inter-domain PAE	Trust each domain, not the relative orientation or linker; split at high-PAE hinges
ESMFold much worse than AlphaFold on an orphan	ESMFold is single-sequence and degrades where evolutionary signal is thin	Use MSA-based ColabFold/AF for orphan/de-novo proteins; keep ESMFold for scale
Ligand pose has wrong chirality or clashes	AF3-class diffusion can violate stereochemistry (~4.4% chirality)	Run PoseBusters/validity checks on every pose; do not assume physical plausibility
Reported Kd from a co-fold pose	Co-folders give geometry, not affinity; CASP16 found affinity ranking unreliable	Use Boltz-2 affinity only as a screening prior; confirm with FEP or experiment
esmatlas API returns SSL / internal-server error	The hosted ESMFold endpoint is intermittently down	Run ESMFold locally via esm.pretrained.esmfold_v1()
Two predictions "disagree" but were run differently	Different MSA depth/source, recycles, seeds, or templates change the answer	Report the MSA pipeline and settings; two predictions are not comparable if these differ
RMSD between predictions looks huge for the same fold	Global all-atom RMSD is dominated by flexible loops and needs a stated selection	Superimpose on CA/core and report the selection; use TM-score for fold agreement

Related Skills

• alphafold-predictions - Retrieve precomputed AlphaFold DB models and read their pLDDT/PAE
• structure-io - Parse and write predicted PDB/mmCIF files
• geometric-analysis - RMSD, superposition, and TM-score caveats for comparing models
• structure-navigation - Walk chains/residues/atoms in a predicted structure
• structure-preparation - Trim, add hydrogens, and protonate a predicted model before docking or MD
• binding-site-detection - Detect pockets on a predicted model (inherits apo/rotamer uncertainty)
• alignment/structural-alignment - Structure-based alignment before comparing sequence-different models
• chemoinformatics/virtual-screening - Dock into a predicted pocket (inherits predicted rotamer/backbone error)
• chemoinformatics/ml-docking-rescoring - Rescore co-folded poses; co-fold geometry is not affinity

References

Jumper J, et al. Highly accurate protein structure prediction with AlphaFold. Nature 596:583-589 (2021). doi:10.1038/s41586-021-03819-2. Abramson J, et al. Accurate structure prediction of biomolecular interactions with AlphaFold 3. Nature 630:493-500 (2024). doi:10.1038/s41586-024-07487-w. Lin Z, et al. Evolutionary-scale prediction of atomic-level protein structure with a language model. Science 379:1123-1130 (2023). doi:10.1126/science.ade2574. Evans R, et al. Protein complex prediction with AlphaFold-Multimer. bioRxiv 2021.10.04.463034 (2021, preprint). doi:10.1101/2021.10.04.463034. Baek M, et al. Accurate prediction of protein structures and interactions using a three-track neural network. Science 373:871-876 (2021). doi:10.1126/science.abj8754. Mirdita M, et al. ColabFold: making protein folding accessible to all. Nat Methods 19:679-682 (2022). doi:10.1038/s41592-022-01488-1. Wayment-Steele HK, et al. Predicting multiple conformations via sequence clustering and AlphaFold2. Nature 625:832-839 (2024). doi:10.1038/s41586-023-06832-9. Schafer JW, ..., Porter LL (2025) Sequence clustering confounds AlphaFold2 (Matters Arising). Nature 638:E8-E12. doi:10.1038/s41586-024-08267-2. Buel GR, Walters KJ. Can AlphaFold2 predict the impact of missense mutations on structure? Nat Struct Mol Biol 29:1-2 (2022). doi:10.1038/s41594-021-00714-2. Pak MA, et al. Using AlphaFold to predict the impact of single mutations on protein stability and function. PLoS ONE 18:e0282689 (2023). doi:10.1371/journal.pone.0282689. Wohlwend J, et al. Boltz-1: democratizing biomolecular interaction modeling. bioRxiv 2024.11.19.624167 (2024, preprint). doi:10.1101/2024.11.19.624167. Chai Discovery. Chai-1: decoding the molecular interactions of life. bioRxiv 2024.10.10.615955 (2024, preprint). doi:10.1101/2024.10.10.615955.