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

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	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
requests.HTTPError	if the request to the API fails.