tako.molecularDynamics 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.molecularDynamics

Runs a newly initialized MD trajectory and returns stored frames plus a scalar trace. The public result has no velocities, pressure trace, effective-mode label, or restart state.

Signature: await tako.molecularDynamics(structure, { calculator, properties, mdSteps, mdTimestepFs, mdTemperatureK, mdFrameInterval, mdEnsemble, mdThermostat, mdBarostat, mdPressureEvPerAngstrom3, mdCompressibilityAngstrom3PerEv, mdTautFs, mdTaupFs, mdFrictionPerFs, mdAndersenProbability, mdTchain, mdPchain, mdTloop, mdPloop, mdMtkMask, mdFixCom, mdSeed })

Theory

• Molecular dynamics integrates Newtonian equations of motion on the selected model potential. The timestep controls numerical stability; too large a timestep causes energy drift, unstable trajectories, or unphysical heating.
• The requested ensemble, thermostat, and barostat are independently normalized but resolved by precedence. NVE or thermostat none selects fixed-cell velocity Verlet; coherent NVT uses one thermostat plus barostat none; coherent NPT uses Berendsen/Berendsen or Nose-Hoover with one MTK barostat.
• Every call discards incoming velocities, draws a seeded mass-weighted Gaussian field, removes center-of-mass motion, and rescales with 3N components. It cannot continue a prior call because velocities and extended-system restart variables are not public.

Usage Notes

• Use short MD first to check stability, then extend mdSteps only after inspecting temperature, energy drift, and trajectory behavior.
• Use only an explicitly documented coherent routing tuple; returned settings report requested labels rather than the effective integrator.
• mdFixCom always removes initial COM motion and is applied during Berendsen, Bussi, Langevin, and Andersen propagation, but not during Nose-Hoover-chain or MTK propagation.
• NPT requires a fully periodic cell and calculator stress. MTK rejects all constraints. Pressure uses eV/ų and trace-cell matrices currently remain in internal Bohr units.

Settings

Example

const structure = await tako.input("input/liquid.extxyz");
const calculator = tako.calculator.gfn2({ dispersion: "d4" });
const result = await tako.molecularDynamics(structure, {
  calculator,
  properties: ["energy", "forces"],
  mdSteps: 1000,
  mdTimestepFs: 0.5,
  mdTemperatureK: 300,
  mdEnsemble: "nvt",
  mdThermostat: "bussi",
  mdFrameInterval: 10,
  mdSeed: 42,
});
await tako.output("output/md-result.json", result);

Result

Resolved MD object with final scalar energy/temperature, interval-sampled frames, a scalar trace that always includes the final step, final atoms, and normalized requested settings. No velocities, pressure/stress trace, resolved-integrator label, or restart state are public.

Errors and Promise Behavior

• Rejects NPT without a periodic cell and rejects effective NPT when stress is unavailable or calculator evaluation fails.
• All MTK modes reject structures with constraints; masked MTK also rejects an all-false axis mask.
• Validation does not reject ambiguous routing tuples. The promise can resolve while the effective integrator differs from the labels retained in settings.
• Calculation, serialization, worker reset, done-without-result, and cancellation failures reject. Frames streamed before rejection are diagnostic partial evidence, not a resolved trajectory.
• Cancellation and ordinary completion expose no restart state. A later call always reinitializes velocities and extended-system variables.