Organize a Reproducible Workspace

Page type: Task guide

On this page

Recommended layout
Procedure
Artifact responsibilities
Verify reproducibility
Troubleshooting

Make a computational project understandable without relying on the original browser session or the author’s memory.

Recommended layout

reference/
  run.js
  source-notes.md
input/
  structure.extxyz
output/
  summary.json
  results.csv
  figure.svg
  final.extxyz
debug/
  run-log.jsonl
analysis.md

Use cache/ only for validated resumable stages; a cache is not a substitute for final outputs or provenance.

Procedure

Put executable method logic in reference/run.js.
Preserve imported/generated starting structures under input/ and record external identifiers.
Write machine-readable headline values to output/summary.json.
Write auditable intermediate/result tables to CSV or JSON.
Write visualizations from those same tables, not from separate hard-coded values.
Write analysis.md with question, method, validation, result, limitations, and links.
Export a workspace ZIP after a successful checked run.

Artifact responsibilities

Path	Must answer
`reference/run.js`	Exactly what was executed?
`input/`	What structures/data entered and where did they come from?
`output/summary.json`	What are the headline values and quality gates?
`output/*.csv`	Can a reviewer rederive the result?
`output/*.svg` / Plotly JSON	Can the result be inspected visually?
`analysis.md`	What does the result support and not support?
`debug/`	What happened when a stage failed or was retried?

Verify reproducibility

Open the exported archive in a separate workspace/profile when practical. Confirm all referenced files exist, inputs are independent of hidden state, model identifiers/settings are explicit, and failure gates prevent an incomplete run from producing success claims.

Troubleshooting

Symptom	Cause	Fix
Report cites missing file	Output path changed	Generate links from stable paths and verify archive
Result cannot be rederived	Only headline number saved	Preserve raw energies/terms and formula
Rerun depends on current tab	Script uses implicit active state	Read explicit input paths
Cache hides failed work	Cache acceptance is weak	Store version/settings/convergence metadata
Archive is enormous	Raw trajectories/caches dominate	Use `.takoignore` for live share; retain deliberate durable data