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.

Parameters:

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

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	If the 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	If True, 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

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	if True, compute frequencies on the final optimization of each state.	False
transition_state	bool	if True, 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	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 any multiplicity is incompatible with the molecule.
requests.HTTPError	If the request to the API fails.