oteam/oinvfold-ligand

OInvFold

Native PyTorch implementation of the four released OInvFold inverse-folding checkpoints for protein, DNA, RNA, and ligand backbones.

Disclaimer

This is an unofficial OFoldX implementation of the OInvFold models released with ODesign. The upstream authors did not write, review, or endorse this implementation or model card.

Model Details

OInvFold is an independently runnable graph model family. It predicts polymer identities or ligand atom elements from fixed coordinates; it is not an alias for ProteinMPNN, LigandMPNN, or gRNAde.

Variants

Checkpoint	Model and Processor pair	Decoded output
Protein	OInvFoldPolymerModel and OInvFoldPolymerProcessor(modality="protein")	Protein sequence and a Structure with only design-masked residue identities replaced
DNA	OInvFoldPolymerModel and OInvFoldPolymerProcessor(modality="dna")	DNA sequence and canonical nucleotide identities
RNA	OInvFoldPolymerModel and OInvFoldPolymerProcessor(modality="rna")	RNA sequence and canonical nucleotide identities
Ligand	OInvFoldLigandModel and OInvFoldLigandProcessor	Ordered atom-element assignments with unresolved bonds

Protein, DNA, and RNA share the registered oinvfold graph and its 25 released output columns, read on the 72 canonical classes. Each repository's Model configuration fixes the classes standing for the shared nucleic columns, and its Processor configuration the coordinate convention and allowed chemistry. Ligand uses the distinct oinvfold_ligand graph and released 37-token element vocabulary.

Decoding and Scores

OInvFoldPolymerPipeline.design and OInvFoldLigandPipeline.design expose the released decoding controls without conflating them:

• With use_beam=False, decoding is greedy and returns one candidate; num_beams does not request additional greedy candidates.
• With use_beam=True, num_beams is the beam width and controls the number of returned supported candidates; explicitly excluded classes do not fill beam width.
• Candidate selection always uses the released unscaled logits and raw log probabilities.
• probability_temperature changes only the returned probabilities view. It does not change the selected greedy or beam sequences.
• Every candidate names both total_log_probability and mean_log_probability; OFoldX does not collapse the upstream scoring conventions into one ambiguous score.

Raw results retain logits, raw log probabilities, and temperature-view probabilities.

Preparation reads one polymer instance through the shared contract: its rows are the residues of the modality in a polymer instance whose read atoms (N, CA, C, O; or seven backbone atoms and the glycosidic N9, else N1) are all observed, and each row's token is its canonical class read as the released column: either nucleic type's A, C and G read the shared columns, inosine reads A, and T and U read the modality's pyrimidine column, as the released preparation does. The model's class axis is the 72 canonical classes; logits outside the released 25 output columns are -inf, so log probabilities equal the released ones. A training crop keeps every designed row unless every row is designed. Each candidate's target is built by the shared design producer: a decoded class that encodes the source occurrence retains it (MSE decoded as M stays MSE), and every other designed position is replaced by the class's standard component with its backbone kept as guide coordinates. The loss refuses a scored class the model does not predict.

Local geometric frames require noncoincident, noncollinear defining points. Unsupported frames are refused before feature construction. Virtual global nodes use the coordinate centroid and declared Cartesian axes; those axes do not claim a uniquely inferred molecular orientation. Both polymer and ligand global edges carry the actual relative rotations and translations. The upstream polymer indexing that produced constant identity/zero global features is not reproduced; checkpoint predictions therefore differ, and inference quality needs separate evaluation.

Ligand Identity Boundary

The ligand Pipeline consumes caller-owned coordinates and slot identifiers, or the observed atoms of one ligand instance of a known input Structure. Its candidates retain slot identifiers, coordinates, predicted elements, and per-atom probabilities, while bond_state remains "unresolved". Element assignment alone does not determine bond topology, formal charge, or a canonical chemical-component identity, so the Pipeline never fabricates a Molecule or generated-atom Structure.

Usage

Install OFoldX:

pip install ofoldx

Polymer Inverse Folding

Load the checkpoint repository whose Processor has the desired protein, DNA, or RNA modality:

import ofoldx
from ofoldx.io import read_structure

backbone, report = read_structure("backbone.cif")
pipeline = ofoldx.pipeline("design", model="oteam/oinvfold-protein")
result = pipeline.design(backbone, use_beam=True, num_beams=4, probability_temperature=0.8)

Ligand Element Assignment

For a known canonical ligand, design_from_structure reads the observed atoms of one ligand instance while keeping decoded connectivity unresolved:

import ofoldx
from ofoldx.io import read_structure

ligand, report = read_structure("ligand.cif")
pipeline = ofoldx.pipeline("design", model="oteam/oinvfold-ligand")
result = pipeline.design_from_structure(ligand)

Call pipeline.design(coordinates, slot_ids=(...)) instead when the coordinates belong to provisional atoms that do not yet have a canonical molecular graph.

Training Details

OFoldX preserves the checkpoint-backed encoder corruption and exposes the released masked polymer negative log likelihood as a training objective. Polymer and ligand encode/forward, and the polymer autoregressive operation, accept one optional torch.Generator that controls every per-block graph corruption draw. This objective covers polymer identity prediction only; ligand graphs carry no target atom identities. Ligand decoding assigns elements only; connectivity, formal charge, and canonical component identity remain unresolved.

Citation

Please cite the ODesign work and repository accompanying the released OInvFold checkpoints.

If OFoldX supports your research, also cite the OFoldX software:

@software{chen2026ofoldx,
  author = {Chen, Zhiyuan},
  title  = {OFoldX},
  year   = {2026},
  url    = {https://github.com/OTeam-AI4S/OFoldX},
}

Contact

Please use OFoldX GitHub issues for questions about this implementation or model card.

License

This model implementation is licensed under the GNU Affero General Public License.

SPDX-License-Identifier: AGPL-3.0-or-later

The Pipeline is callable and supports staged execution with prepare, forward, and postprocess. Prepared values retain the source and correspondence needed by the scientific result; the concrete signatures describe each stage's controls.

Converted checkpoint

This repository contains converted model parameters under apache-2.0; the original terms and notices are preserved in LICENSE. OFoldX implementation licensing is described separately in license.md and license-faq.md. Conversion changes parameter names and native tensor layout; the upstream authors do not endorse this implementation.

• https://huggingface.co/The-Institute-for-AI-Molecular-Design/OInvFold
• https://github.com/The-Institute-for-AI-Molecular-Design/ODesign/blob/main/LICENSE