v2.1.0 — Reproducible results

v2.0 made SimpleAtom stop returning wrong numbers. v2.1 makes the numbers it returns
verifiable by someone else, months later, without asking you.

Every result carries a reproducibility manifest

A model name is not a reproducible identifier. "MACE-OFF small" tells you nothing about
which weights ran. Each calculation now returns:

• the SHA-256 of the checkpoint that was actually loaded
• versions of mace-torch, torch, ase, numpy
• a hash of the input structure, and of the input file
• device, precision, and the MD seed
• the source commit, with a dirty flag — a commit hash from a modified tree names code
  that never ran, so that distinction is recorded rather than implied

The checkpoint is identified by observing the load as it happens, not by re-deriving the
cache path, so it cannot silently drift out of step with upstream. It records how it
identified the file, and where something cannot be resolved it reports null with a reason
instead of guessing. No absolute paths are included — a manifest travels into shared links
and PDF exports, and a home directory does not belong in either.

Cost is ~0.06 s on a 134 MB checkpoint, cached so a replaced file cannot keep serving a
stale digest.

Advisory validation on every run

A validation pass now runs on every calculation and reports alongside the result. It is
advisory and never blocks: its thresholds are plausibility heuristics, and a single-point
on a strained or clashing geometry is a legitimate request — precisely the case where you
want the number. The checks that must block already run earlier, before any model loads.

Two places the interface stated things that were not true

• The Run Configuration described a run that never happened. Client form state was merged
  underneath the backend's record of what was effective, so a static single-point displayed
  300 K · Δt 1 fs · friction 0.005 /fs · 100 MD steps · NVT. Eight molecular-dynamics and
  optimisation parameters for a calculation that had none — and it propagated into PDF
  exports, CSV exports and every shared link.
• Reported timing was round-trip latency wearing a fabricated decimal. A run the backend
  timed at 0.132 s displayed "4.0 s": wall clock including model download, rounded to a whole
  second, then rendered to one decimal place. Compute time and round-trip are now separate,
  separately labelled, and displayed precision never exceeds what the source actually has.

3D viewer

• Click atoms to measure. Two atoms give a bond length in Å, three an angle in degrees
  with the vertex named, four a signed dihedral — and selection order sets the vertex and the
  sign, as it should. Two atoms report Bond length only when a bond was actually
  perceived; otherwise Distance, with the distinction stated rather than glossed.
• Ambient occlusion had never once rendered. The WebGL2 capability check probed the
  visible canvas, which holds a blit target rather than a WebGL context whenever the viewer
  renders offscreen — so the check failed on every capable machine and the feature disabled
  itself silently on every load.
• Structures were framed too small, and bulkier representations came out smaller than
  slimmer ones. The padding term added the largest radius of any element present to the
  outermost atom's position, so the error grew with the radii — spacefill, with the largest
  spheres, was framed smallest.
• New settings menu: rotate, hide C–H bonds, clear selection, and PNG export.
• The canvas is transparent, so the molecule sits on the page rather than in a white box.

Mobile

/calculate overflowed the viewport on a phone. A grid declared its columns only above the
lg breakpoint, so below it both panes fell into a single content-sized track and every card
inherited a width wider than the screen — which real browsers answer by zooming the whole
interface out.

Housekeeping

Removed a dead 417-line results component that still carried the mislabelled energy fixed
everywhere else — a trap for anyone who found it by search. Corrected every remaining
reference to a validator path that has never existed.

Verifying it yourself

export KMP_DUPLICATE_LIB_OK=TRUE
python3 -m unittest discover -s test_scripts -p "test_provenance.py"   # 40 tests
python3 test_scripts/validate_calculation.py --test

The provenance suite was mutation-tested: six deliberate defects were injected —
including a plausible hardcoded SHA-256 and a manifest built after the geometry had already
relaxed — and all six were caught. The strongest test re-finds the checkpoint by filename and
hashes it with plain hashlib, through no project code at all, so a stale or fabricated
digest fails it.

Known limitations in this release. The validator is not present in the hosted container
(its build context cannot reach the test directory), so hosted results report validation as
unavailable rather than running. Viewer framing still sits a few percent under target, and
force-vector arrows are included in the fit, which shrinks the molecule when they are shown.

Full documentation: https://mace-lake.vercel.app/docs

v2.0.0 — Correctness release

SimpleAtom v2.0 is a correctness release. The interface changed; what changed more is
whether you can trust the numbers.

SimpleAtom wraps MACE. The main risk in a wrapper is not
crashing — it is returning a plausible number for a calculation that never ran. v2.0 was
audited specifically for that failure mode and found six instances. Every one read as
correct code. None would have been caught by reviewing a diff.

Calculations now fail loudly instead of quietly returning the wrong thing

