| --- |
| tags: |
| - Biology |
| - Protein |
| - RNA |
| - DNA |
| - Structure Prediction |
| license: agpl-3.0 |
| library_name: ofoldx |
| pipeline_tag: other |
| --- |
| |
| # Protenix |
|
|
| Protenix is OFoldX's AlphaFold 3-shaped all-atom structure-prediction family for |
| proteins, nucleic acids, small molecules, and their complexes. OFoldX exposes |
| all ten released checkpoint variants through four exact |
| Model/Processor/Pipeline pairs. |
|
|
| ## Disclaimer |
|
|
| This is an unofficial OFoldX implementation of |
| [Protenix - Advancing Structure Prediction Through a Comprehensive AlphaFold3 Reproduction](https://doi.org/10.1101/2025.01.08.631967) |
| by Xinshi Chen and Yuxuan Zhang. The upstream authors did not write, review, or |
| endorse this implementation or model card. |
|
|
| The official repository is |
| [bytedance/Protenix](https://github.com/bytedance/Protenix). |
|
|
| ## Model Details |
|
|
| Protenix is an AlphaFold 3-style all-atom structure predictor for proteins, |
| nucleic acids, small molecules, ions, and their complexes. It combines atom and |
| token embeddings with an MSA-conditioned recycled Pairformer trunk, EDM |
| coordinate diffusion, and distogram and confidence heads. The constraint variant |
| adds learned pair biases for atom contacts, token contacts, pockets, and |
| substructures. |
|
|
| ### Variants |
|
|
| Conversion requires one of these exact identifiers; OFoldX does not infer the |
| variant from a filename or tensor shape: |
|
|
| - `protenix_base_default_v0.5.0` |
| - `protenix_base_constraint_v0.5.0` |
| - `protenix_mini_default_v0.5.0` |
| - `protenix_mini_tmpl_v0.5.0` |
| - `protenix_tiny_default_v0.5.0` |
| - `protenix_mini_esm_v0.5.0` |
| - `protenix_mini_ism_v0.5.0` |
| - `protenix_base_default_v1.0.0` |
| - `protenix_base_20250630_v1.0.0` |
| - `protenix-v2` |
|
|
| The variants map to ordinary registered pairs: |
|
|
| | Pair | Model, Processor, Pipeline | Released variants | |
| | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | |
| | Default (`protenix`) | `ProtenixModel`, `ProtenixProcessor`, `ProtenixPipeline` | base default v0.5, mini default, tiny default, mini ESM, and mini ISM | |
| | Template (`protenix_template`) | `ProtenixTemplateModel`, `ProtenixTemplateProcessor`, `ProtenixTemplatePipeline` | both base v1 releases and `protenix-v2` | |
| | Structure condition (`protenix_structure_condition`) | `ProtenixStructureConditionModel`, `ProtenixStructureConditionProcessor`, `ProtenixStructureConditionPipeline` | mini template v0.5 | |
| | Constraint (`protenix_constraint`) | `ProtenixConstraintModel`, `ProtenixConstraintProcessor`, `ProtenixConstraintPipeline` | base constraint v0.5 | |
|
|
| The two v1 releases share one graph and differ in weights. Mini ESM and mini ISM |
| also share one graph and package their selected ESM2 companion weights inside the |
| model artifact. The template pair owns the released template and RNA-MSA input |
| paths. The constraint pair exposes atom-contact, token-contact, and pocket |
| controls. Its fourth learned branch accepts a `Structure` through |
| `substructure=` and digitizes resolved token-center distances into the released |
| four-channel representation. |
|
|
| The mini template checkpoint is not an ordinary template model. Its distinct |
| pair accepts `structure_condition=` as an in-memory `Structure`, aligns resolved |
| representative-atom coordinates to the model token axis, and applies the |
| checkpoint's noisy-structure pair update on every recycling pass. |
| Direct `ProtenixNoisyStructureEmbedder` callers may enable its released |
| `add_noise` distance perturbation and supply a `torch.Generator` for that draw. |
|
|
| MSA pools are given per instance; those of protein and RNA chains of more than |
| four residues are paired by `ofoldx.msa.pair_msas` after any crop, and an exact |
| `MsaCollection` plan is used as given. The Processor keeps Protenix's |
| featurisation of the rows it is given: upstream's MSA letter classes (`B`, `Z`, |
| `U` as `D`, `E`, `C`; `J`, `O` as `X`), the profile and deletion mean over the |
| pool's unique unpaired rows, query-only rows for chains of at most four |
| residues, and the query in a non-protein chain's all-gap rows. Templates are |
| resolved by `ofoldx.templates.resolve_template`; each protein chain of more than |
| four residues takes up to four of them. |
|
|
| ### Links |
|
|
| - **Code**: [ofoldx.models.protenix](https://github.com/OTeam-AI4S/OFoldX/tree/main/ofoldx/models/protenix) |
| - **Paper**: [Protenix - Advancing Structure Prediction Through a Comprehensive AlphaFold3 Reproduction](https://doi.org/10.1101/2025.01.08.631967) |
| - **Developed by**: Xinshi Chen, Yuxuan Zhang, Chan Lu, Wenzhi Ma, Jiaqi Guan, |
| Chengyue Gong, Jincai Yang, Hanyu Zhang, Ke Zhang, Shenghao Wu, Kuangqi |
| Zhou, Yanping Yang, Zhenyu Liu, Lan Wang, Bo Shi, Shaochen Shi, and Wenzhi |
| Xiao |
| - **Model type**: Pairformer-based all-atom biomolecular structure predictor with optional learned constraints |
| - **Original Repository**: [bytedance/Protenix](https://github.com/bytedance/Protenix) |
|
|
| ## Feature and geometry contract |
|
|
| Preparation follows the shared contract (`ofoldx.models.preparation`): the |
| layout, gating, reference conformers and constraint features come from the one |
| OFoldX rule each; represented atoms need known elements and formal charges. Ranking combines `0.8 * ipTM + 0.2 * pTM - 100 * has_clash`. |
| This implementation has no disorder estimator and reports no disorder value. |
|
|
| 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. |
|
|
| Every token's class is its canonical class (72 classes); the checkpoint's residue |
| and profile axes are regenerated onto them at conversion. `token_bonds` are |
| upstream inference's: covalent bonds between tokens except the junctions of chain |
| neighbours. Decode writes the prepared slots back onto the target with |
| `decode_coordinates` (every atom regenerated in a new frame). |
|
|
| ## Usage |
|
|
| The model depends on the [`ofoldx`](https://github.com/OTeam-AI4S/OFoldX) |
| library. Install it with pip: |
|
|
| ```bash |
| pip install ofoldx |
| ``` |
|
|
| ### Structure Prediction |
|
|
| Load the concrete folding Pipeline: |
|
|
| ```python |
| import ofoldx |
| |
| pipeline = ofoldx.pipeline("fold", model="oteam/protenix") |
| output = pipeline.fold(structure) # a Structure, read or constructed |
| ``` |
|
|
| The Pipeline is callable with the same arguments as `fold`. All four registered pairs |
| prepare a `ProtenixPipelineInput` holding the `Prepared` task and its TFG |
| guidance policy. Staged execution: |
|
|
| ```python |
| import numpy as np |
| import torch |
| |
| prepared = pipeline.prepare(structure, generator=np.random.default_rng(42)) |
| generator = torch.Generator(device=pipeline.processor.device).manual_seed(42) |
| raw = pipeline.forward(prepared, num_samples=1, generator=generator) |
| result = pipeline.postprocess(prepared, raw) |
| ``` |
|
|
| For chemical guidance, pass `tfg_guidance=ProtenixTfgGuidance()` to `prepare`. |
| The prepared value retains that strategy for `forward`; execution does not take |
| a second guidance argument. `postprocess` decodes its retained `Prepared` task. |
|
|
| Template variants additionally accept `templates=`. Constraint repositories |
| route to `ProtenixConstraintPipeline`, whose concrete `fold` method accepts |
| `atom_contacts`, `token_contacts`, `pocket` and the released `substructure` |
| coordinate condition. Every concrete Protenix Pipeline accepts |
| per-call `num_recycles`, `num_sampling_steps`, `churn_rate`, and |
| `step_scale`; `None` uses the converted checkpoint configuration. |
|
|
| Training-free chemical guidance is a sampling-time operation. Pass the released |
| enabled configuration explicitly: |
|
|
| ```python |
| import ofoldx |
| |
| from ofoldx.models.protenix import ProtenixTfgGuidance |
| |
| pipeline = ofoldx.pipeline("fold", model="oteam/protenix") |
| output = pipeline.fold(structure, tfg_guidance=ProtenixTfgGuidance()) |
| ``` |
|
|
| Leaving `tfg_guidance` as `None` disables guidance. The guidance value exposes |
| the eight named chemical terms, schedules, Monte Carlo smoothing, and iteration |
| counts; setting one term to `None` removes that term. TFG is family-specific and |
| therefore remains an argument of the concrete Pipeline. |
|
|
| ## Training Details |
|
|
| `ProtenixProcessor.prepare_training(structure, ...)` returns the `Prepared` task |
| and its `StructureTarget`; `target_tensors` gives the `ProtenixStructureTarget`. Calling the model with |
| those values runs one differentiable stochastic denoising pass and returns |
| denoised coordinates, augmented target coordinates, sampled noise levels, the |
| distogram, and all four confidence logits. `model.denoise(...)` retains the |
| explicit noisy-coordinate operation, while `model.sample(...)` exposes raw |
| reverse-diffusion output. `ProtenixPipeline.postprocess(...)` maps that raw |
| output onto structures and public confidence metrics. |
|
|
| OFoldX exposes the shared EDM coordinate objective with |
| `compute_auxiliary_heads=False`. Its rigid-aligned MSE weights resolved atoms |
| equally and omits Protenix's molecule weights and `1/3` coordinate normalization. |
| It also omits smooth lDDT, distogram and confidence losses, and stage-dependent |
| loss composition. Full Protenix training uses an independent mini-rollout, |
| prediction-dependent truth matching, and detached trunk representations for |
| confidence supervision; computing auxiliary heads on the single denoising pass |
| does not supply that training data flow or those losses. |
|
|
| OFoldX reproduces the complete released Model graph, not Protenix's complete |
| four-stage training program. Dataset policy, objectives, stage weights, |
| condition-dropout curriculum, optimizer, and training orchestration remain the |
| responsibility of the training application. |
|
|
| ### Gradient checkpointing |
|
|
| `model.gradient_checkpointing_enable()` enables non-reentrant recomputation |
| with RNG preservation during training. |
| Checkpointing is inactive in evaluation and no-grad execution. |
|
|
| Ragged inputs with nonzero shared dropout support eager execution but cannot be |
| compiled with `fullgraph=True`. This also limits regional compilation of blocks |
| containing that dropout path. Dense regional compilation and eager ragged training are |
| separate supported paths. Unsupported compilation raises an error. |
|
|
| ## Citation |
|
|
| ```bibtex |
| @article{protenix2025advancing, |
| author = {ByteDance AML AI4Science Team and Chen, Xinshi and Zhang, Yuxuan and others}, |
| title = {Protenix - Advancing Structure Prediction Through a Comprehensive AlphaFold3 Reproduction}, |
| year = {2025}, |
| doi = {10.1101/2025.01.08.631967}, |
| journal = {bioRxiv} |
| } |
| ``` |
|
|
| If OFoldX supports your research, also cite the OFoldX software: |
|
|
| ```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 |
| upstream model should be directed to the authors of the |
| [Protenix paper](https://doi.org/10.1101/2025.01.08.631967). |
|
|
| ## License |
|
|
| The original model parameters are licensed under [Apache-2.0](LICENSE-weights.txt). OFoldX conversion changes parameter names, packing and vocabulary axes. |
|
|
| This model implementation is licensed under the [GNU Affero General Public License](https://www.gnu.org/licenses/agpl-3.0.en.html). |
|
|
| ```spdx |
| SPDX-License-Identifier: AGPL-3.0-or-later |
| ``` |
|
|
