Calculator Construction and Validation

Calculation functions do not infer a scientific method from the structure. A Tako Script constructs a calculator explicitly and supplies that object to every operation whose result depends on a potential-energy model. This makes the calculator part of the executable record rather than an implicit interface preference.

The physical assumptions and selection criteria are discussed in Choosing a Method. This chapter defines the Script contract. Interface controls are documented separately in Choose a Calculator.

Calculator objects

A calculator object contains a normalized model specification and three inspection methods:

• capabilities() reports the operations, property channels, periodicity, charge, spin, and cell-relaxation features exposed by the backend.
• validate(operation, request) compares a proposed operation and property request with those capabilities.
• readiness(manifest, records) describes the runtime modules and model assets required by that calculator.

The object is reusable. Construct it once when several stages must use the same model, then pass the same object to each stage. Reconstructing an apparently equivalent calculator is valid, but explicit reuse makes accidental method drift easier to detect during review.

GFN2 calculators

Construct a semi-empirical calculator with tako.calculator.gfn2(options):

const calculator = tako.calculator.gfn2({
  levelOfTheory: "gfn2",
  dispersion: "d4",
  charge: 0,
  unpaired: 0,
  spinPolarized: false,
  solvation: {
    enabled: true,
    model: "alpb",
    solvent: "water",
  },
});

The level and correction are deliberately separate. Use levelOfTheory: "gfn2" for the electronic method and dispersion: "default" or "d4" for the interaction correction. Do not encode dispersion in the level name.

Charge and spin specify the modeled electronic state. A neutral singlet default is inappropriate for an ion or radical even when the calculation converges. For a comparison series, construct a calculator for each intended electronic state and record that state beside every energy term.

Machine-learned calculators

Construct a machine-learned interatomic potential with tako.calculator.mlip(options):

const calculator = tako.calculator.mlip({
  levelOfTheory: "nequix",
});

The registered levels currently include nequix, nequix-phono, nequip-s, nequip-l, equiformer, and equiformer-gradient. State levelOfTheory even when the default happens to be suitable. Defaults are conveniences for an interactive session; they are weak provenance for a shared script.

An MLIP calculator has no molecular charge, multiplicity, orbital, or solvent state, and the backend does not read such fields. If the scientific question depends on electron number, spin, charge transfer, orbital populations, or a dielectric environment, a different calculator is required.

Capability validation

Validation should occur before an expensive operation and before any downstream code assumes that a property will exist:

const properties = ["energy", "forces", "stress"];
const check = calculator.validate("optimization", { properties });

if (!check.ok) {
  throw new Error(`Calculator request is invalid: ${check.reasons.join("; ")}`);
}

const result = await tako.optimize(structure, {
  calculator,
  properties,
  optimizer: "bfgs",
  fmaxEvPerAngstrom: 0.02,
  maxSteps: 300,
});

validate returns { ok, reasons }; it does not run a calculation, download a model, or judge scientific accuracy. A successful result means only that the requested operation and channels are implemented for that calculator profile.

The public Script operation names accepted by validate are singlePoint, optimization, molecularDynamics, phonon, xrd, vibration, stda, reactionPath, and transitionState. The capability profile additionally lists lower-level scan, but Tako currently exposes no top-level tako.scan call. X-ray diffraction is geometry-based and does not require an energy calculator, although its name remains part of the common validation vocabulary.

Validation is operation-aware for electronic post-processing: GFN2 charges, DOS/PDOS, density, NCI, and WFN are implemented by singlePoint, not by optimization, MD, phonon, vibration, reaction-path, or transition-state calls. A request such as gfn2.validate("optimization", { properties: ["charges"] }) therefore returns ok: false with a reason directing the property evaluation to singlePoint.

The common property names are energy, forces, stress, dos, pdos, charges, electronDensity, chargeDensity, nci, and wfn. Machine-learned calculators expose the structural channels—energy, forces, and, where supported, stress. GFN2 supplies additional electronic channels for operations that implement them. Capability support remains distinct from physical suitability.

Asset readiness

Calculator construction is synchronous; runtime preparation may not be. WebAssembly modules and MLIP weights are acquired on demand and cached locally. The scientific request therefore has two independent preconditions:

1. the calculator supports the requested operation and properties;
2. the required executable and model assets can be loaded.

calculator.readiness(manifest, records) evaluates the manifest and stored-asset records supplied by the caller. With no live manifest or records it cannot inspect the browser cache; it describes requirements relative to the data it received. Use it in infrastructure code that already owns those records. In an interactive workflow, use the Model Manager; in an agent workflow, use list_models.

missing normally means that a required asset has not yet been downloaded. Conversely, ready means only that bytes are present and verified sufficiently for loading; it says nothing about training-domain coverage or accuracy.

One calculator across a staged calculation

The following pattern uses one explicit method for optimization and the final property calculation, rejects an unconverged geometry, and writes the calculator choice into the output record:

const structure = tako.structure.benzene();
const calculator = tako.calculator.gfn2({
  levelOfTheory: "gfn2",
  dispersion: "d4",
  charge: 0,
  unpaired: 0,
});

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

const optimization = await tako.optimize(structure, {
  calculator,
  properties: ["energy", "forces"],
  optimizer: "bfgs",
  fmaxEvPerAngstrom: 0.02,
  maxSteps: 300,
});

if (!optimization.converged) {
  throw new Error("Optimization did not meet its force criterion.");
}

const optimized = tako.analysis.finalStructure(structure, optimization);
const properties = await tako.singlePoint(optimized, {
  calculator,
  properties: ["energy", "forces", "charges", "dos"],
});

await tako.output("output/calculation.json", {
  method: {
    family: "GFN2-xTB",
    levelOfTheory: "gfn2",
    dispersion: "d4",
    charge: 0,
    unpaired: 0,
  },
  optimizationConverged: optimization.converged,
  energyEv: tako.analysis.energyEv(properties),
});

Both stages use the same calculator. The final single point is a property evaluation on the accepted optimized geometry.

Comparing calculators without mixing references

Different calculators generally have different energy zeros. A script may evaluate the same geometry with several methods for validation, but cross-method total energies do not belong to one thermodynamic cycle and cannot be subtracted. Compute each reaction, binding, or relative energy wholly within one calculator, then compare the derived differences.

async function fixedGeometryEnergy(structure, calculator) {
  const check = calculator.validate("singlePoint", { properties: ["energy"] });
  if (!check.ok) throw new Error(check.reasons.join("; "));
  const result = await tako.singlePoint(structure, {
    calculator,
    properties: ["energy"],
  });
  return tako.analysis.energyEv(result);
}

This helper deliberately accepts the calculator as an argument. The caller must preserve method identity with the returned value. A bare number is insufficient provenance for later comparison.

Errors and interpretation

Provenance record

For a reusable result, retain the calculator family, level-of-theory string, runtime and model identifier, immutable asset hash when available, application/backend version, dispersion treatment, charge and spin convention, solvation model, SCF overrides, requested properties, and the operation settings that determine convergence. Model availability, capability validation, numerical convergence, and scientific validation are four separate claims; record evidence for each rather than collapsing them into “the calculation ran.”