Align AlphaFold2 model card with OFoldX

README.md

@@ -14,42 +14,27 @@ Pre-trained model for protein structure prediction from amino-acid sequences, mu
 
 ## Disclaimer
 
-This is an unofficial OFoldX implementation of
-[AlphaFold 2](https://doi.org/10.1038/s41586-021-03819-2) by John Jumper,
-Richard Evans, Alexander Pritzel, Tim Green, Michael Figurnov, Olaf
-Ronneberger, Kathryn Tunyasuvunakool, Russ Bates, Augustin Žídek, Anna
-Potapenko, Alex Bridgland, Clemens Meyer, Simon A. A. Kohl, Andrew J. Ballard,
-Andrew Cowie, Bernardino Romera-Paredes, Stanislav Nikolov, and Rishub Jain,
-and [AlphaFold-Multimer](https://doi.org/10.1101/2021.10.04.463034). The
-upstream authors did not write, review, or endorse this implementation or
-model card. The official implementation is maintained by
-[Google DeepMind](https://github.com/google-deepmind/alphafold).
+This is an UNOFFICIAL implementation of the [Highly accurate protein structure prediction with AlphaFold](https://doi.org/10.1038/s41586-021-03819-2) by John Jumper, et al.
+
+The OFFICIAL repository of AlphaFold 2 is at [google-deepmind/alphafold](https://github.com/google-deepmind/alphafold).
+
+**The team releasing AlphaFold 2 did not write this model card for this model so this model card has been written by the OFoldX team.**
 
 ## Model Details
 
-AlphaFold 2 predicts protein three-dimensional structure from amino-acid
-sequence, multiple-sequence alignments, and optional structural templates. Its
-Evoformer jointly updates MSA and residue-pair representations before an
-invariant-point-attention Structure Module produces backbone frames, side-chain
-angles, atomic coordinates, and confidence estimates. AlphaFold-Multimer extends
-the same design with paired MSAs and chain-relative features for protein
-complexes.
+AlphaFold 2 jointly updates MSA and residue-pair representations with an Evoformer, then uses an
+invariant-point-attention structure module to predict backbone frames, side-chain angles, atomic coordinates, and
+confidence. AlphaFold-Multimer extends the model with paired MSAs and chain-relative features for protein complexes.
+
+Please refer to the [Training Details](#training-details) section for more information on the training process.
 
 ### Variants
 
-- **[oteam/alphafold2](https://huggingface.co/oteam/alphafold2)**: AlphaFold 2 monomer model with pLDDT confidence.
-- **CASP14 five-model Pipeline**: The fixed released `model_1` through
-  `model_5` monomer ensemble. Every checkpoint uses eight input ensembles; one
-  shared processed input is evaluated sequentially, all samples are
-  stable-ranked by mean pLDDT, and the concrete Pipeline owns optional Amber
-  relaxation of none, the best prediction, or all predictions.
-- **[oteam/alphafold2-ptm](https://huggingface.co/oteam/alphafold2-ptm)**: Monomer model with predicted aligned error and pTM confidence.
-- **AF2 initial guess**: Distinct monomer/pTM Model--Processor--Pipeline pair
-  using `model_1_ptm` weights. It seeds the first recycled atom37 `prev_pos`
-  state from an in-memory target--binder structure without initializing
-  Structure Module frames. Its all-GAP template retains backbone/CB geometry
-  for every chain and masks target--binder template pair features.
-- **[oteam/alphafold2-multimer](https://huggingface.co/oteam/alphafold2-multimer)**: AlphaFold-Multimer for multi-chain protein complexes.
+- **[oteam/alphafold2](https://huggingface.co/oteam/alphafold2)**: Monomer structure prediction with pLDDT confidence.
+- **[oteam/alphafold2-ptm](https://huggingface.co/oteam/alphafold2-ptm)**: Monomer prediction with PAE and pTM confidence.
+- **[oteam/alphafold2-multimer](https://huggingface.co/oteam/alphafold2-multimer)**: Multi-chain protein complex prediction.
+- **[oteam/alphafold2-casp14](https://huggingface.co/oteam/alphafold2-casp14)**: The five-model CASP14 protocol with eight input ensembles per checkpoint.
+- **[oteam/alphafold2-initial-guess](https://huggingface.co/oteam/alphafold2-initial-guess)**: The `model_1_ptm` initial-guess evaluator used by PXDesign.
 
 ### Model Specification
 
@@ -66,118 +51,106 @@ complexes.
 - **Upstream attribution**: AlphaFold 2 parameters © 2022 DeepMind Technologies Limited; [parameter license](https://github.com/google-deepmind/alphafold#model-parameters)
 - **Upstream source revision**: `c77e5d2a8961d1a353632c462914ff0a32a950f6`
 - **Code**: [ofoldx.models.alphafold2](https://github.com/OTeam-AI4S/OFoldX/tree/main/ofoldx/models/alphafold2)
-- **Paper**: [Highly accurate protein structure prediction with AlphaFold](https://doi.org/10.1038/s41586-021-03819-2)
-- **Multimer Paper**: [Protein complex prediction with AlphaFold-Multimer](https://doi.org/10.1101/2021.10.04.463034)
-- **Developed by**: John Jumper, Richard Evans, Alexander Pritzel, Tim Green,
-  Michael Figurnov, Olaf Ronneberger, Kathryn Tunyasuvunakool, Russ Bates,
-  Augustin Žídek, Anna Potapenko, Alex Bridgland, Clemens Meyer, Simon A. A.
-  Kohl, Andrew J. Ballard, Andrew Cowie, Bernardino Romera-Paredes,
-  Stanislav Nikolov, Rishub Jain, Jonas Adler, Trevor Back, Stig Petersen,
-  David Reiman, Ellen Clancy, Michal Zielinski, Martin Steinegger,
-  Michalina Pacholska, Tamas Berghammer, Sebastian Bodenstein, David
-  Silver, Oriol Vinyals, Andrew W. Senior, Koray Kavukcuoglu, Pushmeet
-  Kohli, and Demis Hassabis
-- **Model type**: MSA- and template-conditioned protein structure predictor with an Evoformer trunk and invariant-point-attention structure module
+- **Paper**: [Highly accurate protein structure prediction with AlphaFold](https://doi.org/10.1038/s41586-021-03819-2); [Protein complex prediction with AlphaFold-Multimer](https://doi.org/10.1101/2021.10.04.463034)
+- **Developed by**: John Jumper, Richard Evans, Alexander Pritzel, Tim Green, Michael Figurnov, Olaf Ronneberger,
+  Kathryn Tunyasuvunakool, Russ Bates, Augustin Žídek, Anna Potapenko, Alex Bridgland, Clemens Meyer, Simon A. A. Kohl,
+  Andrew J. Ballard, Andrew Cowie, Bernardino Romera-Paredes, Stanislav Nikolov, Rishub Jain, Jonas Adler, Trevor Back,
+  Stig Petersen, David Reiman, Ellen Clancy, Michal Zielinski, Martin Steinegger, Michalina Pacholska, Tamas Berghammer,
+  Sebastian Bodenstein, David Silver, Oriol Vinyals, Andrew W. Senior, Koray Kavukcuoglu, Pushmeet Kohli, and Demis
+  Hassabis
+- **Model type**: MSA- and template-conditioned protein structure predictor with an Evoformer trunk and
+  invariant-point-attention structure module
 - **Original Repository**: [google-deepmind/alphafold](https://github.com/google-deepmind/alphafold)
 
-## Feature and geometry contract
-
-All public model coordinate boundaries consume an explicit finite numerical projection. Unavailable values are selected out under the declared mask before arithmetic or dtype conversion and have zero coordinate derivatives. Active nonfinite values are invalid requests; finite values outside the model dtype range are an unsupported numeric range. Normalization returns the same input carrier type without changing canonical membership, source masks, or source precision. Decode uses prepared atom correspondences. APIs without an availability mask require complete finite model fields.
-
-The model's atom37/atom14 slots and pseudo-beta convention belong to its residue vocabulary. Template observations and initial model coordinates have separate masks. Physical backbone frames additionally require available, noncollinear defining atoms. Relaxation and its linear-neighbor diagnostics admit only the actual closed standard linear protein graph; sequence labels alone do not certify this chemistry. The clash calculation exempts the admitted peptide C–N pair and has no blanket exemption for slot 5 or putative disulfides.
-
 ## Usage
 
-The model depends on the [`ofoldx`](https://github.com/OTeam-AI4S/OFoldX)
-library. Install it with pip:
+The model file depends on the [`ofoldx`](https://ofoldx.valhalla.technology/) library. You can install it using pip:
 
 ```bash
 pip install ofoldx
 ```
 
-### Structure Prediction
+### Direct Use
+
+#### Structure Prediction
 
-Load the concrete folding Pipeline:
+You can use this model directly with a pipeline for protein structure prediction:
 
 ```python
 import ofoldx
-
 from ofoldx.io import read_structure
 
 structure, report = read_structure("input.cif")
 pipeline = ofoldx.pipeline("fold", model="oteam/alphafold2")
-output = pipeline.fold(structure)
+result = pipeline(structure, seed=7)
 ```
 
-Every prediction is decoded onto the input `Structure`: each residue's atom37
-atoms get predicted coordinates in a new frame, and atoms the model does not
-predict (ligands, hydrogens, a terminal OXT) have none.
-
-The Pipeline is callable with the same arguments as `fold`. For staged execution:
+The result contains predicted structures and confidence values. Each prediction uses a new coordinate frame;
+unpredicted atoms, including ligands, hydrogens, and terminal OXT, have unavailable coordinates.
 
-```python
-prepared = pipeline.prepare(structure)
-raw = pipeline.forward(prepared.input, num_samples=1)
-result = pipeline.postprocess(prepared, raw)
-```
+### Downstream Use
 
-An ordinary Pipeline returns raw `AlphaFold2Output` values from `forward`.
-The CASP14 ensemble returns checkpoint-labelled predictions; its `postprocess`
-ranks them and accepts `models_to_relax`, `platform`, and `platform_properties`.
-Stages describe the operation and do not prescribe CPU or GPU placement.
+#### CASP14 Ensemble
 
-Load the CASP14 five-model ensemble through the same high-level API:
+You can use the five-model ensemble to rank predictions and optionally relax the best structure:
 
 ```python
+import ofoldx
+from ofoldx.io import read_structure
+
+structure, report = read_structure("input.cif")
 pipeline = ofoldx.pipeline("fold", model="oteam/alphafold2-casp14")
-result = pipeline.fold(structure, num_samples=1, models_to_relax="best", platform="CPU")
+result = pipeline(structure, num_samples=1, models_to_relax="best", platform="CPU", seed=7)
 best = result.best
 ```
 
-`result.ranked` retains every prediction, its official checkpoint name,
-zero-based sample index, and any Amber relaxation result. Equal mean-pLDDT
-values retain checkpoint and sample generation order.
-
-The initial-guess variant consumes a sequence-assigned target--binder
-`Structure` and an explicit binder instance:
+Each checkpoint evaluates eight input ensembles from shared preparation. `result.ranked` retains checkpoint names,
+sample indices, and relaxation results; equal mean-pLDDT scores retain generation order. Amber relaxation requires
+[OpenMM](https://docs.openmm.org/latest/userguide/application/01_getting_started.html) and
+[PDBFixer](https://github.com/openmm/pdbfixer), installed in the same environment:
 
-```python
-initial_guess_pipeline = ofoldx.pipeline("fold", model="oteam/alphafold2-initial-guess")
-result = initial_guess_pipeline.fold(structure, binder_instance_id="binder", num_recycles=4)
+```bash
+conda install -c conda-forge openmm pdbfixer
 ```
 
-Amber relaxation also remains an independently callable family operation over a
-decoded structure.
+Relaxation requires a closed, standard linear protein graph. Relaxed coordinates replace experimental coordinate
+metadata; source identity and independent chemical facts are retained. Ordinary unrelaxed prediction needs neither
+additional package.
 
-Install [OpenMM](https://docs.openmm.org/latest/userguide/application/01_getting_started.html)
-and [PDBFixer](https://github.com/openmm/pdbfixer) in the same environment before
-requesting Amber relaxation, including `models_to_relax="best"`:
+#### Initial-Guess Evaluation
 
-```bash
-conda install -c conda-forge openmm pdbfixer
+You can evaluate a sequence-assigned target-binder complex using its existing coordinates as the initial guess:
+
+```python
+import ofoldx
+from ofoldx.io import read_structure
+
+structure, report = read_structure("target_binder.cif")
+pipeline = ofoldx.pipeline("fold", model="oteam/alphafold2-initial-guess")
+result = pipeline(structure, binder_instance_id="binder", num_recycles=4, seed=7)
 ```
 
-These packages are required for the requested relaxation operation. The folding
-Model and the default unrelaxed prediction use the ordinary OFoldX installation.
+The input must contain the named binder instance. The initial guess seeds recycled atom37 positions; the dedicated
+processor retains the target-binder template masking used by PXDesign.
+
+See the [pipeline guide](https://github.com/OTeam-AI4S/OFoldX/blob/main/ofoldx/pipelines/README.md) for staged execution and composition.
 
 ## Training Details
 
+AlphaFold 2 is trained for protein structure prediction with structural and masked-MSA objectives.
+
 ### Training Data
 
-Refer to the AlphaFold 2 and AlphaFold-Multimer papers and supplementary
-materials for the upstream training corpora and data construction. OFoldX does
-not redistribute those corpora, sequence databases, or template databases.
+The AlphaFold 2 and AlphaFold-Multimer papers describe the upstream protein structure, sequence, and template corpora.
+OFoldX does not redistribute those corpora or databases.
 
 ### Training Procedure
 
-The upstream monomer models use recycling, MSA and template evidence, and the
-released auxiliary losses; the pTM variants were fine-tuned with the
-predicted-aligned-error head. AlphaFold-Multimer adds paired-MSA and
-chain-relative features and interface confidence.
+The upstream models use recycling and structural and auxiliary objectives. The pTM variants were fine-tuned with a
+predicted-aligned-error head; AlphaFold-Multimer adds paired-MSA and chain-relative features and interface confidence.
 
-OFoldX preserves a differentiable final recycle and exposes a masked-MSA
-reconstruction loss covering that recycle. It is not the complete released
-structural and auxiliary-loss program; MSA, template, and sequence-database
+OFoldX exposes a differentiable final recycle and a masked-MSA reconstruction objective for that recycle. This does not
+reproduce the complete upstream structural and auxiliary-loss training program. MSA, template, and sequence-database
 generation remain caller-owned.
 
 ## Citation
@@ -197,20 +170,33 @@ generation remain caller-owned.
 For AlphaFold-Multimer predictions, also cite
 [Protein complex prediction with AlphaFold-Multimer](https://doi.org/10.1101/2021.10.04.463034).
 
+> [!NOTE]
+> The artifacts distributed in this repository are part of the OFoldX project.
+> If OFoldX supports your research, please cite the OFoldX project as follows:
+
+```bibtex
+@software{chen2026ofoldx,
+  author = {Chen, Zhiyuan},
+  title  = {OFoldX},
+  year   = {2026},
+  url    = {https://github.com/OTeam-AI4S/OFoldX},
+}
+```
+
 ## Contact
 
-Please use [OFoldX GitHub issues](https://github.com/OTeam-AI4S/OFoldX/issues)
-for questions about this implementation or model card. Questions about the
-original models should be directed to the upstream AlphaFold authors.
+Please use GitHub issues of [OFoldX](https://github.com/OTeam-AI4S/OFoldX/issues) for any questions or comments on the model implementation or model card.
+
+Please contact the authors of the [AlphaFold 2 paper](https://doi.org/10.1038/s41586-021-03819-2) for questions or comments on the paper/model.
 
 ## License
 
 The model weights, implementation, configuration, and documentation distributed by OFoldX are licensed under the
 [GNU Affero General Public License](license.md).
 
-For additional terms and clarifications, please refer to our [License FAQ](license-faq.md).
+For additional terms and clarifications, please refer to our
+[License FAQ](license-faq.md).
 
 ```spdx
 SPDX-License-Identifier: AGPL-3.0-or-later
 ```
-