Protein Cofolding

Protein cofolding workflow - predict protein-protein and protein-ligand complexes.

CofoldingScores dataclass

CofoldingScores(ptm: float | None = None, iptm: float | None = None, avg_lddt: float | None = None, confidence_score: float | None = None)

Confidence scores for a cofolding prediction.

Attributes:

Name	Type	Description
ptm	float | None	predicted TM-score, overall structure confidence (0-1, higher is better)
iptm	float | None	interface pTM, inter-chain packing confidence (0-1, higher is better)
avg_lddt	float | None	mean per-residue pLDDT, local atomic accuracy (0-1, higher is better)
confidence_score	float | None	overall aggregate confidence in the prediction (0-1, higher is better)

AffinityScore dataclass

AffinityScore(pred_value: float | None = None, pred_value1: float | None = None, pred_value2: float | None = None, probability_binary: float | None = None, probability_binary1: float | None = None, probability_binary2: float | None = None, binding_confidence: float | None = None, optimization_score: float | None = None)

Predicted binding affinity scores.

Every field is optional; which ones a given run populates depends on the cofolding model. In current runs Boltz-2 fills the pred_value and probability_binary fields while Boltz-2.1 fills binding_confidence and optimization_score, but the schema does not guarantee this split.

Attributes:

Name	Type	Description
pred_value	float | None	predicted pIC50, -log10(IC50 in M); higher means stronger binding (ensemble average of the two affinity heads)
pred_value1	float | None	predicted pIC50 from affinity head 1
pred_value2	float | None	predicted pIC50 from affinity head 2
probability_binary	float | None	predicted probability (0-1) that the ligand binds its target; higher is better (ensemble average of the two affinity heads)
probability_binary1	float | None	binding probability (0-1) from affinity head 1
probability_binary2	float | None	binding probability (0-1) from affinity head 2
binding_confidence	float | None	predicted probability (0-1, higher is better) that the molecule or binder is a true binder rather than a decoy. Primary metric for hit discovery (computed when binding is requested)
optimization_score	float | None	binding-strength ranking derived from the model's predicted log(IC50) affinity; higher means stronger predicted binding. Use to rank-order likely binders during lead optimization (computed when binding is requested)

CofoldingResult dataclass

CofoldingResult(scores: CofoldingScores | None = None, affinity_score: AffinityScore | None = None, strain: float | None = None, mmgbsa_score: float | None = None, posebusters_valid: bool | None = None, lddt: list[float] | None = None, pose_uuid: str | None = None, predicted_structure_uuid: str | None = None, predicted_refined_structure_uuid: str | None = None)

Single cofolding prediction result.

Attributes:

Name	Type	Description
scores	CofoldingScores | None	confidence scores for the prediction
affinity_score	AffinityScore | None	predicted binding affinity (if computed)
strain	float | None	ligand strain energy (if computed)
mmgbsa_score	float | None	MM/GBSA binding free energy estimate in kcal/mol (if computed)
posebusters_valid	bool | None	whether the pose passes PoseBusters validation
lddt	list[float] | None	per-residue LDDT confidence scores
pose_uuid	str | None	UUID of the pose
predicted_structure_uuid	str | None	UUID of the predicted structure
predicted_refined_structure_uuid	str | None	UUID of the refined structure (if refinement was run)

ProteinCofoldingResult dataclass

ProteinCofoldingResult(workflow_data: dict[str, Any], workflow_type: str, workflow_uuid: str, complete: bool = True)

Bases: WorkflowResult

Result from a protein-cofolding workflow.

scores property

scores: CofoldingScores | None

Confidence scores for the primary prediction.

affinity_score property

affinity_score: AffinityScore | None

Predicted binding affinity for the primary prediction.

strain property

strain: float | None

Ligand strain energy for the primary prediction.

posebusters_valid property

posebusters_valid: bool | None

Whether the primary pose passes PoseBusters validation.

lddt property

lddt: list[float] | None

Per-residue LDDT confidence scores for the primary prediction.

predicted_structure_uuid property

predicted_structure_uuid: str | None

UUID of the predicted structure.

predicted_refined_structure_uuid property

predicted_refined_structure_uuid: str | None

UUID of the refined structure (if pose refinement was enabled).

predictions property

predictions: list[CofoldingResult]

All cofolding predictions.

cofolding_results property

