Upload README.md with huggingface_hub

README.md

@@ -1,9 +1,9 @@
 ---
-license: 
-- mit 
+license:
+- mit
 - other
 license_link: https://github.com/Biohub/esm/blob/main/THIRD_PARTY_NOTICE.md
-language: en 
+language: en
 tags:
 - biology
 - esm
@@ -16,162 +16,169 @@ tags:
 - molecular-dynamics
 - transformers
 ---
+
 # Model Card for ESMFold2
 
 ## Model Details
 
-ESMFold2 is a state-of-the-art model for protein structure prediction and design that defines a new frontier for speed and accuracy. The model achieves unprecedented success rates for protein binder and antibody generation, validated through biophysical and functional characterization.
+ESMFold2 is a state-of-the-art model for protein structure prediction and design that defines a new frontier for speed and accuracy. The model predicts high-resolution, all-atom 3D protein structures directly from amino acid sequences, with optional multiple sequence alignment (MSA) input for enhanced accuracy on challenging targets. The model outputs comprehensive structural information including all-atom coordinates (backbone and side chains), confidence metrics (pLDDT, pAE, pTM, iPTM), and optional distogram predictions for detailed analysis of predicted structures. Unlike ESMFold, ESMFold2 is able to predict structures for all biomolecules, including small molecules, DNA, RNA, and modified amino acids.
 
-The model predicts high-resolution, all-atom 3D protein structures directly from amino acid sequences, with optional multiple sequence alignment (MSA) input for enhanced accuracy on challenging targets. The model outputs comprehensive structural information including all-atom coordinates (backbone and side chains), confidence metrics (pLDDT, pAE, pTM, iPTM), and optional distogram predictions for detailed analysis of predicted structures. Unlike ESMFold, ESMCFold is able to predict structures for all biomolecules, including small molecules, DNA, RNA, and modified amino acids.
+ESMFold2 is capable of either single-sequence or MSA conditioned structure prediction for improved accuracy on difficult targets. The ESMFold2-Fast variant is an inference optimized single-sequence structure prediction model and is not MSA conditioned.
 
