diff ref struct Rietveld refinement for the Mac · powder diffraction with X-rays, synchrotron and neutrons · started October 2026

Design: open questions

Design: open questions

What has to be decided before the core is written, with the options seen today and a first opinion on each. Every question now has a logged decision: Q1 in L021, Q3 in L020, Q2 and Q4–Q6 in L022. The options weighed are kept below each decision.

The shape: core, app, ecosystem

As in difes: the core holds all the crystallography and the refinement, has no user interface, has a test for every feature and a command-line path to every feature. The app is a native Mac window around it and holds no physics. The ecosystem is this site, its data and its tools. One repository holds the three (L003).

Q1 · The language of the core

  • Rust. The same language as Tauri's side, so the core links straight into the app with no server or interpreter to ship; fast; one binary for the command line. Fewer crystallographic libraries to lean on.
  • Python with compiled kernels. The GSAS-II route and the difes habit; quick to write and to script; the interpreter has to be shipped inside the app.
  • A Fortran or C++ kernel under either of the above. Where FullProf's and GSAS's numerics come from.

First opinion: Rust for the core, with Python bindings for scripting, because a refinement program lives or dies by the speed of its inner loop and the Mac app is best as one signed binary. To be confirmed against the feature matrix.

decided (L021) The core is written in Rust, linked straight into the Tauri app and built as one command-line binary. Python is the scripting interface: bindings to the Rust core (PyO3) in version 2 (P48). No physics is written in Python.

Q2 · The space groups

R12 asks for the complete set with all the needed information. The tables can be generated from generators (Hall symbols) rather than typed in, and checked against an independent source (the International Tables, Vol. A; spglib; cctbx's sgtbx) for all 230 groups and their settings. Magnetic groups (the 1651 Shubnikov groups) are needed if magnetic refinement is in scope, which the study will tell.

decided (L022) All 230 space-group types in their 530 settings are generated from Hall symbols, not typed in, and every one is tested against spglib and the International Tables, Vol. A. Magnetic groups are not built now (magnetic structures are "later", L012), but symmetry is stored as general operators (rotation matrix and translation), so that magnetic and superspace groups can be added without rewriting the core.

Q3 · The control file

R13 and R14 ask for a GUI that writes the control file and an editor made for it. That supposes a control file that a person can read and write. The choice: adopt an existing format (FullProf's .pcr, TOPAS's .inp) or define a new, readable one and import the others. First opinion: a new format designed for reading and diffing, with importers for .pcr and GSAS-II project files, so that existing refinements open in the app.

decided (L020) A new readable text format of our own, written and read by the core, with an importer for FullProf .pcr files. A GSAS-II importer is not planned for version 1.

Q4 · The editor

A text editor made for the control and output files: syntax colouring, completion of keywords and of the names of phases and atoms, inline errors from the core's parser, folding by phase and pattern, a structure outline, jump from an output line to the parameter it refers to. A web editor component (CodeMirror 6) inside the Tauri window gives all of that with a language mode written for the format.

decided (L022) CodeMirror 6 inside the Tauri window, with a language mode for the diff-ref-struct control file (L020): colouring, completion of keywords and of phase and atom names, inline errors from the core's parser, folding by phase and pattern, an outline.

Q5 · The live plot

R08: as in FullProf's WinPLOTR, the observed, calculated and difference curves and the reflection markers redrawn after every cycle, with the agreement factors. The core must therefore report each cycle as an event (parameters, curves, R-factors) that the app draws without waiting for the end. The same event stream feeds a history of the refinement that can be scrolled back.

decided (L022) The core reports every least-squares cycle as an event (parameters with their shifts, calculated curve, agreement factors); the app redraws the observed, calculated and difference curves and the reflection markers on each event, and the events form the refinement history behind accept/reject (proposal, L020).

Q6 · The Mac app

R01: a document-based app (one refinement project per window or tab), the full menu bar with the standard entries and shortcuts, Settings, Recent items, Undo and Redo of every change to the model, a source list, an inspector and a command palette, as in the difes shell.

decided (L022) A document-based Mac app as in the difes shell: one refinement project per window or tab, the full menu bar with standard shortcuts, Settings, Recent items, Undo and Redo of every change to the model, a source list, an inspector and a ⌘K command palette.

Q7 · The licence

Several parts of the core are ported from CrysFML, FullProf's library, which is under the LGPL-3: the Finger–Cox–Jephcoat profile (Prof_Val), the choice of unique reflections (Hkl_Uni, Asu_Hkl), the scattering tables and the profile range (Locate). A translation into Rust is a derivative work. While the repository stays private nothing follows from it; a distributed app brings the LGPL's obligations for those parts. The options: an LGPL-compatible licence for the project; keeping it private and undistributed; or rewriting those parts from the published papers instead of from CrysFML's code. open (L045) To be decided before any public release of the core or the app.

Q8 · FullProf as a reference, not a template

decided (L043) FullProf and GSAS-II are references for the results, not models for the design. The core's own model is the default: parameters with physical names, equations from the original papers, algorithms chosen on their merits. What FullProf does differently from its manual or from the papers (the Bérar–Baldinozzi sign, the peak window, the .prf background offset, …) lives in a documented and tested FullProf-compatibility layer, used to validate against FullProf and to import .pcr files. Where FullProf departs from its manual, the original paper decides what the default is.

Q9 · The results file (R28)

One self-describing file with everything a refinement produced, portable to other programs, in place of FullProf's .prf. The comparison of pdCIF, NeXus/HDF5 and a format of our own, with its evidence: The results file: the choice.

First opinion: pdCIF, with a local prefix for the control file, the data file's identity and \(\chi^2\) (L092). open: for Josu

Beyond the brief

R15 asks for more than the brief lists. Candidates to weigh against the study: joint refinement of X-ray and neutron patterns; sequential and parametric refinement over temperature or pressure series; Le Bail and Pawley fits; indexing; quantitative phase analysis with amorphous content; restraints and rigid bodies; magnetic structures; time-of-flight neutrons; fundamental-parameters peak shapes; texture; size and strain; export of the result as a CIF ready for deposition; a refinement history that can be replayed; and a test ledger that reproduces published refinements, as difes reproduces FOCUS.