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

reduce only produces asymmetry, not per-detector counts with an N₀ and relaxation term.

Multi-group / orientation-resolved analysis

The workflow reduces exactly one forward/backward detector pair — the file’s own, or one named with --pair — not several groups fit together.

Maximum-entropy spectra

fourier provides an FFT and peak table, not maximum entropy reconstruction.

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: integral-scan --period green-red builds it, though the packaged skill does not yet steer an agent to it.)

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:

  • --json emits a machine-readable payload on stdout instead of the human table; every payload carries "schema": 1 and "asymmetry_version". Omit it for the default human-readable table, which is usually easier to read directly.

  • --plot (on reduce, integral-scan, wizard, fit, fit-global, fit-series, trend and fourier) writes one or more headless PNGs into the work directory’s plots/ — see Plots.

  • --workdir overrides 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 main asymmetry command, before the subcommand) prints every warning as Python’s own multi-line traceback-style block. Without it, a repeated warning — the fit wizard’s AsymmetryScaleWarning from 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, and alpha) restricts the folder to one instrument’s files, matched case-insensitively against the file prefix — EMU selects EMU… and emu…, one instrument across eras. Needed whenever a folder holds two instruments whose run numbers collide; see Two instruments in one folder.

  • Exit codes: 0 on success, 1 on a user error (one line on stderr — a bad run number, a missing recipe), 2 on 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/BWD names the forward and backward groups by the file’s group names or ids — --pair Up/Down or --pair 3/4 for the transverse pair of a five-histogram PSI GPS file, whose default pair is Back/Forw. info lists each file’s groups and its default pair.

  • --deadtime from_file applies each file’s own per-detector deadtimes (default off, the GUI’s fresh-run default). Missing or incomplete file coefficients leave the whole deadtime operation unapplied and emit File deadtime correction not applied: a complete per-detector deadtime table is unavailable. Continuing uncorrected. The usable result records requested from_file and actual skipped in its correction outcomes, including cached work-directory results. A supplied complete zero table is an applied identity.

  • --background tail_fit fits the late half of selected good-data support on native bins and subtracts the flat rate. --background range:FIRST:LAST averages that exact inclusive zero-based acquisition interval, independently of facility labels. Without bounds, range uses 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-scan takes 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 BINS shifts every detector’s file t0 by a signed number of bins. --t-good-offset BINS is 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 green or --period N selects one period of a multi-period file; --period green-red reduces each period of a two-period run on its own and takes green − red.

  • --alpha X fixes the selected pair’s balance and --alpha-from RUN estimates it on a calibration run reduced with the same options, so alpha balances the spectra it is applied to (reduce and integral-scan; alpha measures 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:

prec

Meaning

larmor

A line at SNR ≥ 10 within 25 % of the Larmor frequency of the recorded field. The field is transverse, and geom reads TF* — the * marks a geometry the spectrum decided rather than the file.

other@<MHz>

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 geom falls back to the file.

none

No line above SNR 10. The applied field is not precessing the muon, so the file’s TF stamp is refuted and geom reads - (geometry_source "refuted"): the run is either a longitudinal measurement or a transverse one with no resolvable line, and the file’s claim is evidence for neither. Compare the scan response and context before choosing a physical geometry.

-

Not measured: no field is recorded, or its Larmor frequency is above the record’s Nyquist frequency. precession_note in the JSON says which.

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, and classify_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):

--scope

Physics looked for

auto (default), all

every class

zf-static-magnetism, tf-knight-precession

static magnetism

tf-superconductor

superconductivity and static magnetism

lf-dynamics

spin dynamics and static magnetism

fluoride-fmuf

F–μ–F and nuclear dipoles

muonium-radical

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-series chains along the scan. A value named in pinned (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 own fixed flag, 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

failed

The minimiser did not converge. The row is not a result.

large_rel_err

A free parameter’s σ/value is large — the data barely constrained it.

bound_pinned

A free parameter sat on a bound.

spurious_reseeded

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. reduce and fit plots 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 .asymp project 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; fourier is an FFT.

  • No general N-nucleus radical repolarisation model. MuRepolarisation seeds 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 replaces warnings.showwarning in the parent process), so a wizard run 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.