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

Files

Files

Every kind of file in a project started in the app (R27, L091): its folder and name, what it holds, its format, and the files that do the same in FullProf and GSAS-II. The core, the command line and the app take their names from the same file, as they take the parameters' names from the parameter dictionary. A project that comes from FullProf keeps FullProf's names.

30 kinds of file in a project started in the app, each with its folder, name, role, contents and format, and the files that do the same in FullProf and GSAS-II. Names marked proposed await Josu's acceptance (L091); a project that comes from FullProf keeps FullProf's names. Generated from data/files.yml; do not edit by hand.

Principles

  • Readable names, no numeric codes: a file says what it is in words, never FullProf's CODFILn, _calc or 1.fst (R27).
  • Phases by their names, not their numbers: {phase} is the phase's name as the control file gives it.
  • One place per role: a folder for each kind of input and output, so that the project's folder holds the control file and little else.
  • Versions by their time: a version or a result is named by the control file and the time it was made, so that names sort in time and never collide.
  • Measured files keep their own names: the data are the instrument's, and renaming them would lose the link to the lab book.
  • Spaces are allowed, as in the versions decided in L080: every file is a name a person reads; the command line quotes them.

The project folder

Folder Name Kind Status
(the project's folder) {project}.drc Control file decided (L070: the extension .drc; L099: the name, the project's for the first control file, the user's for the others)
(the project's folder) {control} pattern {n}.drc A pattern's control file of a joint refinement decided (L329)
Data/ {original} Measured data decided (L099)
Data/ {data} processed.xys Data after the operations decided (L099)
(the project's folder) {stem} background.drb Background points decided (L081: the format and the extension .drb; L099: the name; L116: one kind, {stem}, Josu's decision on the app's request 29)
Plots/ {set} {operation}.xys Derived pattern of a plot set proposed (L175)
Plots/ {set}.drv Plot set proposed (L192); the extension is Josu's to confirm (plots/DESIGN.md §2.2)
Publish/ {name}.drp Publication set proposed (publish/DESIGN.md §5.1, the app's request 37); the extension is Josu's to confirm (L192)
Structures/ {phase}.cif Structure decided (L099)
Structures/ {phase} AMPLIMODES.txt Symmetry-mode analysis decided (L099)
Instrument/ {instrument}.irf Instrument resolution decided (L099)
Versions/ {control} {time}.drc Version of the control file decided (L080)
Versions/ {control} refinement log.md Refinement log decided (L080)
Results/ {control} {time} results.cif Results of a refinement decided (L092: pdCIF; L099: the name)
Results/ {control} {time} summary.txt Summary of a refinement decided (L256)
Results/ {control} {time} listing.txt Listing of a refinement decided (L256)
Results/ {control} {phase}.cif CIF for deposition decided (L099)
Results/ {control} {phase} bonds.txt Distances, angles and bond valences decided (L099)
Exports/FullProf/ {control}.pcr Control file exported for FullProf decided (L099: FullProf's names, which FullProf requires, in a folder of their own; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Exports/FullProf/ {control}.bac Background file exported for FullProf decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Exports/FullProf/ {control}{n}.hkl Reflection list exported for FullProf decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Exports/FullProf/ {control}.irf Resolution file exported for FullProf decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Exports/FullProf/ {control}.xys Data exported for FullProf decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
(the project's folder) {control} notes.toml Reflection notes decided (L099)
Exports/ {control} reflections.csv Reflections, exported decided (L099)
Results/ {control} {time} series.csv Series of refinements, table decided (L317)
Results/ {control} {time} series.cif Series of refinements, CIF decided (L317)
Exports/ {control} profile.csv Profile, exported decided (L099)
Exports/ {control} {phase} intensities.int Extracted intensities, exported decided (L256: FullProf's format, read by FullProf with Irf = 4 and by its simulated annealing)
.drs/ {original} The app's state decided (L067, L080)

The kinds

Control file

control

Name {project}.drc (extension drc)
Role control
Contents The refinement: the pattern and its data file, the phases and their atoms (or symmetry modes), what is refined, the cycles, the conventions. A joint refinement's (P06, L329): its patterns' control files (pattern_control) with their weights, refined flags and phases, the phases' names, and the parameters the patterns share ([[joint.pattern]], [[joint.phase]], [[joint.tie]]).
Format diff-ref-struct control file: a strict subset of TOML 1.0 with the parameter dictionary's names (core/src/control)
FullProf CODFIL.pcr, the control file (FullProf_Manual.pdf, p. 8)
GSAS-II the project file NAME.gpx, which holds the controls, the data and the results together (a Python pickle)
Written by drs convert; the app's Editor
Status decided (L070: the extension .drc; L099: the name, the project's for the first control file, the user's for the others)
Why this name The file the user works on stays in sight at the top of the project's folder; named after the project, it is found without looking.

A pattern's control file of a joint refinement

pattern_control

Name {control} pattern {n}.drc (extension drc)
Role control
Contents One pattern of a joint refinement (P06): its data file, its instrument, the phases that contribute to it with their own scale, profile and cell, and its free parameters, as a control file of one pattern.
Format diff-ref-struct control file, as control (core/src/control); the joint control file names it
FullProf the pattern's lines of a multi-pattern CODFIL.pcr (FullProf_Manual.pdf, p. 64)
GSAS-II a histogram of the project file NAME.gpx
Written by Joint::control_files (drs joint --save); the app's joint refinement
Status decided (L329)
Why this name Each pattern stays a control file of its own, which every reader of one pattern opens; the joint control file, {control}.drc, names them with their weights, flags, contributions and the parameters they share.

Measured data

data

Name Data/{original} (extension any the registry reads)
Role data
Contents The measured pattern(s) as the instrument wrote them, never changed.
Format the instrument's (31 formats, core/src/formats)
FullProf CODFIL.dat or the file named after 'Files =>' (FullProf_Manual.pdf, p. 8)
GSAS-II imported into the .gpx; the file itself stays where it was
Written by the app (a copy, when the user asks to copy the data into the project; W2)
Status decided (L099)
Why this name Measured files keep the instrument's name; a Data folder keeps them apart from what the refinement writes.

Data after the operations

processed_data

Name Data/{data} processed.xys (extension xys)
Role output
Contents The scan after the control file's data operations (masks, smoothing, rebinning, …): x, y, \(\sigma\).
Format FullProf's XYDATA (Ins = 10), written by formats::write (L088)
FullProf none: FullProf has no data operations; WinPLOTR writes the treated pattern to a file of the user's name
GSAS-II none: the operations change the data inside the .gpx; export as .xye (G2export_pwdr.py L112)
Written by drs data apply --out; the .pcr export (as {control}.xys in the FullProf folder)
Status decided (L099)
Why this name Next to the data it comes from, named by it, and plainly not the measured file.

Background points

background_points

Name {stem} background.drb (extension drb)
Role input
Contents The background points (2\(\theta\), intensity) and their interpolation, picked by the user (R26), on a data file opened alone or for a control file.
Format diff-ref-struct background file (format = "diff-ref-struct background 1", interpolation, points; core/src/background.rs)
FullProf the points in the .pcr (Nba \(\ge 2\)) or CODFIL.bac (Nba = 1, FullProf_Manual.pdf, p. 8)
GSAS-II the fixed background points of a histogram, in the .gpx
Written by drs background store; the app's background tool
Status decided (L081: the format and the extension .drb; L099: the name; L116: one kind, {stem}, Josu's decision on the app's request 29)
Why this name One kind whether or not a control file exists: points picked on a data file opened alone are named by its stem, and the control file made from it takes the same stem, so the file keeps its name and its link; two refinements in one project keep their own points.

Derived pattern of a plot set

derived_data

Name Plots/{set} {operation}.xys (extension xys)
Role output
Contents The sum, average or difference of members of a plot set on a common grid, with \(\sigma\), its '!' lines naming the members, each with its value of the series variable and the source of that value (Plots' PL9).
Format FullProf's XYDATA (Ins = 10): six header lines (XYDATA, TITLE, the derivation, the columns), the members as '!' lines, then x, y, \(\sigma\); read back by the registry with negative y kept (an xye file would lose them: GSAS-II reads y \(\le 0\) as no weight). Whether FullProf skips the '!' lines after the header is not stated in its manual (not checked)
FullProf none: WinPLOTR writes its Summation, Difference and Average to a file of the user's name (its guide p. 30)
GSAS-II none
Written by drs plots derive (plots::derived_text)
Status proposed (L175)
Why this name Beside the plot set it comes from, named by it and by the operation, and in Plots/ so that it is never taken for a measured file in Data/.

Plot set

plot_set

Name Plots/{set}.drv (extension drv)
Role input
Contents Several data files as one set (Plots' PL12): the members (each file relative to the project's folder, a scan, a value of the series variable typed or read from a temperatures file, with its source (PL23), visible, opacity, colour), the variable's name and unit, the x quantity, the y scale, the order, the displacement rule, the reference member, the windows; the views' steps and scales, the normalisation (PL27); the map's and the difference map's colour range as clipped by the user (map_range, difference_range), and the regions of the variable–x plane saved by name ([[regions]]: x with the quantity it was drawn in, the variable's range, a colour range of its own, the window it came from) (PL37).
Format the control file's TOML subset (format = "drs plot set 1"); what is not written is the core's default
FullProf none: WinPLOTR's .buf lists the files of a set, one per line, with a comment (its guide p. 19, §5.1.4), and keeps nothing else
GSAS-II none
Written by drs plots save (plots::SetFile::to_text); read by plots::SetFile::read
Status proposed (L192); the extension is Josu's to confirm (plots/DESIGN.md §2.2)
Why this name Beside the derived patterns it makes, in Plots/, so that a figure is made again from its file (Publish's source, PL15) and a script opens it as a .buf.

Publication set

publication_set

Name Publish/{name}.drp (extension drp)
Role input
Contents What a document of the Publish module holds (R30, L094): the source (control file, version, results file), the sample's facts the files cannot give, and the figures, tables and CIFs with their options, built from those sources only (publish/DESIGN.md §5).
Format the control file's TOML subset (format = "drs-publish set 1"), read by the core's syntax reader
FullProf none
GSAS-II none
Written by the Publish module and drs-publish (publish/src/set.rs); its builds go to Publish/{name}/
Status proposed (publish/DESIGN.md §5.1, the app's request 37); the extension is Josu's to confirm (L192)
Why this name One file per document in Publish/, beside the folder its build writes, so that a paper's figures and tables are made again from it.

Structure

structure

Name Structures/{phase}.cif (extension cif)
Role input
Contents A starting structure for a phase: cell, space group, atoms.
Format CIF (IUCr)
FullProf the atoms of each phase in the .pcr; a CIF converted with CIF2PCR or read with the CFL format
GSAS-II a phase imported from a CIF into the .gpx (imports/G2phase_CIF.py)
Written by the app (a CIF dropped on the data, W5 proposal)
Status decided (L099)
Why this name Phases by their names: a project with two phases has two files a reader recognises.

Symmetry-mode analysis

modes_analysis

Name Structures/{phase} AMPLIMODES.txt (extension txt)
Role input
Contents AMPLIMODES's output for a phase: parent and distorted structures, transformation, reference structure, modes and amplitudes, the block for FullProf (R29).
Format AMPLIMODES's text output, as the Bilbao Crystallographic Server prints it (read by modes::read_amplimodes)
FullProf none: its block for FullProf is pasted into the .pcr (V_MODES, A_MODES)
GSAS-II an ISODISTORT CIF read as a phase with its modes
Written by the user (saved from the server)
Status decided (L099)
Why this name The modes' source kept beside the phase's structure, with its reference metric, so that the normalisation can be checked again.

Instrument resolution

resolution

Name Instrument/{instrument}.irf (extension irf)
Role input
Contents The instrument's peak widths (U, V, W, X, Y, Z or a table), measured on a standard.
Format FullProf's resolution file, read as it is (FullProf_Manual.pdf, p. 70)
FullProf the .irf named on line 6 of the .pcr (Res ≠ 0)
GSAS-II the instrument parameter file NAME.instprm (GSASIIdataGUI.py L1873)
Written by the user (a library of resolution files by instrument, W5 proposal)
Status decided (L099)
Why this name Named by the instrument, not by the sample: one file serves every project measured there.

Version of the control file

version

Name Versions/{control} {time}.drc (extension drc)
Role version
Contents The control file exactly as it was at that time, never rewritten, locked.
Format the control file's
FullProf CODFIL.new, the last one only (FullProf_Manual.pdf, p. 8)
GSAS-II none in its code (the .gpx is written over)
Written by the app (before and after a refinement, on demand)
Status decided (L080)
Why this name Versions by their time, in a visible folder, so that every step can be gone back to.

Refinement log

refinement_log

Name Versions/{control} refinement log.md (extension md)
Role version
Contents One entry per refinement step, appended: time, versions, parameters freed, cycles, \(\chi^2\) and Rwp before and after, the warnings accepted, the user's note.
Format plain text (Markdown)
FullProf CODFIL.out and CODFIL.sum, written over at every run (FullProf_Manual.pdf, p. 9)
GSAS-II the listing NAME.lst, written over at every refinement (GSASIIstrMain.py L462)
Written by the app
Status decided (L080)
Why this name A record that is never rewritten, readable outside the app, next to the versions it names.

Results of a refinement

results

Name Results/{control} {time} results.cif (extension cif)
Role output
Contents Everything a refinement produced (R28): the agreement factors, the refined parameters with their standard uncertainties, the control file, every phase (cell, symmetry, atoms with their uncertainties, R_Bragg), the profile (2\(\theta\), Yobs, its weight, the background, Ycal, each phase's curve), the excluded regions, the reflections (h k l, multiplicity, d, 2\(\theta\), FWHM, |F|², I calc, I obs partitioned by the model and its \(\sigma\)).
Format powder CIF (pdCIF): the IUCr's DDL1 core and powder dictionaries where they name an item, the local prefix _drs_ for the rest; one data block for the whole, one per phase, one for the pattern, linked by _pd_block_id (core/src/results.rs); a joint refinement's, one block per pattern (|pattern 1, |pattern 2, …) with its weight and agreement, its reflections with their pattern, and the contributions of the phases (P41, core/src/joint.rs)
FullProf CODFIL.prf (profile), CODFIL.out, CODFIL.sum, CODFILn.hkl
GSAS-II the .gpx itself; CIF and .csv exports (G2export_CIF.py L4827)
Written by results::write (drs results), Joint::results (drs joint); the app after each refinement (the record)
Status decided (L092: pdCIF; L099: the name)
Why this name One results file per refinement, named by its control file and time like the versions, so that each version has its results; a CIF that GSAS-II and the journals read.

Summary of a refinement

run_summary

Name Results/{control} {time} summary.txt (extension txt)
Role output
Contents What a run reached, to read (P57): the agreement over all the points and over those with Bragg contributions (Rp, Rwp, Rexp, \(\chi^2\), the conventional R's, the deviance, the Durbin–Watson d and its bound, the goodness of fit in \(\sigma\)'s), the global \(\chi^2\), the Bérar factor, each phase's reflections, R_Bragg, R_F, volume and weight fraction, the amorphous content, and the refined parameters with their esd's.
Format plain text (listing::summary_text)
FullProf CODFIL.sum
GSAS-II none
Written by drs results, with the results file
Status decided (L256)
Why this name Written beside the results file it summarises, named by its control file and time; the record stays the results file (L093), the summary is for reading.

Listing of a refinement

run_listing

Name Results/{control} {time} listing.txt (extension txt)
Role output
Contents A run cycle by cycle (P57): each cycle's agreement, the steps refused, the steering's notes, every parameter's value, shift, esd and shift/esd and each phase's R_Bragg and R_F; the summary at the end.
Format plain text (listing::listing_text)
FullProf CODFIL.out
GSAS-II the refinement's log in the .gpx (its covariance and history)
Written by drs results, with the results file
Status decided (L256)
Why this name Written beside the results file, named by its control file and time, so that a run can be followed cycle by cycle without the app.

CIF for deposition

deposition_cif

Name Results/{control} {phase}.cif (extension cif)
Role output
Contents A phase's refined structure with its uncertainties, the experiment and the agreement factors (L083).
Format CIF (IUCr core and powder dictionaries)
FullProf CODFIL.cif / CODFILn_dis.cif (Rpa, news)
GSAS-II the project's CIF export (G2export_CIF.py L4827)
Written by drs cif (cif_write::deposition); drs results, with the results file (results::write)
Status decided (L099)
Why this name Named by the refinement and the phase, so that two phases give two files and a journal's reader knows which is which.

Distances, angles and bond valences

bonds_report

Name Results/{control} {phase} bonds.txt (extension txt)
Role output
Contents The phase's interatomic distances and angles with their uncertainties and the bond-valence sums (P12, L083).
Format plain text, as drs bonds prints it
FullProf CODFILn.dis and CODFILn_sum.bvs (Bond_Str)
GSAS-II the distance and angle tables of the .lst
Written by drs bonds
Status decided (L099)
Why this name Named by the refinement and the phase, not by FullProf's phase number.

Control file exported for FullProf

fullprof_pcr_export

Name Exports/FullProf/{control}.pcr (extension pcr)
Role output
Contents The control file in FullProf's terms, where FullProf can express it (L066, L069).
Format FullProf's .pcr (COMM format)
FullProf CODFIL.pcr itself
GSAS-II none
Written by drs convert <file.drc> --to (control::pcr_export)
Status decided (L099: FullProf's names, which FullProf requires, in a folder of their own; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Why this name FullProf finds its files by CODFIL; a FullProf folder keeps its names, and the files FullProf writes there, apart from ours.

Background file exported for FullProf

fullprof_background_export

Name Exports/FullProf/{control}.bac (extension bac)
Role output
Contents The background at the data's points, in FullProf's first format (Nba = 1; L082).
Format FullProf's .bac, first format (FullProf_Manual.pdf, p. 8)
FullProf CODFIL.bac
GSAS-II none
Written by control::pcr_export
Status decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Why this name FullProf reads CODFIL.bac by the control file's name.

Reflection list exported for FullProf

fullprof_reflections_export

Name Exports/FullProf/{control}{n}.hkl (extension hkl)
Role output
Contents A profile-matching phase's reflections and intensities (Jbt = 2, Irf = 2).
Format FullProf's reflection list (FullProf_Manual.pdf, p. 11)
FullProf CODFILn.hkl
GSAS-II none
Written by control::pcr_export
Status decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Why this name FullProf reads CODFILn.hkl by the control file's name and the phase's number.

Resolution file exported for FullProf

fullprof_resolution_export

Name Exports/FullProf/{control}.irf (extension irf)
Role output
Contents The instrument's widths for FullProf (Res = 1–4).
Format FullProf's resolution file (FullProf_Manual.pdf, p. 70)
FullProf the .irf named on line 6
GSAS-II none
Written by control::pcr_export
Status decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Why this name Written beside the exported .pcr that names it.

Data exported for FullProf

fullprof_data_export

Name Exports/FullProf/{control}.xys (extension xys)
Role output
Contents The data after the operations, for FullProf (Ins = 10).
Format FullProf's XYDATA (formats::write)
FullProf CODFIL.dat or the file of 'Files =>'
GSAS-II none
Written by control::pcr_export
Status decided (L099: FullProf's name; L123: in Exports/FullProf/, Josu, where FullProf/ holds the original files)
Why this name Written beside the exported .pcr that names it.

Reflection notes

reflection_notes

Name {control} notes.toml (extension toml)
Role input
Contents The user's notes on the refinement's reflections and peaks (W8): a reflection or a 2\(\theta\) and what was seen there.
Format TOML, written by the app
FullProf none
GSAS-II none
Written by the app
Status decided (L099)
Why this name Notes are the user's own writing, so they stay visible beside the control file they belong to, not in .drs/ (L093).

Reflections, exported

export_reflections

Name Exports/{control} reflections.csv (extension csv)
Role output
Contents One line per reflection: phase, wavelength, h k l, multiplicity, 2\(\theta\), d, FWHM, η, |F|², I calc, I obs partitioned by the model, its \(\sigma\), (I obs − I calc)/\(\sigma\).
Format CSV with a header line (results::reflections_csv)
FullProf CODFILn.hkl (Hkl ≠ 0)
GSAS-II the reflection list export (G2export_csv.py)
Written by drs results --exports; the app's Export, on demand
Status decided (L099)
Why this name Written only when asked: the record is the results file (L093); an Exports folder keeps what leaves the project apart.

Series of refinements, table

series_table

Name Results/{control} {time} series.csv (extension csv)
Role output
Contents A sequential refinement (P54, P59), one line per pattern: its label, external parameter (the temperature its header gives), cycles, stop, \(\chi^2\), Rp, Rwp, Rexp, each phase's cell volume and su, every free parameter's value and su by name.
Format CSV with a header line (sequential::series_csv); read by drs parametric
FullProf CODFIL.seq (Rpa = −2)
GSAS-II the sequential results' CSV export (G2export_csv.py)
Written by drs sequential
Status decided (L317)
Why this name Written beside the results files, named by the control file and time; one table of the whole series, which a spreadsheet, Plots and drs parametric read.

Series of refinements, CIF

series_cif

Name Results/{control} {time} series.cif (extension cif)
Role output
Contents A sequential refinement (P59): an index block of the patterns (label, parameter, \(\chi^2\), Rwp, overall block id), then every pattern's results file, its blocks renamed to stay unique.
Format pdCIF, multi-block (sequential::series_cif; split_series gives each pattern's results file back)
FullProf none: one CODFIL.sum and .prf per pattern
GSAS-II the sequential results as a multi-block CIF (G2export_CIF.py)
Written by drs sequential
Status decided (L317)
Why this name One file holds the whole series for deposition and for Publish (D8), every number the core's.

Profile, exported

export_profile

Name Exports/{control} profile.csv (extension csv)
Role output
Contents One line per point: 2\(\theta\), Yobs, \(\sigma\), Ycal, the background, each phase's curve, the weighted difference, the cumulative \(\chi^2\) as a fraction of the whole.
Format CSV with a header line (results::profile_csv)
FullProf CODFIL.prf, CODFILn.sub
GSAS-II the powder pattern export (G2export_csv.py)
Written by drs results --exports; the app's Export, on demand
Status decided (L099)
Why this name Written only when asked, beside the reflections' export.

Extracted intensities, exported

export_intensities

Name Exports/{control} {phase} intensities.int (extension int)
Role output
Contents A Le Bail phase's extracted intensities for structure solution or an integrated-intensity refinement (P35): per reflection h k l, j·Lp·|F|², its \(\sigma\) and 2\(\theta\), the overlapped reflections grouped in clusters by FullProf's rule (−1 within a cluster, the sum on its last reflection).
Format FullProf's CODFILn_cltr.int, Fortran format (3i4,2f16.5,i4,3f14.4) (lebail::int_file)
FullProf CODFILn_cltr.int (Jbt = 2, More = 1, Jvi = 11; manual, the output files)
GSAS-II none
Written by drs results --exports, one per Le Bail phase; the app's Export, on demand
Status decided (L256: FullProf's format, read by FullProf with Irf = 4 and by its simulated annealing)
Why this name Written in FullProf's format so that the programs that read it read ours; one file per phase, named by the phase.

The app's state

app_state

Name .drs/{original} (extension any)
Role state
Contents What the app keeps about the project: the versions' metadata, the open windows, the last run (L067, L080).
Format the app's
FullProf none
GSAS-II none (in the .gpx)
Written by the app
Status decided (L067, L080)
Why this name Hidden, so that the project's folder shows only what a person works with.