Relative Binding Free Energy Perturbation

RBFE perturbation workflow - run relative binding free energy FEP simulations.

RelativeBindingFreeEnergyResult `dataclass`

RelativeBindingFreeEnergyResult(dg: float, dg_err: float)

Aggregate RBFE outcome for a single ligand.

Parameters:

Name	Type	Description	Default
`dg`	`float`	Predicted binding free energy difference (kcal/mol).	required
`dg_err`	`float`	Uncertainty estimate on dg.	required

RelativeBindingFreeEnergyDiagnostics `dataclass`

RelativeBindingFreeEnergyDiagnostics(
    cycle_closure_rms: float | None,
    windows_completed: int | None,
    windows_failed: int | None,
)

Quality-control metrics from an RBFE simulation.

Parameters:

Name	Type	Description	Default
`cycle_closure_rms`	`float \| None`	RMS error across completed thermodynamic cycles.	required
`windows_completed`	`int \| None`	Count of successfully converged lambda windows.	required
`windows_failed`	`int \| None`	Count of failed lambda windows.	required

RelativeBindingFreeEnergyPerturbationResult `dataclass`

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

Bases: WorkflowResult

Result from a relative binding free energy perturbation workflow.

ligands `property`

ligands: dict[str, Molecule]

Ligand molecules keyed by identifier.

protein `property`

protein: Protein

Prepared protein structure used as the simulation target.

settings `property`

settings: TMDRBFESettings

FEP settings used for the simulation.

graph `property`

graph: RBFEGraph | None

The RBFE graph with per-edge results, or None if not constructed.

edges `property`

edges: list[RelativeBindingFreeEnergyGraphEdge]

Graph edges with per-edge FEP results.

ligand_dg_results `property`

ligand_dg_results: (
    dict[str, RelativeBindingFreeEnergyResult] | None
)

Per-ligand binding free energy results, or None if not yet computed.

diagnostics `property`

diagnostics: RelativeBindingFreeEnergyDiagnostics | None

Aggregate QC metrics from the FEP simulation.

download_edge_trajectories

download_edge_trajectories(
    edge_index: int,
    lambda_vals: list[float] | None = None,
    path: Path | str | None = None,
    name: str | None = None,
) -> Path

Download DCD trajectory files for a specific perturbation edge.

Parameters:

Name	Type	Description	Default
`edge_index`	`int`	Index of the edge (0-based, matching `edges` order).	required
`lambda_vals`	`list[float] \| None`	Lambda values to download. Defaults to all windows.	`None`
`path`	`Path \| str \| None`	Directory to save the file to. Defaults to current directory.	`None`
`name`	`str \| None`	Custom name for the tar.gz file (without extension).	`None`

Returns:

Type	Description
`Path`	Path to the downloaded tar.gz file.

Raises:

Type	Description
`IndexError`	If edge_index is out of range.
`HTTPError`	If the API request fails.

download_all_trajectories

download_all_trajectories(
    path: Path | str | None = None,
) -> list[Path]

Download DCD trajectory files for all perturbation edges.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str \| None`	Directory to save the files to. Defaults to current directory.	`None`

Returns:

Type	Description
`list[Path]`	List of paths to the downloaded tar.gz files, one per edge.

Raises:

Type	Description
`HTTPError`	If any API request fails.

write_ligand_results_csv

write_ligand_results_csv(
    path: Path | str = "ligand_results.csv",
) -> Path

Write per-ligand results to a CSV, matching the platform's ligand-results export.

Columns are Ligand name, ΔG, ΔG error, SMILES, quoted and BOM-prefixed for spreadsheet compatibility, identical to the download in the web UI.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str`	destination CSV path.	`'ligand_results.csv'`

Returns:

Type	Description
`Path`	path written to.

Raises:

Type	Description
`ValueError`	if per-ligand results are not yet available.

submit_relative_binding_free_energy_perturbation_workflow

