Tako DocsReproducibility and Reporting
On this page
Every method chapter in this documentation ends with the same two obligations: preserve enough information that another person can rerun and audit the calculation, and phrase the conclusion so its strength matches the evidence. This chapter states those obligations once. The method chapters keep only their method-specific additions and link here for the shared standard.
What a record must allow
A reproducibility record has two audiences. A re-runner needs the exact inputs: the same structures, states, calculator, and settings should produce the same result up to declared numerical noise. An auditor needs the derivation chain: every reported number must trace to a stored artifact through stated formulas and stated exclusions. A record that supports reruns but hides which trajectory frames were discarded fails the auditor; a record with beautiful plots but no normalized settings fails the re-runner.
The shared record skeleton
Every calculation record, regardless of operation, preserves:
| Category | Record |
|---|---|
| Structure | Coordinates, elements, atom ordering and identity mapping, cell, periodicity, and the provenance of the starting geometry |
| Physical state | Total charge, unpaired electrons or spin state, constraints with their justification, imposed external conditions |
| Calculator | Family, level of theory, model/weight asset and version or hash, dispersion, solvation, SCF or inference controls |
| Operation | The operation, its complete normalized settings, and — where requested and effective settings can differ — the effective behavior with a link to Known Limitations |
| Convergence | The method-specific convergence fields and thresholds actually tested, not just a completed status |
| Artifacts | The authoritative machine-readable results (result.json, trajectories, traces, spectra, grids) — not screenshots of them |
| Versions | Tako build or revision and relevant engine/model asset versions |
| Analysis | Every derived quantity with its formula, source artifacts, and unit conventions |
| Failures | Every warning, failed stage, cancellation, rerun, and manual intervention, with the criteria used to exclude anything |
The calculation workspace preserves much of this automatically — the saved input, run.js, normalized settings, logs, and artifacts are described in How Tako Runs Calculations. What the workspace cannot infer is scientific provenance: where the structure came from, why this protonation state or conformer, why these constraints, and which thermodynamic cycle the numbers are destined for. Write those down at run time; they are unrecoverable later.
Completed is not valid
A completed workspace status establishes runtime completion only. Scientific acceptance layers on top of it: the method’s numerical criterion, structural plausibility, and model suitability — plus compatible reference states for any comparison. The layering is defined once in How Tako Runs Calculations; each method chapter defines its own numerical criterion. Never let a green status stand in for the layer it does not test, and never report a plausible-looking number from a run whose convergence field says otherwise.
Language proportional to evidence
Distinguish three kinds of statement and phrase each honestly:
- Observation: what the artifact shows. “The O–H distance remained between 0.95 and 1.05 Å during 5 ps of Bussi dynamics under model X.”
- Bounded inference: what the observation supports within the model and sampled scope. “The local bonded structure is metastable on this model surface over the sampled interval.”
- Extrapolation: a claim beyond the model or timescale. “The material is stable at room temperature” — this needs far more evidence than one trajectory, and the report must say what that evidence would be.
Useful qualifiers carry information: “screening”, “demonstration”, “within this model”, “at this evidence level”.
Three reporting rules follow:
- Report effective behavior, not just requested labels. When a runtime routes or ignores a control (see Known Limitations), the method section must state what was actually integrated, optimized, or evaluated. Reproducing a misleading settings table is worse than omitting it.
- Report sensitivity as comparable cases. Vary one declared thing at a time — threshold, image count, timestep, seed, model — and present the variants side by side. Do not overwrite exploratory runs, do not average results that answer different questions, and do not choose an equilibration cutoff or exclusion after seeing which choice flatters the result without saying so.
- Report failures and exclusions with counts and criteria. Selective removal of unfavorable runs biases every estimate. “Two of five seeds were excluded for SCF failure at step >800” is evidence; silence is not.
Precision and presentation
Numeric precision in a report should reflect the method and convergence evidence, while artifacts may retain full precision for reuse — retaining digits in a file is not a claim of physical accuracy. Lead with the question, effective method, headline observable with uncertainty, and the main limitation; keep routing detail, convergence tables, and provenance in a methods or appendix layer, where the audit trail stays intact without burying the claim.
Method-specific records
Each method chapter defines the fields that matter beyond the shared skeleton:
| Operation | Method-specific record |
|---|---|
| Geometry optimization | Geometry Optimization — force-norm definition, cell policy and masks, staging, basin evidence |
| Molecular dynamics | Molecular Dynamics: Statistics and Validation — effective route, initialization caveats, equilibration, autocorrelation, replicas |
| Reaction paths | Nudged Elastic Band Method — endpoints and mapping, formulation, budgets, band archive |
| Transition states | Transition States and the Dimer Method — stage convergence, effective units, mode and connectivity evidence |
| Vibrations and phonons | Molecular Vibrations · Crystal Phonons — displacement, stencil, supercell, mode treatment |
| Diffraction and spectra | Powder X-ray Diffraction · UV–Vis — branch, radiation or roots, folding kept separate from discrete data |
| Energy comparisons | Comparable Energies and Thermodynamic Cycles — reference states, cycles, correction layers |