Transition-State Search with Tako Script

tako.transitionState runs one combined operation: a hardcoded climbing-image NEB locates a transition region, a dimer search optionally refines its highest interior image, and a fixed finite-difference vibration check optionally counts imaginary modes. Use it only when two atom-matched endpoints are available. The scientific method is documented in Transition States and the Dimer Method; the shared visible dialog belongs in Refine and Verify a Transition State.

Call the combined operation

Pass the initial structure as the first argument and the final structure in the flat options object:

const initial = await tako.input("input/reactant.extxyz");
const final = await tako.input("input/product.extxyz");
const calculator = tako.calculator.gfn2({ dispersion: "d4" });

const result = await tako.transitionState(initial, {
  calculator,
  properties: ["energy", "forces"],
  transitionStateFinalStructure: final,
  transitionStateImageCount: 7,
  transitionStateNebMaxSteps: 100,
  transitionStateDimerMaxSteps: 50,
  transitionStateFmaxEvPerAngstrom: 0.05,
  transitionStateMaxstepAngstrom: 0.2,
  transitionStateSpringConstant: 0.1,
  transitionStateVibrationCheck: true,
});

await tako.output("output/transition-state.json", result);

Both structures must have equal atom counts and the same element at every index. The operation does not validate atom IDs, equivalent-atom correspondence, endpoint cells, periodicity, constraints, or a minimum-image mapping. It clones the initial structure for every image and interpolates Cartesian positions to the final coordinates. Initial cell, PBC, constraints, charge, and unpaired count govern the band; final cell/PBC/constraints are discarded.

Understand the fixed algorithm

The public settings object is intentionally smaller than tako.reactionPath, but several effective choices are not stated by its field names:

transitionStateMaxstepAngstrom limits dimer translation but is not used by the static NEB optimizer. The shared transitionStateFmaxEvPerAngstrom applies to both convergence tests.

The spring value has a current unit defect: the combined bridge does not perform the conversion applied by tako.reactionPath, making the same displayed numeric value roughly 97 times stronger internally (Known Limitations). Preserve the exact runtime revision and treat this parameter as implementation-specific until the bridge is corrected.

Validate endpoint invariants

Calculator capability validation is necessary but not sufficient:

const check = calculator.validate("transitionState", {
  properties: ["energy", "forces"],
});
if (!check.ok) throw new Error(check.reasons.join("; "));

if (initial.atoms.length !== final.atoms.length) {
  throw new Error("Transition-state endpoints have different atom counts");
}
for (let i = 0; i < initial.atoms.length; i += 1) {
  if (initial.atoms[i].element !== final.atoms[i].element) {
    throw new Error(`Endpoint element mismatch at atom ${i}`);
  }
}

Also verify the same physical atom mapping, cell, periodic representation, charge/spin, and constraint intent outside this guard. Two equivalent atoms can be swapped without failing element-by-index validation.

Control the stage budgets

transitionStateImageCount is normalized to 3–21. transitionStateNebMaxSteps is normalized to 1–1000. transitionStateDimerMaxSteps accepts 0–1000: zero skips dimer refinement and retains the NEB saddle image. The interface cannot select zero because its visible dimer-step input has minimum 1.

The budgets are independent. NEB nonconvergence does not stop dimer refinement. Dimer nonconvergence does not stop the vibration calculation. A resolved promise therefore means all requested stages executed without a fatal engine error; it does not mean the saddle is converged or valid.

Use explicit gates:

if (!result.neb.converged) {
  throw new Error(
    `NEB did not converge: ${result.neb.final_fmax_ev_per_angstrom} eV/A`
  );
}
if (!result.dimer?.converged) {
  throw new Error("Dimer refinement is absent or unconverged");
}
if (!result.vibrations.checked) {
  throw new Error("Saddle Hessian index was not checked");
}
if (result.vibrations.imaginaryModes !== 1) {
  throw new Error(
    `Expected one imaginary mode; found ${result.vibrations.imaginaryModes}`
  );
}

