Docking

The docking workflow supports Vina docking and both noncovalent and covalent gnina docking. Passing GninaSettings selects gnina; it does not by itself enable covalent docking.

Covalent docking

Set both covalent atom indices on GninaSettings to form a bond between a known ligand atom and protein atom. Covalent gnina docking requires scoring_function="vina".

Prepare the protein first, then resolve the reactive protein atom from the prepared structure. Protein preparation can change atom ordering and residue numbering.

Supply the ligand in its expected post-reaction, covalently bound topology; gnina does not infer the reaction. For a Michael acceptor C=CC(=O)NR, use the hydrogen-capped product CCC(=O)NR and select the terminal β-carbon as the covalent ligand atom.

prepared_protein = preparation_workflow.result().get_prepared_protein()
reactive_protein_atom_index = prepared_protein.get_atom_index(
    chain="A", residue=reactive_residue, atom="SG"
)
settings = rowan.GninaSettings(
    scoring_function="vina",
    covalent_ligand_atom_index=reactive_ligand_atom_index,
    covalent_protein_atom_index=reactive_protein_atom_index,
)
workflow = rowan.submit_docking_workflow(
    prepared_protein.uuid,
    pocket=[center, size],
    initial_molecule=ligand,
    docking_settings=settings,
)

Both indices are zero-based all-atom indices, including hydrogens. See examples/covalent_docking.py for a complete TG2 example.

PoseBusters validation is skipped for covalent poses. Their posebusters_valid value is None, meaning not evaluated rather than failed; do not use it to reject covalent poses.

Docking workflow - molecular docking to protein targets.

DockingScore dataclass

DockingScore(
    score: float,
    pose: str | None = None,
    complex_pdb: str | None = None,
    posebusters_valid: bool | None = None,
    strain: float | None = None,
    rmsd: float | None = None,
    mmgbsa_score: float | None = None,
)

A docking pose with its scores.

Parameters:

Name	Type	Description	Default
score	float	Docking score in kcal/mol.	required
posebusters_valid	bool | None	PoseBusters validity, or None when not evaluated.	None
mmgbsa_score	float | None	MM/GBSA binding free energy estimate in kcal/mol.	None

DockingResult dataclass

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

Bases: WorkflowResult

Result from a docking workflow.

scores property

scores: list[DockingScore]

List of docking scores with poses.

conformers property

conformers: list[str]

UUIDs of optimized conformers.

best_pose property

best_pose: Molecule

Best docked pose as a Molecule with 3D coordinates.

get_pose

get_pose(index: int = 0) -> Calculation

Fetch a docked ligand pose as a calculation with 3D coordinates.

Parameters:

Name	Type	Description	Default
index	int	Index of the pose (0-based, ordered by score). Default 0 (best).	0

Returns:

Type	Description
Calculation	Calculation containing the docked ligand molecule with 3D coordinates.

Raises:

Type	Description
IndexError	If index is out of range.
ValueError	If the pose has no UUID.

get_poses

get_poses() -> list[Calculation]

Fetch all docked ligand poses as calculations with 3D coordinates.

Returns:

Type	Description
list[Calculation]	List of Calculations for each pose (ordered by score).

get_complex

get_complex(index: int = 0) -> Protein

Fetch a protein-ligand complex structure.

Parameters:

Name	Type	Description	Default
index	int	Index of the pose (0-based, ordered by score). Default 0 (best).	0

Returns:

Type	Description
Protein	Protein object with the full protein-ligand complex.

Raises:

Type	Description
IndexError	If index is out of range.
ValueError	If the complex has no structure UUID.

get_complexes

get_complexes() -> list[Protein]

Fetch all protein-ligand complex structures.

Returns:

Type	Description
list[Protein]	List of Protein objects for each complex (ordered by score).

submit_docking_workflow

submit_docking_workflow(
    protein: Protein | ProteinUUID,
    pocket: list[list[float]],
    initial_molecule: StructureInput,
    docking_settings: VinaSettings | GninaSettings | None = None,
    executable: str | None = None,
    scoring_function: str | None = None,
    exhaustiveness: float | None = None,
    max_poses: int | None = None,
    do_csearch: bool = False,
    do_optimization: bool = False,
    do_pose_refinement: bool = True,
    name: str = "Docking Workflow",
    folder_uuid: str | None = None,
    folder: Folder | None = None,
    max_credits: int | None = None,
    webhook_url: str | None = None,
    is_draft: bool = False,
) -> Workflow

Submits a docking workflow to the API.

Parameters:

Name	Type	Description	Default
protein	Protein | ProteinUUID	Protein to dock. Can be input as a uuid or a Protein object.	required
pocket	list[list[float]]	Binding pocket as [[cx, cy, cz], [sx, sy, sz]] — center (Å) and box size (Å).	required
initial_molecule	StructureInput	Initial molecule to be docked.	required
docking_settings	VinaSettings | GninaSettings | None	settings controlling the docking engine, such as VinaSettings or GninaSettings. Set both GninaSettings covalent atom indices for covalent docking; leave both unset for noncovalent gnina docking. If provided, the deprecated executable, scoring_function, exhaustiveness, and max_poses are ignored.	None
executable	str | None	Deprecated, use docking_settings=VinaSettings(executable=...) instead. Which Vina docking implementation to use.	None
scoring_function	str | None	Deprecated, use docking_settings=VinaSettings(scoring_function=...) instead. Which Vina docking scoring function to use.	None
exhaustiveness	float | None	Deprecated, use docking_settings=VinaSettings(exhaustiveness=...) instead. Which exhaustiveness to employ.	None
max_poses	int | None	Deprecated, use docking_settings=VinaSettings(max_poses=...) instead. Maximum number of poses generated per input conformer.	None
do_csearch	bool	Whether to perform a conformational search on the ligand.	False
do_optimization	bool	Whether to perform an optimization on the ligand.	False
do_pose_refinement	bool	Whether or not to optimize output poses.	True
name	str	Name of the workflow.	'Docking Workflow'
folder_uuid	str | None	UUID of the folder to place the workflow in.	None
folder	Folder | None	Folder object to store the workflow in.	None
max_credits	int | None	Maximum number of credits to use for the workflow.	None
webhook_url	str | None	URL that Rowan will POST to when the workflow completes.	None
is_draft	bool	If True, submit the workflow as a draft without starting execution.	False

Returns:

Type	Description
Workflow	Workflow object representing the submitted docking workflow.

Raises:

Type	Description
requests.HTTPError	if the request to the API fails.