--- 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 ```