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

The brief

The brief

The founding request of 8 October 2026, organised into numbered requirements, then kept verbatim below. Ids never change; requirements added later are appended with the log entry that adds them.

What the app is

  • R01 A macOS application built with Tauri, with the look and behaviour of a Mac app: the full menu bar and the usual Mac entries (File, Edit, View, Window, Help; Preferences/Settings, Recent items, Undo/Redo, standard shortcuts).
  • R02 Its main purpose is Rietveld refinement of crystal structures from powder diffraction data, in the style of the programs in use for it: FullProf, GSAS and the commercial ones.
  • R03 Scope restricted to powder diffraction with laboratory X-rays, synchrotron radiation and neutrons.
    Working name of the brief: diff-ref-struct, “a modern FullProf, Mac version”.

Background study first

  • R04 An inventory of the programs commonly used for these refinements: what each does and how it does it.
  • R05 The brief names FullProf and GSAS as the two most used; check the five most used and study those, as a sufficient starting point.
  • R06 From the study, the set of features in common and, beyond it, the features unique to one program or another, to reach the most ambitious feature set.

The refinement core

  • R07 A core that performs the refinements.

Graphics

  • R08 A graphical part to watch the refinement evolve, cycle by cycle, as FullProf does (observed, calculated, difference, reflection markers updated at every cycle).
  • R09 A graphical part dedicated to analysing the data.
  • R10 A graphical part for analysing the results of the experiments and refinements.
  • R11 Interactive graphics: for example the selection of background points by hand, and similar operations done on the plot.

Crystallography

  • R12 Access to the complete set of space groups, with all the needed information: symmetry operators, symmetry elements, and the rest.

Control files and the editor

  • R13 A user interface that generates the control files of a refinement.
  • R14 A dedicated text editor, handy and powerful, created and adapted exclusively for editing the input control files and for reading the output files.

Beyond the list

  • R15 The features above are those the brief could think of; there are many more. Investigate, think and propose, in detail and with judgement.

How the work is done

  • R16 Log everything and report everything.
  • R17 A website that holds the whole construction process: release notes, findings, the background (the programs used as inspiration), and the manuals of the core and of the app.
  • R18 Work the same way as the difes project and its ecosystem (core, shell, ecosystem site, log, release notes, manual).
  • R19 The work is to be done in Claude; the first step is to create the repository.

The app as an umbrella of modules (added 10 October 2026, L060)

  • R20 The app is a modern, general Mac app that controls everything around the refinement of crystal structures, not a refinement window: an extensible umbrella of modules that work together. A project is a folder on disk, shown as it is; each file opens in the module that handles it. Modules declare what they open, the commands and views they add, and use shared services (project, versions, undo, selection, settings, the parameter dictionary, one plotting component); their computations are in the core, with a command-line path. Adding a module touches no other.
  • R21 A data module: every format FullProf and GSAS-II read, recognised by content and named readably (no numeric format codes); several patterns overlaid; 2\(\theta\), d or Q, linear, √ or log; zoom and pan; points selected, masked or deleted on the plot and in a synced table, excluded regions and background points set by hand, without ever changing the measured file; peak search, smoothing, rebinning, normalising, subtracting, merging, wavelength conversion, export. Not a copy of WinPLOTR.
    Josu, 10 October 2026 (L061): the instruments' files he uses are those of FullProf's list, which come first; then a general CSV reader; GSAS-II's formats; and later the fer format.
  • R22 A powerful editor for the control files and outputs, synced both ways with the app, the project's files in view, and a history of versions of every control file: a snapshot before every refinement and on demand, with \(\chi^2\), Rwp and a note, diff and one-click restore, so that a refinement that explodes costs nothing; the working file keeps its name.
  • R23 Modules to publish the results: the agreed plots as figures for journals, the tables of crystallographic data, CIFs ready for deposition, and the structural data in the formats of the Bilbao Crystallographic Server; and further modules as they are needed (structure view, space groups, indexing, sequential series).

Guardrails before a run (added 10 October 2026, L073)

  • R24 Guardrails: the model is checked before a refinement runs, and while it is edited. A checker watches the control file and the model as they change, as a Python editor marks a syntax error while it is typed, and marks each problem where it is edited (the line of the editor, the field of the inspector, the item of the outline), with a list of all of them. Each problem says what is wrong, why, and what to do, with a suggestion where one can be given ("did you mean …", the value or the line to change). Pressing Run first runs every check: errors stop the run and are shown, warnings ask before going on. The checks go from the file (syntax, unknown names, values out of range, missing files) to the physics: parameters that cannot be refined together (correlated or redundant, such as a zero shift with a sample displacement, or an occupancy with its displacement parameter), found from the model before the run and named with the reason and a tip; constraints, codewords or ties that leave a hole or a conflict; values a site's symmetry fixes. The checks are the core's, with a command-line path, so that drs and the app report the same problems.
    Josu, 10 October 2026, on FullProf stopping LaB6's exported file with "Hole in the matrix, missing element 11" (L071): users make these mistakes, and the usual refinement programs tell them only after, or not at all.

