How Tako Runs Calculations

Every supported Tako calculation passes through the same execution system. An operation combines a structure with a calculator where required and with operation-specific settings, normalizes that request into an engine input, executes it in a browser worker, converts worker events into a persistent calculation workspace, and publishes a structured result with operation-specific artifacts.

This lifecycle is independent of whether the operation is a single-point evaluation, geometry optimization, molecular dynamics trajectory, vibrational calculation, phonon calculation, reaction path, transition-state search, powder diffraction pattern, or simplified excited-state calculation. The scientific meaning of those operations differs; their workspace, execution, cancellation, and artifact behavior shares one foundation.

The calculation state

A calculation request is not defined by coordinates alone. Its scientific state contains at least:

where $\mathbf R$ denotes atomic species and Cartesian positions, $\mathbf h$ denotes the periodic cell when present, $\mathbf p$ contains periodic-boundary information and atomic constraints, $\mathcal M$ identifies the calculator and electronic or model state, $\mathcal O$ is the requested operation, and $\boldsymbol\theta$ contains operation settings.

Two calculation folders are comparable only when the components relevant to the reported quantity are compatible. Equal formulas do not imply equal calculation states: differences in atom ordering, charge, spin convention, model asset, cell, constraints, convergence threshold, or preparation protocol can change the meaning of a result even when both runs complete successfully.

Structure input

Tako serializes the active structure into a worker payload containing the title; atom identifiers, elements, and Cartesian positions; per-axis selective-dynamics flags where present; a $3\times3$ cell matrix for periodic structures; and periodic-boundary flags derived from the presence of the cell. Reaction-path and transition-state workspaces additionally preserve a final endpoint as final_structure.extxyz.

The calculation receives a copy of this state. Editing the viewport structure afterwards does not mutate the saved calculation input, and editing a file inside a calculation folder does not rewrite the normalized in-memory input or retroactively change the result. Preserve an exported, unedited workspace when an audit requires the exact initially generated artifact, and start a new calculation when the numerical input itself must change.

Periodicity deserves explicit attention: a structure with a cell is sent with periodicity enabled on all three axes, and a structure without a cell is nonperiodic. A large cell around a molecule is therefore a periodic calculation, and partially periodic slabs or chains are promoted to bulk periodicity — see Known Limitations.

Calculator state

The calculator defines the potential-energy or electronic model evaluated at the supplied structure. Tako routes supported calculations to two engine families: GFN2-family calculations through the tb WebAssembly engine, and machine-learned interatomic potentials through the shared MLIP runtime with a selected model asset.

The method payload records level of theory, engine, charge, unpaired-electron convention, spin-polarization state, GFN controls, solvation controls, SCF controls, and MLIP runtime/model identity where applicable. A calculator name is only a summary; reproducibility requires the normalized settings and the model asset version associated with the run. Powder diffraction is the exception to the energy-and-force path: its input carries no electronic method payload because the pattern derives from structural and scattering information.

Calculator selection and domain limitations are covered in Choosing a Method; here the point is narrower — the calculator is part of the calculation state and must be preserved with the result.

Operation and requested properties

The operation determines which engine routine executes and which settings are meaningful; properties request additional channels when an operation supports them. Tako may add a property an operation requires — variable-cell optimization and barostatted dynamics add stress automatically. Conversely, requesting a property does not guarantee every operation returns it: the generated Operation Reference is authoritative for each public result contract.

These classes share execution infrastructure but not acceptance criteria; each method chapter defines its own equations and convergence evidence.

Normalization and validation

Interface fields and Script settings are translated into one normalized calculation input before the worker starts. Normalization supplies registered defaults for omitted settings, restricts values to engine-safe ranges or enumerations, and converts product-level names and units into the engine schema. A registered default is part of runtime behavior — a recommendation elsewhere in the documentation does not change what an omitted setting actually does.

Validation occurs at several boundaries: interface-level validation before Start, TypeScript normalization of settings and structures, worker-request validation and asset preparation, Rust/WASM input parsing with operation-specific checks, calculator capability checks, and numerical errors from the engine itself. The existence of one layer does not imply another — the reaction-path endpoint validator, for example, checks atom count and element identity but not cells (Known Limitations). Whether a condition is engine-enforced or a scientific invariant you must verify yourself is stated in each operation’s reference page.

Browser-worker execution

Supported built-in calculations execute in a dedicated browser worker. The main interface thread creates the calculation workspace and worker request; the worker loads the required engine assets, performs the numerical work, and emits structured events.

The separation has practical consequences: numerical work never runs in the viewport component, a calculation cannot touch the document object model, the interface keeps rendering while the worker computes, cancellation terminates the active worker request rather than serializing algorithm state, and results cross the worker boundary as structured data.

The worker sandbox is an execution boundary, not a guarantee that every feature is offline. Engine modules and model weights may require a network download before first use, and the Agent, custom endpoints, and live sharing are separate networked features — see Before You Start for the storage and privacy boundaries.

Model assets and caching

