Known Limitations

This page is the single registry of implementation defects and hard limitations in the current Tako runtime. Method chapters and script guides link here instead of re-describing each defect. Entries are removed when the underlying behavior is fixed, so record the application revision alongside any result whose interpretation depends on an entry below.

Each entry states what is affected, what to do about it, and where the exact contract is documented.

Platform

Structures with a cell are treated as fully periodic

Any structure carrying a cell is serialized into calculation payloads with periodicity enabled on all three axes. Slabs and chains with partial periodicity are promoted to bulk periodicity, which affects periodic branches everywhere they appear — molecular-dynamics NPT, powder diffraction, and any operation that reads periodic flags. Keep genuinely nonperiodic systems cell-free, and treat partially periodic systems as approximations whose vacuum spacing you must validate. Background: How Tako Runs Calculations.

A worker “done” without a result can leave a calculation labelled running

If a worker finishes without returning a result, the pending promise is rejected and the worker reference is cleared, but the workspace is not passed through the normal failure transition and can remain labelled running. Treat that state as failed execution: preserve log.txt for diagnosis and do not interpret the workspace as resumable. See Monitor a Calculation and Diagnose Failed Calculations.

Reaction-path endpoint validation does not compare cells

The endpoint validator for reaction paths and transition states checks atom count and element identity by index only. It does not compare cells, periodicity, constraints, charge, spin, or chemically meaningful atom mapping — every interpolated image inherits the initial endpoint’s cell, boundary conditions, charge, spin, and constraints. Matching endpoint cells and consistent coordinate wrapping are caller invariants you must verify yourself.

Transition-state search (combined NEB + dimer + vibration)

The NEB-stage spring constant is passed in raw atomic units

The combined transition-state runtime passes transitionStateSpringConstant into the engine without the eV/Ų → hartree/bohr² conversion that standalone reaction paths perform, making the band about 97 times stiffer than the displayed value suggests. A displayed 0.1 must not be interpreted as 0.1 eV/Ų in the combined runtime. Record the runtime revision when comparing barriers with another code or a future corrected Tako version. Contract: settings-transitionState.

Residual fields mix units

In saddle_quality, nebResidual is currently passed through in internal hartree/bohr without a unit suffix, while dimerFmax is converted to eV/Å. Never compare the two numbers directly; use neb.final_fmax_ev_per_angstrom for a public-unit NEB residual. Contract: Transition-State Search with Tako Script.

Most dimer controls are ignored and the NEB stage is hardcoded

The combined operation runs a hardcoded improved-tangent static climbing-image NEB: interpolation, optimizer, NEB-method, preclimb, IDPP, and static-alpha selections visible in broader reaction-path controls are not used, and the public maximum-step value is not applied to the NEB stage. Of the dimer-specific controls, only the dimer maximum-step budget is read; optimizer, force threshold, maximum step, initial-mode, displacement, separation, Gaussian width, maximum rotations, and seed selections are ignored. Do not cite those settings as evidence of what the engine did. Contract: settings-transitionState.

The output frame mixes stages

The single returned frame takes its geometry, cell, and atoms from the final (possibly dimer-refined) saddle, while its step number, energy, force residual, and the top-level final_energy_ev / final_fmax_ev_per_angstrom are copied from the NEB stage. For a dimer-refined geometry, read the dimer block for its scalar result and do not assume the top-level energy belongs to the serialized coordinates. Contract: Transition-State Search with Tako Script.

The dimer stage cannot be skipped from the interface

The runtime accepts a dimer step budget of zero (keeping the NEB image as the saddle), but the setup dialog’s numeric control has a minimum of one. Skip-dimer behavior is therefore reachable only through Tako Script.

No partial results or checkpoints

The combined call does not stream stage progress or return a structured partial result: a failure in the vibration stage rejects the whole run after the NEB and dimer stages have already spent their budgets, and cancellation terminates the worker without a checkpoint. Stage-by-stage evidence requires running the stages as separate operations.

Molecular dynamics

Requested and effective dynamics can differ silently

The runtime routes the requested ensemble/thermostat/barostat triple through a first-match dispatcher, and the result metadata echoes the request rather than the effective mode. Three combinations deserve emphasis: npt + none + mtkFull runs fixed-cell velocity Verlet; npt + noseHoover + none runs isotropic MTK (cell motion despite the requested none barostat); npt + langevin + none runs Berendsen NPT. Always determine the effective mode from the routing table in Run Molecular Dynamics before interpreting a trajectory as sampling a named ensemble.

Trace cells are in Bohr while frame cells are in ångström

