Scripting and AI-agent workflow
An ordinary recipe’s model payload can include
"time_response": {"mode": "double_delta", "separation_us": 0.324}.
The same payload feeds fit_one, series fits, and shared fits; an omitted
setting means off. See Fixed double-pulse prediction for units and limits.
A μSR temperature or field scan starts the same way every time: survey what
is in the folder, calibrate the detector balance, reduce to asymmetry, screen
a model, fit the scan, and read the trend. Doing that from the GUI is a guided
interactive session; doing it from a shell script, a notebook, or an AI coding
agent needs a command that returns the same answers without a window to
click through. The asymmetry command-line workflow is that command: a
thin layer of subcommands over the pure-core asymmetry.core.workflow
façade, one per step of the analysis above, each readable by a person and
parseable by a program.
It is meant to be driven by a person from a shell, or by an AI coding agent —
Claude Code or Codex are the two tested so far — through the packaged
asymmetry-analysis skill, which teaches an agent the same workflow, the
decision rules an analyst applies at each step, and the summary a
spectroscopist would recognise at the end.
In scope: preliminary forward–backward asymmetry analysis of zero-field
(ZF), transverse-field (TF) and longitudinal-field (LF) runs — a temperature
scan or a field scan at one geometry, named or numbered periods in a
multi-period run, Fourier spectra, integral-asymmetry ALC/QLCR field scans,
and a simultaneous group of runs with shared fitted parameters. Input may be
ISIS NeXus (.nxs) or PSI (.bin, .mdu), using one forward group
against one backward group. “Preliminary” is the operative word: the workflow produces a
defensible first pass — the right model family, a trend, and flagged runs —
not a publication analysis.
Out of scope. The workflow does not improvise around any of these; the skill tells an agent to say so and stop rather than force a fit:
Case |
Why it is out of scope |
|---|---|
Count-domain fitting |
|
Multi-group / orientation-resolved analysis |
The workflow reduces exactly one forward/backward detector pair — the
file’s own, or one named with |
Maximum-entropy spectra |
|
Negative-muon (μ⁻) elemental analysis |
Gamma spectra and elemental lines are not asymmetry data. |
Rotating-reference-frame runs |
Data modulated at a reference frequency needs a different demodulation
step than forward–backward asymmetry. (An RF-resonance field scan is
in scope: |
A fragment of a published multi-field campaign |
No self-contained scan in the survey and fields the files do not record cannot be reconstructed from what is on disk. Two complete scans at two recorded fields are analysable even with a gap in run numbers between them. |
A folder the tool can load is not automatically a folder the tool can analyse — loadability is not scope.
For the underlying Python API this CLI wraps, see the API cookbook; for the physics behind each step, see the workflow chapters linked from Analysis workflows and section 5 of the skill itself.
Installation
The CLI ships as part of the asymmetry package; the agent extra adds
the two optional dependencies the workflow needs for headless plots and NeXus
loading (matplotlib and h5py):
pipx install "asymmetry[agent] @ git+https://github.com/BenHuddart/asymmetry.git"
Add the hdf4 extra for legacy HDF4-container .nxs files, or root
for ROOT files, alongside agent in the same bracket
(asymmetry[agent,hdf4]). The prebuilt desktop application does not
put this CLI on PATH — it is a separate, self-contained bundle — so
agent-driven use always needs this pip/pipx install even on a machine
that already has the desktop app.
Install the skill for an agent, then verify it:
asymmetry skill install --agent claude # or --agent codex
asymmetry skill check
asymmetry skill uninstall --agent claude
For developing the skill itself, skill install --link symlinks the packaged
skill instead of copying it, so edits in a checkout reach the agent without
reinstalling:
asymmetry skill install --agent claude --link
A linked install writes no manifest — nothing is written into the package
directory — and needs none: the symlink resolves to the packaged skill, which is
both the proof this command made it (so install may replace it and
uninstall may remove it, the link only, never what it points at) and the
reason it is always current. skill check reports it as linked
(development). A symlink pointing anywhere else is refused without --force.
skill install copies the packaged skill into the agent’s usual skill
directory — ~/.claude/skills/asymmetry-analysis/ for Claude, or
~/.agents/skills/asymmetry-analysis/ for Codex — and stamps a
.asymmetry-skill.json manifest beside SKILL.md recording the
installed version, so a later skill check can tell a stale copy from a
current one and uninstall can tell a directory this command wrote from
one that just happens to be in the way. Pass --project to install under
./.claude or ./.agents in the current directory instead of the home
directory, or --into DIR to install (or remove) at an explicit path.
skill check reports, for every installed agent, whether the CLI is on
PATH, matplotlib imports, at least one file-format loader extra is
present, and whether each installed skill’s manifest matches the running
asymmetry version — rerun skill install after upgrading the package
if it does not.
Restart the agent (or start a new session) after installing or upgrading the skill — an already-running agent has already scanned its skills directory and will not pick up a change made mid-session.
Common options
Every subcommand below shares the same conventions:
--jsonemits a machine-readable payload on stdout instead of the human table; every payload carries"schema": 1and"asymmetry_version". Omit it for the default human-readable table, which is usually easier to read directly.--plot(onreduce,integral-scan,wizard,fit,fit-global,fit-series,trendandfourier) writes one or more headless PNGs into the work directory’splots/— see Plots.--workdiroverrides the work directory, which otherwise defaults to./asymmetry-work— in the directory the command is run from, not in the data folder. One work directory holds one data folder’s session, so this is the flag to reach for when a second folder is analysed from the same project:--workdir asymmetry-work-<name>, passed to every command on that folder. Pointing a command at a directory that already holds a different folder’s session is a user error, not a silent merge.--verbose(on the mainasymmetrycommand, before the subcommand) prints every warning as Python’s own multi-line traceback-style block. Without it, a repeated warning — the fit wizard’sAsymmetryScaleWarningfrom candidate seeding, in particular — is collapsed to one line on stderr per distinct warning rather than once per occurrence.--instrument NAME(every command with a work directory, andalpha) restricts the folder to one instrument’s files, matched case-insensitively against the file prefix —EMUselectsEMU…andemu…, one instrument across eras. Needed whenever a folder holds two instruments whose run numbers collide; see Two instruments in one folder.Exit codes:
0on success,1on a user error (one line on stderr — a bad run number, a missing recipe),2on an internal error (a full traceback, because that is a bug worth reporting).
Two instruments in one folder
Every command that resolves run numbers keys the work directory on the run
number alone. Two instruments whose runs happen to sit in the same folder —
an EMU and a MUSR campaign on the same sample, say — are two campaigns whose
run numbers may collide, and a command that resolved them blindly would
silently mix one instrument’s spectra into the other’s work directory. Where
no run number collides, every command works across every instrument in the
folder as before; --instrument is only needed once one does, and every
affected command is refused with both instruments named until it is given:
$ asymmetry reduce runs --runs 101-108
asymmetry: Run numbers in runs collide between instruments EMU and MUSR:
run 101 is EMU00000101.nxs and MUSR00000101.nxs. The work directory is
keyed on the run number alone, so name the instrument: --instrument EMU or
--instrument MUSR (the file prefix, in any case). The folder holds EMU (58
files), MUSR (9 files).
survey never refuses this way — it lists every file regardless, measures
each one’s alpha and precession per file rather than per run number, and
prints a RUN NUMBERS COLLIDE line naming the runs and instruments that
need --instrument on every other command.
A work directory is bound to (folder, instrument), recorded in its
manifest by the first command that writes one (survey or reduce): a
later command against the same directory with a different instrument — or
the whole folder, with no instrument — is refused the same way an unrelated
folder is (see One directory, one data folder), naming the bound
instrument and the requested one. Use a separate --workdir per
instrument, exactly as for a second data folder.
Reduction options
reduce, alpha and integral-scan reduce runs, and take the same
options for the same choices. Each is part of the reduction’s cache digest,
and each is printed on the line under the command’s table:
--pair FWD/BWDnames the forward and backward groups by the file’s group names or ids —--pair Up/Downor--pair 3/4for the transverse pair of a five-histogram PSI GPS file, whose default pair is Back/Forw.infolists each file’s groups and its default pair.--deadtime from_fileapplies each file’s own per-detector deadtimes (defaultoff, the GUI’s fresh-run default). Missing or incomplete file coefficients leave the whole deadtime operation unapplied and emitFile deadtime correction not applied: a complete per-detector deadtime table is unavailable. Continuing uncorrected.The usable result records requestedfrom_fileand actualskippedin its correction outcomes, including cached work-directory results. A supplied complete zero table is an applied identity.--background tail_fitfits the late half of selected good-data support on native bins and subtracts the flat rate.--background range:FIRST:LASTaverages that exact inclusive zero-based acquisition interval, independently of facility labels. Without bounds,rangeuses the pre-t0 fraction suggestion where supported; a zero-t0 acquisition requires explicit bounds. Only automatic defaults receive native-bin period adjustment. An unusable automatic tail warns and leaves the whole result background-unsubtracted; invalid authored intervals retain errors.integral-scantakes the same--background: the grouping’s constant subtracted level is removed from the forward and backward window sums before they are combined into the integral asymmetry, and its correlated error (one level estimated once, so it enters the window sum linearly in the bin count rather than as its square root) is propagated into the point’s error alongside the prepared count variance. An unavailable requested correction excludes that operation with its reason. The GUI retains its verified observation’s effective correction settings and resolved reference; CLI settings are resolved explicitly before invoking the same scalar reducer.--t0-offset BINSshifts every detector’s file t0 by a signed number of bins.--t-good-offset BINSis a signed first-bin offset from effective t0; an omitted option retains the mapped file first limit. Negative offsets and manual overrides outside advisory file-good limits are valid within acquired support. Reversed or unsupported requests report an error without altering raw data (see Detector Grouping and Layout).--period red,--period greenor--period Nselects one period of a multi-period file;--period green-redreduces each period of a two-period run on its own and takes green − red.--alpha Xfixes the selected pair’s balance and--alpha-from RUNestimates it on a calibration run reduced with the same options, so alpha balances the spectra it is applied to (reduceandintegral-scan;alphameasures it instead).
Commands
survey
List the runs in a folder with their metadata, scans and calibration candidates — always the first command run against a new folder.
asymmetry survey [-h] [--pair FWD/BWD] [--json] [--workdir WORKDIR]
[--instrument NAME]
folder
Writes survey.json into the work directory. --pair measures each run’s
precession on the named groups instead of the file’s own pair; on a PSI GPS
folder whose transverse signal sits in Up/Down, survey --pair Up/Down is
the survey that sees it. --instrument restricts the listing to one
instrument (see Two instruments in one folder); without it, every file in
the folder is listed and, where two instruments share a run number, each row
is labelled with its own instrument and alpha is measured per file rather
than per run number. A folder with no run files of its own but immediate
sub-folders that hold them — a top-level data/ that merely contains the
experiment — is refused, naming those sub-folders with their run counts, so
the caller can point at one of them instead; survey does not recurse
deeper than one level. Groups runs into scans by
(instrument, field) ordered by temperature and by (instrument, temperature)
ordered by field, so the structure of a multi-scan folder is visible without
reading every file. When the logged sample temperature departs from the
setpoint by more than 0.3 K and 1 % on any run, a TEMPERATURE: line names
those runs (temperature_departures in --json): they were not at their
setpoint, and the setpoint-grouped scans that contain them are provisional.
The line lists the runs in consecutive blocks of similar offset with each
block’s range (T log − T/K), so a block sitting several kelvin away from the
rest stands out as its own measurement.
Runs whose line sits within 15 % of muonium’s weak-field triplet frequency for
their field (about 1.394 MHz per gauss) are named on a MUONIUM: line, with
the recipe (one damped line started at a low-field run’s own line) and the
fit-series that chains it up a field scan. Same-field detections instead
print MUONIUM KINETICS:: compare temperature or composition using the
muonium oscillation’s envelope rate, with frequency and phase constrained by
a reference and an early window that retains the oscillation. A high-field
diamagnetic control or slow late-time baseline is not that reaction rate.
Each alpha-calibration candidate is listed with its own
measured alpha, and where alpha moves by more than 10 % between consecutive
candidates in run order — a sample change, a moved detector, a second
instrument — the survey prints an ALPHA STEP line naming the two runs: no
single run calibrates such a folder, and each block of runs is reduced with a
calibration run from inside it (alpha_steps in --json). reduce and
integral-scan print a NOTE naming any run they reduced on the far side of a
step from its --alpha-from run. T/K is the temperature setpoint and T log/K the
logged sample temperature where the file records one (- where it does
not, as in these simulated files and in PSI .bin files); a cryostat can
leave the two several kelvin apart, and a series can be ordered by either:
$ asymmetry survey runs
8 run(s) in runs — SIM
run T/K T log/K B/G geom prec orient hist periods points events dt title
--- ----- ------- ------ ---- ------ ------------ ---- ------- ------ ------- --- -------------------------------------
101 5.00 - 100.00 TF* larmor Longitudinal 8 1 500 2000123 no Calibrant T=5.0 K B=100.0 G
102 10.00 - 0.00 ZF - Longitudinal 8 1 500 1999876 no Sample T=10.0 K B=0.0 G
...
107 60.00 - 0.00 ZF - Longitudinal 8 1 500 2000456 no Sample T=60.0 K B=0.0 G
108 2.00 - 110.00 - none Longitudinal 8 1 500 1999544 no Sample T=2.0 K B=110.0 G (decoupling)
Alpha-calibration candidates (alpha on raw counts: deadtime off, background none; `reduce --alpha-from` re-measures under its own corrections, and applies that):
run 101 (best) [measured] alpha 1.2500: precession at the Larmor frequency of the recorded 100 G (SNR 93)
Scans:
temperature scan, SIM, ZF, B = 0 G: 6 runs, 10 to 60 K (runs 102-107)
Measured transverse-field precession
A run file’s own account of its applied-field geometry cannot be trusted. ISIS
EMU files from 2024 record no field state at all; other ISIS files stamp TF
on longitudinal decoupling runs and on the zero-field runs of a scan that opened
with a weak-TF calibration. A survey built on that metadata alone reports “no
calibration candidates” for a folder holding a perfectly good transverse-field
run, and mislabels a decoupling scan.
So the survey measures instead. Every run with a recorded non-zero field is
reduced under the default reduction settings and fingerprinted with the same
spectral reading the fit wizard shortlists candidate models from
(fingerprint_spectrum()), and its
dominant line is compared with the Larmor frequency of the recorded field,
γμ/2π × B. The prec column reports the verdict:
|
Meaning |
|---|---|
|
A line at SNR ≥ 10 within 25 % of the Larmor frequency of the recorded
field. The field is transverse, and |
|
A line somewhere else, printed with its frequency: the muon precesses
in a field that is not the applied one — an internal field in an
ordered magnet below its transition, muonium in a weak transverse field
(1.394 MHz/G), or the critical field inside a type-I superconductor’s
normal domains. This says nothing about the applied field’s direction,
so |
|
No line above SNR 10. The applied field is not precessing the muon, so
the file’s |
|
Not measured: no field is recorded, or its Larmor frequency is above
the record’s Nyquist frequency. |
A run with no measurable precession (prec none or -) can still
have its geometry named from the run’s own logged field-coil readbacks — HiFi
logs the main solenoid and a small Z coil separately, so an axial reading
dominating the transverse by a wide margin is longitudinal even where the
spectrum is silent or the file stamps it TF. Where this decides, geom
carries a + (TF+, LF+; geometry_source "coils") instead of
the * a measured precession earns, and ranks below a measured line but
above the file’s own stamp; see Loading Data for the readback rule.
The plain-text table includes a source column, and every scan lists
geometry sources before the long run table. file is a header claim,
not a measured line or a coil readback. In particular, an above-Nyquist
prec - cannot verify a TF stamp. Detector-bank orient is not the
applied-field direction. For an ALC or recovery hypothesis, the reduced
spectra and a consistent-block integral scan can test whether a substantial
nonoscillating signal contradicts TF cancellation. For matched ZF/applied-field
measurements, strong suppression of a ZF KT relaxation supports longitudinal
static-field decoupling; missing orientation metadata remains a caveat, not a
reason to discard that measured contrast. These tests do not classify every
unresolved precession as LF.
Zero-field runs are searched for a spontaneous line by the same reading —
the resolved dominant line, else the damped-line scan’s. There is no Larmor
frequency to compare with, so a line is other@<MHz>: precession in a static
internal field, the signature of long-range magnetic order. none means no
line was resolved in that record. On the corpus this finds the ordered-state
lines of EuO (29.9 MHz at 10 K, falling towards Tc), nickel and a
molecular antiferromagnet, and nothing in paramagnetic, Kubo–Toyabe or F–μ–F
zero-field runs.
The thresholds are PRECESSION_SNR_FLOOR
(10) and LARMOR_FREQUENCY_TOLERANCE
(0.25). They were set on measured data: genuine 20 G and 100 G transverse-field
runs score SNR 89–418 and land 3–14 % above the nominal Larmor frequency, while
the longitudinal decoupling runs ISIS stamps Transverse at 40–120 G score
about 3, and ordered-state runs put their line a factor of 4 to 40 away.
A dominant line that completes fewer than two cycles in the record (the fit
wizard’s own
MIN_CYCLES_IN_EFFECTIVE_WINDOW)
away from the Larmor frequency is the relaxation leaking into the lowest
frequency bins, not precession — on the corpus it sat near 0.1 MHz in every
weak-field and decoupling run. For such a run the survey reports the line the
fingerprint’s damped-line scan found instead, which reaches the heavily damped
lines a windowed FFT misses (a muonium line in a 2 G field, the normal-domain
line of a type-I superconductor), and none when that scan found nothing. A
slow line at the Larmor frequency — a weak-TF calibration completing only a
few cycles — is kept.
Calibration candidates follow from the same measurement, from two sources, each named in the candidates block:
[measured]— precession at the Larmor frequency of a recorded field inside the weak-TF window (WEAK_TF_FIELD_RANGE_GAUSS), with the SNR quoted. The best candidate is the strongest such line.[metadata]— no measurement was possible, andclassify_tf_calibration_run()decides from the file’s own transverse-field evidence alone.
Where a measurement was possible it decides: a file’s TF stamp on a run
with no precession in it is not a calibration candidate. asymmetry alpha
applies the same rule and prints its own precession line, so the two
commands use the same advisory recommendation for calibration.
Each run’s survey.json row carries n_periods, total_events,
geometry, geometry_source
(field, measured, coils, refuted, file or none),
precession, precession_frequency_mhz, precession_snr,
precession_larmor_mhz and precession_note, plus
sample_temperature_logged and sample_temperature_log_source where the
file logs a sample temperature distinct from the setpoint (T log/K in the
table; see Loading Data).
total_events is the gross count summed over every raw detector histogram
in the default (first) period. The human table shows the same value under
events. Use it to choose between otherwise comparable science runs; do not
rank candidate spectra by precession SNR, which can favour a calibration run
or a warmer, narrower line.
How scans are grouped
A scan’s key is the instrument and the held quantity — never the geometry. Two instruments in one folder are two campaigns and must never merge into one scan (an EMU and a MUSR scan of the same sample, say).
A field scan is also cut by what an ALC or decoupling campaign varies at one
temperature. Its members share the run note and the number of periods, so an
ALC scan of one region, a scan of another and a red/green repeat of the second
are three scans, each listed with its note (notes "o-p scan"); passes
interleaved at offset fields under one note stay one scan, since each alone
undersamples a narrow resonance. A run at a field its scan already holds, taken
after the cryostat visited another temperature, starts a repeat of the scan —
two decoupling scans at 420 K with a 400 K one between them are two scans —
while a point re-measured in the same visit (a return sweep) stays in its scan,
and so does a scan measured alternately at two temperatures, field by field.
A sweep whose widening steps (a decoupling curve, 1, 1.8, 3 … G) give way to
even ones (a level-crossing scan) is cut into two scans at the first field of
the even run, where the step falls fivefold and then holds for four steps.
Runs that precess at their Larmor frequency, when they are a minority among
runs that do not, are transverse-field calibrations taken beside a longitudinal
scan and are left out of it; when they are the majority the scan is transverse,
and its runs too slow to show a line stay in it. Temperature scans are not cut
this way, since fields are switched within a temperature point all the time.
A temperature scan every run of which also sits in a longer field scan is a
cross-section through a grid of field scans — an ALC campaign repeated at
several temperatures on the same fields makes one at every field — and is not
listed; the survey says how many it left out (cross_sections in
--json). Geometry, by contrast, is
measured per run, so a scan that resolves only in part is still one scan: a
transverse-field scan taken through a magnetic transition resolves above it,
where the sample is paramagnetic, and not below.
Each ScanGroup therefore reports
instrument alongside geometry, which is the members’ single agreed
geometry — and None with a geometry_note tallying them when they
disagree:
Scans:
temperature scan, EMU, mixed geometry, B = 100 G: 21 runs, 340 to 380 K (runs 124249-124269)
geometry: TF measured on 12 of 21 runs; 9 unresolved
That note is itself a finding: it says where in the scan the measurement could settle the geometry and where it could not. When a temperature scan resolves as transverse on at least three runs in four, and a remaining run shows no line and also sits in a field scan with no transverse line of its own, the note names it — “run 20898 also belongs to a field scan with no transverse line at this temperature — likely its points, not this scan’s” — since a longitudinal point the file does not label is otherwise fitted with a precession model.
Repeated sets of three to five weak fields, including zero field, print
COUPLED FIELD GROUPS when no member is transverse or precesses (a
Larmor line, or an ordered magnet’s spontaneous zero-field line). The survey
gives a DynamicGaussianKT + Constant recipe and a fit-global --groups
command sharing the amplitudes, static width, and fluctuation rate within
each temperature group, with B_L fixed from each run. Confirm longitudinal
decoupling from the reduced spectra before using that physical model.
Independent field fits do not measure those shared parameters, so audit
holds the reply until each group has a fit-global fit — of any model, so
a competing coupled model satisfies it as well as the Kubo-Toyabe one. A
minority Larmor-precessing point is removed from a field scan as a likely
transverse calibration, unless a zero-field member precesses at the same
frequency (see INTERNAL-FIELD AMBIGUITY below); then it stays a member.
Consecutive runs of one sample at one condition — field, temperature,
geometry, note and set-up — whose co-add at least halves the counting
variance of the largest print as a repeat set with the command that co-adds
them (REPEATS: runs 3678-3682 repeat one condition … asymmetry reduce …
--coadd --workdir asymmetry-work-coadd); when their shared note names a
scan (P scan), the runs step a quantity the files do not record and print
as UNRECORDED SCAN instead. Runs of different bin widths or period counts
are different set-ups and never share a scan; a scan of two-period (red/green)
runs says so on its line and, for a field scan, names integral-scan
--period green-red.
The survey also finds scans the files do not record in any field. Among runs
that share instrument, set-up, sample, temperature setpoint and field, a note
(or title) that reads the same once its numbers are masked, with one number
stepping through at least three values on at least three runs, is a scan of
that quantity — a steering current, a degrader foil count, a slit width. Each
prints under NOTES SCANS: with its template (Steering <x> A), the value
range and the commands that fit it (asymmetry wizard on its first run,
then asymmetry fit-series … --order steering --x RUN=VALUE,…). A run whose
note leaves words out of the template, with its one number where the step is
(0 foils beside 4 (30um) foils), is a point of the scan; a number that
steps 1, 2, 3 with the runs counts repeats, and dates, times and ranges are not
numbers, so neither is reported. The scans are stored in survey.json as
notes_scans, and audit lists one whose runs no fit holds.
Each scan line also names its members’ samples — the file’s own sample name,
or the run title before its T=/F= fields — so a folder holding several
samples scanned on the same fields reads as several measurements, and a scan
naming more than one sample says it crosses them. Where such a scan holds
three or more samples at one setpoint, two or more of them naming one substance
with a leading number (0.25 M salt/water, 0.5 M Salt/Water),
the scan line is followed by a composition: block: those runs with their
samples and notes, a fit-series --order concentration --x RUN=VALUE,…
command with the numbers the names give (<value> for a solvent or a sample
whose name gives none, to fill in from its title and notes or drop), and the
trend --model Linear that reads a rate linear in concentration as a rate
constant. It names the other setpoints that hold the same set, and says the
shared setpoint makes the series whatever the logged temperatures do. A folder of more than a
hundred runs prints these findings (the notes, the calibration candidates and
the scans) before the per-run table, which comes last under Runs:.
When no run precesses on the files’ own detector pair, the survey tries every
other pair of groups on the first run in a field that shows no line, and
prints PAIR: with the one the field precesses the muon across — a pair
whose names face each other (Up/Down, Left/Right) before the
strongest line — and the --pair to survey again with:
PAIR: no run precesses on the file's own detector pair, but run 3366 does on Up/Down (at the Larmor frequency: yes — 5.427 MHz (SNR 21) against a Larmor 5.422 MHz), the pair across the field. Survey again with --pair Up/Down, and pass the same --pair to alpha, reduce and integral-scan.
A PSI GPS run in a transverse field is the usual case: the spin precesses
across the beam, on Up/Down, and the file’s Back/Forw pair
sees nothing.
alpha
Estimate the forward/backward detector balance α on one run. The fresh explicit default is TF calibration fit with automatic four-envelope
selection and beta fixed at one, shared with the GUI and omitted-option API call.
Use --calibration-method automatic for the separate per-run integral ratio.
asymmetry alpha [-h] --run RUN [--deadtime {off,from_file}]
[--pair FWD/BWD]
[--background none|tail_fit|range[:FIRST:LAST]]
[--t0-offset BINS] [--t-good-offset BINS]
[--period RED|GREEN|N|green-red] [--instrument NAME]
[--json]
folder
alpha takes no --workdir and writes nothing to disk; it loads the
named file directly and prints the estimate, whether the run is a suitable
calibration candidate, and a warning when it is not. The Reduction options
decide which counts it balances — --pair Up/Down measures the Up/Down
balance, not the file’s default pair’s. --instrument picks the file when
the folder holds two instruments sharing this run number (see Two
instruments in one folder); a period selection reports the encoded
run’s source run number, not run*1000 + period.
Explicit calibration uses the shared core operations:
asymmetry alpha runs --run 101 --calibration-method tf_calibration_fit --fit-beta --json
asymmetry reduce runs --runs 102-107 --alpha-from 101 --calibration-method tf_calibration_fit --fit-beta
--calibration-method accepts tf_calibration_fit, diamagnetic,
general, ratio, and automatic. Omission selects TF calibration fit; automatic selects the per-run integral ratio;
survey also retains that policy. --fit-beta requires
tf_calibration_fit; without it TF fixes beta at one. Other methods use
beta one. --calibration-envelope undamped|exponential|gaussian|stretched
constrains TF to that envelope; omission compares all four by minimum finite
summed cost among usable fits, with declared-order exact ties. The stretching
exponent is distinct from detector beta. --calibration-frequency MHZ supplies
a frequency seed; omission uses the source field. Envelope/frequency/free-beta
options require the TF method. These options on reduce and integral-scan
require --alpha-from and never fit arbitrary target samples implicitly.
--calibration-period RED|GREEN|N selects the acquired source period independently
of the target --period. Without it the source follows --period. TF requires
an explicit acquired period for a multi-period source and rejects a difference
or cached-only period. All calibration methods require the source period’s
histograms; cached curves cannot supply counts for another period. Quick methods
without a selector use red on a combined run and record acquired period 1.
Nontrivially mapped TF sets require the original acquired
source, since a mapped ordinal cannot name a source acquisition. An already-selected
acquired period keeps its original ordinal, including when the matching selector
is repeated. For a target difference, supply the source period explicitly.
The automatic and explicit ratio paths retain their red-period difference
semantics and single-period source adaptation. Pair, timing, good-window, and
correction options resolve on the calibration source, rather than the target.
TF uses its own native support and fitted count backgrounds: requested range/tail
backgrounds retain the shared model-preparation semantics described in
Alpha calibration.
Text reports alpha/beta, available symmetric errors, fixed beta, selected model, failed candidates, and requested/applied correction states. TF errors are conditional on the selected model; missing/unreliable errors remain absent. Quick Diamagnetic and General have no added uncertainty; explicit ratio reports first-order propagation. Precession/calibrant advice does not prevent an explicit request. A failed/no-usable TF result remains diagnostic and cannot be applied.
--json includes the complete canonical calibration block for TF, with
source, acquired period, raw support, effective constraints, covariance, candidates,
and correction outcomes. Both coefficients derive from this block when
--alpha-from applies it. Stored workdir settings retain the same capture
identity and tagged nonfinite endpoints through restoration; reading does not
refit or generate a new identity. Scalar/source-only documents remain scalar
records without inferred joint provenance. Explicit quick results retain their
shared typed estimate, method/error meaning, source, acquired period, pair,
correction outcomes, resolved F/B channel members, authored exclusions,
contributor mapping, and timing/window context in
quick_calibration settings; a nontrivial mapped quick source retains its
contributor recipe and selected mapped-set ordinal with no acquired-period ordinal;
no TF covariance or joint record is inferred. General count-domain science fitting
is a separate API capability.
reduce
Reduce runs to forward/backward asymmetry and cache them in the work directory.
asymmetry reduce [-h] --runs RUNS [--coadd] [--alpha ALPHA]
[--alpha-from ALPHA_FROM] [--deadtime {off,from_file}]
[--pair FWD/BWD]
[--background none|tail_fit|range[:FIRST:LAST]]
[--t0-offset BINS] [--t-good-offset BINS]
[--period RED|GREEN|N|green-red] [--rebin REBIN]
[--tmin TMIN] [--tmax TMAX]
[--plot-tmax PLOT_TMAX]
[--plot] [--json] [--workdir WORKDIR]
[--instrument NAME]
folder
When the files carry per-detector deadtimes and the reduction leaves deadtime
off, reduce (and integral-scan) end with a NOTE to pass --deadtime
from_file before fitting further.
--runs takes ranges and commas (102-107, 102-105,107). The
alpha, deadtime, pair, background, t0 and period choices are the
Reduction options; without --alpha or --alpha-from, alpha defaults
to 1.0. Writes
reduced/<run>.npz (time, asymmetry, error) and reduced/<run>.json
(metadata, settings and a cache digest) per run, plus manifest.json, and
plots/reduced-<run>.png per run with --plot. Results are cached on a
digest of the source file, the grouping and the reduction settings, so
re-running reduce on unchanged runs is cheap.
--coadd sums the counts of every run in --runs (the same combine the
GUI’s data browser offers on a multi-selection) and reduces the sum as one
run under the reduction options, storing it under the first run’s number —
that run’s own, separate reduction is replaced, so co-add a group into its
own --workdir if the individual runs are also wanted. The stored entry
records its members, and every later command that reads it — wizard,
fit, fit-series, fourier — prints Run N is co-added from
runs … on stderr so a co-add is never mistaken for an ordinary run’s own
statistics. A mismatch between the named runs (different detector layout,
incompatible binning) is a user error naming the mismatch, not a silent
partial sum.
--tmin/--tmax cut the stored reduction, so every later wizard,
fit and fit-series sees only that window, and each of those commands
ends with a note naming runs reduced that way. To zoom the reduced PNG on early
precession without cutting the record, use --plot-tmax.
--period red, --period green or --period N selects one period
before alpha calibration and reduction, and --period green-red stores the
difference of the two periods, each reduced on its own. The choice is part of
the cache digest. ISIS photo-μSR commonly records light-ON as red and light-OFF as
green, but the experiment notes and spectra remain the authority. Since the
cache is keyed by source run number, use separate work directories if two
periods of the same run must coexist.
For photo-μSR, use the weak-TF run only to obtain alpha, then reduce the same
science run’s light-ON and light-OFF periods into separate work directories.
Fit the dark period first when its amplitude is needed to stabilise an
early-time light-period rate. Run order may visualise a rate sequence, but it
is not a substitute for injected carrier density or laser delay; do not report
a density exponent or carrier lifetime unless those x values were supplied from
the experiment’s record (--order with --x) and fitted with
trend --model.
$ asymmetry reduce runs --runs 102-107 --alpha-from 101 --deadtime from_file --plot
run T/K B/G points A(0)/% err/% alpha deadtime
--- ----- ---- ------ ------- ----- ------ --------
102 10.00 0.00 500 8.537 2.366 1.2521 file
...
107 60.00 0.00 500 -11.301 2.321 1.2521 file
wizard
Screen a reduced run against the fit wizard’s candidate models — the same engine behind the GUI’s single-fit wizard.
asymmetry wizard [-h] --run RUN [--geometry {ZF,TF,LF}] [--scope NAME]
[--include C,D] [--exclude C,D] [--tmin TMIN]
[--tmax TMAX] [--plot] [--json] [--workdir WORKDIR]
[--instrument NAME]
folder
--geometry overrides every other source. Without it the geometry comes from
the folder’s survey.json when one exists — including a geometry the survey
measured from Larmor precession (see Measured transverse-field precession) — and
otherwise from this run’s own metadata; the header line names the source
(user, survey, field, file or none). Pass it whenever the
reduced spectrum tells you something the survey could not, such as a
longitudinal decoupling run the file stamps TF. --scope names the
physics to look for when it is already known, the command-line counterpart of
the GUI picker’s “Looking for” chips. It chooses physics only, never a
geometry: the geometry always comes from the run or --geometry, so
--scope lf-dynamics on a zero-field run screens zero-field dynamics. The
names and the physics each looks for (generic relaxation and the background
are always included):
|
Physics looked for |
|---|---|
|
every class |
|
static magnetism |
|
superconductivity and static magnetism |
|
spin dynamics and static magnetism |
|
F–μ–F and nuclear dipoles |
|
muonium |
--include adds time-domain components the scope leaves out (for
example Oscillatory for a precession line in an LF run, as in a type-I
superconductor’s intermediate state) and --exclude drops components the
physics rules out (VortexLattice,VortexLatticePowder for a magnet in TF);
exclude wins over include, the header line lists both (scope lf-dynamics
+Oscillatory), and an unknown component name is refused with the full list.
--tmin/--tmax screen a window of the run, and the recipe written keeps
it. Below the ranked table the report prints Spectral lines (every line
the spectral search detected, with its SNR) and Recommended fit (the
recommended model’s fitted values), so a precession frequency found while
screening is on the page, not only in the stored recipe. When a detected line
is not in the recommendation, the wizard also writes recipes/line-<run>.json
— the recommended model plus that line, started at its frequency with a
small amplitude, since a weak line sits on the relaxation the recommendation
already describes — and prints the fit command to try it. Lines that complete fewer than two cycles in the
record’s informative window — relaxation leaking into the lowest bins — are
not listed, by the survey’s rule.
When the verdict is no_significant_structure and the folder’s survey puts
the run inside a scan of four or more runs, a NOTE says a featureless run is
often the scan’s quiet end, so a recipe from it fits the scan only if its ends
are featureless too, and prints the wizard command for each end of the
scan.
When the recommendation is a precession model (the Oscillatory
category: a Bessel, a damped cosine, an Overhauser form) but the spectral
search found no line in the run, a NOTE says the model is fitting the shape
of a relaxation — a Kubo–Toyabe’s dip and recovery read as one slow cycle —
and the best relaxation model, however far behind, is written as
recipes/wizard-<run>-alt.json.
When the recommendation is a relaxation model and another relaxation model
with at most one parameter more sits within 10 AICc of it, the wizard also
writes that runner-up as recipes/wizard-<run>-alt.json and names it: a run
that hardly tells two models apart leaves the scan to decide, and
fit-series offers the runner-up when the recommended recipe’s series flags
at least half of its runs failed or amplitude_exceeds_data.
For Exponential + Constant with a comparable stretched-exponential
alternative, DISTRIBUTED RELAXATION also prints that comparison command
without requiring widespread failures: one run’s ranking cannot establish
one rate throughout a scan, especially in a disordered/glassy magnet.
For a detected precession signal, a close nested model with fewer parameters
also gets an alternative recipe when it retains the precessing components.
This lets a scan test whether an extra relaxation term is identifiable,
without discarding the measured oscillation.
Writes wizard/<run>.json (the full screening payload:
recommendation, ranked candidate table, narrative) and
recipes/wizard-<run>.json (the fit recipe built from the recommended
candidate’s fitted values — see The fit recipe), plus
plots/wizard-<run>.png (data, recommended curve, residuals) with
--plot:
$ asymmetry wizard runs --run 102 --plot
Run 102 — geometry ZF (from survey), scope auto
Recommendation: exp_constant
Recommended: Exponential + Constant by AICc (medium confidence).
confidence : medium
verdict : structured
key title category AICc chi2_red params
- ------------ --------------------- -------- ----- -------- ------
* exp_constant Exponential + Constant General 487.7 0.969 3
wizard, fit, fit-series, and fit-global print
Fit windows (retained bin
centres) with the actual first and last fitted bin centres. This includes
the full stored record when no explicit time cut was supplied; recipe
rebinning is included for fits, and the wizard’s own analysis rebinning for
the wizard. Their JSON products retain the same bounds
as time_window or, for a series or coupled group, time_windows. Quote these alongside
relaxation rates, rather than inferring exact limits from plot axes.
Series and grouped-fit batches also print Fit quality counts — each
verdict as “N of M” with its chi2_red range — so a report can quote the verdict
totals directly rather than calculate them from rows; fit-series tallies
each flag beside its flagged count the same way.
For a field sweep containing a zero-field reference, the survey reports
INTERNAL-FIELD AMBIGUITY when a high-field Larmor-like line also matches
the spontaneous zero-field precession. That coincidence cannot establish
applied TF geometry. The note asks the analyst to inspect relaxation and
late-time recovery for LF decoupling and verify the instrument configuration.
An unresolved survey geometry remains unknown in the wizard instead of
falling back to a file stamp the survey did not confirm. An explicit
--geometry still takes precedence.
When a dynamic Lorentzian KT wins the screen, FIELD DISTRIBUTION reminds
the analyst that it describes dilute moments. Dense nuclear moments instead
call for Gaussian KT; ionic motion changes the fluctuation rate, not that
physical distribution. The single-run statistical ranking does not decide
which distribution the sample contains; see Kubo–Toyabe for the
model definitions and references.
recipe
Write a fit recipe for a model expression, bypassing the wizard — for the model the physics calls for when the wizard does not recommend it, or has no template for it.
asymmetry recipe [-h] --expression EXPRESSION --name NAME [--run RUN]
[--initial NAME=VALUE] [--fix NAME=VALUE] [--tmin TMIN]
[--tmax TMAX] [--json] [--workdir WORKDIR]
[--instrument NAME]
folder
--run seeds the amplitudes, phase, background, applied field and Larmor
frequency from that reduced run (the same seeding every fit surface uses):
an amplitude role is seeded positive, with its sign carried instead by
phase (0 or π, the fit wizard’s own rule), and a frequency parameter
is seeded from the applied field’s Larmor value when it sits below the
run’s Nyquist frequency. The applied field (field, B_L) is marked
run-bound, so fit-series and fit-global re-seed it per run from each
run’s own record rather than carrying the first run’s value down the scan (see
The fit recipe); the Larmor frequency is only a start, since the line being
fitted may be an internal or critical field’s, and a series keeps the
recipe’s or the neighbouring run’s frequency. Once the frequencies and rates
are set (--initial and --fix included), each precessing term’s
amplitude and phase, and a single background, are solved by linear least
squares against that run — two lines inside one FFT peak then start apart
rather than both at the record-scale phase, where a fit collapses one onto the
other. A value passed with --initial or --fix is kept. A line completing
under one cycle in the record (a diamagnetic line at a few gauss) keeps its
record-scale start, and a solve whose amplitudes exceed twice the record’s own
excursion is discarded.
--initial moves a start value, --fix holds one (and pins it, so a series never re-seeds it), and
--tmin/--tmax set the fit window. The command writes
recipes/<name>.json and prints every parameter — the names a repeated
component is numbered with are otherwise easy to guess wrong:
$ asymmetry recipe runs --name mu --run 101 \
--expression "Oscillatory * Exponential + Oscillatory * Exponential" \
--fix frequency_1=2.79 --fix frequency_3=0.0271
mu — Oscillatory * Exponential + Oscillatory * Exponential, seeded from run 101
parameter start min max state
----------- --------- ------ --- -----
A_1 ... 0.0000 inf free
frequency_1 2.790000 0.0000 inf fixed
phase_1 ... -inf inf free
Lambda_2 ... 0.0000 inf free
A_3 ... 0.0000 inf free
frequency_3 0.027100 0.0000 inf fixed
phase_3 ... -inf inf free
Lambda_4 ... 0.0000 inf free
An unknown component is refused with the nearest names, and a parameter the expression does not have with the list it does.
fit
Fit one reduced run with a recipe.
asymmetry fit [-h] --run RUN --recipe RECIPE [--fix NAME=VALUE] [--free NAME]
[--tmin TMIN] [--tmax TMAX] [--plot] [--json] [--workdir WORKDIR]
folder
--recipe takes a name in the work directory’s recipes/ (no path, no
.json) or an explicit path. --fix NAME=VALUE holds a parameter
(repeatable); --free NAME releases one the recipe holds fixed. fit
stores its result in fits/<recipe>-<run>.json (so audit counts the run
as fitted) and plots/fit-<run>.png with --plot; it is the quick way to
check a hand-edited recipe converges on one run before spending a whole series
on it (see Hand-editing a recipe).
A relaxation too slow to tell from a constant over the fitted window lets its
amplitude and A_bg run off in opposite signs: χ² barely changes as the
amplitude grows, the rate falls and the background goes negative to cancel it.
When a fit — converged or not, since a runaway often stops at the call limit
— has fitted amplitudes above the record’s early-time asymmetry
(amplitude_exceeds_data), an amplitude of opposite sign to a free
A_bg, and a rate (or static width) that decays by less than half over the
window, fit repeats it from its own values with A_bg held at 0. The
held fit is kept when it converges, its amplitudes fit inside the record, and
it costs less than 25 χ²ᵣ in χ² (under 5σ for the one parameter dropped:
the data do not need the background). The stored fit then carries
background_held: true and the command ends with a NOTE saying so; the
summary should say A_bg was held. A background the data do need, or a
model the hold cannot rescue, keeps its free fit and its flags. fit-series applies the same rule to
each run after the chains (a --global background is left alone) and names
the held runs in one NOTE.
fit-global
Fit two or more reduced runs in one coupled objective with named parameters fitted once across every run:
asymmetry fit-global [-h] (--runs RUNS | --groups RUNS;RUNS;...)
--recipe RECIPE [--fix NAME=VALUE]
[--free NAME] --shared P,Q [--field-param NAME]
[--strategy {joint,profiled,least_squares}]
[--order QUANTITY] [--x RUN=VALUE,...]
[--group-order QUANTITY]
[--group-x GROUP=VALUE,...] [--name NAME] [--plot]
[--json] [--workdir WORKDIR] [--instrument NAME]
folder
--shared P,Q is a true shared fit, unlike fit-series --global.
--field-param B_L seeds that parameter from each run’s recorded field and
holds it for that run, which is the usual structure of an LF decoupling
triplet. Other parameters remain run-local. --order and --x work as
for fit-series (the default is run): the printed table lists every run
along that axis with its run-local parameters, and the stored
series/<name>.json carries them as a trend table, so trend reads and
fits a simultaneous fit exactly as it does a series. The shared values and
their uncertainties are stored beside it; --plot writes one fit plot per
run. Over more than three runs ordered by field it
notes that a shared rate cannot show how relaxation changes with field, which
is a fit-series and Redfield question.
--groups "a,b,c;d,e,f;…" fits several groups at once — the sequence of LF
triplets a temperature series of them naturally is — instead of one
invocation per group. Each group is fitted exactly as --runs fits one and
stored as its own global series <name>-<i> (<i> from 1); <name>
itself stores a global-batch series whose trend rows are the groups’
shared parameters and uncertainties, so trend --series <name> reads and
plots them exactly like an ordinary parameter trend. --group-order
chooses the axis the groups are ordered and trended along — temperature
(the default; each group’s mean setpoint), sample_temperature_logged,
field or run, or any other name given per group with --group-x
(--group-order concentration --group-x 1=0,2=0.25,3=0.5); --order and
--x still control each group’s own within-group axis.
The batch closes with MODEL COMPARISON: when competing coupled families
were fitted, report representative shared values, uncertainties and quality
for each successful family, then choose from sample physics and joint
results. A single-run wizard ranking is insufficient to discard a viable
coupled comparison.
fit-series
Fit a recipe across a scan of reduced runs, chained along the scan order — the command that actually produces a trend.
asymmetry fit-series [-h] --runs RUNS --recipe RECIPE [--fix NAME=VALUE]
--order QUANTITY [--x RUN=VALUE,...] [--tmin TMIN]
[--tmax TMAX] [--global P,Q]
[--start RUN] [--name NAME] [--plot] [--json]
[--workdir WORKDIR]
folder
--order names the scan quantity the series is ordered and trended along:
temperature (the setpoint), sample_temperature_logged, field or
run, read from each run’s file. Any other name orders the series along a
quantity the files do not record — a concentration, a degrader foil count, a
magnet current — whose value for every run is given with --x, for
example --order concentration --x 101=0,102=0.25,103=0.5. A run
with no value, a value for a run outside the series, or a file-recorded
quantity given values by hand is refused.
--start RUN chains outward from that run in both directions instead of
from the first run in scan order — see Series fitting for why this
matters. --global P,Q pins those parameters at their recipe value for
every run rather than fitting them (see The fit recipe). --runs skips
run numbers the folder does not hold, as reduce does. Along a field scan,
a recipe line at the start run’s Larmor frequency starts every run at another
field scaled by that field over the start run’s, rather than at the
neighbouring run’s fitted frequency, which belongs to another field; a line
away from the Larmor frequency — an internal or critical field — is chained as
along any other scan. Besides the engine’s quality flags, a run whose fitted amplitudes
(backgrounds included) add up to more than 1.5 times the record’s own
early-time asymmetry is flagged amplitude_exceeds_data — two components
cancelling to describe a signal the data do not hold — and one whose fitted
frequency completes fewer than two cycles in the informative window is flagged
frequency_unresolved, a relaxation fitted as a line; fit applies both
checks. A series that fits a frequency adds a survey_line_mhz column: the line the
survey measured in each run, beside the fitted frequency, so a fit that drifted
off the measured line or found one where the survey saw none shows in the
table. When the recipe carries exactly one relaxation envelope, Gaussian or
Exponential, every converged run is refitted with the other one from its
fitted values and the table gains an envelope column — the shape that wins
by a χ² margin of 10 (the two have the same parameter count), or either —
and envelope_dchi2, χ²(other) − χ²(recipe). When the winning shape changes
along the scan the command ends with a note naming the runs on each side; on a
temperature axis it adds that a Gaussian (a static spread of fields) turning
exponential as the fluctuations outrun it is motional narrowing — and, when
the exponential is the cold side instead, that it is not: a broad, skewed
distribution (a vortex lattice beside a narrow background line) fits an
exponential better. When the series fits a frequency and the survey found no line in at least
two runs at one end of the scan, while another run holds one, the command
names every contiguous lineless run at that end, whatever their fit flags say:
the side with no precession — at the warm end of a temperature scan, likely
the paramagnetic side, though a line also vanishes where the local field at
the muon passes through zero. The precession model’s values there are not
results; the note prints the recipe and fit-series commands that fit
exactly those runs with Exponential + Constant, and asks for a refit with
the width held only where a weak line the survey missed still holds a
frequency. Ordered by temperature (the setpoint) while the logged sample
temperature departs on some of its runs, the command ends with a note naming
them. Writes
series/<name>.json (per-run results, a trend table, and quality flags —
the default name is series-<recipe stem>), plus a PNG per run
(plots/<name>/<run>.png) and one trend PNG per free parameter
(plots/<name>-trend-<param>.png) with --plot.
$ asymmetry fit-series runs --runs 102-107 --recipe wizard-102 \
--order temperature --start 102 --name zf-scan --plot
run temperature chi2_red verdict flags
--- ----------- -------- ------- --------------------------------
102 10.000 0.969 good -
...
107 60.000 1.004 good large_rel_err, spurious_reseeded
flagged : 1 of 6 run(s) — none were dropped
trend
Print, export or fit the parameter trend of a stored series or simultaneous fit.
asymmetry trend [-h] --series SERIES [--from-fits SERIES,...]
[--fit PARAM[:EXPR]] [--order QUANTITY]
[--x SERIES=VALUE,...] [--csv CSV] [--plot]
[--model EXPR] [--param PARAM] [--xmin XMIN]
[--xmax XMAX] [--initial NAME=VALUE] [--fix NAME=VALUE]
[--exclude KEYS] [--json] [--workdir WORKDIR]
[--instrument NAME]
folder
Reads series/<name>.json and prints the scan variable and every fitted
parameter with its uncertainty, per run, with the quality flags carried
through. --csv PATH also writes the table as CSV. --plot writes one
PNG per free parameter (plots/<series>-trend-<param>.png):
$ asymmetry trend runs --series zf-scan --plot
run x A_1 A_1_err Lambda Lambda_err flags
--- -- -------- -------- -------- ---------- --------------------------------
102 10 19.7178 2.06445 0.143275 0.0228251 -
...
107 60 0.198726 0.232033 1.06863 1.67424 large_rel_err, spurious_reseeded
--model EXPR --param NAME fits a parameter-vs-x law to one trend column —
the same fit, seeding and extra starts as the desktop
parameter trending dialog. The expression uses the
trend-model components: OrderParameter for a precession frequency or
internal field below a transition, Arrhenius for an activated rate,
Redfield for a relaxation rate against longitudinal field, the SC_*
gap models for a superconducting σ(T), Linear and sums such as
Redfield + Constant. --xmin/--xmax bound the fit in the trend’s x
units, --fix NAME=VALUE holds a law parameter and --initial NAME=VALUE
moves a start value. When χ²r is above 1 the error column holds the
errors scaled by √χ²r (the unscaled ones follow), and a NOTE
appears when --param is one of several components of the same kind in the
series’ model (Lambda_1 beside Lambda_2): a law describes one physical
rate or line, not one of two that split it between them. Without --model,
the report ends by naming the law the series’ axis and parameters call for —
Redfield for a rate against field (and a warning when the model splits the
rate between two components), OrderParameter for a frequency that falls
with temperature — one that holds within 10 % along the scan follows a fixed
field and is pointed at the relaxation’s rate and shape instead, with a note
when it still moves by more than five combined errors (a Knight or
diamagnetic shift) — and Linear for a rate against a supplied quantity; a
note repeats a change of envelope along the scan. For every fitted width or
rate (sigma, Delta, Lambda, nu) the report also finds the split
of the scan into two contiguous blocks whose weighted means differ most and,
when that is more than five combined errors, names the step, which way it
goes and where it falls, bracketed by where the parameter leaves the level of
one end and reaches the other’s (where it levels off), and gives the step’s size
and its percentage of the low end’s level. Along temperature, in a model of two
or more lines, a line whose amplitude at one end is under 30 % of the other’s
gets a note naming where it leaves its warm level on cooling: that span is the
line’s onset, which a width it multiplies cannot show once the amplitude is
near zero. Along a supplied axis
(a steering current, a foil count) an amplitude lower or higher inside the
scan than at both ends by five combined errors is named a minimum or maximum
instead, to report with where it lies — a Kubo–Toyabe width a few percent larger below a superconductor’s
Tc is the time-reversal-symmetry-breaking signal, however small. Along
a field scan it names a phase that runs linearly with field as a t0 offset
(printing the implied Δt and the reduce --t0-offset to test it) and an
amplitude that falls as its frequency rises as the instrument’s frequency
response; a line held near a high field, or with an exponential envelope on
its cold side, is offered a ready two-line recipe, since an unresolved
pair fits as one line. A superconducting gap-law suggestion uses Gaussian
sigma; an exponential Lambda instead calls for an explicit Gaussian
recipe comparison before a gap law is fitted. Broadening alone does not
identify the sample as superconducting.
Envelope comparisons are reported even when only one shape is preferred and
the remaining points are marked either. Such a comparison does not
establish a shape change; short-window results should be checked against
background and window choices before interpreting slow warm envelopes.
For a cold-broadened, downward-shifted TF line, the CLI suggests comparing a
Gaussian-width series and a conditional gap model while keeping the material
classification separate. A determined concentration slope can be reported as
an apparent fitted rate coefficient, with fit-quality and temperature caveats,
without claiming a validated intrinsic constant.
Temperature trends also print ENDPOINTS: values and errors for the first
two distinct reliable temperatures and the warm end. Compare these individual
rows before treating a weighted cold block as a plateau: a cold-end upturn can
coexist with a change farther along the scan. Dynamic Gaussian KT trends print
KT CONTROL: to compare both Delta and nu, including a control with
no corresponding onset. These notes omit unreliable fit rows and do not turn
poorly constrained parameters into measurements.
A series fitted in a field the survey found no Larmor
line at (longitudinal, whatever the file’s stamp), whose fitted curves lose
less than a tenth of what a zero-field series’ curves lose by 8 µs — on most
runs, against the zero-field runs within its own temperature span — is read
as decoupled: the note says the zero-field relaxation at those temperatures is
from fields static on the muon time scale, and that a rate pinned at zero or a
width left unconstrained there is that result, not a failed fit. Comparing the
curves rather than a rate holds whatever model each side was fitted with (a
Kubo–Toyabe fitted in the field leaves its width unconstrained, not small).
When the zero-field series’ model has no static-width term (a Bessel or a
plain exponential), the note also asks for the zero-field runs to be refitted
with a static Kubo–Toyabe and its width reported against temperature. Reading either series of the pair prints it. A fitted law’s
report states the x span of the points it rests on and each parameter’s unit,
and judges the law on the √χ²r-scaled errors of its physical
parameters (a prefactor or offset — a, b, c — that the data leave
open does not by itself sink a determined Tc); it notes when the fitted
points turn through an extremum, across which a monotonic law averages two
regimes. A law fitted against an axis it is not written in — Redfield
against anything but field, OrderParameter, Arrhenius or
CriticalDivergence against anything but temperature — carries a note that
its parameters have no physical meaning there. A law not established ends with
the next step: for OrderParameter
with alpha free, refit with --fix alpha=1 (points near Tc fix
only a power of Tc − T, so α trades off against y0); for
Redfield with m free, --fix m=2; otherwise,
when some physical parameters are determined and others are not, hold the
undetermined ones at a textbook value and report the rest with it stated.
Trend hints defer mechanism selection to the supplied experiment context.
Cooling-induced broadening and a line shift alone do not identify a
superconducting phase; established magnetic systems require a magnetic
interpretation rather than an automatic gap-law fit. Generic trend hints
therefore offer bounded local-susceptibility, internal-field and inequivalent-site
hypotheses without printing gap-law commands. An explicitly selected
tf-superconductor wizard scope prints the Gaussian-width/gap-law workflow
and the matching ZF/LF tests for a small static-field onset. A cold-end excess
compares the actual next measured temperature only when both estimates pass
the parameter-quality gates; a failed intervening point cannot be skipped and
a distant point called adjacent.
Generalized Redfield exponents have a model-specific positive lower bound; this does not constrain Linear slopes. Initial Redfield fluctuation frequencies use the field scale converted to frequency, and the zero-field rate sets the initial field-distribution scale. These are optimizer seeds, not measured parameters or evidence that the law is established.
Excluding a row is the analyst’s call: every row with a
value enters unless --exclude KEYS names it (a run number for an ordinary
series, a member series name for one built with --from-fits), and the
output lists both the rows left out (with the reason) and the flagged ones
that were fitted. The fit
is stored in series/<name>.json under trend_fits, keyed by the fitted
column and expression together (param:expression) so two different laws
fitted to the same column coexist instead of one overwriting the other, and
--plot
draws the curve over the points it rests on. On the simulated scan, whose rate
was generated as 0.10 + 0.004 T:
For a series fitted with differently shaped relaxation terms (an
Exponential beside a Gaussian), trend notes when the relaxing
amplitude — counting only terms whose rate stands above its error — moves
from one shape to the other between the scan’s ends, and asks for that change
of shape to be reported.
For a temperature trend containing r_muF, DIPOLAR COUPLING prints a
Constant --param r_muF comparison. It asks whether the fitted distance
and coupling are roughly constant or vary, with fit-quality caveats,
separately from a change in the dynamic fluctuation rate nu.
After a superconducting gap-law fit (SC_SWave, SC_DWave and the other
SC_* σ(T) laws), trend asks for an explicit verdict — does the law
describe σ(T), judged by χ²r and the trend plot — and after
SC_SWave prints the ready SC_DWave command on the same points. When the
fitted range leaves fewer than two points above the fitted Tc, the
normal-state width (sigma_bg) is not set by the data; trend says so and
gives the refit without --xmax, rather than advising a held value.
$ asymmetry trend runs --series scan --model Linear --param Lambda
...
Fit of Linear to Lambda against temperature: 5 point(s), chi2_red 0.285
parameter value error
--------- -------- --------
m 0.004150 0.000646
b 0.099391 0.022419
flagged but fitted: 102 (large_rel_err); 103 (large_rel_err); ...
For Gaussian-component widths entering a Brandt field fit, explicitly apply the same conversion as the GUI Custom Y transform:
$ asymmetry trend runs --series field-scan --param sigma \
--model SC_Brandt_VortexLattice --y-transform 'sqrt(2)*x'
The stored x axis is in gauss for a Brandt field law; Bc2 is in tesla.
--y-transform EXPR transforms the selected Y values and their errors for the
new fit. The stored source table and CSV remain raw; the fit records its actual
transform and its plot uses the transformed coordinates. Known unconverted
Gaussian sources are refused with the explanation in Gaussian widths at second-moment consumers.
Stored tables without captured source conventions remain usable and unknown;
loading never invents attribution or changes their numbers.
A trend of fitted trend parameters
--from-fits S1,S2,… builds a new series from other stored series’
already-fitted trends, rather than from runs — the way to fit a law through a
law: an Arrhenius rate through the rate constants of several Linear
fits, each made at its own temperature. Each named member series (an
ordinary series, or a global/global-batch series from fit-global)
must already carry a trend_fits entry for --param NAME; where a
member holds more than one law fitted to that column, --fit
PARAM[:EXPR] picks which (by the column the law was fitted to, or
column:expression when the column alone is ambiguous). The built series
is stored under --series (its new name here) with kind
fit-trend, one row per member holding that law’s parameter NAME and
its error scaled by √χ²r; --order/--x choose the row axis
exactly as fit-global’s --group-order/--group-x do — each
member’s mean temperature (the default), sample_temperature_logged,
field or run, or any other name given per member with --x.
--model then fits the built series like any other:
$ asymmetry trend runs --series k-vs-T --from-fits scan-280K,scan-300K,scan-320K \
--param m --order temperature
$ asymmetry trend runs --series k-vs-T --model Arrhenius
Refitting a member series after its trend fit was built into a derived one
leaves the derived series pointing at data that no longer matches what it
read; trend refuses to read it, naming the stale member, until it is
built again from the current fits.
audit
List the numbers in a draft summary that no command printed.
asymmetry audit [-h] [--workdir WORKDIR] [--json | --prepare-reply] draft
Named parameter values with explicit units in printed tables are also checked
for contradictory units in the draft, including rejected-fit diagnostics. This
is a conservative check, not full dimensional validation of arbitrary prose.
Both values and uncertainties retain their parameter units. In particular,
CriticalDivergence uses a dimensionless exponent nu; it is not the
fluctuation rate with the same name in a dynamic KT or Redfield model.
Tables may place the unit before or after the error columns.
Illumination measurements with two periods require a common science run fitted
in separate red and green workdirs; a differential integral cannot substitute
for the two time spectra. Mixed-instrument surveys use each scan’s instrument
when matching completed fits in other workdirs.
The audit also requires the acquisition instrument/file suffix and the distinct
recorded sample names; magnet-reference groups do not replace sample identity.
A completed Gaussian-width comparison should retain its measured values and
onset/plateau separately from exponential damping, even when material identity
is uncertain. Successful command results remain evidence despite stderr
warnings; a failed retry does not erase a completed recommendation.
A muon or proton hyperfine coupling (A_hf, A_mu, A_p, or a
diffusion model’s A) fitted at least two scaled errors from zero prints a
CONDITIONAL COUPLING note. That estimate, and significant coldest-versus-next
excesses, remain reportable with their model and fit-quality limitations.
An ADJACENT ENDPOINT diagnostic also retains the actual next temperature
when its fit is flagged. Describe that pair and its limitation; a bound-pinned
point cannot establish a significant measured upturn and must not be replaced
by a distant reliable point. Extreme logged/setpoint offsets require a channel,
unit and experimental-context check: a railed logger is not a physical thermal
confound in an instrument calibration.
The audit also checks that the report gives the folder run count and explicit
members for each longer scan. For repeated weak-field groups it checks for
actual simultaneous fits with shared dynamic parameters and per-run fields;
independent fit-series coverage does not satisfy that check.
Every other command appends what it printed to cli-output.log in the work
directory it used (commands without a --workdir, such as alpha, log to
the default one when it exists). audit extracts each number from the draft
and reports the ones that appear in none of those logs, with the line they sit
on. A number written with d decimals matches any printed value it rounds
from, so a clean audit means every number appears in some output, not that it
is the right one. A percentage of a total or relative fraction requires its
printed percentage token, even when it follows A_bg or contains decimals;
an absolute amplitude in percent asymmetry is a different quantity. A multiple,
a significance, a whole-number percentage or a
Δ-quantity (10×, 4.3σ, 32 %, ΔAICc 11) matches only when a
command printed that exact token (×, x and “times” alike). A number its
context makes arithmetic — after “a factor of” or a difference phrase (“within
about 2 G”, “differ by 0.6”, “falls by about 0.03 MHz”, “agree with the survey
to about 0.02 MHz”, “a margin of 3.6”, “the step is about 0.007”), named as a comparison (“4 points
better”, “a 1.2–1.3 % spread”), or a spread after a bare ± (±0.2 MHz) —
is listed unless a command printed it verbatim to three or more significant
digits, as a run number or a field on the scan’s grid is; a ratio in words
(“a factor of six”, “five and a half times its error”, “three times broader”)
is listed too. While a surveyed scan is unfitted, a clean audit says not to
reply yet. A written number matches a printed value within one unit of its
last digit (rounded or truncated). 4,200 and 3.2 × 10⁻⁸ read as one number. A hedged integer
(“about 12340 G”) may round away its trailing zeros, a field in kG verifies
against one printed in G, an error in parentheses after its value
(“2.91 (±0.12)”) is that value’s error, and “1σ errors”, “> 3σ” and
“2× LorentzianLCR” are a convention, a threshold and a count, not results. Every command
that produces results (fit, fit-series, fit-global, trend,
integral-scan, fourier) ends its text output with the step: write
summary.md and run asymmetry audit summary.md before replying, preceded
by a “Still unfitted:” line naming the surveyed measurements no fit holds yet.
For the final send, run asymmetry audit summary.md --prepare-reply.
The repeated result-command footer and the evaluation image-review prompt use
this same preparation step after the last edit. Copy its passed body without
reformatting numeric precision or adding a final newline.
After all checks pass, this opt-in operation removes terminal line endings
from the saved draft and emits only that exact body on stdout, without markers,
status lines or a copy-check footer. Copy the entire stdout unchanged. Failed
preparation returns a nonzero status and leaves the draft unchanged. Repeat it
after every edit; editors may restore a newline. Without the option, audit leaves
the file unchanged. It cannot be combined with --json.
A clean audit without --prepare-reply prints the passed draft between ----- BEGIN ----- and
----- END ----- lines for the reply to copy whole, since agents that retype
it add unaudited text. A COPY CHECK after the markers gives the report’s
line count and final line, so copying can be checked through the last file-list
entry. The cue is outside the report and must not be included in the reply. Preserve
whitespace and duplicate file entries as audited: final formatting, added
Markdown line-break spaces or tail edits invalidate exact copying.
A report listing only numbers ends by asking for
another audit before replying. What it catches is the arithmetic an
analyst does in prose — percentage changes, ratios, unit conversions (“which
would be a field of about 21 G”, “corresponds to roughly 16 G”),
differences between printed columns (“29 AICc units behind”, “0.37 MHz
apart”), a spread across windows (“stable to about 200 G”) — which the agent
skill’s number rule forbids. A comparison copied verbatim from the output, or
a number word whose digits a command printed (“within two resolution
elements”), verifies. A hedged round number’s
trailing zeros are not significant digits, so “about 200 G” cannot verify
against an unrelated printed 200. A count “N of M” verifies only as a
printed tally (the envelope NOTE and Fit quality counts print theirs as
“14 of 15”), so a recount by hand is listed. It also lists a law’s vocabulary (“critical slowing”,
“activation energy”, “correlation time”) when every fit of that law in the
logged session printed LAW NOT ESTABLISHED; explicit failed or rejected
attempts remain valid descriptions. Integral scans with significant local
minima are checked even before the first resonance fit. Testing a local window
can end in an unresolved result; a candidate is not automatically a resonance.
A fit of a co-added representative covers its recorded member runs, without
requiring redundant repeat fits. The audit also lists a run with a correlation
spectrum but no plain
transform in the same work directory, whose two lines the summary needs.
Printed cross-condition COMPARE notes also require field-centre and
width directions in prose. Conditional estimates retain their window and
background limitations; listing numbers or describing a wider fit window
does not state which feature is broader. STABILITY notes for alternative
fits of the same runs do not impose a cross-condition claim. These are
omission checks; the analyst still checks each direction against the two
labelled estimates. When one scan resolves a narrow line and the other’s
estimate is at least three times broader with its flanks outside its window,
COMPARE adds that only the first resolves a narrow line there, so the
summary says the other shows none; and integral-scan no longer asks for a
same-window refit of a scan whose converged fit already holds such a broad line.
It holds the reply, quoting the printed line back, when a command asked the
summary to say something the draft leaves out: that A_bg was held at 0
(fit, fit-series); which deadtime correction was used, when
reduce left the files’ deadtimes off; why a long-range integral-scan
fit is not a result (a background no polynomial can follow); that the scan
measures some points twice; that no radical ALC or hyperfine model converts
the resonance fields; a trend step and its span, a line’s frequency shift,
the instrument’s frequency response, a change of relaxation shape, an
extremum a monotonic law averages over, or a longitudinal field decoupling the
zero-field relaxation (the fields are static); and, for a draft quoting the muon
hyperfine coupling, that A_μ = ν₁ + ν₂ is the sum of the radical’s two lines.
The check reads keywords, so it catches a point left out, not one stated
badly. It also
holds the reply while a fitted series has not been read with trend, while a
tesla-field line fourier offered a two-line test for has no two-line fit,
and while a run the survey found no line in has only precession fits flagged
as not describing it (amplitude_exceeds_data, frequency_unresolved,
failed) — for those it prints the relaxation-only recipe and
fit-series commands. A dip an integral-scan fit announced (“the scan holds
another dip”) holds it too until a fit of the same scan has a line whose
centre ± width lies inside that window — another scan’s line, or a broad line a
poor whole-scan fit stretched across two dips, does not hold it. Bulk arrays a --json payload dumped (a time axis, a histogram) are
left out of the match, since a rounded sum would otherwise find one of their
elements by chance.
Before the numbers, audit lists every scan in the stored survey whose runs
no fit-series, fit-global or integral-scan holds a result for, with
the runs left out:
Scans the survey found with runs that no fit, fit-series, fit-global or integral-scan fitted. Each scan is a measurement:
temperature scan, SIM, ZF, B = 0 G: 6 runs, 10 to 60 K (runs 102-107)
not fitted: runs 105-107. Fit it — a scan crossing a transition needs a series on each side. A run counts once a fit was tried on it, failed or not: a survey 'none' means no Fourier line, not no signal, so fit it before calling it unusable and report what the fit shows.
The far side of a transition that one series stopped short of is still a
measurement, and so is a temperature scan whose runs served to measure alpha:
for one of those audit says that the calibration does not account for the
scan and prints the wizard and fit-series commands that fit it. Scans of
two or three runs share one line. A run fitted on its own with fit counts
as fitted.
audit also holds the reply until the draft states the folder’s coverage as
a run count (24 runs; a bare 24 elsewhere, such as 24 K, does not
count) and each surveyed scan of more than three runs by its own members —
its --runs spelling or its first-to-last range (201-206, 201 – 206).
integral-scan
Build count-integral asymmetry versus field (or temperature/run order) and
optionally fit a field-scan expression. The default --method integral sums
corrected native counts before forming \((F-\alpha B)/(\beta F+\alpha B)\).
--period green-red subtracts the two period ratios with shared chosen
calibration. --method differential explicitly requests the equal-time-bin
mean of pointwise asymmetries; it is distinct from dA/dB and can give a different
value on the same counts. Bounds include whole native bins by centre, and
omitted bounds use the good window. Stored scan values/errors are fractions,
conditional on calibration. See Integral scan mode (avoided-level-crossing field scans) for period and history semantics.
The scan JSON records each point’s mathematical observation status and
exclusive used/omitted counts, plus point-index correlated_pairs and
source_assumption.
Run-ordered scans use source run numbers in both their coordinates and effective
recipes. Selected acquired periods remain recorded in the individual point recipes.
Undefined numeric values and unavailable errors are JSON null. A defined
zero-variance point retains its value and error zero. Text output reports
omissions and known shared counting observations. Fits select usable points
before seeds and weights; known dependent selections require an independent
subset. Scan inspection and export remain available without a fit. These
errors include supported reused counting responses, conditional on calibration;
they do not include calibration uncertainty. See Integral scan mode (avoided-level-crossing field scans) for the
operation-specific messages and shared-reference limits.
This is the ALC/QLCR path:
asymmetry integral-scan [-h] --runs RUNS [--name NAME] [--alpha ALPHA]
[--alpha-from ALPHA_FROM]
[--deadtime {off,from_file}] [--pair FWD/BWD]
[--background none|tail_fit|range[:FIRST:LAST]]
[--t0-offset BINS] [--t-good-offset BINS]
[--period RED|GREEN|N|green-red] [--tmin TMIN]
[--tmax TMAX]
[--method {integral,differential}]
[--order {field,temperature,run}]
[--model MODEL] [--initial NAME=VALUE]
[--fix NAME=VALUE] [--bound NAME=LO:HI]
[--xmin XMIN] [--xmax XMAX]
[--baseline MODEL]
[--baseline-regions LO:HI,...] [--plot]
[--json] [--workdir WORKDIR]
[--instrument NAME]
folder
For example, --model "LorentzianLCR + Cubic" fits an off-zero resonance
and background together, and --model "LorentzianLCR + LorentzianLCR +
Cubic" two resonances: each LCR component starts on its own resonance, found
in turn as the largest excursion from a straight baseline that falls to half
height on both sides inside the scan, so a background curving away at one end
of the scan is not taken for one. Each resonance is held inside the scan, with
a width between a thousandth and a quarter of it by default, to discourage a
line from absorbing a poorly constrained polynomial background. A broad line
can require a different interval: --bound Bwid=10:2000 replaces that
parameter’s automatic bounds. Bounds must be finite and ordered, and widths
and differential field steps must stay positive. Indexed component names work
the same way. The selected intervals are stored in the fit’s bounds field.
Include baseline data on both flanks and check nearby windows before accepting
a width recovered this way; relaxing a bound does not resolve a background
degeneracy. Alternatively, --baseline
Cubic --baseline-regions 2000:2600,4500:5000 --model LorentzianLCR
determines the background only from non-resonant regions before fitting the
corrected scan, and --xmin/--xmax fit only the points inside a window
of the scan axis — the way to fit one resonance at a time where the background
is not a polynomial across the whole scan. A window holding no more points than
the model has free parameters is refused. A fit that does not converge is
reported with FAILED and the parameters it ended on (the component that ran
away is usually plain from them); the scan is written either way. The fitted
parameters print as a table of value, unit (G or MHz, for fields and couplings) and error — fixed for a held one,
(at bound) beside one pinned on a bound, and - for the errors of a fit
that failed; a failed fit names the minimiser’s reasons and any parameter at a
bound, and suggests fitting one resonance per --xmin/--xmax window
around the scan’s own dips. A fit that converges with a χ²r above 2
is told why that may be — a background no polynomial can follow across a long
scan, or a dip the model leaves out. After a resonance fit, converged or
failed, supported independent windows are investigated for dips the fitted lines
leave out. A supported dip is named with its own window and the command that
fits it (“the scan holds another dip”, or “N more dips”): the
seeder’s window for one more resonance, and the window of each other significant
interior minimum (the LOCAL DIP CANDIDATES screen below), taken deepest
first. A window is named when a single line fitted inside it falls below its
background by five errors and lands outside every window already named, so a
wide shallow minimum whose window reaches a deeper neighbour’s line is not named
twice. Known dependent subwindows are omitted from these independent-error
exploratory fits. The fit JSON’s next_dip_limit records
Known shared counting observations restrict independent-error dip checks.
when the full scan has such restrictions. A completed independent fit within
--xmin/--xmax remains available, and other independent subwindows can
still be investigated. An omitted exploratory fit does not establish absence
of a dip. A line fitted
inside an --xmin/--xmax window with data on both flanks, an amplitude
five errors from zero, nothing at a bound and a χ²r of at most 8 is
called a resolved RESONANCE to report, with its errors qualified when
χ²r is above 2; a background step read as a dip fits far worse.
The two-width coverage test checks the outer baseline. A shorter window can
still constrain a centre: compare nearby windows and baseline models and
report a stable, non-bound estimate with a determined error as a conditional
fitted centre. Keep that estimate distinct from an established isolated line;
a failed fit or a bound-pinned width remains unmeasured. Poor chi-squared
requires a model-mismatch caveat and stability checks, rather than discarding
every fitted parameter solely because the model is approximate.
The automatic width search extends to half the fitted field span. This allows
a partially covered line to be investigated without falsely pinning it at the
stricter two-width-flank resolution limit. Such a fit still needs coverage and
stability qualifications. For inadequate flanks the CLI prints a wider-window
Cubic command: compare it with nearby windows, independently for each condition,
because a sharp line’s window can truncate its broader partner. Explicit
--bound values still override the search interval.
When no resonance model was selected, the CLI independently screens the field
curve for significant interior minima and prints LOCAL DIP CANDIDATES
with exploratory windows. Five combined point errors of prominence reject
small noise excursions; these coordinates are measured minima, not fitted
resonance fields. Quarter-prominence widths keep the initial windows near the
trough bottom without claiming measured line widths. Inspect each candidate,
compare nearby windows and local Linear/Cubic baselines, and report a stable
fitted estimate or the remaining limitation. A failed whole-scan recovery
model does not establish that local resonances are absent. Monotonic recovery
curves do not generate interior-dip candidates.
A scan that measures one field (or other x) more than once is noted with the
runs and whether each repeat came back within three errors, provided the
observations have usable independent Gaussian errors. Otherwise the repeat
note says uncertainty unavailable; it retains the repeated coordinate and
runs without an agreement claim. A dip another stored fit of the same scan holds (a line whose
centre ± width lies inside the dip’s window) is not announced again. When a windowed line (both flanks in range, five errors deep) matches one
another scan in the work directory fitted near the same field, a COMPARE
line prints both centres and widths, with errors scaled by
√χ²r, and says which is broader and which higher in field — the
direction a summary of two conditions must state. A feature that
has incomplete flanks can still be compared as a
significant, non-bound fitted estimate. Such COMPARE notes explicitly say
conditional fitted estimates and not two resolved lines; scaled errors
and window/background sensitivity qualify the direction. Failed, bound-pinned
or insignificant fits are excluded. This does not relax the resolved-line gate.
Fits with identical run membership instead print STABILITY: these test
window/background sensitivity of the same measurement. Agreement there does
not imply agreement between different temperatures. Only comparisons of
different run sets carry the cross-condition interpretation guidance.
A resolved line that
another analysed scan covers, with no fitted line within five widths of it
there, gets a NOTE with the command that fits that scan on the same window: a
line one scan shows and another lacks is a finding to report either way. Retained integral asymmetry does not measure geometry or invalidate the declared
label; keep the metadata and experimental interpretation distinct. An LCR fit notes
that no radical ALC or hyperfine model is available, so its fields are not
converted into couplings. Without --period, a scan of two-period runs
notes that it summed the periods. With --json every NOTE and Next line is
kept under notes. --alpha-from a single-period calibration run serves a
--period scan too: the detector balance is the same in every period.
Every field-scan component with a resonance or a half-rise to find in the
data — the LCR line shapes, LorentzianLCRPair, RFResonanceMuP and
MuRepolarisation — is seeded from the scan itself this way, so a fit
usually converges without --initial; --initial/--fix values are
folded into that seeding, not applied afterwards, so a fixed value is never
overridden by a seed near it.
The scan points, excluded runs, reduction settings, fit parameters and
uncertainties are stored in scans/<name>.json. The human-readable fit
table puts uncertainties scaled by sqrt(chi2_red) first when reduced chi-squared
exceeds one, with unscaled error alongside. Fixed parameters remain
fixed, bound flags remain visible, and a failed fit prints no usable error.
Stored JSON uncertainties remain the raw fit errors. Scaling does not make a
poor model physically adequate; retain window and baseline limitations.
Each run’s counts are
grouped and corrected under the Reduction options — --deadtime
from_file on an ISIS repolarisation or ALC scan, as in reduce, and
--background the same way (see Reduction options for how its error
propagates into the integral).
--method integral (the default) sums corrected counts before forming each
asymmetry. --method differential instead takes an equal-weight mean of
per-bin asymmetries; late low-count bins can make it much noisier. This
estimator choice is independent of period subtraction. An integrated RF
contrast normally uses --method integral --period green-red. The printed
scan identifies the estimator so a failed resonance fit can be revisited
without confusing the two operations.
--period green-red builds the RF-resonance or differential-ALC scan: each
point is the green period’s integral asymmetry less the red period’s, each
formed from that period’s own counts under the Reduction options, with their
supported shared counting responses combined before evaluating variance. The period labels alone do not identify the switched quantity. Missing
field-step metadata does not prove RF switching. For a justified physical field
step use --model LorentzianLCRPair --fix dB=<B_green-B_red in G>;
for a known RF contrast use --model RFResonanceMuP --fix nu_RF=<MHz>.
A documented red-minus-green step changes sign once. No model is chosen from
log presence or absence. After an RFResonanceMuP
fit the report prints the two resonance fields its couplings imply, or says the
couplings are not a result when those fields fall outside the scan. RFResonanceMuP fits the muon and proton
couplings of an RF scan with the RF frequency held at its acquisition value.
With nu_RF fixed (or given as a start), the couplings are seeded by solving
the resonance condition at the scan’s own two dip fields rather than taken from
the model’s defaults (515 and 124 MHz, the benzene radical’s). On the benzene
DEVA data of the WiMDA school, recorded at 218 MHz:
asymmetry integral-scan data --runs 56426-56462 --period green-red \
--deadtime from_file --model RFResonanceMuP --fix nu_RF=218
gives A_mu ≈ 514.8 MHz and A_p ≈ 124.4 MHz, and reaches the same
minimum from --initial A_mu=470 --initial A_p=90: the fit also tries the
scan’s own seed beside a start given by hand, so another radical needs no
--initial near its couplings.
Raw Hall-probe logs retain their declared units. They do not establish a
physical step in gauss through cross-run regression. Historical stored inferred
offsets remain part of that saved analysis and are not reused as fresh physical
calibration or model advice. The existing --fix input accepts an independently
justified step; no new calibration control is required.
The scan fit boundary accepts original observables. Derivatives remain available
for display/export through the API at adjacent-pair midpoints, with positive
spacing and explicit optional max_gap. Units are the recorded asymmetry
scale per selected axis unit. Adjacent differences share observations, so their
marginal errors do not establish an independent-error likelihood. Known dependent
input pairs retain derivative values with unavailable uncertainty. See
Integral scan mode (avoided-level-crossing field scans) for the formula, units and persistence contract.
Report the resonance field, width, amplitude and uncertainties the command prints. Do not use shell arithmetic or a literature formula to turn them into a numeric hyperfine coupling and present it as command output; keep that relationship qualitative unless Asymmetry itself emitted the derived value.
fourier
Transform one reduced run and report quantitative peaks:
asymmetry fourier [-h] --run RUN [--name NAME] [--correlation]
[--correlation-field GAUSS]
[--correlation-order CORRELATION_ORDER]
[--window {none,hann,cosine,gaussian,lorentzian}]
[--padding PADDING] [--tmin TMIN] [--tmax TMAX]
[--phase PHASE] [--filter-tau FILTER_TAU]
[--fmin FMIN] [--fmax FMAX] [--peaks PEAKS] [--plot]
[--json] [--workdir WORKDIR] [--instrument NAME]
folder
--correlation builds the muoniated-radical correlation spectrum instead of a plain FFT — the GUI’s Correlation
(radical) display mode, on the command line. It reloads the reduced
entry’s source run(s) (every member, for a co-add) and pairs the radical
lines of the forward and backward groups at the transverse field the run
recorded, so it needs the run files themselves, not just the stored reduced
curve; a green − red entry has no single transverse field to pair at and is
refused. --correlation-field GAUSS overrides the field the pairing uses
when the header value is missing or slightly off, and
--correlation-order sets how strongly an unequal-amplitude (spurious)
pair is penalised (default 2, as WiMDA). The stored spectrum’s axis and peak
table are on the hyperfine-coupling axis (MHz), not frequency — a peak
names a coupling \(A_\mu\) directly, the way RFResonanceMuP and
LorentzianLCRPair do for the corresponding field-swept methods.
Combined with reduce --coadd, a correlation spectrum can be built from
several runs at one field summed for statistics before the FFT. The report’s
header names the transform, its window and resolution; after a correlation
spectrum it points at the plain transform of the same run, whose radical
lines belong beside \(A_\mu\) in a summary; it states that the peak is
\(A_\mu = \nu_1 + \nu_2\), the sum of the radical’s two lines. The header
also gives the band searched against the whole transform, and a note names the
strongest lines detected outside a --fmin/--fmax band. (wizard,
for its part, names a recommended component at twice a tesla-field line’s
frequency as that line’s harmonic and points here.) A line near the
Larmor frequency of a field above about 0.74 T (100 MHz) gets a note that
inequivalent sites or sublattices split a line by about the resolution there,
with the recipe and fit commands that test two lines started either
side of it; and every plain transform closes by saying that MaxEnt and
multi-group field-distribution analysis are not available, to be named under
Not done where the field distribution matters.
The command stores numerical arrays in spectra/<name>.npz and settings,
resolution and the peak table in spectra/<name>.json. Zero padding makes
the plotted curve smoother but does not improve the reported resolution,
which is set by the selected time window. This is an FFT, not MaxEnt.
Peaks are detected on the whole spectrum and then restricted to
--fmin/--fmax, so a narrow zoom around a line keeps the line in the
table (the noise floor is the spectrum’s, never the zoomed band’s). Peak
detection is deliberately conservative: when nothing passes it, the command
lists the band’s strongest maxima with their height over the noise floor,
headed “candidates, not detections” (candidate_maxima in --json) — a
weak line to confirm or refute with a time-domain fit started at that
frequency. Inspect the spectrum PNG for weak shoulders as well as reading the
table. Heed an
ApodisationEarlySignalWarning: use an unwindowed physical --tmax crop,
or a lorentzian window whose --filter-tau matches the damping rate,
when a symmetric taper removes the early-time signal.
Use a science run—not the weak-TF alpha-calibration run—for the representative FFT. In a temperature series, the coldest high-statistics science run is the usual first choice when splitting or broadening is expected. If several runs share that temperature, use their event counts to choose the highest-statistics one rather than the first run number. For semiconductor/shallow-donor or muonium data, inspect around the Larmor line for a central peak and symmetric satellites. When Fourier structure is the experiment’s point, call the result an FFT rather than MaxEnt and include its window, resolution, peak table and visual PNG inspection in the final report; a generic time-domain fit does not replace them.
skill
Install, check or remove the asymmetry-analysis agent skill — see
Installation above for install, check and uninstall in detail.
asymmetry skill [-h] {install,check,uninstall} ...
info
Show metadata for a single data file, independent of any work directory —
the same summary the GUI’s file inspector shows, useful for checking one
file directly without surveying a whole folder. --json adds the run
number, the point count, the groups and default pair, and the file’s metadata
beside that summary (without
the loader’s verbatim NeXus field tree, which would bury it).
asymmetry info [-h] [--json] file
It also lists the file’s detector groups by id and name, and the pair it
reduces on by default (Groups : 1 Forw, 2 Back, 3 Up, 4 Down, 5 Righ
(default pair Back/Forw)) — the names --pair takes.
The work directory
survey, reduce, integral-scan, wizard, recipe, fit
(fits/<recipe>-<run>.json), fit-global, fit-series and fourier
persist their state in ./asymmetry-work/; trend reads it and adds its
law fits and what --plot and --csv ask for. alpha and info are
stateless — they load a file, print, and write nothing — and skill writes
into the agent’s own skill directory instead.
The directory is resolved against the directory the command is run from — the project the analysis lives in — and never against the data folder, which is routinely a read-only share or an archive and is not somewhere an analyst would want cached spectra and plots to appear. It is deliberately not hidden: the plots, the recipes and the stale sessions in it are all things a person has to find.
The work directory holds:
asymmetry-work/
manifest.json # asymmetry version, folder, settings, run list
survey.json # output of `survey`
reduced/<run>.npz # time, asymmetry, error
reduced/<run>.json # run metadata + reduction settings + cache digest
wizard/<run>.json # screening payload: recommendation, narrative, recipe
recipes/<name>.json # a fit recipe (model + parameters + window)
series/<name>.json # per-run results, trend table, quality flags, trend fits
fits/<recipe>-<run>.json # one run's `fit`
scans/<name>.json # integral-scan points, exclusions and optional fit
spectra/<name>.npz # Fourier frequency, real part and magnitude
spectra/<name>.json # Fourier settings, resolution and peak table
plots/*.png # headless PNGs written by --plot
cli-output.log # every command's printed output, for `audit`
so a later command picks up a reduced spectrum, a recipe, or a series without
reloading or recomputing it, and an agent (or a shell script run in several
steps) has state between invocations without a long-lived process — the same
role a future MCP server would hold in memory instead. A reduced entry is
keyed on a digest of the source file’s identity (size, mtime, and the SHA-256
of the whole file), the resolved grouping payload, the reduction settings, scientific-computation revision, and
the work-directory schema; an entry whose digest no longer matches its inputs
is recomputed, never trusted stale, and a reduced run or series written by an
older asymmetry is refused with a message to reduce or fit it again. The whole directory is safe to delete — every command
rebuilds whatever it needs from the original data files and, for fit,
fit-global and fit-series, the recipe.
One directory, one data folder
Everything under the work directory is keyed on the run number alone, so
two data folders whose run numbers overlap would overwrite each other’s
spectra, recipes and series inside one directory. The manifest therefore
records the folder — and, since two instruments can share a folder (see Two
instruments in one folder), the instrument — the session was opened for,
as an absolute resolved path plus a name, and every command checks both
before reading or writing anything
(asymmetry.core.workflow.workdir.WorkDir.bind()). A directory that
already belongs to another folder or instrument is refused:
$ asymmetry survey /data/nickel
asymmetry: /work/asymmetry-work belongs to /data/ptfe; for /data/nickel pass --workdir asymmetry-work-<name>
survey and reduce write the manifest, so the first of them run against
a fresh directory claims it; a directory with no manifest yet is unclaimed. A
manifest written before instrument selection was recorded (schema below 4)
is read as the whole folder, with no instrument bound. An older manifest is
upgraded the next time survey or reduce writes it; its recorded
instrument is preserved when present. Reduced runs and series under an older
schema must be regenerated rather than trusted. The same folder named
relatively, absolutely, or through a symlink is one
folder — both paths are resolved before they are compared.
Scientific computation revision
Asymmetry also checks a scientific-computation revision before reusing persistent
reductions, wizard assessments, fits, scans, spectra, and dependent series.
computation_revision identifies the numerical implementation that executed
the calculation. It is separate from the package version, storage schema,
effective recipe, and actual-observation digest. A package or documentation-only
release does not invalidate calculations.
An old or missing revision cannot qualify as current work or suppress a needed
calculation. reduce recomputes incompatible cached reductions. Consumers of
historical work-directory products report that they must be recomputed; run the
command that produced them again. This adds no approval dialog. Historical files
remain available for inspection; core work-directory readers offer
require_current=False for historical records. Writing those records again
preserves their old or unknown revision. A new fit over explicitly supplied
historical observations records its own execution and the input’s revision
separately. Applied historical calibration coefficients remain usable.
Effective reduction provenance
Fresh core reductions expose dataset.effective_recipe independently of the
live Run. Its to_dict() method returns a detached JSON view, and its
identity identifies the recorded effective numerical interpretation and
available source references. It includes actual correction outcomes rather than
only requested settings. The record survives fit_record(); raw histogram
replay and retained counting operators do not cross that worker boundary.
Work-directory sidecars and scalar-scan payloads retain the captured recipe.
A cache hit retains the recorded correction outcomes and numerical arrays, but
does not restore raw histograms or counting operators. Older records without
a recipe remain unknown (effective_recipe=None). Public JSON recipe fields
omit nested local locators and diagnostic prose; private work records retain
them. This disclosure does not anonymise other metadata such as titles.
Recipe identity alone does not identify the sampled observations or verify
acquisition contents. Saved fits also record an observation digest of the actual
coordinates, values, retained errors, usable support, and interpretation.
See Count reduction and transformed signals for captured facts and transformations.
The fit recipe
A recipe is the only contract between screening and fitting: small JSON that
wizard writes, that a person or an agent may hand-edit, and that fit,
fit-global and fit-series consume.
{
"schema": 1,
"asymmetry_version": "0.19.0",
"expression": "Exponential + Constant",
"model": { "...CompositeModel.to_dict()..." },
"parameters": [
{"name": "A_1", "value": 19.7, "min": null, "max": null, "fixed": false},
{"name": "Lambda", "value": 0.14, "min": 0.0, "max": null, "fixed": false},
{"name": "A_bg", "value": 0.0, "min": null, "max": null, "fixed": false}
],
"t_min": null,
"t_max": 12.0,
"rebin": 1,
"source": {"wizard_run": 102, "template_key": "exp_constant"},
"pinned": []
}
Two rules govern what a recipe carries, settled once the wizard’s own per-run bounds turned out not to travel across a scan:
A recipe’s bounds are the model’s static defaults, not the wizard’s per-run search window. The wizard’s bounds (a peak window, 0.5–2× a seeded amplitude, Nyquist and duration caps) describe the one run it screened; carrying a frequency window measured at 300 K into a fit at 380 K clamps the fit at a bound instead of letting it follow the physics. The values are still carried — a wizard fit’s numbers are the best available starting point — only the bounds are reset to what typing the same expression into the desktop application would give.
Run-bound values are re-seeded per run in a series unless pinned. A value that describes a run rather than the physics — an applied field, a spectral peak — is re-seeded from each run’s own record as
fit-serieschains along the scan. A value named inpinned(written by--fix,--global, or a hand-edit to this list) is never moved, because it was chosen rather than measured. This is distinct from a parameter’s ownfixedflag, which also covers a parameter the model or the wizard holds fixed by default and which is still re-seeded per run.
Hand-editing a recipe
To swap one component, edit three things: expression, the matching entry
in model’s component list, and the parameter list (name and starting
value) — for example Exponential → Gaussian renames Lambda to
sigma. Write the result to recipes/<name>.json and pass
--recipe <name>; run asymmetry fit --run N --recipe <name> on one run
first to check it converges before spending a whole series on it.
--global P,Q on fit-series pins those parameters at the recipe’s
value for every run rather than fitting them jointly: fit_asymmetry_series
is block-separable. Use fit-global --shared P,Q for a true simultaneous
fit of one run group.
Series fitting
fit-series chains: each run’s fit seeds from its nearest already-fitted
neighbour along the scan order, rather than every run starting cold from the
recipe’s own values. --start RUN picks where the chain begins and lets it
grow outward in both directions, instead of always starting from the first
run in scan order — the recommended flow is to screen the run with the
clearest structure (asymmetry wizard --run N) and then start the series
there (fit-series --start N), so every fit warm-starts from a neighbour
nearer the run the recipe actually describes. Chaining from one end of a scan
with a recipe fitted at the other end can lose the runs in between entirely.
Every per-run result carries quality flags, read from fit_result_summary:
Flag |
Meaning |
|---|---|
|
The minimiser did not converge. The row is not a result. |
|
A free parameter’s σ/value is large — the data barely constrained it. |
|
A free parameter sat on a bound. |
|
The fit landed on the spurious branch (amplitude collapse or frequency jump) near a transition, whether or not a reseed rescued it. |
Nothing is dropped. A flagged run still appears in series/<name>.json
and in the trend table, with its flags attached, so the full scan is
always visible. Bounds and large errors are assessed per parameter: an
unconstrained nuisance damping term does not invalidate a precise amplitude,
frequency or Gaussian width. Trend rows retain params_at_bound in JSON;
whole-fit failures, unresolved frequencies, spurious reseeds and unphysical
amplitudes still qualify the entire fit. Work-directory entries record their
schema. Reduced caches, wizard results and series under an older schema must
be regenerated so their statistics and diagnostic metadata match the analysis
contract.
Temperature endpoints print the coldest-minus-next difference and its combined
error. Values within two combined errors are described as consistent; a
whole-scan step does not prove an endpoint upturn. Linear rate fits against a
supplied axis print APPARENT FITTED COEFFICIENT: with the fitted uncertainty
and units per unit of that axis. This preserves an empirical estimate while
leaving intrinsic kinetic interpretation conditional on the experimental
conditions and model adequacy.
Plots
Each PNG framed by --plot follows the same two rules:
The informative window. μSR errors grow with time and are capped at 100%, so an unframed plot’s y-axis follows the noisy tail rather than the signal.
reduceandfitplots frame the x-range on the same SNR-truncated analysis window the fit wizard’s own fingerprint and peak detector use, and set the y-range from what actually ends up on screen — a cropped or bunched panel says so in a small note in the corner.Display bunching. A panel with more than a few hundred points is bunched to about 400 points for display only; the underlying fit or reduced record is untouched.
trend plots frame the y-axis on points unflagged for the plotted
parameter, so a nuisance offset’s large error cannot clip a measured width.
One
wildly flagged run cannot squash every other point onto the axis edge; a
flagged point outside that range is still drawn, clamped to it, with a
distinct marker, and counted in the frame note, rather than silently moved or
dropped.
A zero recorded field plus a detected line is ambiguous without sample context.
survey prints ZERO-FIELD HEADER: for these runs: a nonmagnetic reference
may carry an unrecorded weak TF, while a magnetic sample may precess in an
internal field. The note prints the field each line implies for a diamagnetic
muon (13.55 kHz/G), so a summary quotes it rather than converting. Calibration sensor drift is not automatically a sample scan.
Broad local ALC troughs also require baseline checks: compare local Linear and
Cubic backgrounds, bounds and adjacent windows before abandoning a bound-pinned
width. A polynomial need not describe a whole scan containing a baseline step.
A centre at a search bound prompts the same investigation even with modest
chi-squared: inspect the full scan, widen or shift the window to include both
flanks, and compare seeds and local backgrounds before concluding no line is
resolved. The CLI prints BOUND-LIMITED CENTRE for this case. The summary
audit requires an explanation of a reported whole-range background limitation;
merely defining a local polynomial does not explain that limitation.
The skill
Reports retain the printed coordinates and ranges of onsets, extrema and plateaus explicitly in prose. For long scans the decisive points belong in the report and full tables remain in the named CLI products. Local resonance comparisons distinguish a resolved narrow component from broad curvature with an unconstrained width; they also explain why one whole-scan polynomial baseline was inadequate. A failed observable is kept separate from a precise parameter beside an unconstrained nuisance term. Final copy checks apply to all characters, including Markdown punctuation: any cleanup happens in the saved report before its final audit.
Reports separate an observation, a supported candidate mechanism, and the quantities that have not been measured. A missing microscopic model limits parameter extraction and site assignment; it need not prevent a qualitative explanation supported by the observed change and experimental context. That explanation belongs in the conclusion with its alternatives and limitations. Rejected fitted quantities cannot supply such evidence, while poor whole-fit quality does not automatically erase an independently supported pattern.
Every comparative sentence is checked against its two labelled fit rows, including the direction of a centre shift and width change. Separate features can move in opposite directions; a correct table does not correct reversed prose. Supported qualitative mechanisms remain distinct from unavailable microscopic fits: narrowing can be consistent with reorientation averaging hyperfine anisotropy without measuring a coupling or motion rate. File lists use complete plain paths, one per line, and are finished before the final audit so their last line is copied as exactly as the scientific results.
The packaged asymmetry-analysis skill tells an agent to work through
seven steps: survey the folder; decide alpha (and never guess it); reduce the
scan; confirm the geometry of every non-zero-field scan from the survey’s
measured precession and the reduced spectrum rather than the file’s stamp;
screen one run with the
wizard; fit the scan as a chained series; read the trend; then write the
summary. Alongside the steps, it carries the decision rules an analyst
applies — which model family the physics calls for versus what AICc ranks
highest, what every fitted amplitude physically means, what to do when many
runs are flagged — and a cost table so an agent screens one or two runs
rather than the whole scan.
The summary template has fixed headings — Experiment, Calibration, Model, Results, Excluded or flagged runs, What this suggests, Files — and one governing rule: every number in the summary must come from a command’s output. A temperature, field, frequency, rate, exponent, run number, alpha, χ² or count that no command printed does not go in; a textbook or literature value may be discussed if it is clearly attributed as such, never presented as a result of the session.
Anyone evaluating an agent against this skill — checking that it makes
sensible choices on real data — should start with the rubrics and runner
under tools/agent_eval/: tools/agent_eval/rubrics/<dataset>.md records
the expected findings for a dataset, and tools/agent_eval/run_eval.py
drives an agent against a copied dataset folder and reports the transcript
and work directory for scoring against the rubric.
The evaluation target is host-specific: use Sonnet through Claude Code and
gpt-6-luna through Codex. Record both the host and exact model with each
result so the two evaluation tracks remain comparable without being conflated.
The Codex runner’s image-review turn writes and audits the complete final
report after inspecting the attached plots. cost.json records
final_report_audited by comparing the reply with the last passed audit;
an audited earlier draft does not verify a rewritten final reply. The runner
preserves the final message’s whitespace without trimming or adding a newline,
and its audit comparison is exact. Passed audits likewise print the saved
report unchanged between their markers. Nominated review images are copied
into review-images/ outside the agent project before the second turn;
image-inputs.json records their snapshot paths and hashes. Later replots
cannot replace the pixels supplied for review.
Both turns explicitly request the workspace-write approval mode; the resume
invocation must not fall back to a read-only sandbox.
Limits and what is not there yet
No headless
.asympproject export — the workflow produces reduced data, recipes, series and plots in the work directory, not a project file the desktop application can reopen.No maximum-entropy transform;
fourieris an FFT.No general N-nucleus radical repolarisation model.
MuRepolarisationseeds and fits a sum of isotropic-muonium terms, one per resolvable half-rise; a radical whose repolarisation curve does not decompose that way (several coupled nuclei, an anisotropic or solid-state radical) needs a model this workflow does not yet have.No MCP server. The work directory is the mechanism that gives an agent state between separate command invocations in its place.
Warnings raised inside the fit wizard’s worker processes are not collapsed by
_collapse_repeated_warnings(which only replaceswarnings.showwarningin the parent process), so awizardrun can still print several identical multi-line warning blocks on stderr on platforms that spawn worker processes. They are benign noise from seeding trial models during the candidate search.
Wizard worker budgets
asymmetry wizard --workers N limits simultaneous fitting workers.
ASYMMETRY_WIZARD_WORKERS supplies its default when several independent
analyses share a host; an explicit flag overrides it. Positive values are
required. The default remains automatic when neither is set. BLAS/OpenMP
thread limits are separate: a pool limit alone does not bound numerical
library threads. screen_run(max_workers=N) exposes the same budget for
scripted analyses.
Temperature trend output identifies actual first/last scan members alongside reliable parameter endpoints. Inspect their reduced/fit plots even when their fits fail; the first valid middle point is not the coldest measured spectrum. Composition-axis summaries name the title/notes source, normalization and units of supplied values. TF broadening alone does not select a superconducting model: unknown samples retain an open physics scope and magnetic experiments need magnetic line-shift/splitting interpretations.
Sampling bandwidth in stored reductions
reduce --rebin merges counts before forming the asymmetry, composing with
any base binning. It honours the requested merge without spectral analysis or
a peak veto. The reduction summary reports precession as unmeasured; use an
explicit survey or spectral operation to measure it. Cached records retain
their recorded summaries.
Merging can attenuate a fast line or fold it into the displayed band. Check the
native-resolution spectrum and choose a width small enough for the frequencies
of interest. Deliberately averaging a known fast line to study slower relaxation
is permitted; record that choice. A shorter analysis window or --plot-tmax
can reduce fit cost or zoom without coarsening the stored observations.
Actual FFT and MaxEnt operations retain their uniform-sampling requirements.
Fit-recipe rebin uses independent curve-bin means, recorded as
rebin_operation: merge_curve_bins in the recipe.
Automatic timing API
source_is_pulsed(metadata) returns None for unknown source facts.
find_t0_for_run(histograms, metadata, pulsed=True/False) accepts an explicit
supported strategy. resolve_selected_timing applies that strategy to the
selected acquired channels and reports unresolved requirements without changing
raw histograms. Saved policy strategy text alone does not author this override.
See Time-zero search for fallback and provenance semantics.
Automatic-tail skips
--background tail_fit warns and continues when an optional estimate is
unusable. Both F/B groups and all contributing periods remain background-unsubtracted.
JSON output and stored reductions retain requested: tail_fit,
status: skipped, and the reason in correction_outcomes. A warm cache
preserves the same warning; it does not convert the request to none.
Integral scans retain per-point, per-period correction outcomes, including
accepted skips, in their saved payloads. Missing references and invalid authored
settings retain their errors. Grouped count fits retain a background preflight
without subtracting it from their joint-model inputs.
Fixed supplied TF calibration response
Use --calibration-pulse-separation US with alpha or with
--alpha-from to supply a fixed TF double-pulse separation. Omission means
Off; zero is the causal single-birth limit. CalibrationOptions uses
pulse_separation_us in scripts. Every envelope consumes the same supplied
source, observations, and count objective. Other calibration methods reject an
active TF pulse request. Saved workflow calibration records retain that source
intent; applying coefficients does not replace the target timing or ordinary
fit/Fourier response. See Alpha calibration for the centre approximation
and conditional errors.
Acquisition bytes and saved calculations
Fresh built-in acquisition reads capture complete-file SHA-256 facts with their counts. Supported reductions, reference results, and frozen calibration records retain the facts available to that calculation. Workdir hashing and acquisition capture share the same whole-file reader; workdir size/mtime cache policy remains separate from byte equality. Retained reference-cache counts keep their captured identity, even if stat hints fail to notice an edit. Explicit core verification reads the candidate afresh; see Input/output.
Project expected identities survive restoration and saving independently of
fresh observed identities. Historical unknowns stay unknown. A digest match
does not make an old computation revision current, establish independent counting
noise, or grant a new likelihood. Project reopening and explicit replacement use
the owner-aware application operation described below; the lower-level comparison
API remains read-only.
Inspect and replace project inputs
asymmetry project-sources session.asymp --json reads and verifies without
writing a project or work-directory log. Source rows include index, owner,
active, role, status, expected/observed digests, and ordered selection
facts. Status is matched, changed, missing, legacy_unknown, or
unreadable. Paths and private diagnostics are omitted from this report.
Exit 0 means the comparison completed, including changed or unavailable outcomes;
exit 1 indicates an invalid action or project, and exit 2 an internal error.
--candidate INDEX=PATH proposes an explicit candidate for one row; repeat it
for different rows. Relative saved locators resolve against the selected project’s
directory. A candidate is compared, never accepted merely from its name.
To accept a listed current input, use
asymmetry project-sources session.asymp --replace 0 --output accepted.asymp --json.
Repeat --replace for each selected current owner, including required dependent
requests. --replace and --output are required together. Historical rows and
unavailable candidates cannot be accepted. Saving is atomic with the existing
one-generation backup when replacing an output file. There is no interactive
approval loop or implicit model/calibration rerun. The action updates expectations;
GUI reopening or an explicit reduction supplies new observations through its normal
workflow. Old result and calibration expectations remain unchanged. See
Project files and Project persistence.