Spin States

Spin-states workflow - calculate energies of different spin multiplicities.

SpinState dataclass

SpinState(multiplicity: int, energy: float, calculation_uuids: tuple[str | None, ...])

Spin state result.

Attributes:

Name	Type	Description
multiplicity	int	spin multiplicity (1=singlet, 2=doublet, 3=triplet, etc.)
energy	float	energy in Hartree
calculation_uuids	tuple[str | None, ...]	UUIDs for each optimization stage (for multistage optimization)

SpinStatesResult dataclass

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

Bases: WorkflowResult

Result from a spin-states workflow.

spin_states property

spin_states: list[SpinState]

List of spin states with energies, in submission order.

messages property

messages: list[Message]

Any messages or warnings from the workflow.

get_calculation

get_calculation(multiplicity: int, stage: int = -1) -> Calculation

Fetch the calculation for a specific spin state.

Note

Makes one API call per spin state on first access. Results are cached. Call clear_cache() to refresh.

Parameters:

Name	Type	Description	Default
multiplicity	int	spin multiplicity to fetch	required
stage	int	optimization stage (-1 for final stage)	-1

Returns:

Type	Description
Calculation	calculation object with molecule and energy data

Raises:

Type	Description
ValueError	multiplicity is not found or has no calculation

get_energies

get_energies(relative: bool = False) -> list[float]

Get energies for each spin state.

Parameters:

Name	Type	Description	Default
relative	bool	return relative energies in kcal/mol (relative to the ground state / lowest energy spin state). If False (default), return absolute energies in Hartree	False

Returns:

Type	Description
list[float]	list of energies for each spin state

submit_spin_states_workflow

submit_spin_states_workflow(initial_molecule: StructureInput, states: list[int] | None = None, multistage_opt_settings: MultiStageOptSettings | None = None, frequencies: bool = False, transition_state: bool = False, constraints: list[Constraint] | None = None, name: str = 'Spin States 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[SpinStatesResult]

Submits a spin-states workflow to the API.

Defaults to a r2scan_3c//gfn2_xtb stack. Pass an explicit MultiStageOptSettings(...) to override.

Parameters:

Name	Type	Description	Default
initial_molecule	StructureInput	molecule to calculate spin states for	required
states	list[int] | None	list of multiplicities to calculate (e.g., [1, 3, 5] for singlet, triplet, quintet). Defaults to [1, 3, 5] for even-electron molecules and [2, 4, 6] for odd-electron molecules	None
multistage_opt_settings	MultiStageOptSettings | None	optimization stages and singlepoint settings describing the method stack	None
frequencies	bool	compute frequencies on the final optimization of each state	False
transition_state	bool	optimize each state to a transition state	False
constraints	list[Constraint] | None	geometric constraints held fixed during every state's optimization, see Constraint	None
name	str	name of the workflow	'Spin States 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[SpinStatesResult]	submitted workflow

Raises:

Type	Description
ValueError	any multiplicity is incompatible with the molecule
HTTPStatusError	request to the API fails