How the work flows (added 10 October 2026, L075)

  • R25 A data file is the first step. With no project open the app offers to open a data file; File ▸ Open Data File… lists every format the app reads by name; the file opens in its own window without being moved, and a first look (what the file says, the pattern, peaks, an automatic background) needs no model. Several projects are open at once, each in its own window. A refinement starts from the data and a previous control file found anywhere on the disk (a .drc or a .pcr), copied into the project, pointed at the new data, with what does not fit the new data shown before it is accepted, and saved where the user chooses.
  • R26 The background chosen with the numbers in view: points picked on the plot (added, moved, removed) appear as they are picked in a list and in the background file's text, synced both ways; they are kept in a background file that the control file names or in the control file itself, at the user's choice, never pasted by hand; points, the automatic background and a refined function are drawn and compared on the same data, and a function can start from the points.
    Josu, 10 October 2026, after trying app 0.7.0. The workflows in detail, with what FullProf and GSAS-II do: APP_WORKFLOWS.md.

Our files, our results, and refinement by modes (added 10 October 2026, L086)

  • R27 Our own names for files, as for parameters. A project started in the app names its files by a scheme of ours: readable names, no numeric codes (FullProf's CODFILn, _calc, 1.fst), phases by their names, one place per role, versions by their time. The scheme is written once, in a file dictionary (each kind: name pattern, extension, role, what it holds, its format, its FullProf and GSAS-II equivalents), used by the core, the command line and the app, and published on the site. A project that comes from FullProf keeps FullProf's names; the app reads and writes them as they are.
  • R28 A results file of our own in place of FullProf's .prf: one self-describing file that holds everything a refinement produced (observed, calculated, difference, \(\sigma\), background, each phase's curve, excluded regions, reflections with hkl, positions, intensities and phases, the agreement factors, the model and the control file it came from, the data file it was fitted to), readable without our app and portable to other programs. The app draws from the model (recomputed whenever it is opened, so it is never stale) and writes the results file as the record of each refinement and for exchange; .prf stays an export for FullProf and WinPLOTR.
  • R29 Refinement by symmetry modes (mode crystallography): a distorted structure described as a parent structure plus the amplitudes of its symmetry-adapted distortion modes, the amplitudes refined in place of the atomic coordinates, grouped by irreducible representation, read from what AMPLIMODES (Bilbao Crystallographic Server) and ISODISTORT write and from FullProf's mode input, checked against FullProf's mode refinements; with the guardrails of R24 and the dictionary's names.
    Josu, 10 October 2026. P13 moves from 'later' to the next work (L086).

Publishing the results (added 11 October 2026, L094)

  • R30 A Publish module that exports everything a publication needs, for a paper, a TFG, a TFM, a PhD thesis or a chapter: the figures (the Rietveld plot with its difference and ticks, zooms, series against temperature or composition, cell and mode amplitudes, the modes' displacements), the tables (crystal data and refinement details, atomic parameters with esd's, distances, angles and bond valences, mode amplitudes by irrep), the CIF for the paper and the databases, the pdCIF with the profile, and the supplementary material. A publication set says once what a document contains and from which version of the refinement; exporting rebuilds it, so the figures, tables and CIFs always agree and each records where it came from. One rule for esd's everywhere. Targets as presets (IUCr, ACS, RSC, Elsevier, APS journals; UPV/EHU TFG, TFM and PhD; slides) set widths, fonts, formats and table style. Figures follow Josu's ThesisFigures rules (text typeset by LaTeX, identical geometry across a series, one colour per meaning) and come as PGF/PDF for LaTeX documents and as PDF, SVG, TIFF or PNG for journals; tables as LaTeX, Word, Markdown, HTML and CSV. Checks before export: tables equal to the CIF, no item from a stale version, the CIF as checkCIF would see it. Structures are exported for VESTA.
    Josu, 11 October 2026. Refines R23. What publications contain is to be checked against the IUCr's Rietveld refinement guidelines (McCusker et al. 1999) and the journals' instructions, not assumed.

Seeing the refinement's path (added 11 October 2026, L104)

  • R31 An Explore module that shows the path of a refinement, not only its end: the point in the space of the freed parameters as it moves, projected sensibly (each parameter's trace scaled by its esd; any two as a path with the covariance ellipse; the directions the data cannot fix), a \(\chi^2\) map around the current point for a chosen pair with the path drawn on it, and the physical subspaces as pictures that evolve: the cell, the peak shape (a reflection's profile and FWHM(2\(\theta\))), the structure with its distances, angles and bond valences against their plausible ranges, the symmetry-mode amplitudes with the structure morphed from the parent, the microstructure. Cycles can be replayed, a past cycle opened and refined again from there, and two refinements' paths compared. Every number comes from the core.
    Josu, 11 October 2026: to see physical evolutions and judge whether they make sense. Whether FullProf or GSAS-II show anything of the kind is to be checked, not assumed.