-ESMFold2 is capable of either single-sequence or MSA conditioned structure prediction for improved accuracy on difficult targets.
+To run this model with the Biohub Platform API, visit the [Biohub Platform](https://biohub.ai/).
 
-To run this model with the Biohub Platform API, visit the [Biohub Platform](https://biohub.ai/). 
+Read more about ESMFold2 in our paper [here](https://biohub.ai/papers/esm_protein.pdf).
 
-Read more about ESMFold2 in our paper [here](https://biohub.ai/papers/esmc.pdf).
+## Model Variants
 
-### System Requirements
+| Model | MSA Conditioning | Description | Data Cutoff |
+| :---- | :---- | :---- | :---- |
+| [esmfold2](https://huggingface.co/biohub/esmfold2) | Yes | Large model, capable of either single-sequence or MSA conditioned structure prediction for improved accuracy on difficult targets | Sept 2021 |
+| [esmfold2-fast](https://huggingface.co/biohub/esmfold2-fast) | No | Inference optimized single-sequence structure prediction model | Sept 2021 |
 
-* Compute Requirements: GPU  
-* PyTorch environment with GPU support recommended.
+## Performance Metrics
 
-### Usage
+ESMfold2 was evaluated against state-of-the-art single-sequence and MSA-based structure prediction models on the FoldBench benchmark. ESMFold2 meets or exceeds performance by AlphaFold3 on antibody-antigen complex prediction, protein-protein complex prediction and [Runs N' Poses](https://www.biorxiv.org/content/10.1101/2025.02.03.636309v1) benchmarks. Inference-time compute can dramatically improve performance of ESMFold2, especially across antibody-antigen complexes.
 
-Coming soon
+![][image1]
 
-### Citation
+Refer to the [paper](https://biohub.ai/papers/esmc.pdf) for details on additional performance metrics.
 
-Coming soon.
+### Usage
 
-### Model Architecture
+Please install `esm` via PyPi:
 
-The architecture consists of an input embedder, which includes the ESMC language model embeddings, a pairwise folding block trunk, an atom diffusion module, an optional MSA encoder, and a confidence head.
+```
+pip install esm
+```
 
-This hybrid architecture combines the representational power of large-scale protein language models with and efficient structure prediction modules listed in detail below:
+You can fold your first protein with
 
-**1\. Language Model Inputs Embedder:**
+```py
+from esm.models.esmfold2 import (
+    ESMFold2InputBuilder,
+    ProteinInput,
+    StructurePredictionInput,
+)
+from transformers.models.esmfold2.modeling_esmfold2 import ESMFold2Model
 
-- Uses a frozen ESMC 6B parameter language model to generate rich single-sequence embeddings.  
-   
-- Provides evolutionary and functional context encoded in high-dimensional representations.  
-   
-- Embeddings capture long-range dependencies and sequence patterns learned from billions of protein sequences.
+# Ubiquitin (PDB 1UBQ)
+sequence = (
+    "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG"
+)
 
-**2\. Pairformer Trunk:**
+model = ESMFold2Model.from_pretrained("biohub/ESMFold2").cuda().eval()
+processor = ESMFold2InputBuilder()
+spi = StructurePredictionInput(sequences=[ProteinInput(id="A", sequence=sequence)])
 
-- Processes language model embeddings through a pairformer architecture that refines pairwise and single representations  
-   
-- Architectural improvements: Triangle attention was removed as it did not provide significant benefits, and the single state was removed to improve generalization  
-   
-- Evolves pairwise representations through iterative updates, enabling the model to capture inter-residue relationships and spatial constraints
+result = processor.fold(
+    model, spi, num_loops=3, num_sampling_steps=50, num_diffusion_samples=1, seed=0
+)
 
-**3\. Diffusion-Based Structure Module:**
+print(f"pLDDT mean: {float(result.plddt.mean()):.3f}")
+print(f"pTM: {float(result.ptm):.3f}")
+```
 
-- Employs a diffusion process to generate all-atom 3D coordinates (backbone and sidechains)  
-   
-- Uses an ODE (Ordinary Differential Equation) solver for efficient sampling  
-   
-- Optimized sampling schedule: 32 steps for sidechain prediction and 8 steps for backbone prediction provide optimal performance without additional benefit from more steps  
-   
-- This efficient sampling strategy significantly reduces computational cost while maintaining accuracy
+You may directly use the model through huggingface/transformers
 
-**4\. Optional MSA Encoder (ESMFold2 MSA variant):**
+```py
+from transformers.models.esmfold2.modeling_esmfold2 import ESMFold2Model
 
-- Processes multiple sequence alignments to extract evolutionary information  
-   
-- Distills MSA information into pairwise representations that enhance structure prediction  
-   
-- Particularly beneficial for difficult targets with limited sequence information
+# Ubiquitin (PDB 1UBQ)
+sequence = (
+    "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG"
+)
 
-**5\. Confidence Head:**
+model = ESMFold2Model.from_pretrained("biohub/ESMFold2").cuda().eval()
+output = model.infer_protein(sequence, num_loops=3, num_sampling_steps=50)
 
-- Additional 4-layer pairformer module that estimates prediction confidence  
-   
-- Outputs multiple confidence metrics: pLDDT (per-residue), pAE (pairwise aligned error), pTM (template modeling score), and iPTM (interface template modeling score for complexes)
+print(f"pLDDT mean: {float(output['plddt'].mean()):.3f}")
+print(f"pTM: {float(output['ptm'].mean()):.3f}")
+```
 
-**6\. Auxiliary Losses:**
+And the Biohub API:
 
-- A trunk distogram head, a smooth-LDDT loss on the denoised sample, and a polymer-ligand bond loss supplement the diffusion MSE and confidence losses.
+```py
+TODO minimal biohub API code snippet
+```
 
-**Model Variants:**
+First install the `esm` Python package.
 
-| Model | MSA Conditioning | Description | Data Cutoff |
-| :---- | :---- | :---- | :---- |
-| [esmfold2-fast](https://huggingface.co/biohub/esmfold2-fast) | No | Inference optimized single-sequence structure prediction model | June 2025, older cutoff is Sept 2021 |
-| [esmfold2](https://huggingface.co/biohub/esmfold2) | Yes | Large model, capable of either single-sequence or MSA conditioned structure prediction for improved accuracy on difficult targets | June 2025, older cutoff is Sept 2021 |
+```
+pip install esm
+```
 
-**Confidence Head (optional, for inference):**
+Import the necessary libraries.
 
-- 4 pairformer layers  
-- Outputs: pLDDT, pAE, pTM, ipTM
+```py
+from esm.sdk.forge import SequenceStructureForgeInferenceClient
+from esm.sdk import client
+from esm.sdk.api import ESMProtein, ESMProteinError, LogitsConfig, LogitsOutput
+```
 
-## Intended Use
+Generate an [API key](https://biohub.ai/developer-console/api-keys) and add it to your Biohub account. This API key manages your access to credits and tokens, and the term API key/token is often used interchangeably within documentation. Call the inference client with the selected model of choice and replace with your token name.
 
-### Primary Use Cases
+```py
+client = SequenceStructureForgeInferenceClient(model="esmfold2-fast-2026-05", url="https://biohub.ai", token="<your API token>")
+```
 
-ESMFold2 is designed to handle a wide range of structural prediction tasks, including:
+####
 
-#### **Complex biomolecular interactions**
+The Hugging Face implementation directly supports proteins only. For complex biomolecules, we recommend using the internal API. Here's an example of folding a Ubiquitin with ESMFold2:
 
-- **Complex structure folding**: Predict structures of DNA, RNA, and small molecule ligands, including protein–protein interactions and protein-nucleic acid complexes.
+```py
+import os
 
-- **Single-sequence folding**: Predict 3D structures from amino acid sequences without requiring multiple sequence alignments
+from esm.models.esmfold2 import LigandInput, ProteinInput, StructurePredictionInput
+from esm.sdk import esmfold2_client
+from esm.sdk.api import FoldingConfig
 
+# Ubiquitin (PDB 1UBQ) + ATP cofactor (illustrative pairing).
+protein = ProteinInput(
+    id="A",
+    sequence=(
+        "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG"
+    ),
+)
+ligand = LigandInput(id="L", ccd=["ATP"])
 
-#### **Confidence Estimation and Quality Assessment**
+# TODO: replace ``esmc-fold-flash-2604`` with the public ESMFold2 model name
+# once the Biohub Platform inference server announces it.
+client = esmfold2_client(model="esmc-fold-flash-2604", token=os.environ["ESM_API_KEY"])
 
-- **Per-residue confidence (pLDDT)**: Local confidence scores (0-100) indicating prediction reliability at each residue position  
-   
-- **Predicted aligned error (pAE)**: Pairwise error estimates for assessing inter-residue distance accuracy  
-   
-- **Template modeling score (pTM)**: Global confidence metric (0-1) for overall structure topology and domain packing  
-   
-- **Interface confidence (iPTM)**: Specialized confidence scores for multimeric complex interfaces
+spi = StructurePredictionInput(sequences=[protein, ligand])
+result = client.fold_all_atom(
+    spi, config=FoldingConfig(num_loops=3, num_sampling_steps=50)
+)
 
-#### **Computational Biology Research**
+print(f"pLDDT mean: {float(result.plddt.mean()):.3f}")
+print(f"pTM: {float(result.ptm):.3f}")
+```
 
-- **Evolutionary analysis**: Study structural conservation and divergence across protein families  
-   
-- **Disease variant analysis**: Predict structural impacts of mutations and genetic variants  
-   
-- **Drug discovery**: Support structure-based drug design through accurate binding site prediction
+## Training Data
 
-## Training Details
+ESMfold2 was trained on sequences from the Protein Data Bank (PDB) and the AlphaFold DB (AFDB).
 
-The model was trained on sequences from [PDB](https://www.rcsb.org/) and [AlphaFold DB](https://alphafold.ebi.ac.uk/). Refer to the supplement in the [paper](https://biohub.ai/esmc) for details on how data is processed and sampled.
+## Frontier Safety
 
-## Performance Metrics
+Biohub has established a safety team to assess the benefits and potential risks of our models and tools prior to release, and develop mitigations where necessary. Risk assessment was conducted for ESMFold2 prior to release. Further details are available in our corresponding paper appendix.
 
-ESMfold2 was evaluated against state-of-the-art single-sequence and MSA-based structure prediction models on the FoldBench benchmark. ESMFold2 meets or exceeds performance by AlphaFold3 on antibody-antigen complex prediction, protein-protein complex prediction and [Runs N’ Poses](https://www.biorxiv.org/content/10.1101/2025.02.03.636309v1) benchmarks. For inference time-scaling on FoldBench, ESMCFold scales gracefully with sample count, comparable to or exceeding AlphaFold3’s scaling behavior on the same targets.
+Informed by our risk assessments, we are releasing the source code and model weights for ESMFold2.
 
-Refer to the [paper](https://biohub.ai/papers/esmc.pdf) for details on additional performance metrics.
+[Biohub.ai](http://Biohub.ai) Platform: We implement guardrails that detect and restrict the use of keywords and sequences corresponding to controlled pathogens and toxins on our freely accessible platform. For further details regarding these guardrails, please refer to our Biohub platform Resources page.
 
-## Biases, Risks, and Limitations
+## Biases and Limitations
 
 ### Potential Biases
 
 - The model may reflect biases present in the training data.
-
-### Risks
-
-- Potential misuse: Protein structure predictions may be used for malicious purposes such as designing pathogens or toxins.
+-
 
 ### Limitations
 
-- **Static structure prediction**: The model predicts single static conformations and is not designed for modeling protein dynamics, conformational flexibility, or multiple conformations of the same protein. It does not capture functional motions, allosteric transitions, or time-dependent structural changes.  
-   
-- **Sequence length constraints**: Maximum sequence length is approximately 1600 residues per chain, with total complex size limited by available GPU memory. Very large complexes may require specialized hardware or memory optimization strategies.  
-   
-- **Training data biases**: The model may reflect biases present in the training data (PDB, AFDB, SAbDab), including over-representation of certain protein families, experimental conditions, or structural classes. Performance may vary for underrepresented protein types.  
-   
-- **Novel folds and rare structures**: While the model generalizes well, extremely novel folds or rare structural motifs not well-represented in training data may have reduced accuracy.  
-   
-- **Post-translational modifications**: The model provides limited support for non-standard amino acids and post-translational modifications. Performance may be reduced for heavily modified proteins.  
-   
-- **Membrane proteins**: While the model can predict membrane protein structures, specialized membrane protein prediction tools may provide better results for transmembrane domains and membrane-embedded regions.  
-   
-- **Disordered regions**: The model may struggle with intrinsically disordered regions, which lack well-defined structure. Low pLDDT scores (\<50) often indicate disordered or flexible regions.  
-   
+- **Dataset biases**: The model may reflect biases present in the training data (PDB, AFDB), including over-representation of certain protein families, experimental conditions, or structural classes. Performance may vary for underrepresented protein types.
+- **Dataset limitations:** PDB historically lacks comprehensive data on protein conformations, post-translational modifications, disordered regions, etc. Like all other structure prediction models trained on the PDB, performance may degrade on other biomolecules.
+- **Computational demand:** Highest accuracy structure predictions require scaling inference time compute. Predictions made with reduced inference parameters may lead to suboptimal performance.
 - **Experimental validation required**: All predictions should be considered hypotheses requiring experimental validation. The model cannot replace experimental structure determination methods (X-ray crystallography, cryo-EM, NMR) for definitive structural characterization.
 
 ### Out-of-Scope or Unauthorized Use Cases
@@ -182,16 +189,18 @@ Do not use the model for the following purposes:
 
 ### Caveats and Recommendations
 
-- Always review and validate outputs generated by the model.  
-   
-- Treat model outputs as machine-generated hypotheses that require further experimental validation, not as established biological facts.  
-   
-- We are committed to advancing the responsible development and use of artificial intelligence. Please follow our [Acceptable Use Policy](https://biohub.org/acceptable-use-policy/) when using the model.
+- Always review and validate outputs generated by the model.
+- Treat model outputs as machine-generated hypotheses that require further experimental validation, not as established biological facts.
+- We are committed to advancing the responsible development and use of artificial intelligence.
 
 Should you have any security or privacy issues or questions related to this model, please reach out to our team at [support@biohub.org](mailto:support@biohub.org).
 
+### Citation
+
+Coming soon.
+
 ## Acknowledgements
 
 Many people on the Biohub AI Research team and prior EvolutionaryScale team contributed to the development of this model. It would not have been possible without them.
 
-
+[image1]: folding_evals.png