tako.singlePoint Settings

This page is generated from code-owned Doxygen-style metadata in src/script/takoScriptDocs.ts. Update that file first, then regenerate this page so runtime capability descriptions, docs, and agent guidance stay aligned.

tako.singlePoint

Runs a fixed-geometry calculation and returns properties for the exact input coordinates.

Signature: await tako.singlePoint(structure, { calculator, properties })

Theory

• A single point evaluates the potential-energy model without changing atomic positions or the cell. It is the base primitive for energy comparisons, force checks, charge analysis, DOS/PDOS extraction, density-derived analysis, and final-energy refinement after a relaxation.
• Energy differences are meaningful only when structures use the same calculator family, model, charge/spin settings, convergence settings, and compatible reference states. A single point does not repair bad geometries; large forces mean the structure is not stationary under the selected model.
• For periodic structures, stress is meaningful only when the calculator supports cell derivatives. For molecular GFN2 calculations, electronic properties such as charges and DOS/PDOS are method-specific outputs, not universal observables.

Usage Notes

• Use singlePoint after generating or loading candidate structures when you want comparable fixed-geometry energies.
• Request the smallest property set needed for the analysis; extra properties increase runtime and may require method support.
• For screening recipes, write both raw energies and normalized energies to output/summary.json or a CSV so downstream comparisons are auditable.

Settings

Example

const structure = await tako.input("input/candidate.extxyz");
const calculator = tako.calculator.mlip({ levelOfTheory: "nequix" });
const result = await tako.singlePoint(structure, {
  calculator,
  properties: ["energy", "forces", "stress"],
});
await tako.output("output/single-point-summary.json", {
  energyEv: tako.analysis.energyEv(result),
});

Result

Returned calculation result with total energy, convergence data, fixed output atoms, and calculator-dependent forces, stress, charges, and electronic-property payloads. Logs and persisted files belong to the calculation workspace rather than this returned object.

Errors and Promise Behavior

• Normalization removes unknown property names and reinserts energy and forces; calculator capability validation should be run before execution. MLIP electronic-analysis requests are unsupported and are rejected, disabled, or omitted according to the calling path.
• The promise resolves only after the final result event. Validation, asset loading, calculator/SCF execution, analysis, serialization, reset, cancellation, and done without result reject it; cancellation uses Canceled by user and provides no restart checkpoint.
• GFN2 emits cumulative partial results after core energy/forces and then DOS, PDOS, charges, electron density, charge density, NCI, orbitals, spin density, ESP, density derivatives, Fukui functions, ELF, and WFN in that order. Failure in a later requested stage rejects the overall promise even when earlier partial artifacts remain.
• Requested volumetric analyses map to exact cube artifacts including electron/charge density, NCI RDG/signed density, frontier orbitals, spin density, ESP, density gradient/Laplacian, Fukui/dual descriptor, and ELF; absence is not a numeric zero.