Working with data as graphics (added 12 October 2026, L154)

  • R32 A module for analysing data as plots, the counterpart of WinPLOTR, better and modern, with more features. It opens every kind of file WinPLOTR opens, and CSV, and several files at the same time, to show and compare them together: from different sources, from different experiments, at different temperatures. Each file can be dimmed at will and displaced by an amount to separate it from the others, so as to build the stacked views and projections of a series that publications show. Its name is to be found.
    Josu, 12 October 2026: WinPLOTR's features are to be studied and improved, not copied. A stream of its own (plots/), kept in step with the others by the merging session.
  • R33 An interactive map of a series for finding phase transitions. The range of intensities shown is clipped on the colour bar itself, so that the strong peaks saturate and the weak details come up; a row cursor and a column cursor show the two sections through the map (one scan's pattern, one 2\(\theta\)'s intensity against the temperature). The map zooms in the temperature against 2\(\theta\) plane (a rectangle for both axes, the wheel for one), with the clip following the zoom when asked, and a region of the plane is saved by name in the plot set, so that the user comes back to it and Publish's map draws the same one. The map opens from the command line without the app: drs plots show launches the installed app onto the set, or writes a self-contained page beside the set and opens it in the browser. One viewer, hosted by the app's Plots module and by that page, computing nothing: every number is the core's.
    Josu, 23 October 2026, from the maps of the ESRF ID22 series (I08, L403–L405). The clip is a view and never changes the data; the clip and the regions are kept in the set file, so that a figure made through Publish shows the same slice, its caption saying the range and the saturation.

The analysis in the browser (added 25 October 2026, L423)

  • R34 The analysis in the browser, public. A standalone web app, public on Josu's repositories, so that anyone with the URL has a UI for this kind of analysis: the user's own files, read from the local file structure and never uploaded; the possible map plots offered from the files; the interactive map with its clip, cursors, zoom and regions; a file inspector on the left that can be shrunk and resized, rich in icons and selection; a y interval shared by the set or adapted to the file shown; the √ or the raw values; the temperature beside the time on the map's axis. The core itself computes, compiled to WebAssembly: the browser computes nothing. A tool for the instrument's users, live on the folder where the scans land.
    Josu, 25 October 2026 (I10, L422, L423): "innovate, propose, be wise: a powerful tool that should be in the instruments at the ESRF so that the users do not have to do all this." Yes to all of the assessment's proposals; a stream of its own.

The text, verbatim

As written, typing included, so that the organised list above can always be checked against it.

diff-ref-struct modern FullProf mac version

I would like this project to be the one to work on the claude; I have already claim my credit, this moring

the big idea is to create an app for the macos, tauri…as usual vith the aspect,style of a mac app, and with all the menus and the usual entries of a mac app, but being an app for perfomeing, mainly, rietveld refinements of crystal structures, from x-ray, nuetrons or synchrotron radiation of powder samples, at the style of the used app for that, like FullProf, Gsas and some othere, commercial

so, the first point is to have an inventory of the app that usually are used for that kind of refinements, and see what do they do, and how do they do that, to get the set of features in coomon but also to extend that set to the features unique to one or another I think taht 2 mentioned are the most used ones, but check the 5 most used, that is enough to have a good starting point for having the most ambitious set of unique features

the should be restricted to refinements of the powder diffraction experiments using laboratory x-rays, or synchrotron radion or neutrons it shoul have the core for the refinements, a graphical part for watching the evolution of the refinements, in each cycle as FullProf has, a graphica part dedicated to analyse the data, but also the results of the experiments, or something like the selection of the background, a prahical itnteractive part access to the complete set os space groups, with all the needed information, symmetry elements etc a UI for generating the control files, but the access to a handy and powerful etext editor dedicatad exclusively, and created, adapted for th editing of the input control files, or to read the outfull files…

please, these are some of the features I can think of, but of course there many more investigate, think, propose, be detaield and wise log evrything, report everything and create a website to hold all the process of the construction of the app, the releas notes, the findings, the background in the form of the apps used as insipiration, the manuals, of the core and of the app…work in the same wasy as we are working in the difes project, and its complete ecosystem you have it here, study it to work like that: /Users/User/Desktop/2026/20260901/20260913_tfg_tfm_tesia_irati/2025_20250601_irati_tesis_everything/00_20250501_FTIR_APPS_ecosystem

so to work in the claude the first thing is to create the repo