MATERIA Workbench

MATERIA — an AI-native foundation for materials science. Crystal and magnetic structure refinement that runs entirely in your browser, and is built from the core up to be driven by LLM agents as well as by people. This is its web workbench; the same pure core is exposed to agents as tools (see docs/AGENT_TOOLS.md).

▶ Try it in your browser: drthyang.github.io/web-refinement — a fully static GitHub Pages app; nothing to install, and your data never leaves your machine. Two bundled demos open converged from the start page: a two-phase Mn₃Ga neutron TOF Rietveld fit (wR 3.9%) and a GaTa₄Se₈ X-ray PDF fit of the local structure, where the average-structure model is deliberately left to disagree with the data at short range.

_{A converged two-phase TOF Rietveld fit (Mn₃Ga + MnO impurity, POWGEN) in the workbench. The screenshot is generated from the live app by scripts/device-screenshots.mjs.}

The vision: refinement an agent can reason about

Structure refinement is not a black-box optimization — it is an expert loop. Never refine everything at once; watch parameter correlations; free only symmetry-allowed parameters; judge the residuals, not just wR. Learning that judgment is the hardest part of the field, and it is exactly the kind of reasoning a language model can drive.

This workbench is designed for that from the ground up. Every scientific capability lives in a pure, side-effect-free TypeScript core (src/core/**): deterministic functions over plain, serializable data. The same functions that back the UI buttons can therefore be exposed as agent tools (via MCP or the Claude Agent SDK), and the expert procedures that compose them become skills — one validated engine, whether you click the button or the agent calls the tool. The engine already returns what an agent needs to think with — parameter correlations, SVD near-null directions, at-bound flags — not just a scalar wR — so an agent can run the same loop an expert runs by hand:

observe → decide → act → check

This agent layer is a work in progress: it ships incrementally as each scientific milestone lands — never a wholesale "agent mode" bolted on at the end. See docs/AGENT_TOOLS.md for the tool/skill catalog and the LLM-guided refinement design, and docs/ROADMAP.md for the build sequence.

The second goal: lowering the barrier to entry

Starting a Rietveld or single-crystal refinement today means choosing among several mature packages — GSAS-II, Jana2020, FullProf, TOPAS, SHELX, Olex2 — several of which handle both powder and single-crystal data. Each choice pulls in its own ecosystem: its own data formats, its own instrument-parameter files, its own split between single-crystal and powder workflows, and its own formalism for magnetic structures (magnetic space groups in one, irreducible representations in another). Some closed-source options are effectively Windows-only, which puts them out of reach on Unix/Linux systems. None of this is any package's fault — each grew deep to serve its facility and its community, and they remain the tools of record that this project validates against. But the combined effect is a steep on-ramp: a beginner faces many consequential choices before ever seeing a first fit.

This project aims to lower that barrier:

• Nothing to install. A static web app that runs on any OS with a modern browser — Linux included. Live at drthyang.github.io/web-refinement, or self-host the built dist/; the core workflow has no backend, so your data stays on your machine.
• One workflow instead of four ecosystems. Single-crystal and powder, X-ray and neutron (constant-wavelength and time-of-flight), nuclear and magnetic — one shared refinement engine, one UI.
• Reads what you already have. CIF/mCIF, hkl and FullProf .int reflection lists, plain-column / GSAS .gsa·FXYE / ILL powder data, and instrument files from GSAS-II (.instprm), classic GSAS (.prm INS/ICONS), and FullProf (.irf — CW Caglioti and TOF, plus the D2B/3T2/G4.2 INSTRM=6 variant) — with format auto-detection that reports how each decision was made, lets you override it, and names the beamline · facility when the file identifies one.
• Transparent by design. A guided step-by-step procedure that starts from a small, safe set of choices; fit quality judged with F_obs vs F_calc and normal-probability plots, not wR alone. Every scientific function is pure, tested TypeScript you can read.
• A bridge between magnetic formalisms. A magnetic-space-group (Shubnikov/BNS) workflow today, with representation analysis being built alongside it — so both descriptions of the same physics live in one tool.

This is a complement to the established packages, not a replacement — see docs/COMPARISON.md for an honest capability matrix.

This package is an early browser-native refinement workbench for transparent model building, simulation, and basic constrained refinement. Results intended for publication must be validated against established tools and expert crystallographic judgment.

Status

Public beta. A working app — atomic/nuclear refinement (single-crystal + powder) plus a commensurate single-k magnetic workflow — and a first agent-tool layer over the same core. The scientific core, Levenberg–Marquardt refinement engine, symmetry-adapted constrained parameters, CIF parsing, a 3D structure/moment viewer, plots, and Web Worker compute are implemented and tested (1111 passing tests). Crystallographic and scattering foundations are validated against bundled GSAS-II refinements (see docs/REPORT.md and docs/VALIDATION.md). As with any beta, results intended for publication must be validated against established tools (docs/LIMITATIONS.md).

Agent tools (milestone 1): an MCP server exposes the pure core to LLM agents — parse → build → refine → assess (expert judgment: verdict, dangerous correlations, at-bound/unphysical parameters, unexplained residual peaks) → suggest next steps → interpret (materials reading). The judgment lives in tested pure core (src/core/diagnostics/), so an agent reasons about a refinement rather than just running it. See docs/AGENT_TOOLS.md.

The magnetic workflow runs end to end: auto-detect magnetic peaks → k-vector search → little-group magnetic subgroups → editable moment preview → moment refinement (k = 0 and k ≠ 0, CW and TOF, on one shared scale). Occupancy- disorder sites refine with tied position/ADP, a Σ(occupancy) restraint (optionally = 1), and an optional shared moment. Fit quality is judged with F_obs vs F_calc and normal-probability plots, not just wR. Candidate magnetic groups carry their standard BNS/OG labels (bundled ISO-MAG table), and refined structures export as CIF/mCIF with esds (k ≠ 0 writes the magnetic supercell). The star of k / multi-k and full representation analysis are the next milestones; see docs/ROADMAP.md and docs/LIMITATIONS.md.

Real-space PDF (pair distribution function). A local-structure track now runs on the same engine — "real-space Rietveld": nuclear neutron and X-ray G(r) fitting (Proffen–Billinge forward model, δ1/δ2 and sratio/rcut correlated motion, Qdamp/Qbroad envelopes, Qmax termination ripples, spdiameter nanoparticle envelope, Faber–Ziman element-pair partials), multi-phase and multi-dataset (temperature-series / joint X-ray+neutron) co-refinement, and .gr/.sq/.fq import (PDFgetX3 + Mantid dialects). It is cross-checked against a local PDFfit2 1.6.0 with committed CI golden fixtures — Ni and MnO X-ray G(r) to corr ≈ 0.9998 and refined cell recovery < 1 mÅ — plus a PDFgui G_calc golden.

The PDF track also carries a symmetry-mode distortion workflow (AMPLIMODES/ISODISTORT-style): refine symmetry-adapted mode amplitudes instead of raw coordinates — enumerated from the structure's own space group or decomposed against a parent CIF — activate a symmetry-breaking Γ mode from the isotropy-subgroup tree, or pick a target subgroup from the full translationengleiche (Bärnighausen) subgroup lattice; clicking a mode draws its eigenvector on the 3D model. The nuclear track (P0–P3) and its agent slice are done, and the magnetic PDF (mPDF) core is validated against diffpy.mpdf; the mPDF page and the symmetry-constrained local-spin model are the next milestones. Full plan in docs/PDF_MPDF_ROADMAP.md.

Bayesian uncertainty (new — prototype). The engine can now sample the posterior, not just linearize it: an affine-invariant ensemble MCMC sampler (Goodman–Weare stretch move) runs behind the same pure-core seam as the least-squares driver, with a noise model suited to PDF unit weights, split-R̂ / ESS convergence diagnostics, and credible intervals. On the Ni PDF golden the posterior widths match the linearized LM esds to 1% (esdRatio 0.99–1.01) — uncertainty an agent can reason about, not just a scalar esd. It rides on the first analytic PDF gradients (a fused ∂G/∂p pass, bit-identical G(r), measured 2.3× faster LM refinement on the same golden), which also power a gradient-based NUTS sampler (mass matrix seeded from the LM esds — R̂ ≈ 1.001 in ~5× fewer evaluations). Surfaced two ways: the sample_posterior agent tool (ensemble or NUTS, resume-token continuation) and a Posterior view in the PDF workbench (marginals, credible intervals, esd ratio, R̂/ESS). Approach after Fancher et al. (2016, Sci. Rep. 6, 31625); reporting per McCluskey et al. (2023, J. Appl. Cryst. 56, 12) — see docs/REFERENCES.md.

The MCP tool surface has grown to 33 contract-tested tools spanning the powder, single-crystal, and PDF tracks (the PDF tools: parse_pdf_data, build_pdf_model, refine_pdf, compute_partial_pdf, calibrate_qdamp, sample_posterior, plus build_distortion_modes / build_symmetry_modes for mode-amplitude fits).

Commands

npm install     # install dependencies
npm run dev     # start the local dev server
npm run build   # type-check and build the static site
npm run test    # run the test suite (Vitest)
npm run test:ganb4se8  # required real-data powder regression

Use npm run test:ganb4se8 for refinement-engine changes. It requires the local data/GaNb4Se8_XRD/ files and fails if they are missing; this dataset is the primary real-data check because it exposes the current build's powder-refinement failure modes much better than synthetic examples.

Scope

Single-crystal and powder workflows sharing one refinement engine, for both nuclear and magnetic structures:

• Load CIF structures, hkl reflection tables, powder patterns, and reduced pair distribution functions (.gr/.sq/.fq).
• Compute nuclear and magnetic structure factors and intensities.
• Fit reduced pair distribution functions G(r) (neutron / X-ray) in real space — "real-space Rietveld," single- and multi-phase, with element-pair partials.
• Refine scale, coordinates, occupancies, displacement, lattice, background (Chebyshev / Fourier / lin+log interpolation), peak width, microstructure (crystallite size & microstrain, isotropic / uniaxial / generalized Mustrain), and magnetic moments — with fixed/free states, bounds, and constraints.
• Compare observed vs calculated, track refinement history, and export the refinement — a reproducible project JSON, or a one-click FullProf / GSAS-II cross-check bundle (control file + data + instrument, with your original instrument and data files included verbatim).

Architecture in one paragraph

A static web app (React + TypeScript + Vite) with strict layering and one-directional dependencies. src/core/** is pure TypeScript — no React, DOM, or workers — so every scientific function is pure and independently testable. UI components handle presentation only; long calculations run in Web Workers, with optional WebGPU kernels adding opt-in f32 acceleration over the correct f64 CPU path (WebAssembly is skipped). Full detail in docs/ARCHITECTURE.md.

Documentation

• docs/ROADMAP.md — the single authoritative roadmap (vision, foundations, milestones, agent layer)
• docs/PDF_MPDF_ROADMAP.md — the real-space PDF / mPDF track (nuclear done; mPDF next)
• docs/AGENT_TOOLS.md — agent tools, skills, and the LLM-guided refinement plan
• docs/ARCHITECTURE.md — layers, source tree, conventions
• docs/DATA_MODEL.md — data types and their reasoning
• docs/REFINEMENT_ENGINE.md — the least-squares design
• docs/SCATTERING_TABLES.md — neutron / X-ray / magnetic form-factor tables
• docs/VALIDATION.md — testing & external comparison strategy
• docs/LIMITATIONS.md — scope and known simplifications
• docs/PROJECT_FORMAT.md — the project JSON format
• docs/REFINEMENT_PROCEDURE.md — the guided 7-step workflow
• docs/COMPARISON.md — features vs GSAS-II / Jana2020 / FullProf
• docs/REFERENCES.md — bibliography: papers, data sources, and GSAS-II (validation reference)
• docs/REPORT.md — build & validation report
• docs/archive/ — superseded plans (POWDER_ROADMAP, MATURITY_PLAN), kept for detail

License

GNU Affero General Public License v3.0 (AGPL-3.0-only).

This is a web application: if you run a modified version on a network server, you must make the complete corresponding source code available to its users (AGPL §13).

This project is personal work, developed and maintained in my personal capacity.