Multistage Optimization

Multistage optimization workflow - optimize molecules with staged methods.

MultiStageOptResult dataclass

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

Bases: WorkflowResult

Result from a multistage-optimization workflow.

calculation_uuids property

calculation_uuids: list[str]

UUIDs of all calculations in the optimization stages.

calculations property

calculations: list[Calculation]

All optimization stage calculations (lazily fetched).

Typically includes xTB pre-optimization, DFT optimization, and final single-point. Access final_calculation for just the last stage.

final_calculation property

final_calculation: Calculation | None

The final Calculation object with full molecule data (lazily fetched).

molecule property

molecule: Molecule | None

The final optimized molecule geometry.

energy property

energy: float | None

Energy of the final optimized molecule (Hartree).

charges property

charges: list[float] | None

Partial charges on each atom.

dipole property

dipole: tuple[float, float, float] | None

Dipole moment vector (Debye).

get_stage_energies

get_stage_energies() -> list[tuple[str, float | None]]

Fetch energies for all completed stages.

Useful for polling partial results – call this on each poll to see which stages have completed and their energies.

Returns:

Type	Description
list[tuple[str, float | None]]	list of (calculation_uuid, energy_in_hartree) for each completed stage

Note

Makes one API call per completed stage. Results are not cached since this is intended for use during polling with result(wait=False).

submit_multistage_optimization_workflow

submit_multistage_optimization_workflow(initial_molecule: StructureInput, optimization_settings: Sequence[Settings] | None = None, singlepoint_settings: Settings | None = None, frequencies: bool = False, transition_state: bool = False, name: str = 'Multistage Optimization 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[MultiStageOptResult]

Submits a multistage-optimization workflow to the API.

Defaults to a r2scan_3c//gfn2_xtb stack (GFN2-xTB optimization, r2SCAN-3c single point).

Parameters:

Name	Type	Description	Default
initial_molecule	StructureInput	molecule to optimize	required
optimization_settings	Sequence[Settings] | None	optimization stages to apply in order	None
singlepoint_settings	Settings | None	final singlepoint settings, applied after the last optimization stage	None
frequencies	bool	whether to calculate frequencies on the last optimization step	False
transition_state	bool	optimize to a transition state rather than a minimum. Applies to every optimization stage, so a transition-state guess is not relaxed to a minimum	False
name	str	name of the workflow	'Multistage Optimization 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[MultiStageOptResult]	submitted workflow

Raises:

Type	Description
HTTPStatusError	request to the API fails