mctest: %Scan: prototype

[willend]

Free-form text area

Please describe what your PR is adding in terms of features or bugfixes:

mctest: %Scan: tests, per-point scan seeds in mcrun, and HTML plotting of scan directories

Summary

Adds a scan test mode to mctest. An instrument header can now hold a %Scan: line, which gives an mcrun parameter scan and one expected detector value per scan point:

* %Scan: mcrun SE_example.instr dBz=-0.0001,0.0001 -N41 -n1e5 Detector: detector_I={
*   86.04,101.892,108.731,...
*   85.406 }

The scan arguments go to mcrun unchanged, so every mcrun scan syntax works (a,b -N, a:delta:b, -L, -M, -N=a,b,c, …) and mctest has no scan parsing of its own.

The HTML plotting frontends could not plot mcrun scan directories, which mctest scan results need. This PR fixes that too.

Changes

mctest

• A %Scan: line becomes a test like %Example:: its own test number, output directory and JSON entry ("scan": true, with list-valued targetval/testval).
• The target values are a {}-enclosed, comma-separated list and may span several header lines.
• mcrun and *.instr tokens on %Example:/%Scan: lines are ignored.
• A scan uses its own -n if given, otherwise at most 1e5 per point.
• Scans run with --scan_split=auto unless MPI is used. The timeout scales with the number of points. mcdisplay runs at the first scan point.
• Values are read from the scan's mccode.dat, which works for both the McCode and NeXus formats. A scan passes when every point is within 20 % of its target.
• New --noscans option.

mcviewtest: one cell per scan (e.g. scan, 41/41 pts (41/41 pts OK)). Hovering shows each point's test value, target and percentage. The diff/coplot links now work for scan rows (see plotting below).

mcdoc: %Scan: lines appear like %Example: lines, labelled Scan: …, with the value list shortened to {N values}.

mcrun

• --scan_split=auto is an alias for the existing (undocumented) 0: the number of cores minus one.
• --scan_split is now overridden only by an explicit --mpi greater than 1, with a warning. Before, the default --mpi=1 silently disabled it.
• Per-point scan seeds: point i uses base + i*1024 in both the serial and the --scan_split scanner. Before, only the split scanner did this.
  • The base is --seed if given, otherwise the current time, which is logged so the run can be reproduced.
  • --seeds scans use the scanned seeds unchanged.

HTML plotting of mcrun scan directories (mcplot-html, mccoplot-html, mcplotdiff-html)

Scan curves loaded from mccode.dat had an empty filepath, and all of them had the file name mccode.dat. The HTML frontends build output file names from those two fields, so:

• mcplot-html wrote every curve to .html/_log.html in the current directory, and its parallel jobs raced on deleting that shared file (FileNotFoundError).
• mccoplot-html wrote every pane to coplot_mccode.html, so all panes showed the last detector.
• mcplotdiff-html crashed: scan curves have no values triplet, no (I, ERR) pair and no N column.

Fixes:

• mcplotloader: each scan curve gets its own filepath, <scandir>/<yvar> (e.g. scan/detector_I), so mcplot-html writes scan/detector_I.html.
• mcplot-html: the racy "delete if it exists" step before writing is gone. Opening the file for writing already truncates it.
• mcplotdiffloader:
  • New monitor_basename(): the base name of filepath, falling back to filename. It is used to key and match monitors and to name the diff .dat files and their mccode.sim entries. Ordinary monitors keep their old names (e.g. PSD.dat).
  • The diff and the .dat writer now handle scan curves: the % difference comes from the summed curves when there is no values triplet, an <name>_ERR column is derived, and N is written as 0 when there is no N column.
• mccoplot-html / mcplotdiff-html: page names, and the lookup of existing mcplot-html pages to link to, now use monitor_basename().

Instruments: SE_example gets a 41-point %Scan: test, with targets generated using -s 1000.

⚠️ Numerical behaviour change

Serial mcrun scans run with --seed now give different numbers than before. Each point gets its own seed instead of every point reusing the same one, which also removes the point-to-point correlation in the noise. Split scans are unchanged, and serial and split scans now give identical results for a given seed. Without --seed, scans were already non-reproducible, so nothing is lost there.

Testing (macOS arm64, clang, mccode-dev conda env, McStas only)

• mctest --instr SE_example: 41/41 points pass (about 4 s with --scan_split). Also passes with --nexus.
• With two target values deliberately corrupted, the test fails (39/41 points OK).
• --noscans skips the scan.
• mcviewtest renders one scan row with pass/fail colouring and per-point tooltips.
• Serial and split mcrun scans with -s 1000 give identical results. A --seeds=7,9 -N3 scan matches single runs at those seeds.
• The mcdoc header parser shows Scan: … {41 values}.
• Plotting, on an SE_example scan (-N41):
  • mcplot-html, mccoplot-html and mcplotdiff-html each produce one page per scan curve.
  • The diff output directory reopens in mcplot-html.
  • Diff/coplot output names for a single step directory are unchanged.
  • The matplotlib mcplot and mccoplot still work.

Not tested / known gaps

• Linux, Windows and macOS x86_64.
• McXtrace. The Python tools are shared, but no McXtrace instrument has a %Scan: line yet and mxtest/mxrun/mxplot weren't run.
• mctest with --mpi (scans then run serially through MPI).
• The pyqtgraph frontend on scan directories. Nothing in it was changed.
• The HTML pages in other browsers and at narrow widths.

---

Declaration of use of AI-tools

• Please add a checkmark here if you used AI-tools during the work for this contribution
• Furter, please describe how / where and for what the tools were used:

^ 🤖 Generated with Claude Code

---

Development OS / boundary conditions

Please describe what OS you developed and tested your additions on, and if any special dependencies are required:

---

PR Checklist for contributing to McStas/McXtrace

For a coherent and useful contribution to McStas/McXtrace, please fill in relevant parts of the checklist:

• My contribution contains something else

  • Explanation is added in free form text above or below the checklist

---

[willend]

Now adding %Scan: lines to instruments with non-executed Example: (without %) scans lines.

[willend]

@mads-bertelsen, @g5t, @farhi, @Lomholy won't request a full review from either of you (I know you are all busy with other stuff), but wanted you to know this is incoming.

A quick thumbs up / down is sufficient for now - and we can of course re-model details later.

[willend]

@Lomholy likes it. ;-) This makes me think "let's roll with it for a while". Merging.