submit_relative_binding_free_energy_perturbation_workflow(
    graph_result: RelativeBindingFreeEnergyGraphResult,
    protein: Protein | ProteinUUID,
    tmd_settings: Literal[
        "fast", "recommended", "rigorous"
    ] = "recommended",
    forcefield: Literal[
        "off_sage_2_0_0", "off_sage_2_2_1"
    ] = "off_sage_2_0_0",
    charge_method: Literal["amber_am1bcc", "nagl"] | None = None,
    n_eq_steps: int | None = None,
    n_frames: int | None = None,
    steps_per_frame: int = 400,
    n_windows: int | None = None,
    min_overlap: float | None = None,
    target_overlap: float | None = None,
    water_sampling_padding: float = 0.4,
    rest_max_temperature_scale: float = 1.0,
    rest_temperature_scale_interpolation: Literal[
        "exponential", "linear"
    ] = "exponential",
    local_md_steps: int | None = None,
    local_md_k: float = 10000.0,
    local_md_radius: float = 1.2,
    local_md_free_reference: bool = False,
    legs: list[Literal["vacuum", "solvent", "complex"]]
    | None = None,
    save_trajectories: bool = False,
    trajectory_save_interval: int = 1000,
    validate_forcefield: bool = True,
    name: str = "RBFE Perturbation",
    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 relative binding free energy perturbation (RBFE) workflow to the API.

Runs FEP simulations along edges of the perturbation graph to predict relative binding free energies between ligands.

Preset settings (any individual param overrides the tmd_settings): - "fast": fewer windows/steps for quick screening (NAGL charges). - "recommended" (default): balanced speed and accuracy (NAGL charges). - "rigorous": same as recommended but disables local MD for higher accuracy.

Parameters:

Name	Type	Description	Default
`graph_result`	`RelativeBindingFreeEnergyGraphResult`	Completed `RelativeBindingFreeEnergyGraphResult`.	required
`protein`	`Protein \| ProteinUUID`	Protein target, as a UUID string or Protein object.	required
`tmd_settings`	`Literal['fast', 'recommended', 'rigorous']`	Starting settings profile. Individual params override this.	`'recommended'`
`forcefield`	`Literal['off_sage_2_0_0', 'off_sage_2_2_1']`	Force field for the simulation (e.g. `"off_sage_2_0_0"`).	`'off_sage_2_0_0'`
`charge_method`	`Literal['amber_am1bcc', 'nagl'] \| None`	Method for computing partial charges.	`None`
`n_eq_steps`	`int \| None`	Equilibration steps per lambda window.	`None`
`n_frames`	`int \| None`	Production frames saved per lambda window.	`None`
`steps_per_frame`	`int`	MD integration steps per saved frame.	`400`
`n_windows`	`int \| None`	Maximum number of lambda windows considered for bisection.	`None`
`min_overlap`	`float \| None`	Minimum acceptable overlap during schedule bisection.	`None`
`target_overlap`	`float \| None`	Desired overlap after HREX optimization.	`None`
`water_sampling_padding`	`float`	Extra nanometers added to the solvent sampling radius.	`0.4`
`rest_max_temperature_scale`	`float`	Maximum effective temperature scaling for REST.	`1.0`
`rest_temperature_scale_interpolation`	`Literal['exponential', 'linear']`	Functional form used for REST scaling.	`'exponential'`
`local_md_steps`	`int \| None`	Number of local MD steps per frame (0 disables local MD).	`None`
`local_md_k`	`float`	Spring constant used during local MD.	`10000.0`
`local_md_radius`	`float`	Sphere radius in nanometers for the local MD region.	`1.2`
`local_md_free_reference`	`bool`	Whether to free the reference frame during local MD.	`False`
`legs`	`list[Literal['vacuum', 'solvent', 'complex']] \| None`	Which thermodynamic cycle legs to run.	`None`
`save_trajectories`	`bool`	Whether to save DCD trajectories.	`False`
`trajectory_save_interval`	`int`	Save every Nth frame when saving trajectories.	`1000`
`validate_forcefield`	`bool`	If True (default), validate protein forcefield compatibility before submitting.	`True`
`name`	`str`	Name of the workflow.	`'RBFE Perturbation'`
`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 workflow.

Raises:

Type	Description
`ValueError`	If graph_result has no graph or both folder and folder_uuid are provided.
`requests.HTTPError`	if the request to the API fails.

Relative Binding Free Energy Perturbation

RelativeBindingFreeEnergyResult dataclass

RelativeBindingFreeEnergyDiagnostics dataclass

RelativeBindingFreeEnergyPerturbationResult dataclass

ligands property

protein property

settings property

graph property

edges property

ligand_dg_results property

diagnostics property

download_edge_trajectories

download_all_trajectories

write_ligand_results_csv

submit_relative_binding_free_energy_perturbation_workflow

RelativeBindingFreeEnergyResult `dataclass`

RelativeBindingFreeEnergyDiagnostics `dataclass`

RelativeBindingFreeEnergyPerturbationResult `dataclass`

ligands `property`

protein `property`

settings `property`

graph `property`

edges `property`

ligand_dg_results `property`

diagnostics `property`