hasImaginaryMode means count greater than zero; it is not an exactly-one transition-state predicate.

Read the public result

The top-level object contains calculator provenance, stage summaries, one saddle structure, a minimal vibration summary, one compatibility frame, final atom records, and NEB-derived final scalars. It does not contain the NEB band, path energies, barrier, reaction energy, dimer/NEB traces, full frequencies, normal modes, Hessian, settings record, or restart state.

neb contains converged, steps, final_energy_ev, and final_fmax_ev_per_angstrom. Its energy is the highest current band-image energy, not a sum and not necessarily a dimer-refined saddle energy.

dimer is null when the zero-step branch is selected; otherwise it contains the same four summary fields for the dimer objective. saddle_image remains the zero-based index of the pre-dimer NEB image.

saddle_structure contains symbols, positions in ångström, optional cell in ångström, PBC, charge, and unpaired count. It does not contain atom IDs or selective flags.

vibrations contains checked, hasImaginaryMode, imaginaryModes, and optional lowestFrequencyCmInv. saddle_quality duplicates the imaginary count and optionally contains nebResidual and dimerFmax. The two residual fields do not share a unit: nebResidual is currently unconverted Hartree/bohr, while dimerFmax is eV/Å (Known Limitations). Use the explicitly named stage fields instead.

Do not combine hybrid frame scalars with its geometry

The sole frames[0] geometry and top-level atoms describe the final saddle after dimer refinement when it ran. However, the frame step, energy, force maximum, and top-level final_energy_ev/final_fmax_ev_per_angstrom are copied from the NEB result. The returned geometry and those scalars can therefore describe different stages.

Obtain a coherent saddle energy and forces with a separate single point on the returned structure. The exact structure conversion helper available to a particular script should be checked against the public structure API; do not reconstruct atom identities from the one-frame XYZ string when the structured saddle_structure is available.

await tako.output("output/raw-transition-state.json", result);

const audit = {
  neb: result.neb,
  dimer: result.dimer,
  vibrations: result.vibrations,
  saddleQuality: result.saddle_quality,
  warning: "Top-level final energy/fmax are NEB values, not a coherent dimer-saddle single point",
};
await tako.output("output/transition-state-audit.json", audit);

Handle vibration and constraint limits

The vibration stage excludes fully fixed atoms. Partially fixed atoms remain active on all Cartesian displacement axes while constrained force components are removed. This can distort the numerical Hessian. No public transitionState option changes the 0.01-bohr displacement or two-point stencil, so convergence with respect to finite differences cannot be tested inside this combined call.

The public summary cannot show whether the imaginary eigenvector connects the intended endpoints. A count of one is necessary but insufficient. Preserve the saddle and perform an operation that returns mode vectors or downhill connectivity evidence before claiming a mechanism.

Handle rejection, cancellation, and partial work

A calculator, NEB, dimer, or vibration error rejects the promise. The combined implementation does not stream stage frames through an event sink, so a rejected call has no structured earlier-stage band or saddle to salvage. Cancellation terminates the worker and marks pending artifacts failed. There is no public checkpoint or restart input. The generic progress message names all three stages even when the dimer budget is zero or vibration checking is disabled.

The calculation workspace ordinarily derives result.json, transition_state.json, trajectory.extxyz, and log.txt. transition_state.json duplicates the result. The trajectory contains one saddle frame, not a band. Script output only writes what the script explicitly saves; do not promise workspace-derived artifacts as fields of the returned object.

Preserve a defensible record

Archive both endpoint structures and atom mapping, the initial cell/PBC/constraints, calculator and checkpoint identity, complete options object, runtime revision, raw result, stage gates, separate single-point saddle energy/forces, and independent imaginary-mode/connectivity evidence. The exhaustive types, units, and availability conditions are generated in tako.transitionState Settings.