Spin State Workflow

The Spin State Workflow evaluates the relative energies of different spin multiplicities for a molecular system. For each spin state, it performs a geometry optimisation followed by a single-point energy evaluation, then ranks the results by energy.

When to Use

Use this workflow when you need to determine the ground-state spin multiplicity of a transition-metal complex, open-shell organic molecule, or any system with multiple accessible spin states.

Your First Spin State Workflow

import atomiverse
from atomiverse import Atoms, SpinStateWorkflow
from atomiverse.levels import GFN2_XTB, WB97MV_SVP_CPCM

atomiverse.configure(api_key="your-api-key")

# Fe(II) complex — try singlet, triplet, quintet
complex = Atoms.from_smiles("[Fe+2]")
job = SpinStateWorkflow(
    atoms=complex,
    charge=2,
    multiplicity=5,
    optimization_level_of_theory=GFN2_XTB,
    single_point_energy_level_of_theory=WB97MV_SVP_CPCM,
    possible_spins=[1, 3, 5],
)

job.submit()

try:
    result = job.require_result()
except JobFailedError as exc:
    print(f"Job failed: {exc.failure.error}")
else:
    print(f"Evaluated {len(result.results)} spin states")
    print(f"Lowest-energy spin: {result.lowest_energy_spin}")

    for r in result.results:
        print(
            f"  Spin {r.spin}: opt energy = {r.optimization_energy:.8f} Ha, "
            f"SPE = {r.single_point_energy:.8f} Ha"
        )

    print("Ranked by SPE:")
    for rank, r in enumerate(result.ranked, start=1):
        print(
            f"  #{rank}: spin {r.spin} "
            f"({r.single_point_energy:.8f} Ha)"
        )

Input

Parameter	Type	Description
atoms	Atoms	Starting molecular geometry.
charge	int	Total charge of the system (default 0).
multiplicity	int	Ground-state spin multiplicity — used as metadata (default 1).
optimization_level_of_theory	LevelOfTheory	Method for geometry optimisations.
single_point_energy_level_of_theory	LevelOfTheory	Method for final single-point energies.
possible_spins	list[int]	Spin multiplicities to evaluate. Must be ≥ 1 each.

Result

job.require_result() returns a SpinStateWorkflowResult with:

Field	Type	Description
results	list[SpinStateResult]	One entry per requested spin, in input order.
ranked	list[SpinStateResult]	Same entries sorted by single_point_energy ascending.
lowest_energy_spin	int	Spin multiplicity of the lowest-energy state.

Each SpinStateResult contains:

Field	Type	Units	Description
spin	int	—	Spin multiplicity (2S + 1)
optimized_positions	list[list[float]]	Å	Converged geometry
optimization_energy	float	Hartree	Final energy from geometry optimisation
single_point_energy	float	Hartree	Single-point energy at the optimised geometry

Choosing Levels of Theory

A common pattern is to use a fast semi-empirical method for the geometry optimisation step and a higher-level DFT method for the single-point ranking:

from atomiverse.levels import GFN2_XTB, WB97MV_SVP_CPCM

job = SpinStateWorkflow(
    atoms=molecule,
    optimization_level_of_theory=GFN2_XTB,
    single_point_energy_level_of_theory=WB97MV_SVP_CPCM,
    possible_spins=[1, 3, 5, 7],
)

This combination is especially useful for transition-metal systems where DFT-level optimisations for multiple spin states would be computationally expensive.

Thresholds

The geometry optimisation uses the standard convergence preset:

• Maximum force threshold: 0.005 Hartree/Å (≈ 0.1 eV/Å)
• Maximum steps per optimisation: 200

The optimisation for each spin is indepdendent. If any spin fails to converge, the entire job fails with a descriptive error message. The geometries are optimised separately — no constraints are shared across spin states.

Non-blocking Submission

job.submit(wait=False)
print(job.job_id)

# do other work …

job.refresh()
if job.state == State.DONE:
    result = job.require_result()
    print(f"Ground state: spin {result.lowest_energy_spin}")

See Single Point Energy — Non-blocking Submission for the full pattern including save/load, cancellation, and BYOC capacity waits.

Charge and Multiplicity

• charge sets the total charge for all spin-state evaluations.
• multiplicity is the ground-state guess and is included as metadata; it does not affect which spin states are evaluated (only possible_spins controls that).

See Also

• Single Point Energy — single energy evaluation at a fixed geometry
• Optimization — geometry relaxation at a single spin state
• Levels of Theory — all available computational methods
• Job Management — rename and delete jobs