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.

Attributes:

Name	Type	Description
dg	float	predicted binding free energy difference (kcal/mol)
dg_err	float	uncertainty estimate on dg

RelativeBindingFreeEnergyDiagnostics dataclass

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

Quality-control metrics from an RBFE simulation.

Attributes:

Name	Type	Description
cycle_closure_rms	float | None	RMS error across completed thermodynamic cycles
windows_completed	int | None	count of successfully converged lambda windows
windows_failed	int | None	count of failed lambda windows

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	edge_index is out of range
HTTPStatusError	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
HTTPStatusError	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	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', 'mango_1_0_0'] = '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[RelativeBindingFreeEnergyPerturbationResult]

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', 'mango_1_0_0']	force field for the simulation. Mango requires charge_method="nagl"	'off_sage_2_0_0'
charge_method	Literal['amber_am1bcc', 'nagl'] | None	method for computing partial charges. The "recommended" and "fast" profiles use NAGL by default; override the "rigorous" profile to NAGL when using Mango	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	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	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[RelativeBindingFreeEnergyPerturbationResult]	submitted workflow

Raises:

Type	Description
ValueError	graph_result has no graph or both folder and folder_uuid are provided
HTTPStatusError	request to the API fails