• calculationType had no allow-list. The backend dispatched if geometry-opt / elif molecular-dynamics with no else, so any unrecognised type fell through to a
  single-point and came back labelled as whatever was requested. The API accepts arbitrary
  JSON, so {"calculationType":"phonon"} returned a single-point energy presented as a
  phonon run.
• modelType had no allow-list. Selecting a custom model without uploading a checkpoint
  returned MACE-MP-0 results labelled custom — shareable and exportable, permanently
  attributing numbers to a model that was never loaded.
• Both are now validated in the Python backend, which is the real boundary since the API is
  callable directly, and mirrored in the route handler as a fast 400.
• Geometry optimisation reports whether it actually converged. BFGS.run()'s return
  value was discarded, so a run that exhausted maxOptSteps without reaching fmax was
  described as completed.
• Results echo the parameters that actually ran — defaults resolved, CUDA→CPU fallback
  applied, the real dispersion state, and the precision read off the loaded model rather
  than the one requested.

Molecular dynamics is reproducible and correctly reported

• Every stochastic source is seeded from one generator, and the seed is recorded in the
  result message so it survives sharing and PDF export. Two runs at the same seed produce
  identical trajectories.
• The MD chart was plotting potential energy under a "total energy" label, which made
  the NVE conservation the docs tell you to verify impossible to see. Potential, kinetic and
  total energy plus temperature are now all recorded and plotted separately. Measured on a
  real run: total drifts 1.4 meV while potential swings 112 meV — the trajectory was
  conserving energy correctly all along.
• Centre-of-mass drift is removed after velocity initialisation, so reported temperature is
  no longer inflated by rigid translation (mean 201.0 K → 181.3 K on a test run).

A structure-parsing bug that corrupted every crystal

CIF fractional coordinates were never converted through the unit cell. Most
crystallographic CIFs store fractional coordinates, so loading one packed every atom into a
1 Å box — silicon came out with a 0.433 Å nearest-neighbour distance instead of 2.3516 Å, a
factor of 5.4. Every distance, every perceived bond, and any energy computed from it was
meaningless. The parser also read no unit cell at all, so nothing downstream could tell a
crystal from an isolated molecule.

Now fixed for CIF, POSCAR and extended-XYZ, with public/demo/silicon.cif committed as a
regression fixture.

Scientific guardrails at the point of entry

• MACE-OFF warns when the structure contains elements outside its coverage
  (H, C, N, O, F, P, S, Cl, Br, I).
• NPT is disabled without a periodic cell, and falls back to NVT if the structure changes.
• MD timestep ceiling lowered from 10 fs to 4 fs — 10 fs produces garbage and was silently
  allowed.
• D3 dispersion is locked out where it would double-count, including for custom checkpoints
  whose loader ignores the flag entirely.
• Every numeric input shows its unit and valid range.

Other fixes

• D3 dispersion never worked. torch-dftd was in neither our requirements nor
  mace-torch's, so enabling it always failed — after downloading the model. Now installed,
  with a preflight check that fails before any model is fetched if it is missing.
• Precision follows upstream's defaults (float64 for MACE-OFF and for geometry
  optimisation) instead of being pinned to float32.
• The docs advertised a FIRE optimiser that does not exist; BFGS is hardcoded.
• npm run lint was linting a Python virtualenv and reporting 42,891 problems, making the
  project's own "no new warnings" gate meaningless. Now 37, all real.

What SimpleAtom deliberately cannot do

MACE is an interatomic potential. It produces energies, forces and stress, and has no
electron density — so orbitals, partial charges, Fukui indices, pKa, redox potentials and
NMR shifts are not approximated, stubbed, or hidden behind a "coming soon" toggle. They are
absent, and phonon is rejected with an error rather than quietly running something else.

Verifying it yourself

These must all fail. If any returns a result, a silent fallthrough has come back:

export KMP_DUPLICATE_LIB_OK=TRUE
python3 mace-api/calculate_local.py public/demo/ethanol.xyz '{"calculationType":"phonon"}'
python3 mace-api/calculate_local.py public/demo/ethanol.xyz '{"modelType":"custom"}'
python3 mace-api/calculate_local.py public/demo/ethanol.xyz '{"modelType":"MACE-MP"}'

And the full scientific validation suite:

python3 test_scripts/validate_calculation.py --test

Full documentation: https://mace-lake.vercel.app/docs

v1.3.0 — Warm redesign, accessibility & in-app docs

SimpleAtom v1.3.0 is a ground-up redesign focused on making MACE genuinely useful — and welcoming — for the science community. It replaces the old dark interface with a warm, humanist, accessible design, adds real in-app documentation, and fixes several correctness issues, all verified with a live end-to-end MACE calculation.

Live: https://mace-lake.vercel.app

✨ Highlights

A new, humanist interface