cofolding_results: list[CofoldingResult]

Alias for predictions (matches API response field name).

messages property

messages: list[Message]

Any messages or warnings from the workflow (e.g., stereochemistry issues).

get_predicted_structure

get_predicted_structure() -> Protein | None

Fetch the predicted structure as a Protein object.

Note

Makes one API call on first access. Results are cached. Call clear_cache() to refresh.

get_refined_structure

get_refined_structure() -> Protein | None

Fetch the refined structure as a Protein object (if available).

Note

Makes one API call on first access. Results are cached. Call clear_cache() to refresh.

submit_protein_cofolding_workflow

submit_protein_cofolding_workflow(initial_protein_sequences: list[str] | list[ProteinSequence] | None = None, initial_dna_sequences: list[str | DNASequence] | None = None, initial_rna_sequences: list[str | RNASequence] | None = None, initial_smiles_list: list[str] | None = None, ligand_binding_affinity_index: int | None = None, use_msa_server: bool = True, use_potentials: bool = False, contact_constraints: list[ContactConstraint] | None = None, pocket_constraints: list[PocketConstraint] | None = None, bond_constraints: list[BondConstraint] | None = None, templates: list[CofoldingTemplate] | None = None, num_samples: int | None = None, compute_strain: bool = False, do_pose_refinement: bool = False, name: str = 'Protein-Ligand Co-Folding', model: CofoldingModel | str = CofoldingModel.BOLTZ_2, folder_uuid: str | None = None, folder: Folder | None = None, max_credits: int | None = None, webhook_url: str | None = None, is_draft: bool = False) -> Workflow[ProteinCofoldingResult]

Submits a protein-cofolding workflow to the API.

Predicts the 3D structure of protein-protein, protein-ligand, protein-DNA, protein-RNA, or other biomolecular complexes.

See examples/protein_cofolding_with_constraints.py for a worked example of using ConstraintTarget, ContactConstraint, and PocketConstraint (Boltz models only).

Parameters:

Name	Type	Description	Default
initial_protein_sequences	list[str] | list[ProteinSequence] | None	protein sequences to be cofolded	None
initial_dna_sequences	list[str | DNASequence] | None	DNA sequences to be cofolded	None
initial_rna_sequences	list[str | RNASequence] | None	RNA sequences to be cofolded	None
initial_smiles_list	list[str] | None	list of SMILES strings for the ligands to be cofolded with	None
ligand_binding_affinity_index	int | None	index of the ligand for which to compute the binding affinity	None
use_msa_server	bool	whether to use the MSA server for the computation	True
use_potentials	bool	whether to use potentials (inference-time steering) with Boltz	False
contact_constraints	list[ContactConstraint] | None	Boltz contact constraints between two tokens	None
pocket_constraints	list[PocketConstraint] | None	Boltz pocket constraints between a binder and contact tokens	None
bond_constraints	list[BondConstraint] | None	Boltz-2 covalent bond constraints between two atoms. Incompatible with pose refinement and strain calculation	None
templates	list[CofoldingTemplate] | None	structural templates to guide prediction (Boltz-2/2.1 or OpenFold-3 only)	None
num_samples	int | None	number of diffusion samples to generate. If None, uses the model default	None
compute_strain	bool	whether to compute the strain of the pose. Requires do_pose_refinement. (if pose_refinement is enabled)	False
do_pose_refinement	bool	whether to optimize non-rotatable bonds in output poses	False
name	str	name of the workflow	'Protein-Ligand Co-Folding'
model	CofoldingModel | str	model to use for the computation. Boltz-2.1 runs via Boltz's hosted API (slower than the locally-run models) and reports a different set of affinity metrics than Boltz-2 (see AffinityScore). DeCAF Boltz does not support nucleic acids, templates, or binding-affinity prediction	BOLTZ_2
folder_uuid	str | None	UUID of the folder to store the workflow in	None
folder	Folder | None	destination folder	None
max_credits	int | None	maximum credits for the workflow	None
webhook_url	str | None	URL that Rowan will POST to when the workflow completes	None
is_draft	bool	save as a draft without starting execution	False

Returns:

Type	Description
Workflow[ProteinCofoldingResult]	submitted workflow

Raises:

Type	Description
ValueError	no protein, DNA, or RNA sequences are provided
HTTPStatusError	request to the API fails