Single-Point Calculations with Tako Script

tako.singlePoint evaluates the supplied structure without changing its coordinates or periodic cell. It returns the worker result through a promise and creates the same persistent calculation workspace used by the interface.

The method theory is in Single-Point Energies and Properties. Calculator construction is defined in Calculator Construction and Validation. This chapter owns the executable operation contract.

Operation contract

const result = await tako.singlePoint(structure, {
  calculator,
  properties,
});

The promise resolves only after a structured result worker event. A worker error, cancellation, reset, or abnormal completion without a result rejects it. A resolved promise says that the result contract completed; scientific acceptance still depends on the fixed geometry, calculator, and requested outputs.

Validate before running

Capability validation is synchronous and should precede asset preparation or numerical work:

const properties = ["energy", "forces", "stress"];
const calculator = tako.calculator.mlip({ levelOfTheory: "nequix" });
const check = calculator.validate("singlePoint", { properties });

if (!check.ok) {
  throw new Error(check.reasons.join("; "));
}

const result = await tako.singlePoint(structure, {
  calculator,
  properties,
});

Validation checks the registered capability profile, not accuracy or training-domain coverage. For GFN2, the operation can additionally produce electronic-analysis channels implemented by Tako. For an MLIP, request only energy, forces, and supported stress.

Complete fixed-geometry calculation

const structure = await tako.input("input/candidate.extxyz");
const calculator = tako.calculator.gfn2({
  levelOfTheory: "gfn2",
  dispersion: "d4",
  charge: 0,
  unpaired: 0,
});

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

const result = await tako.singlePoint(structure, {
  calculator,
  properties,
});

const energyEv = tako.analysis.energyEv(result);

await tako.output("output/result.json", result);
await tako.output("output/summary.json", {
  method: "gfn2",
  charge: 0,
  unpaired: 0,
  properties,
  energyEv,
});

Writing result preserves channels not copied into the summary. The summary is a derived record for comparison and should retain the method state needed to interpret its number.

Result fields

The backend result uses engine-facing snake-case fields. Availability depends on the calculator and requested properties.

Do not replace an absent field with zero. Absence can mean that the property was not requested, was unsupported, or failed during post-processing. Inspect the calculation log and capability request.

The single-point result does not publish a dipole field (Known Limitations). Do not infer one from calculator capability metadata or from unrelated excitation-transition dipoles.

tako.analysis.energyEv(result) rejects explicit error results and refuses an explicitly unconverged result. It accepts energy_ev, energyEv, final_energy_ev, finalEnergyEv, supported Hartree fields, nested energy.ev, or the final frame energy. We prefer the native energy_ev field in raw records, and use the helper at analysis boundaries.

Comparable series

To rank several fixed geometries under one declared method, keep the calculator identity and settings outside the loop, run one single point per structure, and subtract a common reference. The worked loop, validation guard, and relative-energy output live in Energy Analysis with Tako Script under “Build a comparable series” — the pattern is identical for single points.

A ranking of fixed geometries does not relax them or demonstrate that they are minima, and the files must have compatible compositions and state conventions before their energy differences are interpreted. For independent candidates, controlled parallelism can reduce wall time, but each call creates its own worker and workspace; avoid launching an unbounded list whose aggregate model memory exceeds the browser budget.

Derived force diagnostics

When the returned force array is present, compute a transparent maximum norm rather than inferring stationarity from the energy. With constraints, these are the constraint-applied forces returned by the operation; without constraints, they are the calculator forces:

const forces = result.forces_ev_per_angstrom;
if (!Array.isArray(forces)) throw new Error("Force array is absent.");

const forceNorms = forces.map(([fx, fy, fz]) =>
  Math.hypot(fx, fy, fz));
const maxForceEvPerAngstrom = Math.max(...forceNorms);

await tako.output("output/force-summary.json", {
  maxForceEvPerAngstrom,
  forceNormsEvPerAngstrom: forceNorms,
});

This is a diagnostic on the fixed geometry. It is not an optimization convergence claim unless its force convention and threshold match the optimization protocol.

Errors and cancellation

GFN2 analyses run sequentially after the core result in the order DOS, PDOS, charges, electron density, charge density, NCI, frontier orbitals, spin density, ESP, density derivatives, Fukui functions, ELF, and WFN. A cumulative partialResult is emitted after each completed stage. If a later stage fails, the overall promise rejects; earlier partial artifacts may remain but are not a completed all-properties result. Cancellation provides no restartable checkpoint.

Catch an expected cancellation narrowly:

try {
  await tako.singlePoint(structure, { calculator, properties });
} catch (error) {
  if (error instanceof Error && error.message === "Canceled by user") {
    await tako.output("output/cancelled.json", { cancelled: true });
  } else {
    throw error;
  }
}

Output discipline

A reusable Script calculation keeps the exact input structure, explicit calculator state, requested property list, raw result, derived summary, and any comparison formula. Do not rely on Console text as the only numerical record. For a property-specific artifact contract, use the generated tako.singlePoint settings reference together with the Calculation Artifact Reference.