NEB with Tako Script

This chapter is for workflows executed through Tako Script. The scientific definition and numerical behavior of NEB are documented in Nudged Elastic Band Method; the point-and-click workflow is documented separately in Calculate a Reaction Path with NEB.

Operation contract

await tako.reactionPath(initialStructure, settings)

initialStructure supplies the first endpoint. settings.reactionFinalStructure supplies the second. Successful execution resolves to a result object. Validation errors, engine or calculator failures, timeout, and user cancellation reject the promise; cancellation uses the error message Canceled by user.

The runtime validates equal atom counts and equal elements at corresponding indices. It does not compare endpoint cells or detect exchanged atoms of the same element. For periodic paths, your script must verify a common cell and consistently wrapped coordinates before calling the operation. Constraints attached to the initial structure propagate to the band.

let result;
try {
  result = await tako.reactionPath(initial, settings);
} catch (error) {
  await tako.write('output/neb-error.txt', String(error), { createParents: true });
  throw error;
}

Minimal CI-NEB calculation

const initial = await tako.input('input/reactant.extxyz');
const final = await tako.input('input/product.extxyz');

const result = await tako.reactionPath(initial, {
  calculator: tako.calculator.gfn2({ dispersion: 'd4' }),
  reactionFinalStructure: final,
  reactionImageCount: 7,
  reactionInterpolation: 'idpp',
  reactionNebMethod: 'improvedTangent',
  reactionOptimizer: 'bfgs',
  reactionNebClimb: true,
  reactionFmaxEvPerAngstrom: 0.05,
});

await tako.output('output/reaction-path-result.json', result);

The example deliberately states the scientifically important settings instead of relying on every default. Less consequential optimizer controls can remain at their registered defaults.

Inspect before optimizing

Set reactionInterpolateOnly: true to create the seed band without calculator calls:

const seed = await tako.reactionPath(initial, {
  reactionFinalStructure: final,
  reactionImageCount: 7,
  reactionInterpolation: 'idpp',
  reactionInterpolateOnly: true,
});

await tako.output('output/neb-seed.json', seed);

Open the returned frames and inspect atom correspondence, periodic displacement, short contacts, and the proposed mechanism. Interpolation-only is a structural validation step; it does not produce a barrier.

Interpolation-only returns neb.converged: true and neb.steps: 0, but does not return reaction_barrier. Here converged means that seed generation completed; it does not mean that a minimum-energy path was optimized.

Settings

The complete generated contract is Reaction-path settings. The controls most often required in a reproducible script are:

Record settings as data when parameter sweeps are intended. Do not generate property names dynamically; unsupported names are ignored or rejected according to the operation contract.

Validate before extracting a barrier

Do not read a quantitative barrier from an unconverged calculation. Validate the result explicitly:

if (!result.neb?.converged) {
  throw new Error(
    `NEB did not converge: residual = ${result.neb?.residual_ev_per_angstrom} eV/Å`,
  );
}

const profile = result.reaction_barrier;
if (!profile || !Array.isArray(profile.energies_ev)) {
  throw new Error('Reaction-path result does not contain an energy profile');
}

const summary = {
  barrierEv: profile.barrier_ev,
  reactionEnergyEv: profile.reaction_energy_ev,
  saddleImage: profile.saddle_image,
  residualEvPerAngstrom: result.neb.residual_ev_per_angstrom,
  steps: result.neb.steps,
};

await tako.output('output/neb-summary.json', summary);

This checks numerical convergence. Chemical validation still requires inspection of the frames and, for a transition-state claim, saddle refinement and vibrational verification.

Result fields

Field names are part of the operation result contract; do not infer convergence from the presence of barrier_ev alone.

Write an auditable profile

const rows = result.reaction_barrier.relative_energies_ev.map(
  (energy, image) => [image, result.reaction_barrier.coordinate[image], energy],
);

await tako.write(
  'output/neb-profile.csv',
  tako.report.csv({
    columns: ['image', 'reaction_coordinate', 'relative_energy_ev'],
    rows,
  }),
  { mimeType: 'text/csv', createParents: true },
);

await tako.output('output/neb-path.json', result.reaction_path);

Keep the normalized settings, the full band, convergence state, and profile together. A CSV containing only the final barrier is insufficient to audit the mechanism.

Parameter studies

When testing image count, initialization, or force threshold, write each run to its own directory and compare only converged bands:

for (const imageCount of [7, 11, 15]) {
  const run = await tako.reactionPath(initial, {
    calculator,
    reactionFinalStructure: final,
    reactionImageCount: imageCount,
    reactionInterpolation: 'idpp',
    reactionNebClimb: true,
    reactionFmaxEvPerAngstrom: 0.05,
  });

  await tako.output(`output/images-${imageCount}/result.json`, run);
}

Agreement in barrier height is not sufficient if the bands follow different mechanisms. Compare the image structures, saddle region, residual, and endpoint identity as well as the scalar energy.

Errors and recovery

Use Tako Script API Reference for the namespaces used in the examples and Organize a Reproducible Workspace for directory conventions.