• Warm off-white theme with a light-green accent and a serif display face — calm, low-contrast, and readable (replacing the previous dark/neon theme).
• Unified branding as SimpleAtom across the app.
• Built on shadcn/ui primitives for consistent, accessible components.

More ways to start a calculation

• Structure input now covers file upload (.xyz, .cif, .poscar, .pdb), the ml-peg benchmark catalog, SMILES → 3D generation, and a 2D/3D molecular sketcher (Ketcher).
• New "Recent calculations" history — stored locally in your browser, no account required.

In-app documentation

• A new /docs section: Overview, Getting started, Foundation models, Calculations & parameters, Units & conventions, Validation & reproducibility, and an FAQ — accessible to newcomers yet rigorous for practitioners.

Support the project

• A new /support page so the community can help keep SimpleAtom free and running (via Ko-fi). Supporting is always optional — every feature stays free for everyone.

Accessibility

• Proper roles/ARIA on tabs, status, and controls; full keyboard navigation; prefers-reduced-motion support; and the colorblind-safe Paul Tol palette across all charts.

🔬 Scientific correctness fixes

• Removed a misleading Energy R² metric that was hardcoded to 1.0 for a single data point — it now reports the signed energy error vs. a reference instead.
• D3 dispersion is now automatically disabled for MACE-OFF, which already includes dispersion (prevents double-counting).
• Corrected the README/docs — removed a non-existent generate-surface endpoint, documented the real inputs, and replaced the outdated aesthetic description.
• Share/citation/export URLs are now environment-aware (no hardcoded host); removed dead code and stale comments.

✅ Verification

• Production build compiles cleanly; all pages statically prerendered where possible.
• Live end-to-end MACE calculation verified (ethanol single-point, −46.87 eV ≈ −5.21 eV/atom, forces ~0.1–1.6 eV/Å) rendering correctly through the redesigned results dashboard.

🙏 Credits

Powered by the MACE framework (Batatia et al., NeurIPS 2022). Built by Zicheng Zhao, Northeastern University.

---

🤖 Release notes drafted with Claude Code

V 1.2.0 Stable MACE Web Interface

This release marks the transition from active development to a validated, production-ready tool. Every calculation path has been tested end-to-end:

1. All 3 calculation types verified: single-point energy & forces, geometry optimization (BFGS), and molecular dynamics (NVE/NVT/NPT) produce scientifically correct results across both foundation models

2. Automated validation suite: a dedicated validate_calculation.py script checks energy bounds (model-aware for MACE-MP-0 vs MACE-OFF reference conventions), force conservation, interatomic distances, lattice validity, trajectory stability, and parameter sanity (including D3 dispersion double-counting detection)

3. Model verification: MACE-MP-0 on Si bulk returns -5.37 eV/atom with near-zero equilibrium forces; MACE-OFF on H2O achieves perfect force conservation; ethanol geometry optimization converges in 4 steps

4. 14 benchmark structures spanning bulk crystals (Si, Cu, NaCl, Fe, diamond), molecular systems (H2O, ethanol, methane, benzene, aspirin), non-covalent complexes (water dimer, methane dimer), and surfaces (Cu(111), Si(111))

5. Streamlined feature set: removed the experimental 2D molecule sketcher to focus on the validated file-upload and catalog-based workflow

6. Dual-mode backend: local Python subprocess for development, remote FastAPI on Hugging Face Spaces for production — both tested and operational

7. MACE Link sharing: every calculation becomes a permanent, shareable URL backed by Supabase with row-level security

MACE ML Force Field Web Interface

A visual web interface for running MACE force field calculations — no coding required. Upload a molecular structure, pick parameters, and get energy, forces, and a 3D viewer.

General Calculator (/calculate)

1. Upload molecular structure files (.xyz, .cif, .poscar, .pdb)
2. Choose a MACE model: MACE-MP-0 (Pre-trained on materials, 89 elements — use for crystals, alloys, oxides, etc., without training) or MACE-OFF (Pre-trained for organic molecules — use for drug-like molecules, liquids, soft matter)
3. Run calculations: single-point energy, geometry optimization, or molecular dynamics
4. View results: energy, forces, 3D molecule viewer, MD trajectory animation, downloadable PDF report

Semiconductor Materials Discovery (/semiconductor)

1. Browse a pre-built library of 11 chip-relevant materials across 5 categories: substrates (Si, Ge), III-V semiconductors (GaAs, InP), dielectrics (SiO₂, HfO₂, Al₂O₃), nitrides (Si₃N₄, TiN), and metals (Cu, W)

What's Changed

• Install Vercel Speed Insights for Next.js by @vercel[bot] in #1

New Contributors

• @vercel[bot] made their first contribution in #1

Full Changelog: https://github.com/Jamessfks/mace/commits/MACE-Web-Interface