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.

Induced-fit docking

Pass rowan.InducedFitSettings() to induced_fit_settings when nearby receptor side chains may need to relax around the ligand. Induced fit requires Vina or QVina2 and adds substantial work beyond rigid docking.

Results contain both rigid and induced-receptor poses ranked by induced_fit_score. Use get_induced_receptor() or get_induced_receptors() to retrieve the relaxed receptors associated with induced poses. See examples/induced_fit_docking.py for a complete example.

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, receptor_strain: float | None = None, geometry_penalty: float | None = None, induced_fit_score: float | None = None, induced_receptor_pdb: ProteinUUID | None = None)

A docking pose with its scores.

Attributes:

Name	Type	Description
`score`	`float`	docking score in kcal/mol
`posebusters_valid`	`bool \| None`	PoseBusters validity, or `None` when not evaluated
`mmgbsa_score`	`float \| None`	MM/GBSA binding free energy estimate in kcal/mol
`receptor_strain`	`float \| None`	induced receptor strain relative to its locally relaxed unbound state, in kcal/mol. Only populated when induced-fit docking is enabled; zero for rigid poses
`geometry_penalty`	`float \| None`	PoseBusters failure penalty used to rank induced-fit results: 0 for a passing pose, 100 for a failing pose, and `None` when induced-fit docking is disabled
`induced_fit_score`	`float \| None`	composite score used to rank rigid and induced-fit poses together, in kcal/mol. Only populated when induced-fit docking is enabled
`induced_receptor_pdb`	`ProteinUUID \| None`	UUID of the relaxed receptor used for induced-fit redocking. Only set for poses from an induced receptor

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`	index is out of range
`ValueError`	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`	index is out of range
`ValueError`	complex has no structure UUID

get_complexes

get_complexes() -> list[Protein]

Fetch all protein-ligand complex structures.

Returns:

Type	Description
`list[Protein]`	proteins for each complex (ordered by score)

get_induced_receptor

get_induced_receptor(index: int = 0) -> Protein

Fetch the relaxed receptor structure used for an induced-fit pose's redocking.

Only populated for poses produced by the induced-fit phase (see DockingScore.induced_receptor_pdb); rigid poses share the original receptor.

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 induced (relaxed) receptor structure

Raises:

Type	Description
`IndexError`	index is out of range
`ValueError`	pose has no induced receptor UUID

get_induced_receptors

get_induced_receptors() -> list[Protein]

Fetch all induced (relaxed) receptor structures.

Returns:

Type	Description
`list[Protein]`	proteins for each induced-fit pose's receptor (ordered by
`list[Protein]`	score). Poses without an induced receptor are omitted

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, induced_fit_settings: InducedFitSettings | None = None, 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[DockingResult]

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`
`induced_fit_settings`	`InducedFitSettings \| None`	settings enabling induced-fit docking: soft-docks candidate poses, relaxes the receptor around each with restrained local minimization, and redocks into the relaxed receptor. `None` (default) disables it. Requires `docking_settings` to be `VinaSettings` with `executable="vina"` or `"qvina2"`	`None`
`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`	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[DockingResult]`	workflow object representing the submitted docking workflow

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

Docking

Induced-fit docking

Covalent docking

DockingScore dataclass

DockingResult dataclass

scores property

conformers property

best_pose property

get_pose

get_poses

get_complex

get_complexes

get_induced_receptor

get_induced_receptors

submit_docking_workflow

DockingScore `dataclass`

DockingResult `dataclass`

scores `property`

conformers `property`

best_pose `property`