WASM modules and MLIP weights load on demand, with state tracked separately from the calculation workspace: bundled (shipped with the application), downloaded (complete cached asset), partial (interrupted resumable download where supported), and missing (not cached; fetched when requested).

Removing a cached model does not delete calculation folders. Clearing all browser site data is broader — it can remove both cached assets and locally stored workspaces, so export the workspace first when the record must survive. Asset availability is a runtime prerequisite, not scientific validation: a downloaded model can still be wrong for a composition, and a missing asset only means a download is needed.

Calculation workspaces

Starting an operation creates a workspace folder before numerical completion, named with an operation prefix and sequence number (SP-1-calc, Opt-1-calc, and so on — the full prefix table is in the Calculation Artifact Reference). The workspace contains an input record (normally structure.extxyz, run.js, and normalized settings; endpoint operations add final_structure.extxyz) and an output record that begins with expected artifacts in pending or available states, including an immediately available log.txt.

Pre-created artifacts give the interface a stable place to display status; they do not mean the data exist yet. An artifact transitions from pending to available after a successful result, or to failed after worker failure or cancellation.

Each workspace preserves a generated run.js — a Script representation of the operation that serves as an audit and reproduction surface for the saved settings, whether or not the run was started from Script. Copying the call while omitting endpoint files, constraints, charge state, or model identity does not reproduce the calculation state.

Worker events

The worker communicates through typed events — start, asset and calculation progress, SCF steps, optimization and trajectory frames, partial results, result, and error. The full event table, with what each event proves about a running calculation, is in Monitor a Calculation. Live observability differs by operation: geometry optimization emits accepted-step frames, while a reaction path returns detailed band data only at completion — each interface chapter states what is actually visible.

Completion states

Workspace status and scientific convergence answer different questions.

Completed means the worker returned a result that the store accepted — not that an iterative method converged. An optimization can return normally with converged: false after exhausting its step budget; a reaction path can return an unconverged band. The result object, method-specific residuals, trajectory, and warnings determine scientific acceptance.

Failed means validation, asset loading, calculator evaluation, engine execution, or serialization produced an error. Pending artifacts are marked failed; log.txt and saved inputs remain useful for diagnosis. One abnormal path — a worker done event without a result — currently bypasses the failure transition and can leave the workspace labelled running; treat it as failed (Known Limitations).

Cancelled terminates the active worker request, rejects a pending Script promise with Canceled by user, and records the cancellation. Cancellation is not a checkpoint protocol: unless an operation explicitly publishes restartable partial state, nothing resumes from the cancelled worker’s memory. Artifacts already available remain stored; pending ones are not promoted.

Reset before completion disposes active workers and rejects pending promises when the application state changes — an interruption, not a numerical failure.

Convergence and acceptance

Convergence is method-specific, and a universal “completed successfully” indicator cannot replace it: optimization uses a force criterion, molecular dynamics is judged by stability and sampling rather than convergence, vibrations and phonons depend on completed displaced-force evaluations and the reference geometry, NEB uses a path residual plus band inspection, a transition-state workflow has separate path, saddle, and vibrational conditions, and XRD is a deterministic transform still sensitive to its structural assumptions.

Scientific acceptance therefore has at least four layers:

and comparisons add a fifth: compatible reference states and normalization.

Worked lifecycle trace

A fixed-cell geometry optimization of a periodic structure connects the abstract state to evidence:

The counterexample matters equally: if the optimizer exhausts maxSteps and returns converged: false, the workspace can still be completed because the worker fulfilled its result contract. The final geometry and trajectory are diagnostically useful but are not a converged minimum. Increase the step budget only after the trajectory shows stable progress toward the intended basin; otherwise reconsider the starting structure, constraints, optimizer, calculator, or model.

Result and artifact authority

result.json is the structured operation result; operation-specific artifacts are convenient views or extracted subsets. Use the result’s convergence fields and normalized settings for numerical status, the trajectory for geometry evolution, traces for iteration history, spectrum and band artifacts for sampled plot data, cube files for volumetric fields, the saved input and run.js for provenance, and log.txt for warnings and errors. A plot is a derived view, not a replacement for its numerical artifact — the Calculation Artifact Reference maps each file to its authority.

Provenance record

A reproducible calculation record preserves:

1. input structure and endpoint structures where applicable;
2. cell, periodicity, atom ordering, and constraints;
3. calculator family, model/runtime asset, charge, and spin state;
4. operation and normalized settings;
5. result status and method-specific convergence fields;
6. trajectories, traces, spectra, grids, or paths required for interpretation;
7. software version and relevant asset version;
8. any derived analysis with its formula and source artifacts.

The workspace provides much of this automatically, but scientific provenance can include information the program cannot infer: the experimental structure source, protonation rationale, selected conformer, constraint justification, and the intended thermodynamic cycle.

References

1. A. Hjorth Larsen et al., The atomic simulation environment—a Python library for working with atoms, J. Phys.: Condens. Matter 29, 273002 (2017). General calculator/atoms conventions relevant to Tako’s engine layer.