TS Validation

A TS validation job checks whether a transition-state guess is chemically consistent with a reaction path.

The workflow can validate a TS guess with only ts_atoms, and performs an additional mapping/connectivity validation when reference reactant_atoms and product_atoms are provided.

What TS Validation Runs

For each submitted TS validation job, Atomiverse executes:

1. Vibrational analysis on ts_atoms to verify exactly one imaginary mode.
2. Optional reaction mapping + imaginary-mode displacement checks (if reference endpoints are provided).
3. IRC propagation from the TS guess.
4. Endpoint optimization on both IRC ends.
5. Optional endpoint connectivity comparison against supplied reactant_atoms/product_atoms.

Your First TS Validation Job

import atomiverse
from atomiverse import Atoms, JobFailedError, TSValidation
from atomiverse.levels import GFN2_XTB

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

ts_guess = Atoms.from_smiles("[H][H]")

job = TSValidation(
    ts_atoms=ts_guess,
    level_of_theory=GFN2_XTB,
)
job.submit()

try:
    result = job.require_result()
except JobFailedError as exc:
    print(f"Job failed: {exc.failure.error}")
else:
    print(f"Valid TS: {result.is_ts}")
    print(f"IRC frames: {len(result.irc_trajectory)}")

Input Parameters

Required:

• ts_atoms: transition-state guess structure
• level_of_theory: electronic-structure method

Optional:

• reactant_atoms: expected reactant endpoint
• product_atoms: expected product endpoint
• charge (default 0)
• multiplicity (default 1)

If either reactant_atoms or product_atoms is provided, both must be provided.

job = TSValidation(
    ts_atoms=ts_guess,
    reactant_atoms=reactant_guess,
    product_atoms=product_guess,
    charge=0,
    multiplicity=1,
    level_of_theory=GFN2_XTB,
)

Result

job.require_result() returns a TSValidationResult.

Field	Type	Description
is_ts	bool	Whether the TS guess passed all validation checks.
validation_reason	str | None	Human-readable reason when validation fails.
optimized_reactants_atoms	Atoms	Optimized reactant endpoint structure.
optimized_products_atoms	Atoms	Optimized product endpoint structure.
irc_trajectory	list[TrajectoryStep]	IRC path frames with positions, energy, and forces.
frequencies_cm1	list[float]	Harmonic frequencies from TS vibrational analysis.
imaginary_frequency_cm1	float | None	Dominant imaginary frequency used for TS checks.
reactant_optimization_trajectory	list[TrajectoryStep]	Stepwise endpoint optimization data for reactants.
product_optimization_trajectory	list[TrajectoryStep]	Stepwise endpoint optimization data for products.
mapping	ReactionMappingResult | None	Mapping details when endpoint references were supplied.

Non-blocking Submission

from atomiverse import State

job.submit(wait=False)
job.refresh()

if job.state == State.DONE:
    print(job.require_result().is_ts)
elif job.state == State.FAILED:
    print(job.require_failure().error)