The GUI as a text document and a wire¶
Three surfaces underneath the panels: the .rxt text document, the keyboard,
and the HTTP routes. Each exists for the same reason. The GUI is a front end for
the Python API, and none of what it does should be reachable only by pointing at
it.
What here is a promise
The GUI’s HTTP routes are declared provisional; see Provisional by declaration. They are the surface this chapter describes for the release it ships with, and a route may be added, renamed or split in any release. Build programs on the Python API in Calling rietx from a program instead.
The .rxt grammar is normative for the format version it states. The format
carries its own version number, so a change to it is something a reader can see
rather than infer.
The .rxt document¶
The Text tab renders the whole project as one line-oriented document: the settings, the plan, and every parameter row. It is the fastest way to change many things at once, and it is a format you can read.
The shape of it¶
rxt 1
project "fap"
pattern "FAP.XRA" # gsas · sha256 b567c0… · 5753 pts · 15–130.04°
mode rietveld
limits none
excluded 129.99 1000
plan custom
tolerance 1e-06 # intermediate_ftol
stage scale_bkg free phases.*.scale, instrument.background.*
stage cell free phases.*.cell.*
phase 0 "fluorapatite" # P 63/m · No. 176 · hexagonal · Laue 6/m
cell.a 9.3717 min 1
cell.b 9.3717 min 1 = 1·phases.0.cell.a
cell.alpha 90 locked
scale 0.001 min 0 softplus
atoms.0.z 0.001913 = 0.001913 + 1·phases.0.atoms.0.dof.0 # Ca1 Ca
instrument
profile.u 0.0002 min -0.05 max 1
background.c0 @ 0
Grammar¶
The header line is rxt {{ RXT_FORMAT_VERSION }} and states the format
version. It is quoted here from the parser itself, so a bump to the format
cannot leave this page behind.
Indentation is the dispatch. A line at column zero opens a block or sets a
document-level key; an indented line is a parameter row inside the block above
it. It is not cosmetic: an indented plan line is a parameter named plan, and
not the plan block.
Document-level keywords:
Keyword |
Takes |
|---|---|
|
the format version, first line |
|
the project name, quoted |
|
the data file name, quoted; the comment beside it carries the reader, digest, point count and range |
|
|
|
the fitted 2θ range, or |
|
one excluded region, low then high; repeatable |
|
the plan preset name |
|
the intermediate-stage convergence tolerance, or |
|
one stage: its name, then |
|
opens a phase block: its index, then its name quoted |
|
opens the instrument block |
|
opens the picked-line block |
|
a guard setting |
A parameter row is a dot-path, then the value, then any number of modifiers. They render in this order:
Modifier |
Means |
Editable |
|---|---|---|
|
this parameter is free; a bare value holds it |
yes |
the value itself |
the parameter’s value |
yes |
|
the bound the solver is given |
no; bounds come from the schema rather than from this document |
|
the transform the parameter refines through |
no; a transform is part of how the parameter is stored |
|
structurally fixed, by symmetry or by a representation that owns the value |
no |
|
held because the intensity mode holds it; Le Bail and Pawley force-fix every atom parameter, the phase scale and the emission lines |
no |
|
the standard uncertainty the last fit produced |
no; an esd is a result of a fit and not an input to one |
|
this parameter is tied, and its value follows the expression |
no |
A tie renders last on its line, because the expression contains spaces and runs to the end of the line.
Column widths are per block and not fixed across the document, which keeps a narrow value from being padded into its neighbour.
Everything after # is a comment. Comments do not survive a re-render: a
document regenerated from the project has one authority, and storing your
comments in the project would make two.
What is safe to edit¶
Values render at 12 significant digits and are therefore lossy. That is safe, because a typed number is compared against the rendered value rather than the stored one. Apply an untouched document and it emits no verbs at all. Only a row whose text you actually changed becomes a call.
Three consequences:
A read-only field is an error only when it differs. Everything can be shown without a “look, don’t touch” syntax, because leaving it alone is not an edit.
Every refusal is the verb’s own words, with a line number attached. It is the same sentence the form would have given you.
A glob line is bulk sugar. Writing
profile.* @frees everything the glob matches; the next render expands it into one line per parameter.
Applying goes through the same verbs a form calls and records the same history nodes. There is no merge and no force-apply: if the project moved under your buffer, re-read and re-apply. Your stale buffer carries the old value of every row you did not touch, so applying it anyway would silently revert them.
⌥-drag is a rectangular selection, and the format aligns its columns for it:
one field down a hundred rows is a column you can select. ⌘⏎ applies.
The keyboard¶
Single-key shortcuts fire only when focus is not in a text field, so typing r
into the filter box does not start a fit.
Key |
Does |
|---|---|
|
run the fit |
|
run the selected stage |
|
free / fix the parameters the filter glob matches |
|
focus the parameter filter |
|
the Peaks tab |
|
the Model tab |
|
the Text tab |
|
the Report tab |
|
the History tab |
|
the command palette |
|
close the help popover; otherwise cancel a running fit |
|
apply the |
Esc is handled before the shortcut table, and its two meanings are in that
order deliberately: cancelling a run because a popover happened to be open is
not undone by pressing it again.
The command palette¶
⌘K is the index of what the app can do, and it is executable. It lists every
command with the Python call it makes:
Run the fit r ref.fit(data, plan=…)
Run one stage — cell . ref.run_stage(stage)
Free the filtered parameters f ref.set_vary(glob, True)
Show the fit report ? ref.report()
Edit the project as text t print(rietx.gui.textdoc.render(project))
A command that cannot run right now is shown greyed and sorted last, and never hidden. So the palette lists everything the app can do, rather than what it can do at this moment.
The same echo prints in the console when you click a control. Anything you did by pointing, you can look up as the call that did it. A session of clicking leaves a console you can read top to bottom as the script you could have written, and the objects it names are the ones Running a refinement and The refinement history describe.
The transition is meant to be gradual. The project the GUI made is an ordinary
.rex directory (Files and projects), so open it from Python and the history the GUI
wrote is the history Refinement.history gives you.
The routes¶
The server is stdlib http.server bound to 127.0.0.1. Every response is JSON
except the static files and the pattern uploads. Mutating routes return 409
while a run is in flight, and that refusal outranks body validation. The
package’s frozen-per-stage rule is enforced structurally rather than by
discipline.
Non-finite floats are spelled as strings ("Infinity", "-Infinity", "NaN")
in responses and event frames alike, because JSON.parse rejects the bare
tokens Python writes by default.
The build, and things that are not a project¶
Route |
Is |
|---|---|
|
what this build can do: backends, solvers, plans, formats, contract versions |
|
the package version |
|
the help corpus the popovers and Glossary are written from |
|
what one symbol constrains; the wizard’s typed-cell step needs it before a project exists |
|
the person’s own settings, the theme among them, stored beside the recent list rather than in the project; not behind the 409 |
|
the recently-opened list |
|
the filesystem browser’s listing, confined to the home directory and the working directory |
|
the example projects shipped in the wheel |
|
build one into the state directory and open it; throw a copy away and rebuild it |
The project¶
Route |
Is |
|---|---|
|
create; open, replacing the session’s |
|
the project document; a merge into its settings |
|
write the settings file |
|
every parameter row; value and vary edits |
|
the plan; replace it; the presets |
|
the ladder: per stage, what it frees and what stays held |
|
the model, its sites and its symmetry; a whole validated replacement |
|
switch one atom between isotropic and anisotropic displacement |
|
a typed coordinate, projected onto the site’s own directions |
|
the Wyckoff letter per atom, which costs a search per atom |
|
what a space-group change would invalidate; the change |
|
the model as drawable geometry |
|
the instrument, and edits to it |
|
render the |
Running, and what came back¶
Route |
Is |
|---|---|
|
start the plan; ask it to stop between iterations; where it is |
|
the fit’s numbers, without the curves |
|
the curves for one 2θ window, decimated server-side |
|
the |
Peaks and indexing¶
Route |
Is |
|---|---|
|
the picked list; pick it |
|
one line, added, removed, moved |
|
mark a line; refit its group |
|
search for a cell; the ranked candidates |
|
one candidate’s predicted lines, for the overlay |
|
adopt a candidate as a Le Bail scaffold |
|
screen the extinction classes; the answer |
Series and history¶
Route |
Is |
|---|---|
|
the staged pattern list; replace it whole |
|
run the chain; its per-pattern answers and trajectories |
|
one member’s curves; one member’s tree |
|
the node graph |
|
one node against its parent; two nodes against each other |
|
restore a state; fork from one |
|
name a node; attach a note |
Exports and uploads¶
Route |
Is |
|---|---|
|
the refined structure; the interactive figure; the phase fractions |
|
the reflection list; the whole result |
|
the instrument, answered from the project because it needs no result |
|
the three routes whose body is raw bytes rather than JSON: a file goes up as itself, with its name and reader options in the query string |
|
what each scan in a multi-scan file is, fetched when the picker is opened |
Uploads are two-phase. A file is staged and read before anything is created, and only an opaque token crosses back, never a path. So the wizard can show you what a file contains and what the reader made of it before you commit to a project.
Exports and derived tables documents what each export contains; the routes above only choose where it is written.