md_trace[].cell is emitted in the engine’s internal Bohr convention with no unit label, while frames[].cell is converted to ångström. Convert trace cells before computing volumes or densities, and never combine the two fields under an assumed common unit. Workaround code: Molecular Dynamics with Tako Script.

The final state can be missing from the trajectory

Frames are stored when step % frameInterval == 0 and no step-zero frame is emitted. When the step count is not divisible by the frame interval, the final state appears in md_trace and the final_* scalars but not in frames, trajectory_xyz, or the frame-derived energy_trace.json. Choose step counts divisible by the frame interval when the final coordinates matter.

No restart state, and a 10,000-step cap per call

The public result contains no final velocities, thermostat/barostat variables, or RNG state, and the bridge discards the engine’s restart object. A follow-up call regenerates velocities from its seed: two calls are statistically discontinuous and cannot be concatenated as one trajectory, equilibration cannot hand its exact phase-space state to production, and continuous public trajectories are hard-capped at 10,000 steps. Details: Molecular Dynamics.

Velocity initialization and reported temperature use inconsistent degree counts

Initial velocities are always regenerated (incoming velocities are not preserved), center-of-mass motion is removed for every mode, but kinetic rescaling uses 3N degrees of freedom and ignores constraints, while the reported temperature subtracts explicit constraints but not the removed COM components. mdFixCom also means different things in different modes. Expect the largest bias for small or heavily constrained systems. Details: Molecular Dynamics.

Constraint handling differs by dynamics mode

Any MTK variant rejects all constraints with a validation error, so a constrained slab cannot use MTK pressure coupling. Nosé–Hoover chains accept constraints but size thermostat masses with 3N rather than the active degree count. Details: Molecular Dynamics.

Powder diffraction

Debye scattering covers only 12 elements and silently zeroes the rest

The finite-cluster Debye branch has form factors only for C, N, O, P, S, Cl, Ni, Cu, Pd, Ag, Pt, and Au. Hydrogen and every other element silently contribute zero — a cluster of unsupported elements can return an all-zero curve without any warning. The periodic branch uses a different, larger table, so periodic success for an element does not imply Debye coverage. Validate element coverage before running Debye; a checking snippet is in Powder Diffraction with Tako Script.

Several diffraction controls are inert

The two-theta step setting is echoed but ignored by the periodic branch (which returns discrete sticks), and scaledIntensities and symmetryRefinement are ignored in Debye mode, while the Debye damping value stored in settings is used after a silent fallback even though the dialog only shows it for explicit Debye requests. Contract: settings-xrd.

Periodic requests can silently fall back to Debye

A request labelled periodic runs as Debye whenever the structure reaches the worker without both a cell and periodic flags, with no fallback reason recorded. The returned mode field — not the request — is authoritative; branch on it before interpreting the pattern. Contract: Powder Diffraction with Tako Script.

Symmetry refinement reports the request, not success

If symmetry standardization fails internally, the calculation silently proceeds on the exact input lattice while symmetry_refinement: true is still echoed, and no space group, transformation, or success flag is returned. Do not cite that field as evidence of standardization.

The angular grid cap can truncate the curve silently

Curves are capped at 20,000 points; when the cap is hit the curve ends below the requested maximum angle while the metadata still reports the full requested range, which can leave an apparently empty tail in the viewer. Check the last data point against the requested range for fine steps over wide ranges.

Non-covalent interaction analysis

Workflow NCI node settings are ignored

The visual workflow’s NCI node exposes density-floor, isovalue, spacing, and padding controls, but the runner ignores all four and dispatches the fixed native request (density floor 10⁻⁸, 3-bohr padding, fixed grid shape; isovalue is viewer state). Do not serialize those controls as though they reproduced the calculation. Contract: NCI and Volumetric Data with Tako Script.

Single point

No dipole field is published

The single-point result does not include a dipole; do not infer one from calculator capability metadata or excitation transition dipoles. Contract: Single-Point Calculations with Tako Script.

A failed later property stage rejects the whole run

GFN2 emits cumulative partial results per property stage, but a failure in any later requested stage rejects the overall promise; earlier partial artifacts may remain on disk without constituting a completed result, and cancellation leaves no restartable checkpoint.

Analysis and export

The workflow exporter can degrade adsorption-selection nodes

The visual-workflow exporter currently degrades some adsorption-selection nodes to a single active candidate and can pick the first result without computing adsorption energies. Treat exported application scripts as code requiring inspection; the export does not confirm that a thermodynamic ranking occurred. Background: Comparable Energies and Thermodynamic Cycles.