13. CPU — force
14. %include and instrument concatenation
%include "monitor_nd-lib" // C library, from within a %{ %} block
-%include "ILL_H16.instr" // whole instrument or component file
+%include "Mantid/ILL_H16_Mantid/ILL_H16_Mantid.instr" // whole instrument or component file
- Outside a
%{ %} C block, %include "file" reads another .instr/.comp file as
meta-language (component definitions, or — inside TRACE — whole instruments to
concatenate; see below). It's resolved at translation time by mcstas/mcxtrace, not by
the C compiler — don't confuse it with C's #include.
+- Where the file is looked for (both forms, first hit wins): the name as given,
+ relative to the current directory; then each
-I/SEARCH directory (§3); then the
+ installed resource directory itself; then its fixed top-level subdirectories
+ (samples, monitors, sources, optics, misc, obsolete, contrib, …,
+ share, examples). None of these is searched recursively. An instrument sitting
+ in examples/<Institute>/<Name>/ is not found by its bare file name — give its path
+ relative to one of those directories, e.g.
+ %include "Mantid/ILL_H16_Mantid/ILL_H16_Mantid.instr" (relative to examples), or add
+ its folder with -I/SEARCH.
- Inside a
%{ ... %} C code block, %include "name" instead pulls in a runtime C
library from the component search path (.h/.c pair, included once no matter how many
components ask for it) — e.g. %include "read_table-lib". The runtime library is
@@ -582,7 +591,8 @@ 14. %include and i
file is %include'd into another instrument (but present as normal when run standalone).
Real examples: templateTAS.instr (REMOVABLE COMPONENT Origin, REMOVABLE COMPONENT
Source), ILL_IN5_Mantid.instr; concatenation itself: ILL_H16_IN5_Mantid.instr
- (%include "ILL_H16_Mantid.instr" + %include "ILL_IN5_Mantid.instr").
+ (%include "Mantid/ILL_H16_Mantid/ILL_H16_Mantid.instr" +
+ %include "Mantid/ILL_IN5_Mantid/ILL_IN5_Mantid.instr").
15. SAVE / FINALLY / END (instrument level)
SAVE
diff --git a/docs/GRAMMAR/Instrument/INSTRUMENT_Grammar.md b/docs/GRAMMAR/Instrument/INSTRUMENT_Grammar.md
index f4f272dbd4..b34f53f566 100644
--- a/docs/GRAMMAR/Instrument/INSTRUMENT_Grammar.md
+++ b/docs/GRAMMAR/Instrument/INSTRUMENT_Grammar.md
@@ -399,13 +399,22 @@ CPU COMPONENT slow_bit = SomeLib(...) AT (...) ...
```c
%include "monitor_nd-lib" // C library, from within a %{ %} block
-%include "ILL_H16.instr" // whole instrument or component file
+%include "Mantid/ILL_H16_Mantid/ILL_H16_Mantid.instr" // whole instrument or component file
```
* Outside a `%{ %}` C block, `%include "file"` reads another `.instr`/`.comp` file as
meta-language (component definitions, or — inside `TRACE` — whole instruments to
concatenate; see below). It's resolved at translation time by `mcstas`/`mcxtrace`, not by
the C compiler — don't confuse it with C's `#include`.
+* **Where the file is looked for** (both forms, first hit wins): the name as given,
+ relative to the current directory; then each `-I`/`SEARCH` directory (§3); then the
+ installed resource directory itself; then its fixed top-level subdirectories
+ (`samples`, `monitors`, `sources`, `optics`, `misc`, `obsolete`, `contrib`, …,
+ `share`, `examples`). **None of these is searched recursively.** An instrument sitting
+ in `examples///` is *not* found by its bare file name — give its path
+ relative to one of those directories, e.g.
+ `%include "Mantid/ILL_H16_Mantid/ILL_H16_Mantid.instr"` (relative to `examples`), or add
+ its folder with `-I`/`SEARCH`.
* Inside a `%{ ... %}` C code block, `%include "name"` instead pulls in a runtime C
library from the component search path (`.h`/`.c` pair, included once no matter how many
components ask for it) — e.g. `%include "read_table-lib"`. The runtime library is
@@ -425,7 +434,8 @@ CPU COMPONENT slow_bit = SomeLib(...) AT (...) ...
file is `%include`'d into another instrument (but present as normal when run standalone).
Real examples: `templateTAS.instr` (`REMOVABLE COMPONENT Origin`, `REMOVABLE COMPONENT
Source`), `ILL_IN5_Mantid.instr`; concatenation itself: `ILL_H16_IN5_Mantid.instr`
- (`%include "ILL_H16_Mantid.instr"` + `%include "ILL_IN5_Mantid.instr"`).
+ (`%include "Mantid/ILL_H16_Mantid/ILL_H16_Mantid.instr"` +
+ `%include "Mantid/ILL_IN5_Mantid/ILL_IN5_Mantid.instr"`).
## 15. `SAVE` / `FINALLY` / `END` (instrument level)
diff --git a/docs/manuals/mcstas/contrib/Conics_EH.tex b/docs/manuals/mcstas/contrib/Conics_EH.tex
index ad3bb262be..94c1a14090 100644
--- a/docs/manuals/mcstas/contrib/Conics_EH.tex
+++ b/docs/manuals/mcstas/contrib/Conics_EH.tex
@@ -44,6 +44,8 @@ \subsection*{Input parameters}
W & \AA{}$^{-1}$ & Width of supermirror cut-off & 0.003 \\
alpha & \AA{} & Slope of reflectivity for reflectivity curve approximation & 6.07 \\
transmit & 1 & Fraction of statistics to assign to transmitted beam - NOT YET IMPLEMENTED & 0 \\
+sigma\_m & rad & RMS meridional slope (figure) error of the mirror surfaces; for grazing angles below 10*sigma\_m the waviness model of Hansen et al., arXiv:1612.03763 is used & 1e-6 \\
+sigma\_s & rad & RMS sagittal slope (figure) error of the mirror surfaces & 250e-6 \\
\bottomrule
\end{longtable}
diff --git a/docs/manuals/mcstas/contrib/Conics_HE.tex b/docs/manuals/mcstas/contrib/Conics_HE.tex
index 83f938a3c8..838b440f42 100644
--- a/docs/manuals/mcstas/contrib/Conics_HE.tex
+++ b/docs/manuals/mcstas/contrib/Conics_HE.tex
@@ -44,6 +44,8 @@ \subsection*{Input parameters}
W & \AA{}$^{-1}$ & Width of supermirror cut-off & 0.003 \\
alpha & \AA{} & Slope of reflectivity for reflectivity curve approximation & 6.07 \\
transmit & 1 & Fraction of statistics to assign to transmitted beam - NOT YET IMPLEMENTED & 0 \\
+sigma\_m & rad & RMS meridional slope (figure) error of the mirror surfaces; for grazing angles below 10*sigma\_m the waviness model of Hansen et al., arXiv:1612.03763 is used & 1e-6 \\
+sigma\_s & rad & RMS sagittal slope (figure) error of the mirror surfaces & 250e-6 \\
\bottomrule
\end{longtable}
diff --git a/docs/manuals/mcstas/contrib/Conics_PH.tex b/docs/manuals/mcstas/contrib/Conics_PH.tex
index b9a4dea014..ac17bf7935 100644
--- a/docs/manuals/mcstas/contrib/Conics_PH.tex
+++ b/docs/manuals/mcstas/contrib/Conics_PH.tex
@@ -43,6 +43,8 @@ \subsection*{Input parameters}
W & \AA{}$^{-1}$ & Width of supermirror cut-off & 0.003 \\
alpha & \AA{} & Slope of reflectivity for reflectivity curve approximation & 6.07 \\
transmit & 1 & Fraction of statistics to assign to transmitted beam - NOT YET IMPLEMENTED & 0 \\
+sigma\_m & rad & RMS meridional slope (figure) error of the mirror surfaces; for grazing angles below 10*sigma\_m the waviness model of Hansen et al., arXiv:1612.03763 is used & 1e-6 \\
+sigma\_s & rad & RMS sagittal slope (figure) error of the mirror surfaces & 250e-6 \\
\bottomrule
\end{longtable}
diff --git a/docs/manuals/mcstas/contrib/Conics_PP.tex b/docs/manuals/mcstas/contrib/Conics_PP.tex
index 51610f9832..7f8432228a 100644
--- a/docs/manuals/mcstas/contrib/Conics_PP.tex
+++ b/docs/manuals/mcstas/contrib/Conics_PP.tex
@@ -44,6 +44,8 @@ \subsection*{Input parameters}
W & \AA{}$^{-1}$ & Width of supermirror cut-off & 0.003 \\
alpha & \AA{} & Slope of reflectivity for reflectivity curve approximation & 6.07 \\
transmit & 1 & Fraction of statistics to assign to transmitted beam - NOT YET IMPLEMENTED & 0 \\
+sigma\_m & rad & RMS meridional slope (figure) error of the mirror surfaces; for grazing angles below 10*sigma\_m the waviness model of Hansen et al., arXiv:1612.03763 is used & 1e-6 \\
+sigma\_s & rad & RMS sagittal slope (figure) error of the mirror surfaces & 250e-6 \\
\bottomrule
\end{longtable}
diff --git a/docs/manuals/mcstas/contrib/FlatEllipse_finite_mirror.tex b/docs/manuals/mcstas/contrib/FlatEllipse_finite_mirror.tex
index 726237f644..b085b42212 100644
--- a/docs/manuals/mcstas/contrib/FlatEllipse_finite_mirror.tex
+++ b/docs/manuals/mcstas/contrib/FlatEllipse_finite_mirror.tex
@@ -23,7 +23,7 @@ \subsection*{Input parameters}
\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
\midrule
\endhead
-sourceDist & m & Distance used for calculating the spacing of the mirrors & 0 \\
+sourceDist & m & Distance used for calculating the spacing of the mirrors, 0: use LStart & 0 \\
LStart & m & Left focal point & 0.6 \\
LEnd & m & Right focal point & 0.6 \\
lStart & m & z-Value of the mirror start & 0.0 \\
diff --git a/docs/manuals/mcstas/contrib/Mirror_conic.tex b/docs/manuals/mcstas/contrib/Mirror_conic.tex
new file mode 100644
index 0000000000..7bd2cceee0
--- /dev/null
+++ b/docs/manuals/mcstas/contrib/Mirror_conic.tex
@@ -0,0 +1,45 @@
+\section{The \texttt{Mirror\_conic} McStas Component}
+Single flat mirror plate using the conic.h reflection routines (test component)
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} Peter Willendrup
+ \item \textbf{Origin:} DTU
+ \item \textbf{Date:} October 2026
+\end{itemize}
+
+\subsection*{Description}
+Test component for the reflection routines in conic.h (ConicTracer), which are used by e.g. Conics\_*, FlatEllipse\_finite\_mirror and NMO. It models a single flat mirror so that the results can be compared directly with Mirror.comp.
+
+The mirror lies in the local y-z plane at x=0, extending from z=0 to z=length and from y=-yheight/2 to y=yheight/2. Only neutrons arriving from the x\textless{}0 side (vx\textgreater{}0) interact; everything else passes unaffected. Each neutron interacts at most once.
+
+conic=0: the mirror is a conic.h FlatSurf and is handled by reflectNeutronFlat(), which reflects with probability R and otherwise transmits the neutron unaffected. Compare with Mirror(transmit=1). conic=1: the mirror is a conic.h ConicSurf cylinder of (very large) radius 1 km, handled by reflectNeutronConic(), which always reflects and weights by R. Compare with Mirror(transmit=0). A Gaussian figure (slope) error can be applied via sigma\_m and sigma\_s; the default is 0 here, whereas the Conics\_* components default to the conic.h values of 1 and 250 urad.
+
+Example: Mirror\_conic(length=1, yheight=0.1, m=2)
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+length & m & Length of the mirror along z & 1 \\
+yheight & m & Height of the mirror along y & 0.1 \\
+R0 & 1 & Low-angle reflectivity & 0.99 \\
+Qc & \AA{}$^{-1}$ & Critical scattering vector & 0.021 \\
+alpha & \AA{} & Slope of reflectivity & 6.07 \\
+m & 1 & m-value of material & 2 \\
+W & \AA{}$^{-1}$ & Width of supermirror cut-off & 0.003 \\
+conic & 1 & 0: use FlatSurf/reflectNeutronFlat(), 1: use ConicSurf/reflectNeutronConic() & 0 \\
+sigma\_m & rad & RMS meridional slope (figure) error, conic=1 only; for grazing angles below 10*sigma\_m the waviness model of Hansen et al., arXiv:1612.03763 is used & 0 \\
+sigma\_s & rad & RMS sagittal slope (figure) error, conic=1 only & 0 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Mirror\_conic.comp}.
+\end{itemize}
+\IfFileExists{contrib/Mirror_conic_static.tex}{\input{contrib/Mirror_conic_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcstas/contrib/NMO.tex b/docs/manuals/mcstas/contrib/NMO.tex
index cf6d6ba619..9510cca292 100644
--- a/docs/manuals/mcstas/contrib/NMO.tex
+++ b/docs/manuals/mcstas/contrib/NMO.tex
@@ -25,7 +25,7 @@ \subsection*{Input parameters}
\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
\midrule
\endhead
-sourceDist & m & Distance used for calculating the spacing of the mirrors & 0 \\
+sourceDist & m & Distance used for calculating the spacing of the mirrors, 0: use LStart & 0 \\
LStart & m & Left focal point & 0.6 \\
LEnd & m & Right focal point & 0.6 \\
lStart & m & z-Value of the mirror start & 0.0 \\
diff --git a/docs/manuals/mcstas/contrib/contrib.tex b/docs/manuals/mcstas/contrib/contrib.tex
index 1394a97009..d6dac85436 100644
--- a/docs/manuals/mcstas/contrib/contrib.tex
+++ b/docs/manuals/mcstas/contrib/contrib.tex
@@ -42,6 +42,7 @@ \section{Contributed guides and benders}
\input{contrib/Conics_PH}
\input{contrib/Conics_PP}
\input{contrib/FlatEllipse_finite_mirror}
+\input{contrib/Mirror_conic}
\input{contrib/Commodus_I3}
\section{Contributed choppers and collimators}
diff --git a/docs/manuals/mcstas/kernel.tex b/docs/manuals/mcstas/kernel.tex
index 32e2e12448..3ccc16ad04 100644
--- a/docs/manuals/mcstas/kernel.tex
+++ b/docs/manuals/mcstas/kernel.tex
@@ -1929,9 +1929,9 @@ \subsection{The format of the comments in the library source code}
\item
\indexDOCSEC{\%EXAMPLE}{\%EX[AMPLE]}{textbf}\sloppy
\index{Example!McDoc section|textbf}
- The \verb+%EXAMPLE:+
+ The \verb+%EXAMPLE:+ (or \verb+%TEST:+)
lines in instrument headers indicate an example parameter set or command that may be
- run to test the instrument. A following \texttt{Detector: $<$name$>$\_I=$<$value$>$}
+ run to test the instrument. A \verb+%TESTSCAN:+ (older name \verb+%SCAN:+) line defines a parameter scan test with one expected value per scan point. A following \texttt{Detector: $<$name$>$\_I=$<$value$>$}
indicates what value should be obtained for a given monitor. More than one example
line may be specified in instruments.
\item
diff --git a/docs/manuals/mcstas/misc/Annulus.tex b/docs/manuals/mcstas/misc/Annulus.tex
index a0d76fa771..56adb8852f 100644
--- a/docs/manuals/mcstas/misc/Annulus.tex
+++ b/docs/manuals/mcstas/misc/Annulus.tex
@@ -1,5 +1,5 @@
\section{The \texttt{Annulus} McStas Component}
-A geometric shape without effect on neutron, for instrument display purpose.
+A flat annulus shape without effect on neutron, for instrument display purpose.
\subsection*{Identification}
\begin{itemize}
@@ -31,4 +31,4 @@ \subsection*{Links}
\item Component source code found in file \texttt{Annulus.comp}.
\item mcdoc page of \htmladdnormallink{Shape}{Shape.html}} component
\end{itemize}
-\IfFileExists{misc/Annulus_static.tex}{\input{misc/Annulus_static.tex}}{}
+\IfFileExists{misc/Annulus_static.tex}{\input{misc/Annulus_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcstas/misc/Shape.tex b/docs/manuals/mcstas/misc/Shape.tex
index 668e53c2be..b556fbe366 100644
--- a/docs/manuals/mcstas/misc/Shape.tex
+++ b/docs/manuals/mcstas/misc/Shape.tex
@@ -25,7 +25,6 @@ \subsection*{Description}
\begin{verbatim}
sphere: radius (yheight=0 thickness=0)
-hollow sphere: radius and thickness>0 (yheight=0)
any shape: geometry=OFF file
\end{verbatim}
@@ -46,7 +45,7 @@ \subsection*{Input parameters}
xwidth & m & Horiz. dimension of sample (bounding box if off file), as a width & 0 \\
yheight & m & Vert. dimension of sample (bounding box if off file), as a height. A sphere shape is used when 0 and radius is set & 0 \\
zdepth & m & Depth of sample (bounding box if off file) & 0 \\
-thickness & m & Thickness of hollow sample & 0 \\
+thickness & m & Thickness of hollow box or cylinder (spheres are drawn solid) & 0 \\
nx & 1 & x-comp of orientation vector & 0 \\
ny & 1 & y-comp of orientation vector & 1 \\
nz & 1 & z-comp of orientation vector & 0 \\
diff --git a/docs/manuals/mcstas/misc/Text.tex b/docs/manuals/mcstas/misc/Text.tex
new file mode 100644
index 0000000000..39057b296e
--- /dev/null
+++ b/docs/manuals/mcstas/misc/Text.tex
@@ -0,0 +1,37 @@
+\section{The \texttt{Text} McStas Component}
+Release: McStas 3.9
+
+Draw a text
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} Emmanuel Farhi
+ \item \textbf{Origin:} SOLEIL
+ \item \textbf{Date:} Oct 10, 2026
+\end{itemize}
+
+\subsection*{Description}
+A text with given size and orientation. The text is drawn in upper letters.
+
+Example: Text(text="SOLEIL", size=0.5, plane="XY")
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+\textbf{text} & str & Text to draw. & \\
+size & m & Size of text. & 0.5 \\
+plane & str & "XY","YZ",or "XZ" & "XY" \\
+pen\_thickness & 1 & Stroke diameter as fraction of text size. 0 draws thin lines, \textgreater{}0 draws each stroke as a cylinder with spherical joints. & 0.1 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Text.comp}.
+\end{itemize}
+\IfFileExists{misc/Text_static.tex}{\input{misc/Text_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcstas/misc/misc.tex b/docs/manuals/mcstas/misc/misc.tex
index 3081d2aa23..c37caa792f 100644
--- a/docs/manuals/mcstas/misc/misc.tex
+++ b/docs/manuals/mcstas/misc/misc.tex
@@ -59,6 +59,11 @@ \section{KDSource: kernel-density-estimated source from particle lists}
\label{s:kdsource}
\input{misc/KDSource}
+\newpage
+\section{Text: drawing a text label in mcdisplay}
+\label{s:text-comp}
+\input{misc/Text}
+
\newpage
\section{Progress\_bar: Simulation progress and automatic saving}
\component{Progress\_bar}{System}{percent, flag\_save, profile}{}{}
diff --git a/docs/manuals/mcstas/monitors/Monitor_nD.tex b/docs/manuals/mcstas/monitors/Monitor_nD.tex
index 73b545b6a8..30ff725250 100644
--- a/docs/manuals/mcstas/monitors/Monitor_nD.tex
+++ b/docs/manuals/mcstas/monitors/Monitor_nD.tex
@@ -73,7 +73,7 @@ \subsection*{Description}
\end{verbatim}
\begin{verbatim}
-p intensity flux [n/s or n/cm^2/s]
+p i [n/s or n/cm^2/s] ('intensity', 'flux': name the default signal, add no variable, e.g. 'intensity per cm2 x y' is 2D)
ncounts n neutron [1] neutron ID, i.e current event index
pixel id [1] pixelID in histogram made of preceeding vars, e.g. 'theta y'. To set an offset PixelID use the 'min=value' keyword. Sets event mode.
\end{verbatim}
diff --git a/docs/manuals/mcstas/monitors/Monitor_nD_noacc.tex b/docs/manuals/mcstas/monitors/Monitor_nD_noacc.tex
index fba64e5a22..c340f57bae 100644
--- a/docs/manuals/mcstas/monitors/Monitor_nD_noacc.tex
+++ b/docs/manuals/mcstas/monitors/Monitor_nD_noacc.tex
@@ -73,7 +73,7 @@ \subsection*{Description}
\end{verbatim}
\begin{verbatim}
-p intensity flux [n/s or n/cm^2/s]
+p i [n/s or n/cm^2/s] ('intensity', 'flux': name the default signal, add no variable, e.g. 'intensity per cm2 x y' is 2D)
ncounts n neutron [1] neutron ID, i.e current event index
pixel id [1] pixelID in histogram made of preceeding vars, e.g. 'theta y'. To set an offset PixelID use the 'min=value' keyword. Sets event mode.
\end{verbatim}
diff --git a/docs/manuals/mcstas/optics/FermiChopper.tex b/docs/manuals/mcstas/optics/FermiChopper.tex
index 357cd3cae3..d196015da6 100644
--- a/docs/manuals/mcstas/optics/FermiChopper.tex
+++ b/docs/manuals/mcstas/optics/FermiChopper.tex
@@ -9,7 +9,7 @@ \subsection*{Identification}
\end{itemize}
\subsection*{Description}
-Models a fermi chopper with optional supermirror coated blades supermirror facilities may be disabled by setting m = 0, R0=0 Slit packages are straight. Chopper slits are separated by an infinitely thin absorbing material. The effective transmission (resulting from fraction of the transparent material and its transmission) may be specified. The chopper slit package width may be specified through the total width 'xwidth' of the full package or the width 'w' of each single slit. The other parameter is calculated by: xwidth = nslit*w. The slit package may be made curved and use super-mirror coating.
+Models a fermi chopper with optional supermirror coated blades supermirror facilities may be disabled by setting m = 0, R0=0 Slit packages are straight. Chopper slits are separated by an infinitely thin absorbing material. The effective transmission (resulting from fraction of the transparent material and its transmission) may be specified. The chopper slit package width may be specified through the total width 'xwidth' of the full package or the width 'w' of each single slit. The other parameter is calculated by: xwidth = nslit*w. The slit package may be made curved and use super-mirror coating. Neutrons that miss the chopper cylinder are transmitted unchanged, so a realistic set-up needs shielding or a beam-defining slit around it; a monitor downstream that is wider than the chopper also counts the unchopped beam.
Example:
@@ -39,7 +39,7 @@ \subsection*{Input parameters}
alpha & \AA{} & slope of reflectivity & 2.33 \\
m & 1 & m-value of material. Zero means completely absorbing. & 0.0 \\
W & \AA{}$^{-1}$ & width of supermirror cut-off & 2e-3 \\
-length & m & channel length of the Fermi chopper & 0.012 \\
+length & m & channel length of the Fermi chopper. The default suits the fine 200-slit package of the Example; set it for any other package (the curved packages in ISIS\_MERLIN use about 0.1 m). & 0.012 \\
eff & 1 & efficiency = transmission x fraction of transparent material & 0.95 \\
zero\_time & 1 & set time to zero: 0=no, 1=once per half cycle, 2=auto adjust phase & 0 \\
xwidth & m & optional total width of slit package & 0 \\
diff --git a/docs/manuals/mcstas/preamble_common.tex.in b/docs/manuals/mcstas/preamble_common.tex.in
index 529aa70034..b3cbf2e243 100644
--- a/docs/manuals/mcstas/preamble_common.tex.in
+++ b/docs/manuals/mcstas/preamble_common.tex.in
@@ -17,7 +17,7 @@
\newcommand{\MCS}{McStas\xspace}
\newcommand{\mcs}{\texttt{mcstas}\xspace}
\newcommand{\version}{@MCCODE_VERSION@\xspace}
-\newcommand{\reldate}{September, 2026}
+\newcommand{\reldate}{October, 2026}
% Unused:
% The next rawfonts package one is used in the ``datablad''.
diff --git a/docs/manuals/mcstas/running.tex b/docs/manuals/mcstas/running.tex
index 3b62bea766..d958ab37ff 100644
--- a/docs/manuals/mcstas/running.tex
+++ b/docs/manuals/mcstas/running.tex
@@ -273,7 +273,7 @@ \subsubsection*{Alternative code generator: \texttt{mcstas-pygen}}
\verb+-o FILE+ (output file) it accepts \verb+--instrument-name=NAME+ (name of
the generated McStasScript instrument; by default the instrument name followed
by \texttt{\_generated}), \verb+--no-tests+ (do not translate
-\texttt{\%Example} lines into McStasScript tests), \verb+--lint+ (generate a
+\texttt{\%Test} (or \texttt{\%Example}) lines into McStasScript tests), \verb+--lint+ (generate a
script for McStasScript-style diagnostic linting), \verb+--verbose+ and the
version options described above. The C-generator-only options (\verb+-I+,
\verb+-t+, \verb+-p+, \verb+--no-main+, \verb+--no-runtime+) are rejected.
@@ -1200,7 +1200,9 @@ \subsection{Running simulations on the commandline (mcrun)}
A parameter may also be given as \texttt{\textit{min}:\textit{delta}:\textit{max}},
in which case the point count follows from the requested step size and the
parameter may be freely mixed with explicit lists. The option
- \texttt{--seeds} scans over a range of random seeds (each non-zero).
+ \texttt{--seeds} scans over a range of random seeds (each non-zero). In a scan with
+ \texttt{--seed}, point $i$ uses the seed $\mathrm{SEED}+1024\,i$ (without \texttt{--seed} the base seed is taken from the
+ current time and logged).
\item With \texttt{--autoplot}, \verb+mcrun+ opens a plotter on the generated
data set when done (the back-end is chosen with \texttt{--autoplotter}, and
\texttt{--invcanvas} requests an inverted canvas). With
@@ -1340,15 +1342,26 @@ \subsection{Graphical display of simulations (mcdisplay)}
save a file instead of opening a window), and the number of traced rays is
capped at 100.
\item \verb+mcdisplay-webgl+ and \verb+mcdisplay-webgl-classic+: browser-based
- WebGL views (the former uses a small NodeJS-backed server for larger
- instruments/particle counts; its first use performs a one-time
- \texttt{npm}/\texttt{vite} module installation, which needs internet access).
- In addition to the options listed below they accept \verb+-t+/\verb+--trace N+
- (visualisation mode, default 2 resp.\ 1), \verb+-d+/\verb+--dirname DIR+,
- \verb+--first COMP+ and \verb+--last COMP+ (the first and last component of
- the zoomed range), and \verb+--nobrowse+ (do not
- open a browser); \verb+mcdisplay-webgl+ also has \verb+--timeout SEC+ (the
- shutdown time of its development server, default 300~s).
+ WebGL views. The former ships as a prebuilt web application served by a small
+ local web server (only if its \texttt{dist/} folder is missing does the first
+ run perform a one-time \texttt{npm install \&\& npm run build}, which needs
+ internet access). Both accept \verb+-t+/\verb+--trace N+ (visualisation mode,
+ default 2: boxes, cylinders, OFF geometry etc.\ are drawn as 3D shapes; 1
+ selects the legacy line approximations), \verb+-d+/\verb+--dirname DIR+,
+ \verb+--inspect COMP+ (show only rays reaching component \texttt{COMP}) and
+ \verb+--nobrowse+ (do not open a browser). \verb+mcdisplay-webgl+ also has
+ \verb+--timeout SEC+ (the shutdown time of its local viewer web server,
+ default 300~s), while \verb+mcdisplay-webgl-classic+ additionally accepts
+ \verb+--first COMP+, \verb+--last COMP+ (the first and last component of the
+ zoomed range) and \verb+--invcanvas+.
+\item \verb+mcdisplay-plopp+: draws the instrument and the traced rays with
+ the \texttt{plopp}/\texttt{scipp} Python packages (install e.g.\ with
+ \texttt{conda install -c conda-forge plopp ipympl jupyterlab}). By default it
+ opens an interactive 3D view in JupyterLab; with \verb+-o FILE+ it instead
+ writes a static \texttt{png}, \texttt{pdf} or \texttt{svg} with 2D
+ projections. Accepts \verb+-n N+ (number of rays, default 100), \verb+-y+
+ (forwarded to \verb+mcrun+: use defaults for unset parameters) and the
+ instrument parameters as \texttt{name=value}.
\item \verb+mcdisplay-cad+: exports the instrument geometry to a CAD file and
requires the \texttt{cadquery} Python package. The format is selected with
\verb+-f+/\verb+--format+: \texttt{step} (default), \texttt{stl},
@@ -1419,7 +1432,7 @@ \subsection{Plotting the results of a simulation (mcplot)}
As with \texttt{mcdisplay} (section~\ref{s:mcdisplay}), the drawing back-end
may be selected by invoking the dedicated front-end directly:
-\verb+mcplot-pyqtgraph+ (the default), \verb+mcplot-matplotlib+, or
+\verb+mcplot-pyqtgraph+ (the default), \verb+mcplot-matplotlib+, \verb+mcplot-plopp+ (plopp/scipp based, see below), or
\verb+mcplot-html+ (renders an interactive, self-contained web page using
D3.js, see section~\ref{s:run-format}), or by setting the
\verb+MCSTAS_FORMAT+ environment variable.
@@ -1443,6 +1456,14 @@ \subsection{Plotting the results of a simulation (mcplot)}
monitor with \texttt{-png}, \texttt{-jpg}, \texttt{-fig}, \texttt{-eps} or
\texttt{-pdf}.
+\verb+mcplot-plopp+ opens the monitors of a simulation directory, \texttt{mccode.sim}, a single
+monitor file or a NeXus \texttt{mccode.h5} file in an interactive JupyterLab view built on
+\texttt{plopp}/\texttt{scipp} (install with e.g.\ \texttt{conda install -c conda-forge plopp
+ipympl jupyterlab}). With \verb+-o FILE+ it writes a static \texttt{png}, \texttt{pdf} or
+\texttt{svg} instead, \verb+--log+ selects a logarithmic intensity scale, and
+\verb+--source+/\verb+--sample+ name the source and sample components when plotting
+Monitor\_nD event data from NeXus files through McStasToX.
+
All plotters read the plain-text \MCS/McCode data format (section~\ref{s:analyze});
NeXus files are not currently read back by the plotters.
@@ -1560,7 +1581,8 @@ \subsection{Creating and viewing the library, component/instrument help and
\indexEV{BROWSER}
(e.g. firefox, chromium, \ldots). Alternatively, if a search term or a
\textit{file.comp}/\textit{file.instr} path is given, \verb+mcdoc+ will
-search within the library and open documentation for all matching entries.
+search within the library and open documentation for all matching entries. The search results are written to a
+separate page, \texttt{mcdoc\_search.html}, next to the main library page (or in the temporary directory if that is read-only), so the main page is left untouched. Mathematics in component documentation is rendered locally with the MathJax copy installed with the documentation.
Additional options include \verb+--install+/\verb+-i+ (regenerate the local
installation-wide index), \verb+--dir=DIR+/\verb+-d+ (add search results from
@@ -1601,7 +1623,7 @@ \subsection{Self-testing the installation (mctest, mcviewtest)}
\MCS ships with a Python self-test/benchmark harness, replacing the earlier
\verb+mcrun --test+ command. \verb+mctest+ compiles and runs a selection (or
all) of the example instruments found under the current installation(s), and
-stores each run's results (including any test-defined \texttt{\%Example}
+stores each run's results (including any test-defined \texttt{\%Test}
reference values) in a timestamped output folder. Each test compiles the
instrument, displays it with a single particle, runs it, and compares the
result with the target value recorded in the instrument header. Useful options
@@ -1614,13 +1636,33 @@ \subsection{Self-testing the installation (mctest, mcviewtest)}
any of the given components), \verb+--local=DIR+ (test instruments from
\texttt{DIR} instead of the installation), \verb+--limit=N+ (test only the first
N instruments per version), \verb+--skipnontest+ (skip instruments without an
-\texttt{\%Example} line), \verb+--strict+ (fail instruments without
-\texttt{\%Example} line(s) immediately) and \verb+--permissive+ (exit with
+\texttt{\%Test}/\texttt{\%TestScan} line), \verb+--strict+ (fail instruments without
+\texttt{\%Test}/\texttt{\%TestScan} line(s) immediately) and \verb+--permissive+ (exit with
status 0 even if tests fail), \verb+--testdir=DIR+ and \verb+--suffix=SUFFIX+
(where the results are written), \verb+--compilemax+, \verb+--runmax+ and
\verb+--displaymax+ (time limits in seconds) and \verb+--noplots+ (do not
generate the overview plots); run \verb+mctest --help+ for the full list.
+A test is defined in the instrument header by a \texttt{\%Test:} line (older name
+\texttt{\%Example:}), giving instrument parameters and the expected monitor value,
+\textit{e.g.}\ \texttt{\%Test: lambda=2.36 Detector: He3H\_I=9.84026e-10}. A
+\texttt{\%TestScan:} line (older name \texttt{\%Scan:}) defines a parameter scan
+using the \verb+mcrun+ scan syntax, followed by a \texttt{\{\}}-enclosed list with one
+target value per scan point (it may span several header lines), \textit{e.g.}\
+\texttt{\%TestScan: dBz=-0.0001,0.0001 -N41 -n1e5 Detector: detector\_I=\{\ldots\}}.
+A \texttt{\%Test:} always runs at the global \verb+--ncount+ (scaled by
+\verb+--statfactor+); a scan uses its own \texttt{-n} if given, otherwise at most
+$10^5$ per point, and runs its points in parallel (\verb+--scan_split=auto+) unless
+MPI is used. By default a value (every point of a scan) passes when it is within
+20\,\% of its target. With \verb+--nsigma N+ or \verb+--pvalue P+ it is instead
+accepted within the statistical tolerance of the combined error bars, using the
+error bar of the target when the test line gives it
+(\textit{e.g.}\ \texttt{NAME\_I=2.00752e+08 NAME\_ERR=2.28872e+06}).
+\verb+--statfactor F+ scales the particle count of every test (\textit{e.g.}\ 0.01 for
+quick runs, 100 for reference-quality ones) and \verb+--noscans+ skips the
+\texttt{\%TestScan} tests. The statistics are described in more detail in
+\texttt{tools/Python/mctest-statistics.md}.
+
\verb+mcviewtest+ then generates an HTML report of one or more \verb+mctest+
runs found in a given folder (the current directory by default). When more
than one run is present (e.g. a reference run and a run on a different
@@ -1631,7 +1673,7 @@ \subsection{Self-testing the installation (mctest, mcviewtest)}
reference's, adding a \texttt{DIFF~[vs~ref]} link next to each such row in the
report. These comparisons are cached on disk and generated in parallel
(\verb+--diffworkers+, each limited to \verb+--diffmax+ seconds), so
-re-running \verb+mcviewtest+ is fast; use \verb+--nodiff+ to skip generating
+re-running \verb+mcviewtest+ is fast (each test, and each scan, is one row of the report, coloured pass/fail by the rule \verb+mctest+ used for that result set; hovering a scan cell lists every point's value, target and percentage); use \verb+--nodiff+ to skip generating
them entirely, or \verb+--diff-errors-only+ to only diff rows that already show
a discrepancy (by default every valid row is diffed). \verb+--nobrowse+ keeps
the finished report from being opened in a browser.
@@ -1766,7 +1808,7 @@ \section{Using MPI for parallel computing}
clusters (see section \ref{s:mpi}).
\item \texttt{mcrun}'s built-in scan-splitting (\verb+--scan_split=N+, see
Table~\ref{f:mcrunoptions}) distributes the individual steps of a parameter
- scan across \texttt{N} local CPU cores/threads, without requiring MPI. This
+ scan across \texttt{N} local CPU cores/threads (\texttt{auto}, or 0, uses the number of cores minus one), without requiring MPI. It is ignored, with a warning, when an explicit multi-process \verb+--mpi+ is given. This
is a lightweight alternative on a single multi-core machine.
\end{itemize}
diff --git a/docs/manuals/mcstas/samples/PowderN.tex b/docs/manuals/mcstas/samples/PowderN.tex
index 8b072cab6b..2ce64208b1 100644
--- a/docs/manuals/mcstas/samples/PowderN.tex
+++ b/docs/manuals/mcstas/samples/PowderN.tex
@@ -25,7 +25,7 @@ \subsection*{Description}
cylinder: radius x yheight (thickness=0)
\end{verbatim}
-hollow cylinder: radius x yheight and thickness\textgreater{}0
+hollow cylinder: radius x yheight and thickness\textgreater{}0 (no lids: the cavity spans the full yheight, as a sample can without lids)
\begin{verbatim}
sphere: radius (yheight=0 thickness=0)
diff --git a/docs/manuals/mcstas/samples/Res_sample.tex b/docs/manuals/mcstas/samples/Res_sample.tex
index 04dea66f01..db7b64c4cf 100644
--- a/docs/manuals/mcstas/samples/Res_sample.tex
+++ b/docs/manuals/mcstas/samples/Res_sample.tex
@@ -11,7 +11,7 @@ \subsection*{Identification}
\subsection*{Description}
An inelastic sample with completely uniform scattering in both Q and energy. This sample is used together with the Res\_monitor component and (optionally) the mcresplot front-end to compute the resolution function of triple-axis or inverse-geometry time-of-flight instruments.
-The shape of the sample is either a hollow cylinder or a rectangular box. The hollow cylinder shape is specified with an inner and outer radius. The box is specified with dimensions xwidth, yheight, zdepth.
+The shape of the sample is either a hollow cylinder or a rectangular box. The hollow cylinder shape is specified with an inner and outer radius. It has no lids: the cavity spans the full yheight, as a sample can without lids. The box is specified with dimensions xwidth, yheight, zdepth.
The scattered neutrons will have directions towards a given disk and energies betweed E0-dE and E0+dE. This target area may also be rectangular if specified focus\_xw and focus\_yh or focus\_aw and focus\_ah, respectively in meters and degrees. The target itself is either situated according to given coordinates (x,y,z), or setting the relative target\_index of the component to focus at (next is +1). This target position will be set to its AT position. When targeting to centered components, such as spheres or cylinders, define an Arm component where to focus at.
diff --git a/docs/manuals/mcstas/samples/TOFRes_sample.tex b/docs/manuals/mcstas/samples/TOFRes_sample.tex
index c809b90906..b055a7931e 100644
--- a/docs/manuals/mcstas/samples/TOFRes_sample.tex
+++ b/docs/manuals/mcstas/samples/TOFRes_sample.tex
@@ -11,7 +11,7 @@ \subsection*{Identification}
\subsection*{Description}
An inelastic sample with completely uniform scattering in both solid angle and energy. This sample is used together with the TOFRes\_monitor component and (optionally) the mcresplot front-end to compute the resolution function of all time-of-flight instruments. The method of time focusing is used to optimize the simulations.
-The shape of the sample is either: 1. Hollow cylinder (Please note that the cylinder **must** be specified with both a radius and a wall-thickness!) 2. A massive, rectangular box specified with dimensions xwidth, yheight, zdepth. (i.e. **withouht** a thickness)
+The shape of the sample is either: 1. Hollow cylinder (Please note that the cylinder **must** be specified with both a radius and a wall-thickness!). It has no lids: the cavity spans the full yheight, as a sample can without lids. 2. A massive, rectangular box specified with dimensions xwidth, yheight, zdepth. (i.e. **withouht** a thickness)
hollow cylinder shape **must** be specified with both a radius and a wall-thickness. The box is
diff --git a/docs/manuals/mcstas/samples/Tunneling_sample.tex b/docs/manuals/mcstas/samples/Tunneling_sample.tex
index d7a9ba04a0..3ac87f3b0e 100644
--- a/docs/manuals/mcstas/samples/Tunneling_sample.tex
+++ b/docs/manuals/mcstas/samples/Tunneling_sample.tex
@@ -11,7 +11,7 @@ \subsection*{Identification}
\end{itemize}
\subsection*{Description}
-A Double-cylinder shaped all-incoherent scatterer with both elastic, quasielastic (Lorentzian), and tunneling (sharp) components. No multiple scattering. Absorbtion included. The shape of the sample may be a box with dimensions xwidth, yheight, zdepth. The area to scatter to is a disk of radius 'focus\_r' situated at the target. This target area may also be rectangular if specified focus\_xw and focus\_yh or focus\_aw and focus\_ah, respectively in meters and degrees. The target itself is either situated according to given coordinates (x,y,z), or defined with the relative target\_index of the component to focus to (next is +1). This target position will be set to its AT position. When targeting to centered components, such as spheres or cylinders, define an Arm component where to focus to.
+A Double-cylinder shaped all-incoherent scatterer with both elastic, quasielastic (Lorentzian), and tunneling (sharp) components. No multiple scattering. Absorbtion included. The shape of the sample may be a box with dimensions xwidth, yheight, zdepth. With thickness\textgreater{}0 the cylinder is hollow, with no lids: the cavity spans the full yheight, as a sample can without lids. The area to scatter to is a disk of radius 'focus\_r' situated at the target. This target area may also be rectangular if specified focus\_xw and focus\_yh or focus\_aw and focus\_ah, respectively in meters and degrees. The target itself is either situated according to given coordinates (x,y,z), or defined with the relative target\_index of the component to focus to (next is +1). This target position will be set to its AT position. When targeting to centered components, such as spheres or cylinders, define an Arm component where to focus to.
The outgoing polarization is calculated as for nuclear spin incoherence:
diff --git a/docs/manuals/mcstas/sources/ESS_butterfly.tex b/docs/manuals/mcstas/sources/ESS_butterfly.tex
index e2c71a8fc5..12fb79fa5d 100644
--- a/docs/manuals/mcstas/sources/ESS_butterfly.tex
+++ b/docs/manuals/mcstas/sources/ESS_butterfly.tex
@@ -9,6 +9,8 @@ \subsection*{Identification}
\end{itemize}
\subsection*{Description}
+\textbf{Test Beamline (TBL), sector="W", beamline=11} TBL sits at 90 degrees to the proton beam and views both cold wings of the moderator. For exactly this beamport the component switches automatically to a "TBL mode" (adapted from a TBL-specific local version, 2025): the emission geometry is centred between the cold wings, cold neutrons are sampled 50/50 from the two wings, the horizontal brilliance profiles are mirror-symmetric about the moderator centre, and no thermal dx offset is applied. All other sector/beamline combinations are unaffected.
+
ESS butterfly moderator with automatic choice of coordinate system, with origin placed at relevant "Moderator Focus Coordinate System" depending on sector location.
To select beamport N 5 simply use
diff --git a/docs/manuals/mcstas/union/Union_mesh.tex b/docs/manuals/mcstas/union/Union_mesh.tex
index cb8938c423..e5a48cfd4b 100644
--- a/docs/manuals/mcstas/union/Union_mesh.tex
+++ b/docs/manuals/mcstas/union/Union_mesh.tex
@@ -17,9 +17,9 @@ \subsection*{Description}
There is a dedicated manual available for the Union\_components
-The mesh component loads a 3D off or stl files as the geometry. The mesh geometry that is loaded must be a watertight mesh. In order to check this, the component implements a simple Euler Pointcare value, To check if the given geometry is watertight. This check is sometimes too rigid, so a user can set the skip\_convex\_check parameter in order to not have this check performed.
+The mesh component loads a 3D OFF, STL or PLY file as the geometry, using geometry-mesh-lib (polygons are triangulated, duplicated vertices welded). Faces given more than once are removed, so a volumetric mesh (cells sharing faces) gives its outer surface. The mesh geometry that is loaded must be a watertight mesh: every edge must be shared by exactly two triangles.
-If you load an off file, we currently only support rank 3 polygons, i.e triangular meshes.
+Number of intersections per ray: for each mesh, Union\_master stores the GMESH\_MAX\_HITS (default 50) nearest crossings of the ray with the mesh surface. A concave mesh, or one made of several parts, can be crossed more often. Then the farther crossings are lost, the ray can not find the surface where it leaves the mesh, and Union\_master reports trace errors. geometry-mesh-lib warns once when this happens: Warning: \textless{}file\textgreater{}: a ray crossed the mesh N times, but only the 4 nearest hits are kept To fix it, add this line after the DEFINE INSTRUMENT line of the instrument, with N at least the number given in the warning: DEPENDENCY " -DGMESH\_MAX\_HITS=N "
It is allowed to overlap components, but it is not allowed to have two parallel planes that coincides. This will crash the code on run time.
@@ -31,7 +31,7 @@ \subsection*{Input parameters}
\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
\midrule
\endhead
-filename & str & Name of file that contains the 3D geometry. Can be either .OFF, .off, .STL, or .stl & 0 \\
+filename & str & Name of file that contains the 3D geometry: OFF, STL (ascii or binary) or PLY & 0 \\
material\_string & string & material name of this volume, defined using Union\_make\_material & 0 \\
\textbf{priority} & 1 & priotiry of the volume (can not be the same as another volume) A high priority is on top of low. & \\
visualize & 1 & set to 0 if you wish to hide this geometry in mcdisplay & 1 \\
@@ -50,7 +50,6 @@ \subsection*{Input parameters}
mask\_string & string & Comma seperated list of geometry names which this geometry should mask & 0 \\
mask\_setting & string & "All" or "Any", should the masked volume be simulated when the ray is in just one mask, or all. & 0 \\
number\_of\_activations & 1 & Number of subsequent Union\_master components that will simulate this geometry & 1 \\
-skip\_convex\_check & 1 & when set to 1, skips the check for whether input .off file is convex. & 0 \\
coordinate\_scale & 1e-3 & Multiplier that the vertex positions are multiplied by. Set to 1 for input coordinates in meters. Set to 1e-3 for input coordinates in mm. & 1e-3 \\
init & string & Deprecated and unused. Accepted so that instruments written for McStas/McXtrace 3.8.7 and earlier, which name the Union\_init component here, still compile. & "" \\
\bottomrule
diff --git a/docs/manuals/mcxtrace/kernel.tex b/docs/manuals/mcxtrace/kernel.tex
index 41e2f3bb81..3ef343ffeb 100644
--- a/docs/manuals/mcxtrace/kernel.tex
+++ b/docs/manuals/mcxtrace/kernel.tex
@@ -1429,9 +1429,9 @@ \subsubsection{The format of the comments in the library source code}
section). In the generated web documentation pages, the text is set in
\verb++\ldots\verb+
+, so that the line breaks in the source
will be obeyed.
-\item The \verb+%EXAMPLE:+
+\item The \verb+%EXAMPLE:+ (or \verb+%TEST:+)
lines in instrument headers indicate an example parameter set or command that may be
- run to test the instrument. A following \verb+Detector: _I=+
+ run to test the instrument. A \verb+%TESTSCAN:+ (older name \verb+%SCAN:+) line defines a parameter scan test with one expected value per scan point. A following \verb+Detector: _I=+
indicates what value should be obtained for a given monitor. More than one example
line may be specified in instruments.
\item Any number of \verb+%LINK+
diff --git a/docs/manuals/mcxtrace/misc/Annulus.tex b/docs/manuals/mcxtrace/misc/Annulus.tex
new file mode 100644
index 0000000000..354d58267b
--- /dev/null
+++ b/docs/manuals/mcxtrace/misc/Annulus.tex
@@ -0,0 +1,34 @@
+\section{The \texttt{Annulus} McXtrace Component}
+A flat annulus shape without effect on X-rays, for instrument display purpose.
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} E. Farhi
+ \item \textbf{Origin:} SOLEIL
+ \item \textbf{Date:} Oct 15 2026
+\end{itemize}
+
+\subsection*{Description}
+An inactive geometrical shape (annulus), for drawing purposes only. Derived from the \textbf{\htmladdnormallink{Shape}{Shape.html}} component
+
+Example: Annulus(radius=0.05, thickness=0.01)
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+radius & m & Outer radius of annulus in (x,z) plane & 0 \\
+thickness & m & Inner thickness of annulus in (x,z) plane & 0 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Annulus.comp}.
+ \item mcdoc page of \htmladdnormallink{Shape}{Shape.html}} component
+\end{itemize}
+\IfFileExists{misc/Annulus_static.tex}{\input{misc/Annulus_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcxtrace/misc/Circle.tex b/docs/manuals/mcxtrace/misc/Circle.tex
new file mode 100644
index 0000000000..1ee9e7fcd5
--- /dev/null
+++ b/docs/manuals/mcxtrace/misc/Circle.tex
@@ -0,0 +1,36 @@
+\section{The \texttt{Circle} McXtrace Component}
+A geometric shape without effect on neutron, for instrument display purpose.
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} E. Farhi
+ \item \textbf{Origin:} ILL
+ \item \textbf{Date:} June 23rd 2009
+\end{itemize}
+
+\subsection*{Description}
+An inactive geometrical shape (circle), for drawing purposes only. Derived from the \textbf{\htmladdnormallink{Shape}{Shape.html}} component
+
+Example: Circle(radius=0.05, yheight=0.1)
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+radius & m & Outer radius of geometry in (x,z) plane & 0 \\
+xwidth & m & Horiz. dimension of geometry & 0 \\
+yheight & m & Vert. dimension of geometry & 0 \\
+zdepth & m & Depth dimension of geometry & 0 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Circle.comp}.
+ \item mcdoc page of \htmladdnormallink{Shape}{Shape.html}} component
+\end{itemize}
+\IfFileExists{misc/Circle_static.tex}{\input{misc/Circle_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcxtrace/misc/Cone.tex b/docs/manuals/mcxtrace/misc/Cone.tex
new file mode 100644
index 0000000000..e73decafe8
--- /dev/null
+++ b/docs/manuals/mcxtrace/misc/Cone.tex
@@ -0,0 +1,37 @@
+\section{The \texttt{Cone} McXtrace Component}
+An inactive geometrical shape (cone), for drawing purposes only.
+Derived from the \textless{}b\textgreater{}\textless{}a href="Shape.html"\textgreater{}Shape\textless{}/a\textgreater{}\textless{}/b\textgreater{} component
+
+Example: Cone(radius=0.05, yheight=0.1)
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} E. Farhi
+ \item \textbf{Origin:} ILL
+ \item \textbf{Date:} June 23rd 2009
+\end{itemize}
+
+\subsection*{Description}
+
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+radius & m & Outer radius of geometry in (x,z) plane & 0 \\
+xwidth & m & Horiz. dimension of geometry as a width & 0 \\
+yheight & m & Vert. & 0 \\
+zdepth & m & Depth dimension of geometry & 0 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Cone.comp}.
+ \item mcdoc page of \htmladdnormallink{Shape}{Shape.html}} component
+\end{itemize}
+\IfFileExists{misc/Cone_static.tex}{\input{misc/Cone_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcxtrace/misc/Disc.tex b/docs/manuals/mcxtrace/misc/Disc.tex
new file mode 100644
index 0000000000..236d88e006
--- /dev/null
+++ b/docs/manuals/mcxtrace/misc/Disc.tex
@@ -0,0 +1,39 @@
+\section{The \texttt{Disc} McXtrace Component}
+A geometric shape without effect on neutron, for instrument display purpose.
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} E. Farhi
+ \item \textbf{Origin:} ILL
+ \item \textbf{Date:} June 23rd 2009
+\end{itemize}
+
+\subsection*{Description}
+An inactive geometrical shape (annulus), for drawing purposes only. Derived from the \textbf{\htmladdnormallink{Shape}{Shape.html}} component
+
+Example: Annulus(radius=0.05, yheight=0.1)
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+radius & m & Outer radius of geometry in (x,z) plane & 0 \\
+xwidth & m & Horiz. dimension of geometry & 0 \\
+yheight & m & Vert. dimensuon of geometry & 0 \\
+zdepth & m & Depth dimension of geometry & 0 \\
+nx & 1 & x-comp of orientation vector & 0 \\
+ny & 1 & y-comp of orientation vector & 1 \\
+nz & 1 & z-comp of orientation vector & 0 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Disc.comp}.
+ \item mcdoc page of \htmladdnormallink{Shape}{Shape.html}} component
+\end{itemize}
+\IfFileExists{misc/Disc_static.tex}{\input{misc/Disc_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcxtrace/misc/Legacy_circle.tex b/docs/manuals/mcxtrace/misc/Legacy_circle.tex
new file mode 100644
index 0000000000..78f2c6bb48
--- /dev/null
+++ b/docs/manuals/mcxtrace/misc/Legacy_circle.tex
@@ -0,0 +1,54 @@
+\section{The \texttt{Legacy\_circle} McXtrace Component}
+A geometric shape without effect on neutron, for instrument display purpose.
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} E. Farhi
+ \item \textbf{Origin:} ILL
+ \item \textbf{Date:} June 23rd 2009
+\end{itemize}
+
+\subsection*{Description}
+An inactive geometrical shape, for drawing purposes only. It does not propagate neutron, nor interact. \textbf{Shape:} Geometric shape may be a cylinder, a sphere, a box or any other shape
+
+\begin{verbatim}
+box/plate: xwidth x yheight x zdepth (thickness=0)
+\end{verbatim}
+
+hollow box/plate:xwidth x yheight x zdepth and thickness\textgreater{}0
+
+\begin{verbatim}
+cylinder: radius x yheight (thickness=0)
+\end{verbatim}
+
+hollow cylinder: radius x yheight and thickness\textgreater{}0
+
+\begin{verbatim}
+sphere: radius (yheight=0 thickness=0)
+hollow sphere: radius and thickness>0 (yheight=0)
+any shape: geometry=OFF file
+\end{verbatim}
+
+The complex geometry option handles any closed non-convex polyhedra. It computes the intersection points of the neutron ray with the object transparently, so that it can be used like a regular sample object. It supports the OFF and NOFF file format but not COFF (colored faces). Such files may be generated from XYZ data using qhull/powercrust, and viewed with geomview The default size of the object depends of the OFF file data, but its bounding box may be resized using xwidth,yheight and zdepth.
+
+Example: Shape(radius=0.05, yheight=0.1) Shape(geometry="socket.off")
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+radius & m & Outer radius of sample in (x,z) plane & 0 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Legacy\_circle.comp}.
+ \item Geomview and Object File Format (OFF) \textless{}http|://www.geomview.org\textgreater{}
+ \item Powercrust/qhull \textless{}http://www.cs.utexas.edu/users/amenta/powercrust\textgreater{}
+\end{itemize}
+\IfFileExists{misc/Legacy_circle_static.tex}{\input{misc/Legacy_circle_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcxtrace/misc/Shape.tex b/docs/manuals/mcxtrace/misc/Shape.tex
index 315b003491..420354f361 100644
--- a/docs/manuals/mcxtrace/misc/Shape.tex
+++ b/docs/manuals/mcxtrace/misc/Shape.tex
@@ -1,5 +1,5 @@
\section{The \texttt{Shape} McXtrace Component}
-A geometric shape without effect on X-raysX, for instrument display purpose.
+A geometric shape without effect on X-rays, for instrument display purpose.
\subsection*{Identification}
\begin{itemize}
@@ -9,7 +9,7 @@ \subsection*{Identification}
\end{itemize}
\subsection*{Description}
-An inactive geometrical shape, for drawing purposes only. It does not propagate X-rays, nor interact. \textbf{Shape:} Geometric shape may be a cylinder, a sphere, a box or any other shape
+An inactive geometrical shape, for drawing purposes only. It does not propagate x-ray, nor interact. \textbf{Shape:} Geometric shape may be a cylinder, a sphere, a box or any other shape
\begin{verbatim}
box/plate: xwidth x yheight x zdepth (thickness=0)
@@ -25,11 +25,10 @@ \subsection*{Description}
\begin{verbatim}
sphere: radius (yheight=0 thickness=0)
-hollow sphere: radius and thickness>0 (yheight=0)
any shape: geometry=OFF file
\end{verbatim}
-The complex geometry option handles any closed non-convex polyhedra. It computes the intersection points of the X ray with the object transparently, so that it can be used like a regular sample object. It supports the OFF and NOFF file format but not COFF (colored faces). Such files may be generated from XYZ data using qhull/powercrust, and viewed with geomview The default size of the object depends of the OFF file data, but its bounding box may be resized using xwidth,yheight and zdepth.
+The complex geometry option handles any closed non-convex polyhedra. It computes the intersection points of the X-ray with the object transparently, so that it can be used like a regular sample object. It supports the OFF and NOFF file format but not COFF (colored faces). Such files may be generated from XYZ data using qhull/powercrust, and viewed with geomview The default size of the object depends of the OFF file data, but its bounding box may be resized using xwidth,yheight and zdepth.
Example: Shape(radius=0.05, yheight=0.1) Shape(geometry="socket.off")
@@ -46,7 +45,10 @@ \subsection*{Input parameters}
xwidth & m & Horiz. dimension of sample (bounding box if off file), as a width & 0 \\
yheight & m & Vert. dimension of sample (bounding box if off file), as a height. A sphere shape is used when 0 and radius is set & 0 \\
zdepth & m & Depth of sample (bounding box if off file) & 0 \\
-thickness & m & Thickness of hollow sample & 0 \\
+thickness & m & Thickness of hollow box or cylinder (spheres are drawn solid) & 0 \\
+nx & 1 & x-comp of orientation vector & 0 \\
+ny & 1 & y-comp of orientation vector & 1 \\
+nz & 1 & z-comp of orientation vector & 0 \\
center & 1 & Flag to determine if OFF object is centered on its centre of mass. & 1 \\
\bottomrule
\end{longtable}
diff --git a/docs/manuals/mcxtrace/misc/Text.tex b/docs/manuals/mcxtrace/misc/Text.tex
new file mode 100644
index 0000000000..d6c6d87ba1
--- /dev/null
+++ b/docs/manuals/mcxtrace/misc/Text.tex
@@ -0,0 +1,37 @@
+\section{The \texttt{Text} McXtrace Component}
+Release: McXtrace 3.9
+
+Draw a text
+
+\subsection*{Identification}
+\begin{itemize}
+ \item \textbf{Author:} Emmanuel Farhi
+ \item \textbf{Origin:} SOLEIL
+ \item \textbf{Date:} Oct 10, 2026
+\end{itemize}
+
+\subsection*{Description}
+A text with given size and orientation. The text is drawn in upper letters.
+
+Example: Text(text="SOLEIL", size=0.5, plane="XY")
+
+\subsection*{Input parameters}
+Parameters in \textbf{boldface} are required; the others are optional.
+
+\begin{longtable}{p{0.22\textwidth}p{0.12\textwidth}p{0.46\textwidth}p{0.14\textwidth}}
+\toprule
+\textbf{Name} & \textbf{Unit} & \textbf{Description} & \textbf{Default} \\
+\midrule
+\endhead
+\textbf{text} & str & Text to draw. & \\
+size & m & Size of text. & 0.5 \\
+plane & str & "XY","YZ",or "XZ" & "XY" \\
+pen\_thickness & 1 & Stroke diameter as fraction of text size. 0 draws thin lines, \textgreater{}0 draws each stroke as a cylinder with spherical joints. & 0.1 \\
+\bottomrule
+\end{longtable}
+
+\subsection*{Links}
+\begin{itemize}
+ \item Component source code found in file \texttt{Text.comp}.
+\end{itemize}
+\IfFileExists{misc/Text_static.tex}{\input{misc/Text_static.tex}}{}
\ No newline at end of file
diff --git a/docs/manuals/mcxtrace/misc/misc.tex b/docs/manuals/mcxtrace/misc/misc.tex
index 7cea5e6e47..d67183d3d3 100644
--- a/docs/manuals/mcxtrace/misc/misc.tex
+++ b/docs/manuals/mcxtrace/misc/misc.tex
@@ -24,6 +24,8 @@ \chapter{Special-purpose components}
\input{misc/Progress_bar}
+\input{misc/Text}
+
\input{misc/Shadow_input}
\input{misc/Shadow_output}
diff --git a/docs/manuals/mcxtrace/monitors/Monitor_nD.tex b/docs/manuals/mcxtrace/monitors/Monitor_nD.tex
index 322daef2a4..6d152a256b 100644
--- a/docs/manuals/mcxtrace/monitors/Monitor_nD.tex
+++ b/docs/manuals/mcxtrace/monitors/Monitor_nD.tex
@@ -72,7 +72,7 @@ \subsection*{Description}
\end{verbatim}
\begin{verbatim}
-p intensity flux [phts/s or phts/cm^2/s]
+p i [phts/s or phts/cm^2/s] ('intensity', 'flux': name the default signal, add no variable, e.g. 'intensity per cm2 x y' is 2D)
ncounts n photon [1] photon ID, i.e current event index
pixel id [1] pixelID in histogram made of preceeding vars, e.g. 'theta y'. To set an offset PixelID use the 'min=value' keyword. Sets event mode.
\end{verbatim}
diff --git a/docs/manuals/mcxtrace/preamble.tex.in b/docs/manuals/mcxtrace/preamble.tex.in
index d9db077dc9..1a392f64d4 100644
--- a/docs/manuals/mcxtrace/preamble.tex.in
+++ b/docs/manuals/mcxtrace/preamble.tex.in
@@ -41,7 +41,7 @@
\newcommand{\MCX}{McXtrace\xspace}
\newcommand{\MCS}{McStas\xspace}
\newcommand{\version}{@MCCODE_VERSION@\xspace}
-\newcommand{\reldate}{September, 2026\xspace}
+\newcommand{\reldate}{October, 2026\xspace}
\newcommand{\Ombold}{\boldsymbol{\Omega}}
\newcommand{\NBIlong}{Niels Bohr Institute, University of Copenhagen, Copenhagen, Denmark.\xspace}
diff --git a/docs/manuals/mcxtrace/running.tex b/docs/manuals/mcxtrace/running.tex
index 73a302a32e..36de00bd41 100644
--- a/docs/manuals/mcxtrace/running.tex
+++ b/docs/manuals/mcxtrace/running.tex
@@ -212,7 +212,7 @@ \subsubsection*{Alternative code generator: \texttt{mcxtrace-pygen}}
program. Besides \verb+-o FILE+ (output file) it accepts
\verb+--instrument-name=NAME+ (name of the generated McStasScript instrument;
by default the instrument name followed by \texttt{\_generated}),
-\verb+--no-tests+ (do not translate \texttt{\%Example} lines into McStasScript
+\verb+--no-tests+ (do not translate \texttt{\%Test} (or \texttt{\%Example}) lines into McStasScript
tests), \verb+--lint+ (generate a script for McStasScript-style diagnostic
linting), \verb+--verbose+ and the version options described above. The
C-generator-only options (\verb+-I+, \verb+-t+, \verb+-p+, \verb+--no-main+,
@@ -1136,7 +1136,9 @@ \subsection{Running simulations on the commandline (mxrun)}
A parameter may also be given as \texttt{\textit{min}:\textit{delta}:\textit{max}},
in which case the point count follows from the requested step size and the
parameter may be freely mixed with explicit lists. The option
- \texttt{--seeds} scans over a range of random seeds (each non-zero).
+ \texttt{--seeds} scans over a range of random seeds (each non-zero). In a scan with
+ \texttt{--seed}, point $i$ uses the seed $\mathrm{SEED}+1024\,i$ (without \texttt{--seed} the base seed is taken from the
+ current time and logged).
\item With \texttt{--autoplot}, \verb+mxrun+ opens a plotter on the generated
data set when done (the back-end is chosen with \texttt{--autoplotter}, and
\texttt{--invcanvas} requests an inverted canvas). With
@@ -1276,15 +1278,26 @@ \subsection{Graphical display of simulations (mxdisplay)}
save a file instead of opening a window), and the number of traced rays is
capped at 100.
\item \verb+mxdisplay-webgl+ and \verb+mxdisplay-webgl-classic+: browser-based
- WebGL views (the former uses a small NodeJS-backed server for larger
- instruments/particle counts; its first use performs a one-time
- \texttt{npm}/\texttt{vite} module installation, which needs internet access).
- In addition to the options listed below they accept \verb+-t+/\verb+--trace N+
- (visualisation mode, default 2 resp.\ 1), \verb+-d+/\verb+--dirname DIR+,
- \verb+--first COMP+ and \verb+--last COMP+ (the first and last component of
- the zoomed range), and \verb+--nobrowse+ (do not open a browser);
- \verb+mxdisplay-webgl+ also has \verb+--timeout SEC+ (the shutdown time of
- its development server, default 300~s).
+ WebGL views. The former ships as a prebuilt web application served by a small
+ local web server (only if its \texttt{dist/} folder is missing does the first
+ run perform a one-time \texttt{npm install \&\& npm run build}, which needs
+ internet access). Both accept \verb+-t+/\verb+--trace N+ (visualisation mode,
+ default 2: boxes, cylinders, OFF geometry etc.\ are drawn as 3D shapes; 1
+ selects the legacy line approximations), \verb+-d+/\verb+--dirname DIR+,
+ \verb+--inspect COMP+ (show only rays reaching component \texttt{COMP}) and
+ \verb+--nobrowse+ (do not open a browser). \verb+mxdisplay-webgl+ also has
+ \verb+--timeout SEC+ (the shutdown time of its local viewer web server,
+ default 300~s), while \verb+mxdisplay-webgl-classic+ additionally accepts
+ \verb+--first COMP+, \verb+--last COMP+ (the first and last component of the
+ zoomed range) and \verb+--invcanvas+.
+\item \verb+mxdisplay-plopp+: draws the instrument and the traced rays with
+ the \texttt{plopp}/\texttt{scipp} Python packages (install e.g.\ with
+ \texttt{conda install -c conda-forge plopp ipympl jupyterlab}). By default it
+ opens an interactive 3D view in JupyterLab; with \verb+-o FILE+ it instead
+ writes a static \texttt{png}, \texttt{pdf} or \texttt{svg} with 2D
+ projections. Accepts \verb+-n N+ (number of rays, default 100), \verb+-y+
+ (forwarded to \verb+mxrun+: use defaults for unset parameters) and the
+ instrument parameters as \texttt{name=value}.
\item \verb+mxdisplay-cad+: exports the instrument geometry to a CAD file and
requires the \texttt{cadquery} Python package. The format is selected with
\verb+-f+/\verb+--format+: \texttt{step} (default), \texttt{stl},
@@ -1354,7 +1367,7 @@ \subsection{Plotting the results of a simulation (mxplot)}
As with \texttt{mxdisplay} (section~\ref{s:mxdisplay}), the drawing back-end
may be selected by invoking the dedicated front-end directly:
-\verb+mxplot-pyqtgraph+ (the default), \verb+mxplot-matplotlib+, or
+\verb+mxplot-pyqtgraph+ (the default), \verb+mxplot-matplotlib+, \verb+mxplot-plopp+ (plopp/scipp based, see below), or
\verb+mxplot-html+ (renders an interactive, self-contained web page using
D3.js, see section~\ref{s:run-format}), or by setting the
\verb+MCXTRACE_FORMAT+ environment variable.
@@ -1378,6 +1391,14 @@ \subsection{Plotting the results of a simulation (mxplot)}
monitor with \texttt{-png}, \texttt{-jpg}, \texttt{-fig}, \texttt{-eps} or
\texttt{-pdf}.
+\verb+mxplot-plopp+ opens the monitors of a simulation directory, \texttt{mccode.sim}, a single
+monitor file or a NeXus \texttt{mccode.h5} file in an interactive JupyterLab view built on
+\texttt{plopp}/\texttt{scipp} (install with e.g.\ \texttt{conda install -c conda-forge plopp
+ipympl jupyterlab}). With \verb+-o FILE+ it writes a static \texttt{png}, \texttt{pdf} or
+\texttt{svg} instead, \verb+--log+ selects a logarithmic intensity scale, and
+\verb+--source+/\verb+--sample+ name the source and sample components when plotting
+Monitor\_nD event data from NeXus files through McStasToX.
+
All plotters read the plain-text \MCX/McCode data format (section~\ref{s:analyze});
NeXus files are not currently read back by the plotters.
@@ -1448,7 +1469,8 @@ \subsection{Creating and viewing the library, component/instrument help and
\indexEV{BROWSER}
(e.g. firefox, chromium, \ldots). Alternatively, if a search term or a
\textit{file.comp}/\textit{file.instr} path is given, \verb+mxdoc+ will
-search within the library and open documentation for all matching entries.
+search within the library and open documentation for all matching entries. The search results are written to a
+separate page, \texttt{mxdoc\_search.html}, next to the main library page (or in the temporary directory if that is read-only), so the main page is left untouched. Mathematics in component documentation is rendered locally with the MathJax copy installed with the documentation.
Additional options include \verb+--install+/\verb+-i+ (regenerate the local
installation-wide index), \verb+--dir=DIR+/\verb+-d+ (add search results from
@@ -1489,7 +1511,7 @@ \subsection{Self-testing the installation (mxtest, mxviewtest)}
\MCX ships with a Python self-test/benchmark harness, replacing the earlier
\verb+mxrun --test+ command. \verb+mxtest+ compiles and runs a selection (or
all) of the example instruments found under the current installation(s), and
-stores each run's results (including any test-defined \texttt{\%Example}
+stores each run's results (including any test-defined \texttt{\%Test}
reference values) in a timestamped output folder. Each test compiles the
instrument, displays it with a single particle, runs it, and compares the
result with the target value recorded in the instrument header. Useful options
@@ -1502,12 +1524,33 @@ \subsection{Self-testing the installation (mxtest, mxviewtest)}
any of the given components), \verb+--local=DIR+ (test instruments from
\texttt{DIR} instead of the installation), \verb+--limit=N+ (test only the first
N instruments per version), \verb+--skipnontest+ (skip instruments without an
-\texttt{\%Example} line), \verb+--strict+ (fail instruments without
-\texttt{\%Example} line(s) immediately) and \verb+--permissive+ (exit with
+\texttt{\%Test}/\texttt{\%TestScan} line), \verb+--strict+ (fail instruments without
+\texttt{\%Test}/\texttt{\%TestScan} line(s) immediately) and \verb+--permissive+ (exit with
status 0 even if tests fail), \verb+--testdir=DIR+ and \verb+--suffix=SUFFIX+
(where the results are written), \verb+--compilemax+, \verb+--runmax+ and
\verb+--displaymax+ (time limits in seconds) and \verb+--noplots+ (do not
generate the overview plots); run \verb+mxtest --help+ for the full list.
+generate the overview plots); run \verb+mctest --help+ for the full list.
+
+A test is defined in the instrument header by a \texttt{\%Test:} line (older name
+\texttt{\%Example:}), giving instrument parameters and the expected monitor value,
+\textit{e.g.}\ \texttt{\%Test: lambda=2.36 Detector: He3H\_I=9.84026e-10}. A
+\texttt{\%TestScan:} line (older name \texttt{\%Scan:}) defines a parameter scan
+using the \verb+mxrun+ scan syntax, followed by a \texttt{\{\}}-enclosed list with one
+target value per scan point (it may span several header lines), \textit{e.g.}\
+\texttt{\%TestScan: dBz=-0.0001,0.0001 -N41 -n1e5 Detector: detector\_I=\{\ldots\}}.
+A \texttt{\%Test:} always runs at the global \verb+--ncount+ (scaled by
+\verb+--statfactor+); a scan uses its own \texttt{-n} if given, otherwise at most
+$10^5$ per point, and runs its points in parallel (\verb+--scan_split=auto+) unless
+MPI is used. By default a value (every point of a scan) passes when it is within
+20\,\% of its target. With \verb+--nsigma N+ or \verb+--pvalue P+ it is instead
+accepted within the statistical tolerance of the combined error bars, using the
+error bar of the target when the test line gives it
+(\textit{e.g.}\ \texttt{NAME\_I=2.00752e+08 NAME\_ERR=2.28872e+06}).
+\verb+--statfactor F+ scales the particle count of every test (\textit{e.g.}\ 0.01 for
+quick runs, 100 for reference-quality ones) and \verb+--noscans+ skips the
+\texttt{\%TestScan} tests. The statistics are described in more detail in
+\texttt{tools/Python/mctest-statistics.md}.
\verb+mxviewtest+ then generates an HTML report of one or more \verb+mxtest+
runs found in a given folder (the current directory by default). When more
@@ -1519,7 +1562,7 @@ \subsection{Self-testing the installation (mxtest, mxviewtest)}
reference's, adding a \texttt{DIFF~[vs~ref]} link next to each such row in the
report. These comparisons are cached on disk and generated in parallel
(\verb+--diffworkers+, each limited to \verb+--diffmax+ seconds), so
-re-running \verb+mxviewtest+ is fast; use \verb+--nodiff+ to skip generating
+re-running \verb+mxviewtest+ is fast (each test, and each scan, is one row of the report, coloured pass/fail by the rule \verb+mxtest+ used for that result set; hovering a scan cell lists every point's value, target and percentage); use \verb+--nodiff+ to skip generating
them entirely, or \verb+--diff-errors-only+ to only diff rows that already show
a discrepancy (by default every valid row is diffed). \verb+--nobrowse+ keeps
the finished report from being opened in a browser.
@@ -1654,7 +1697,7 @@ \section{Using MPI for parallel computing}
clusters (see section \ref{s:mpi}).
\item \texttt{mxrun}'s built-in scan-splitting (\verb+--scan_split=N+, see
Table~\ref{f:mcrunoptions}) distributes the individual steps of a parameter
- scan across \texttt{N} local CPU cores/threads, without requiring MPI. This
+ scan across \texttt{N} local CPU cores/threads (\texttt{auto}, or 0, uses the number of cores minus one), without requiring MPI. It is ignored, with a warning, when an explicit multi-process \verb+--mpi+ is given. This
is a lightweight alternative on a single multi-core machine.
\end{itemize}
diff --git a/docs/manuals/mcxtrace/samples/PowderN.tex b/docs/manuals/mcxtrace/samples/PowderN.tex
index 4ff7e2b495..e4d1f50d55 100644
--- a/docs/manuals/mcxtrace/samples/PowderN.tex
+++ b/docs/manuals/mcxtrace/samples/PowderN.tex
@@ -25,7 +25,7 @@ \subsection*{Description}
cylinder: radius x yheight (thickness=0)
\end{verbatim}
-hollow cylinder: radius x yheight and thickness\textgreater{}0
+hollow cylinder: radius x yheight and thickness\textgreater{}0 (no lids: the cavity spans the full yheight, as a sample can without lids)
\begin{verbatim}
sphere: radius (yheight=0 thickness=0)
diff --git a/mcstas-comps/examples/ESS/ESS_IN5_reprate/README.md b/mcstas-comps/examples/ESS/ESS_IN5_reprate/README.md
index 1e2b677683..1bbf7ca24a 100644
--- a/mcstas-comps/examples/ESS/ESS_IN5_reprate/README.md
+++ b/mcstas-comps/examples/ESS/ESS_IN5_reprate/README.md
@@ -19,6 +19,7 @@ The sample is incoherent with an inelastic tunneling line.
## Examples
- **Test: Lmin=4.9 Detector: PSDfast2_I=1.18335e+10**
+- **Test: Lmin=4.9 Detector: PSDsample_I=1.8583e+07**
## Input parameters
diff --git a/mcstas-comps/examples/ESS/ESS_butterfly_MCPL_test/README.md b/mcstas-comps/examples/ESS/ESS_butterfly_MCPL_test/README.md
index 1372121534..87420be8bb 100644
--- a/mcstas-comps/examples/ESS/ESS_butterfly_MCPL_test/README.md
+++ b/mcstas-comps/examples/ESS/ESS_butterfly_MCPL_test/README.md
@@ -48,7 +48,7 @@ Parameters in **boldface** are required; the others are optional.
| delta | m | Parameter that allows to scan "collimator" position | 0 |
| thres | | Weight-threshold, neutrons with higher weight are absorbed | 4e8 |
| filter | 1 | Use a 'preconditioned' MCPL file that removes non-transportable neutrons (energy, position, emmision coordinates etc.) Generate such inputs using ESS_MCPL_generate_filtered. | 1 |
-| repeat | | Number of MCPL file repetitions (only valid with use of MCPL_input, not with MCPL_input_once | 1 |
+| repeat | | Number of MCPL file repetitions, requires at least one *_smear parameter | 1 |
| v_smear | 1 | When repeating events, make a Gaussian MC choice within v_smear*V around particle velocity V | 0.1 |
| pos_smear | m | When repeating events, make a flat MC choice of position within pos_smear around particle starting position | 0.01 |
| dir_smear | deg | When repeating events, make a Gaussian MC choice of direction within dir_smear around particle direction | 0.01 |
diff --git a/mcstas-comps/examples/FRMII/FRMII_SPODI/README.md b/mcstas-comps/examples/FRMII/FRMII_SPODI/README.md
index 61509eae3d..57d6726eb2 100644
--- a/mcstas-comps/examples/FRMII/FRMII_SPODI/README.md
+++ b/mcstas-comps/examples/FRMII/FRMII_SPODI/README.md
@@ -37,7 +37,7 @@ the 2D data that are collected on the real detectors.
## Examples
-- **Test: -y -n1e8 Detector: theta_full_I=31556.9**
+- **Test: -y Detector: theta_full_I=31556.9**
## Input parameters
diff --git a/mcstas-comps/examples/FZ_Juelich/FZJ_BenchmarkSfin2/README.md b/mcstas-comps/examples/FZ_Juelich/FZJ_BenchmarkSfin2/README.md
index 3bc8bbbb5a..9c70e2756d 100644
--- a/mcstas-comps/examples/FZ_Juelich/FZJ_BenchmarkSfin2/README.md
+++ b/mcstas-comps/examples/FZ_Juelich/FZJ_BenchmarkSfin2/README.md
@@ -19,7 +19,7 @@ The below test uses defaults of the instrument (SANS_benchmark2 modnum=11)*
## Examples
-- **Test: -y Detector: PSDnear_I=7400**
+- **Test: -y Detector: PSDnear_I=8.5e3**
-
- Many sample-modes are available, from the SANS_benchmark2 component:
- The component includes 19 sample-model-settings:
diff --git a/mcstas-comps/examples/Mantid/templateSANS_Mantid/README.md b/mcstas-comps/examples/Mantid/templateSANS_Mantid/README.md
index e7872fb338..aac3d5ab41 100644
--- a/mcstas-comps/examples/Mantid/templateSANS_Mantid/README.md
+++ b/mcstas-comps/examples/Mantid/templateSANS_Mantid/README.md
@@ -25,8 +25,8 @@ Needed steps:
## Examples
-- **Test: lambda=6 Detector: PSDrad_I=105000000**
-- **Test: lambda=6 --format=NeXus Detector: PSDrad_I=105000000**
+- **Test: lambda=6 Detector: PSDrad_I=9.6e7**
+- **Test: lambda=6 --format=NeXus Detector: PSDrad_I=9.6e7**
## Input parameters
diff --git a/mcstas-comps/examples/Risoe/TAS1_C1/README.md b/mcstas-comps/examples/Risoe/TAS1_C1/README.md
index 78a9165671..1fae1f51c7 100644
--- a/mcstas-comps/examples/Risoe/TAS1_C1/README.md
+++ b/mcstas-comps/examples/Risoe/TAS1_C1/README.md
@@ -25,6 +25,7 @@ detector is at the sample position.
## Examples
- **Test: PHM=-37.077 Detector: sng_I=0.000429426**
+- **TestScan: mcrun TAS1_C1.instr PHM=-38.077,-36.077 -N11 -n1e6 Detector: sng_I={11 values}**
## Input parameters
diff --git a/mcstas-comps/examples/Risoe/TAS1_C1_Tilt/README.md b/mcstas-comps/examples/Risoe/TAS1_C1_Tilt/README.md
index 46a35a9130..4b55e7b6c3 100644
--- a/mcstas-comps/examples/Risoe/TAS1_C1_Tilt/README.md
+++ b/mcstas-comps/examples/Risoe/TAS1_C1_Tilt/README.md
@@ -25,6 +25,7 @@ detector is at the sample position and there is no analyzer.
## Examples
- **Test: TTM=-74 Detector: sng_I=0.000405056**
+- **TestScan: mcrun TAS1_C1_Tilt.instr OMC1=-44.5,55.5 -N21 -n1e6 Detector: sng_I={21 values}**
## Input parameters
@@ -35,7 +36,7 @@ Parameters in **boldface** are required; the others are optional.
| PHM | deg | Monochromator arm angle, aka A1 | -37.077 |
| TTM | deg | Monochromator take-off angle, aka A2 | -74 |
| C1 | min | Collimator 1 aperture (mono-sample arm) | 30 |
-| OMC1 | deg | Tilt angle of the Collimator 1 | 5.5 |
+| OMC1 | arcmin | Tilt angle of the Collimator 1 | 5.5 |
## Links
diff --git a/mcstas-comps/examples/Risoe/TAS1_Diff_Powder/README.md b/mcstas-comps/examples/Risoe/TAS1_Diff_Powder/README.md
index ed127bb271..dc9801ff82 100644
--- a/mcstas-comps/examples/Risoe/TAS1_Diff_Powder/README.md
+++ b/mcstas-comps/examples/Risoe/TAS1_Diff_Powder/README.md
@@ -26,6 +26,7 @@ sample is a powder and there is no analyzer.
## Examples
- **Test: PHM=-37.077 Detector: sng_I=4.50892e-07**
+- **TestScan: mcrun TAS1_Diff_Powder.instr TT=32.92,34.32 -N15 -n1e6 Detector: sng_I={15 values}**
## Input parameters
@@ -38,7 +39,7 @@ Parameters in **boldface** are required; the others are optional.
| TT | deg | Take-off angle at the sample position, aka A4 | 33.52 |
| TTA | deg | Take-off angle at the analyzer position, aka A6 | 0 |
| C1 | min | Collimator 1 aperture (mono-sample arm) | 30 |
-| OMC1 | deg | Tilt angle of the Collimator 1 | 5.5 |
+| OMC1 | arcmin | Tilt angle of the Collimator 1 | 5.5 |
| C2 | min | Collimator 2 aperture (sample-ana arm) | 28 |
| C3 | min | Collimator 3 aperture (ana-detector arm) | 67 |
diff --git a/mcstas-comps/examples/Risoe/TAS1_Diff_Slit/README.md b/mcstas-comps/examples/Risoe/TAS1_Diff_Slit/README.md
index 7c66d3a3cc..e664a7b2b9 100644
--- a/mcstas-comps/examples/Risoe/TAS1_Diff_Slit/README.md
+++ b/mcstas-comps/examples/Risoe/TAS1_Diff_Slit/README.md
@@ -26,6 +26,7 @@ sample is a slit and there is no analyzer.
## Examples
- **Test: C1=30 TT=0 Detector: sng_I=2e-5**
+- **TestScan: mcrun TAS1_Diff_Slit.instr C1=30 TT=-0.6,0.6 -N13 -n1e6 Detector: sng_I={13 values}**
## Input parameters
@@ -37,7 +38,7 @@ Parameters in **boldface** are required; the others are optional.
| TTM | deg | Monochromator take-off angle, aka A2 | -74 |
| TT | deg | Take-off angle at the sample position, aka A4 | 33.52 |
| C1 | min | Collimator 1 aperture (mono-sample arm) | 30 |
-| OMC1 | deg | Tilt angle of the Collimator 1 | 5.5 |
+| OMC1 | arcmin | Tilt angle of the Collimator 1 | 5.5 |
| C2 | min | Collimator 2 aperture (sample-ana arm) | 28 |
| C3 | min | Collimator 3 aperture (ana-detector arm) | 67 |
diff --git a/mcstas-comps/examples/Risoe/TAS1_Diff_Vana/README.md b/mcstas-comps/examples/Risoe/TAS1_Diff_Vana/README.md
index f334c4577f..37bc05d481 100644
--- a/mcstas-comps/examples/Risoe/TAS1_Diff_Vana/README.md
+++ b/mcstas-comps/examples/Risoe/TAS1_Diff_Vana/README.md
@@ -26,6 +26,7 @@ sample is a vanadium cylinder and there is no analyzer.
## Examples
- **Test: PHM=-37.077 Detector: sng_I=1.95173e-09**
+- **TestScan: mcrun TAS1_Diff_Vana.instr TT=31.52,35.52 -N21 -n1e6 Detector: sng_I={21 values}**
## Input parameters
@@ -38,7 +39,7 @@ Parameters in **boldface** are required; the others are optional.
| TT | deg | Take-off angle at the sample position, aka A4 | 33.52 |
| TTA | deg | Take-off angle at the analyzer position, aka A6 | 0 |
| C1 | min | Collimator 1 aperture (mono-sample arm) | 30 |
-| OMC1 | deg | Tilt angle of the Collimator 1 | 5.5 |
+| OMC1 | arcmin | Tilt angle of the Collimator 1 | 5.5 |
| C2 | min | Collimator 2 aperture (sample-ana arm) | 28 |
| C3 | min | Collimator 3 aperture (ana-detector arm) | 67 |
diff --git a/mcstas-comps/examples/Risoe/TAS1_Powder/README.md b/mcstas-comps/examples/Risoe/TAS1_Powder/README.md
index 7bea64fe86..e27487ca4b 100644
--- a/mcstas-comps/examples/Risoe/TAS1_Powder/README.md
+++ b/mcstas-comps/examples/Risoe/TAS1_Powder/README.md
@@ -24,6 +24,9 @@ The sample is a powder and the analyzer is a single plate.
## Examples
- **Test: PHM=-37.077 Detector: sng_I=2.26723e-07**
+- With TTA=0 the detector looks straight through the analyzer, so an OMA scan shows
+- a transmission dip where the analyzer is at its Bragg angle:
+- **TestScan: mcrun TAS1_Powder.instr OMA=-19.45,-15.45 -N21 -n1e6 Detector: sng_I={21 values}**
## Input parameters
@@ -36,7 +39,7 @@ Parameters in **boldface** are required; the others are optional.
| TT | deg | Take-off angle at the sample position, aka A4 | 33.52 |
| TTA | deg | Take-off angle at the analyzer position, aka A6 | 0 |
| C1 | min | Collimator 1 aperture (mono-sample arm) | 30 |
-| OMC1 | deg | Tilt angle of the Collimator 1 | 5.5 |
+| OMC1 | arcmin | Tilt angle of the Collimator 1 | 5.5 |
| C2 | min | Collimator 2 aperture (sample-ana arm) | 28 |
| C3 | min | Collimator 3 aperture (ana-detector arm) | 67 |
| OMA | deg | Analyzer rotation angle, aka A5 | -17.45 |
diff --git a/mcstas-comps/examples/Risoe/TAS1_Vana/README.md b/mcstas-comps/examples/Risoe/TAS1_Vana/README.md
index 4695f2744c..129dbe3dac 100644
--- a/mcstas-comps/examples/Risoe/TAS1_Vana/README.md
+++ b/mcstas-comps/examples/Risoe/TAS1_Vana/README.md
@@ -24,6 +24,9 @@ The sample is a vanadium and the analyzer is a single plate.
## Examples
- **Test: PHM=-37.077 Detector: sng_I=1.11099e-09**
+- With TTA=0 the detector looks straight through the analyzer, so an OMA scan shows
+- a transmission dip where the analyzer is at its Bragg angle:
+- **TestScan: mcrun TAS1_Vana.instr OMA=-19.45,-15.45 -N21 -n1e6 Detector: sng_I={21 values}**
## Input parameters
@@ -36,7 +39,7 @@ Parameters in **boldface** are required; the others are optional.
| TT | deg | Take-off angle at the sample position, aka A4 | 33.52 |
| TTA | deg | Take-off angle at the analyzer position, aka A6 | 0 |
| C1 | min | Collimator 1 aperture (mono-sample arm) | 30 |
-| OMC1 | deg | Tilt angle of the Collimator 1 | 5.5 |
+| OMC1 | arcmin | Tilt angle of the Collimator 1 | 5.5 |
| C2 | min | Collimator 2 aperture (sample-ana arm) | 28 |
| C3 | min | Collimator 3 aperture (ana-detector arm) | 67 |
| OMA | deg | Analyzer rotation angle, aka A5 | -17.45 |
diff --git a/mcstas-comps/examples/TUDelft/SESANS_Delft/README.md b/mcstas-comps/examples/TUDelft/SESANS_Delft/README.md
index c44a88ed7d..660abeaf55 100644
--- a/mcstas-comps/examples/TUDelft/SESANS_Delft/README.md
+++ b/mcstas-comps/examples/TUDelft/SESANS_Delft/README.md
@@ -30,7 +30,7 @@ These parameter and the sphere radius match now with the magnetic fields below t
- **Test: -y Detector: det_I=2.2537e-07**
-
-- Scan Example: SESANS_Delft -n 1000000 -N 31 L0=2.165 DL=0.02 By=0,0.0468
+- **TestScan: mcrun SESANS_Delft.instr L0=2.165 DL=0.02 By=0,0.0468 -N31 -n1e6 Detector: det_I={31 values}**
## Input parameters
diff --git a/mcstas-comps/examples/Templates/BTsimple/README.md b/mcstas-comps/examples/Templates/BTsimple/README.md
index b7648ed4a6..ef8e046760 100644
--- a/mcstas-comps/examples/Templates/BTsimple/README.md
+++ b/mcstas-comps/examples/Templates/BTsimple/README.md
@@ -17,7 +17,7 @@ Example instrument showing how to calculate brilliance transfer using L_monitor'
## Examples
-- **Test: -n1e7 BTsimple.instr lambda=10 Detector: BTransfer_I=75.4758**
+- **Test: BTsimple.instr lambda=10 Detector: BTransfer_I=75.4758**
## Input parameters
diff --git a/mcstas-comps/examples/Templates/Text2OFF/README.md b/mcstas-comps/examples/Templates/Text2OFF/README.md
new file mode 100644
index 0000000000..803fa43d7f
--- /dev/null
+++ b/mcstas-comps/examples/Templates/Text2OFF/README.md
@@ -0,0 +1,55 @@
+# The `Text2OFF` Instrument
+
+*McStas: Render a text string as 3D geometry, e.g. for export to an OFF file*
+
+## Identification
+
+- **Site:** Templates
+- **Author:** Peter Willendrup (pkwi@fysik.dtu.dk)
+- **Origin:** DTU Physics
+- **Date:** October 2026
+
+## Description
+
+```text
+Draws the string given in "letters" with the Text component and nothing else -
+no particles are traced. Use it with mcdisplay-cad to turn a text into CAD
+geometry, for instance an OFF file that can be fed back into components that
+read OFF geometry (labels, logos, test shapes):
+
+mcdisplay-cad Text2OFF.instr -t 2 -f off letters="McStas" size=0.5
+
+Notes:
+- Use --trace 2 (-t 2): with the default trace level 1 Text draws thin lines,
+which carry no surfaces and give an empty OFF/STL file.
+- Each stroke is a cylinder and each stroke end/joint a sphere, so the
+resulting surfaces overlap - fine for display, not a closed single solid.
+- Letters are drawn upper-case; characters without a glyph are left blank.
+
+Example: letters="McStas" size=0.5 plane="XY"
+```
+
+## Examples
+
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| letters | str | Text to draw | "McStas" |
+| size | m | Letter height | 0.5 |
+| plane | str | Plane of the text: "XY", "YZ" or "XZ" | "XY" |
+| thickness | 1 | Stroke diameter as fraction of size | 0.1 |
+| rx | deg | Rotation of the text around the x axis | 0 |
+| ry | deg | Rotation of the text around the y axis | 0 |
+| rz | deg | Rotation of the text around the z axis | 0 |
+
+## Links
+
+- [Source code](Text2OFF.instr) for `Text2OFF.instr`.
+- Text.comp, mcdisplay-cad --help
+
+---
diff --git a/mcstas-comps/examples/Tests_MCPL_etc/Test_MCPL_input_once/README.md b/mcstas-comps/examples/Tests_MCPL_etc/Test_MCPL_input_once/README.md
index c797e4a1cb..eb1d2a55f2 100644
--- a/mcstas-comps/examples/Tests_MCPL_etc/Test_MCPL_input_once/README.md
+++ b/mcstas-comps/examples/Tests_MCPL_etc/Test_MCPL_input_once/README.md
@@ -12,9 +12,9 @@
## Description
```text
-This is a unit test for the MCPL_input_once component, which differs from the original MCPL_input by:
-1) Being MPI-parallelized (no implicit "repeat" of the particles in the file, file content is shared among processes
-2) No implementation of "repetition", if further stats is needed downstream, SPLIT should be applied
+This is a unit test for the MCPL_input_once component. Since Oct 2026 MCPL_input_once
+is an INHERIT of MCPL_input with repeat_count=1 and replicate_across_processes=0 forced:
+the file content is shared among MPI processes and every particle is used once.
```
## Examples
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_DIAPHRAGM/README.md b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_DIAPHRAGM/README.md
new file mode 100644
index 0000000000..fbe85937f2
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_DIAPHRAGM/README.md
@@ -0,0 +1,47 @@
+# The `Unittest_INHERIT_DIAPHRAGM` Instrument
+
+*McStas: Whole-component INHERIT: Diaphragm (DEFINE COMPONENT Diaphragm INHERIT Slit)*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for whole-component inheritance, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+Diaphragm.comp is just "DEFINE COMPONENT Diaphragm INHERIT Slit" + END,
+so all of its code sections must come from Slit.
+
+One unit of intensity is emitted uniformly from a 1x1 m square:
+- a Slit of 0.5x0.5 m passes 1/4: AfterSlit_I = 0.25
+- a Diaphragm of 0.25x0.25 m passes 1/16 of the source: AfterDiaphragm_I = 0.0625
+
+Before the fix, a component inheriting all of its code got none of it, so
+the Diaphragm let everything through (AfterDiaphragm_I = 0.25).
+```
+
+## Examples
+
+- **Test: Detector: AfterSlit_I=0.25**
+- **Test: Detector: AfterDiaphragm_I=0.0625**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_INHERIT_DIAPHRAGM.instr) for `Unittest_INHERIT_DIAPHRAGM.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/README.md b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/README.md
new file mode 100644
index 0000000000..7cc25d2e74
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/README.md
@@ -0,0 +1,57 @@
+# The `Unittest_INHERIT_OVERRIDE` Instrument
+
+*McStas: DEFINE COMPONENT X INHERIT Y: written sections (even empty) replace Y's*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for whole-component inheritance, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+(same rule as mccode-antlr, mccode-dev/mccode-antlr#321).
+
+Local components: Unittest_IO_parent absorbs particles with x>0. Its
+children, DEFINE COMPONENT ... INHERIT Unittest_IO_parent:
+- Unittest_IO_cancel writes an empty TRACE %{ %}: replaces the parent's
+TRACE, absorbs nothing. Before, an empty block counted as "not written"
+and the parent's TRACE was used.
+- Unittest_IO_keep writes no sections: inherits the parent's TRACE.
+- Unittest_IO_extend writes TRACE INHERIT Unittest_IO_parent EXTEND %{..%}:
+the parent's TRACE followed by more code (absorbs x>0 and y>0). It also
+uses INHERIT within USERVARS.
+- Unittest_IO_noinit writes an empty INITIALIZE EXTEND %{ %}: keeps the
+parent's DECLARE and TRACE but not its INITIALIZE (io_val stays 0, so
+its TRACE halves the weight). "Inherit everything but one section".
+
+One unit of intensity is emitted uniformly from a 1x1 m square:
+AfterCancel_I = 1, AfterKeep_I = 0.5, AfterExtend_I = 0.25,
+AfterNoInit_I = 0.125.
+```
+
+## Examples
+
+- **Test: Detector: AfterCancel_I=1**
+- **Test: Detector: AfterKeep_I=0.5**
+- **Test: Detector: AfterExtend_I=0.25**
+- **Test: Detector: AfterNoInit_I=0.125**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_INHERIT_OVERRIDE.instr) for `Unittest_INHERIT_OVERRIDE.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_cancel.md b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_cancel.md
new file mode 100644
index 0000000000..7f89276be1
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_cancel.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_cancel` Component
+
+*McStas: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Inherits everything from Unittest_IO_parent but cancels its TRACE with an
+explicitly written, empty TRACE section: absorbs nothing.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_cancel.comp) for `Unittest_IO_cancel.comp`.
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_extend.md b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_extend.md
new file mode 100644
index 0000000000..22c1ac4019
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_extend.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_extend` Component
+
+*McStas: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Writes TRACE as the parent's TRACE plus more code: absorbs x>0 and y>0.
+Also uses INHERIT within USERVARS.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_extend.comp) for `Unittest_IO_extend.comp`.
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_keep.md b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_keep.md
new file mode 100644
index 0000000000..b54ab6ef44
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_keep.md
@@ -0,0 +1,30 @@
+# The `Unittest_IO_keep` Component
+
+*McStas: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Inherits everything from Unittest_IO_parent (writes no sections): absorbs x>0.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_keep.comp) for `Unittest_IO_keep.comp`.
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_noinit.md b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_noinit.md
new file mode 100644
index 0000000000..cad8a8c36d
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_noinit.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_noinit` Component
+
+*McStas: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Inherits everything from Unittest_IO_parent but cancels its INITIALIZE with
+an empty INITIALIZE EXTEND section: io_val stays 0, so TRACE halves the weight.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_noinit.comp) for `Unittest_IO_noinit.comp`.
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_parent.md b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_parent.md
new file mode 100644
index 0000000000..fd2a3ced58
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_parent.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_parent` Component
+
+*McStas: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Parent: absorbs particles with x>0, and declares a USERVAR. Its DECLARE/
+INITIALIZE set io_val=1; TRACE halves the weight if io_val is not set.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_parent.comp) for `Unittest_IO_parent.comp`.
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_JUMP_RELATIVE/README.md b/mcstas-comps/examples/Tests_grammar/Unittest_JUMP_RELATIVE/README.md
new file mode 100644
index 0000000000..daa52bd9bd
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_JUMP_RELATIVE/README.md
@@ -0,0 +1,50 @@
+# The `Unittest_JUMP_RELATIVE` Instrument
+
+*McStas: Relative JUMP targets: JUMP PREVIOUS(n) and JUMP NEXT(n)*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for relative JUMP targets, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+One unit of intensity is emitted from a 1x1 m square.
+- Back jumps to PREVIOUS(2), i.e. to Target, 'iter' times in total
+(JUMP ... ITERATE), so the Mon monitor in between is passed 'iter' times
+and reads Mon_I = iter.
+- Skip jumps to NEXT(2), i.e. over Skipped and onto Landed, so
+Skipped_I = 0 and Landed_I = 1.
+
+Before the fix, relative targets were used as absolute component indices:
+JUMP PREVIOUS(n) crashed the code generator and JUMP NEXT(n) went to
+component n. JUMP PREVIOUS is PREVIOUS(1) and JUMP NEXT is NEXT(1).
+```
+
+## Examples
+
+- **Test: iter=3 Detector: Mon_I=3**
+- **Test: iter=3 Detector: Landed_I=1**
+- **Test: iter=3 Detector: Skipped_I=0**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| iter | 1 | Number of passes through Mon (JUMP ITERATE count) | 3 |
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_JUMP_RELATIVE.instr) for `Unittest_JUMP_RELATIVE.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/README.md b/mcstas-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/README.md
new file mode 100644
index 0000000000..099a63299b
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/README.md
@@ -0,0 +1,52 @@
+# The `Unittest_USERVARS_TYPES` Instrument
+
+*McStas: USERVARS of non-double type, several declarations per line, USERVARS+EXTEND*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for USERVARS/DECLARE handling in the code generator, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+One unit of intensity is emitted from a 1x1 m square.
+- USERVARS declares "int flag; double wsum;" on ONE line. Before the fix
+only the first declaration on a line was found, so wsum was missing.
+- flag (an int) is set to 1 for x>0 and read by Monitor_nD (user1="flag")
+through particle_getvar(). Before the fix its memory was read as a
+double (garbage); now it is converted, and the [0.5 1.5] range holds
+half of the beam: Flag_I = 0.5. (2 bins: a 1-bin Monitor_nD is 0-D and
+ignores the limits.)
+Note: USERVARS used with Monitor_nD should still be declared double;
+int is used here only to test the conversion.
+- Unittest_UV_check (local component) tests %include "x.hpp", component
+USERVARS followed by EXTEND, and two DECLARE variables on one line. It
+absorbs the particle if its EXTEND-declared USERVAR is missing, so
+AfterCheck_I = 1.
+```
+
+## Examples
+
+- **Test: Detector: AfterCheck_I=1**
+- **Test: Detector: Flag_I=0.5**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_USERVARS_TYPES.instr) for `Unittest_USERVARS_TYPES.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcstas-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/Unittest_UV_check.md b/mcstas-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/Unittest_UV_check.md
new file mode 100644
index 0000000000..5b709f4dee
--- /dev/null
+++ b/mcstas-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/Unittest_UV_check.md
@@ -0,0 +1,39 @@
+# The `Unittest_UV_check` Component
+
+*McStas: Grammar unit test helper for Unittest_USERVARS_TYPES*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Exercises code-generator fixes from
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md:
+- %include "unittest_uv.hpp" (multi-character extension) in SHARE,
+- USERVARS followed by EXTEND: uv_b is declared in the EXTEND block and
+was silently dropped before the fix,
+- two DECLARE variables on one line: only the first was found before.
+
+In TRACE the component writes this instance's uv_b USERVAR (by name,
+"uv_b_", built in INITIALIZE as sprintf is a no-op on GPU) and
+reads it back. If that fails, the particle is
+absorbed, so a monitor after it reads 0 instead of the full intensity.
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_UV_check.comp) for `Unittest_UV_check.comp`.
+
+---
diff --git a/mcstas-comps/examples/Tests_optics/Test_Conics_pairs/README.md b/mcstas-comps/examples/Tests_optics/Test_Conics_pairs/README.md
index 5d8e073ec9..64c9eeb2da 100644
--- a/mcstas-comps/examples/Tests_optics/Test_Conics_pairs/README.md
+++ b/mcstas-comps/examples/Tests_optics/Test_Conics_pairs/README.md
@@ -19,18 +19,18 @@
## Examples
-- **Test: Test_Conics_pairs OPTIC=1 Detector: psd_i_I=6.91402e-13**
-- * %Example: Test_Conics_pairs OPTIC=1 Detector: psd_i_reflections_2_I=6.91402e-13
-- * %Example: Test_Conics_pairs OPTIC=2 fs=100000 Detector: psd_i_I=2.85546e-21
-- * %Example: Test_Conics_pairs OPTIC=2 fs=100000 Detector: psd_i_reflections_2_I=2.85515e-21
-- * %Example: Test_Conics_pairs OPTIC=3 Detector: psd_i_I=6.91402e-13
-- * %Example: Test_Conics_pairs OPTIC=4 ssize=1e-4 Detector: psd_i_I=8.66267e-09
-- * %Example: Test_Conics_pairs quadratic=1 Detector: psd_i_I=5.03026e-13
-- * %Example: Test_Conics_pairs quadratic=1 fs=8 fi=6 Detector: psd_i_I=1.26085e-12
-- * %Example: Test_Conics_pairs OPTIC=2 quadratic=1 fs=100000 Detector: psd_i_I=2.09716e-21
-- * %Example: Test_Conics_pairs OPTIC=3 quadratic=1 Detector: psd_i_I=5.03026e-13
-- * %Example: Test_Conics_pairs OPTIC=3 quadratic=1 fs=8 fi=6 Detector: psd_i_I=9.00287e-13
-- * %Example: Test_Conics_pairs OPTIC=4 quadratic=1 ssize=1e-4 Detector: psd_i_I=6.56678e-09
+- **Test: Test_Conics_pairs OPTIC=1 Detector: psd_i_I=7.13655e-13**
+- * %Example: Test_Conics_pairs OPTIC=1 Detector: psd_i_reflections_2_I=7.13655e-13
+- * %Example: Test_Conics_pairs OPTIC=2 fs=100000 Detector: psd_i_I=3.65133e-21
+- * %Example: Test_Conics_pairs OPTIC=2 fs=100000 Detector: psd_i_reflections_2_I=3.65072e-21
+- * %Example: Test_Conics_pairs OPTIC=3 Detector: psd_i_I=7.13655e-13
+- * %Example: Test_Conics_pairs OPTIC=4 ssize=1e-4 Detector: psd_i_I=8.44676e-09
+- * %Example: Test_Conics_pairs quadratic=1 Detector: psd_i_I=5.23944e-13
+- * %Example: Test_Conics_pairs quadratic=1 fs=8 fi=6 Detector: psd_i_I=1.2236e-12
+- * %Example: Test_Conics_pairs OPTIC=2 quadratic=1 fs=100000 Detector: psd_i_I=2.71421e-21
+- * %Example: Test_Conics_pairs OPTIC=3 quadratic=1 Detector: psd_i_I=5.23944e-13
+- * %Example: Test_Conics_pairs OPTIC=3 quadratic=1 fs=8 fi=6 Detector: psd_i_I=8.80918e-13
+- * %Example: Test_Conics_pairs OPTIC=4 quadratic=1 ssize=1e-4 Detector: psd_i_I=6.42631e-09
## Input parameters
@@ -50,6 +50,8 @@ Parameters in **boldface** are required; the others are optional.
| rmin | m | Radius of the innermost shell | 0.0031416 |
| rmax | m | Radius of the outermost shell | 0.05236 |
| quadratic | | Use the quadratic shell-radius mode instead of the radii vector | 0 |
+| sigma_m | rad | RMS meridional slope (figure) error of the mirrors | 1e-6 |
+| sigma_s | rad | RMS sagittal slope (figure) error of the mirrors | 250e-6 |
## Links
diff --git a/mcstas-comps/examples/Tests_optics/Test_Guides/README.md b/mcstas-comps/examples/Tests_optics/Test_Guides/README.md
index e6b0270f7d..72e21d9982 100644
--- a/mcstas-comps/examples/Tests_optics/Test_Guides/README.md
+++ b/mcstas-comps/examples/Tests_optics/Test_Guides/README.md
@@ -35,7 +35,7 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| Guide | 1 | Choice of Guide component to test, with 1=Guide, 2=Guide_channeled, 3=Guide_gravity, 4=Guide_wavy, 5=Guide_curved 6=Elliptic_guide_gravity 7=Guide_honeycomb | 1 |
+| Guide | 1 | Choice of Guide component to test, with 1=Guide, 2=Guide_channeled, 3=Guide_gravity, 4=Guide_wavy, 5=Guide_curved, 6=Elliptic_guide_gravity, 7=Guide_anyshape, 8=Guide_honeycomb, 9=Guide_anyshape with per-face coatings read from the OFF file (file_coatings=1) | 1 |
## Links
diff --git a/mcstas-comps/examples/Tests_optics/Test_Mirror_FlatEllipse/README.md b/mcstas-comps/examples/Tests_optics/Test_Mirror_FlatEllipse/README.md
new file mode 100644
index 0000000000..599ca6629c
--- /dev/null
+++ b/mcstas-comps/examples/Tests_optics/Test_Mirror_FlatEllipse/README.md
@@ -0,0 +1,56 @@
+# The `Test_Mirror_FlatEllipse` Instrument
+
+*McStas: Compares a (nearly flat) FlatEllipse_finite_mirror with Mirror.comp*
+
+## Identification
+
+- **Site:** Tests_optics
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** October 2026
+
+## Description
+
+```text
+A collimated, polychromatic beam hits a single mirror at grazing angle theta.
+The mirror is either Mirror.comp with transmit=1, or a single-mirror
+FlatEllipse_finite_mirror (conic.h, mirror_width=0) with foci at +/- focus,
+which for the default focus=10 km is flat to within ~1e-10 rad over the mirror.
+Reflected and transmitted beams are recorded separately as function of wavelength,
+and the two COMP settings should give the same result.
+
+COMP=0: Mirror, transmit=1
+COMP=1: FlatEllipse_finite_mirror, nummirror=1, mirror_width=0
+```
+
+## Examples
+
+- **Test: COMP=0 Detector: L_refl_I=8.98208e-07**
+- **Test: COMP=1 Detector: L_refl_I=8.98208e-07**
+- **Test: COMP=0 Detector: L_trans_I=7.01789e-07**
+- **Test: COMP=1 Detector: L_trans_I=7.01789e-07**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| COMP | 1 | Mirror implementation, see description | 0 |
+| theta | deg | Grazing angle of the beam on the mirror | 1 |
+| length | m | Mirror length | 1 |
+| m | 1 | Mirror m-value | 2 |
+| R0 | 1 | Low-angle reflectivity | 0.99 |
+| Qc | AA^-1 | Critical scattering vector | 0.0217 |
+| alpha | AA | Slope of reflectivity | 6.07 |
+| W | AA^-1 | Width of supermirror cut-off | 0.003 |
+| Lmin | AA | Minimum source wavelength | 1 |
+| Lmax | AA | Maximum source wavelength | 11 |
+| focus | m | Distance from the mirror centre to each of the ellipse foci | 1e4 |
+| r0 | m | Distance from the FlatEllipse_finite_mirror optical axis to the mirror | 0.1 |
+
+## Links
+
+- [Source code](Test_Mirror_FlatEllipse.instr) for `Test_Mirror_FlatEllipse.instr`.
+
+---
diff --git a/mcstas-comps/examples/Tests_optics/Test_Mirror_conic/README.md b/mcstas-comps/examples/Tests_optics/Test_Mirror_conic/README.md
new file mode 100644
index 0000000000..13e56b3cfc
--- /dev/null
+++ b/mcstas-comps/examples/Tests_optics/Test_Mirror_conic/README.md
@@ -0,0 +1,65 @@
+# The `Test_Mirror_conic` Instrument
+
+*McStas: Compares the conic.h reflection routines with Mirror.comp*
+
+## Identification
+
+- **Site:** Tests_optics
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** October 2026
+
+## Description
+
+```text
+A collimated, polychromatic beam hits a single flat mirror at grazing angle theta.
+The mirror is either Mirror.comp or Mirror_conic.comp, which uses the reflection
+routines from conic.h (as used by Conics_*, FlatEllipse_finite_mirror and NMO).
+Reflected and transmitted beams are recorded separately as function of wavelength.
+For a given theta, pairs of COMP settings should give identical results:
+
+COMP=0: Mirror, transmit=1 (reference for COMP=1)
+COMP=1: Mirror_conic, conic=0 (FlatSurf, reflectNeutronFlat)
+COMP=2: Mirror, transmit=0 (reference for COMP=3)
+COMP=3: Mirror_conic, conic=1 (ConicSurf, reflectNeutronConic)
+
+COMP=0 and COMP=1 should agree exactly, and so should COMP=2 and COMP=3 when
+no figure error is applied (sigma_m=sigma_s=0).
+With sigma_m comparable to the grazing angle (e.g. theta=0.1 sigma_m=1.745e-3),
+COMP=3 uses the waviness model of Hansen et al., arXiv:1612.03763 (see conic.h).
+```
+
+## Examples
+
+- **Test: COMP=0 Detector: L_refl_I=8.98208e-07**
+- **Test: COMP=1 Detector: L_refl_I=8.98208e-07**
+- **Test: COMP=0 Detector: L_trans_I=7.01789e-07**
+- **Test: COMP=1 Detector: L_trans_I=7.01789e-07**
+- **Test: COMP=2 Detector: L_refl_I=8.9763e-07**
+- **Test: COMP=3 Detector: L_refl_I=8.9763e-07**
+- **Test: COMP=3 theta=0.1 sigma_m=1.745e-3 Detector: L_refl_I=1.35886e-06**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| COMP | 1 | Mirror implementation, see description | 0 |
+| theta | deg | Grazing angle of the beam on the mirror | 1 |
+| length | m | Mirror length | 1 |
+| m | 1 | Mirror m-value | 2 |
+| R0 | 1 | Low-angle reflectivity | 0.99 |
+| Qc | AA^-1 | Critical scattering vector | 0.0217 |
+| alpha | AA | Slope of reflectivity | 6.07 |
+| W | AA^-1 | Width of supermirror cut-off | 0.003 |
+| Lmin | AA | Minimum source wavelength | 1 |
+| Lmax | AA | Maximum source wavelength | 11 |
+| sigma_m | rad | RMS meridional slope (figure) error, COMP=3 only | 0 |
+| sigma_s | rad | RMS sagittal slope (figure) error, COMP=3 only | 0 |
+
+## Links
+
+- [Source code](Test_Mirror_conic.instr) for `Test_Mirror_conic.instr`.
+
+---
diff --git a/mcstas-comps/examples/Tests_polarization/SE_example/README.md b/mcstas-comps/examples/Tests_polarization/SE_example/README.md
index 7f08148ac7..64e96d3829 100644
--- a/mcstas-comps/examples/Tests_polarization/SE_example/README.md
+++ b/mcstas-comps/examples/Tests_polarization/SE_example/README.md
@@ -23,7 +23,7 @@ Example: mcrun SE_example.instr dBz=-0.0001,0.0001 -N41 -n1e5
## Examples
-
+- **TestScan: mcrun SE_example.instr dBz=-0.0001,0.0001 -N41 -n1e5 Detector: detector_I={41 values}**
## Input parameters
diff --git a/mcstas-comps/examples/Tests_polarization/SE_example2/README.md b/mcstas-comps/examples/Tests_polarization/SE_example2/README.md
index 3442174fde..3de2545517 100644
--- a/mcstas-comps/examples/Tests_polarization/SE_example2/README.md
+++ b/mcstas-comps/examples/Tests_polarization/SE_example2/README.md
@@ -17,13 +17,11 @@ This instrument shows the use of essential McStas polarisation components, inclu
Pol_mirror is used to polarize and analyze the incoming and scattered beams.
Pol_FieldBox is used to define guidefields and flippers.
MeanPolLambda_montior is used to monitor beam polarisation.
-
-Example: mcrun SE_example2.instr dBz=-0.0001,0.0001 -N41 -n1e5
```
## Examples
-
+- **TestScan: mcrun SE_example2.instr dBz=-0.0001,0.0001 -N41 -n1e5 Detector: detector_I={41 values}**
## Input parameters
diff --git a/mcstas-comps/examples/Tests_samples/Samples_Incoherent/README.md b/mcstas-comps/examples/Tests_samples/Samples_Incoherent/README.md
index f43991d4c9..83165be719 100644
--- a/mcstas-comps/examples/Tests_samples/Samples_Incoherent/README.md
+++ b/mcstas-comps/examples/Tests_samples/Samples_Incoherent/README.md
@@ -62,6 +62,9 @@ cube.off: 6=PowderN,
- **Test: SAMPLE=8 STOP=1 -n 1e5 Detector: PSD_Sphere_4pi_I=1.3233e+06**
- **Test: SAMPLE=9 STOP=1 -n 1e5 Detector: PSD_Sphere_4pi_I=1.3239e+06**
- **Test: SAMPLE=10 STOP=1 -n 1e5 Detector: PSD_Sphere_4pi_I=1.28905e+06**
+- **TestScan: mcrun Samples_Incoherent.instr SAMPLE=1,5 -N5 STOP=1 Detector: PSD_Sphere_4pi_I={5 values}**
+- **TestScan: mcrun Samples_Incoherent.instr SAMPLE=2,5 -N4 STOP=0 Detector: PSD_Sphere_4pi_I={4 values}**
+- **TestScan: mcrun Samples_Incoherent.instr SAMPLE=2,5 -N4 STOP=0 DB=1 Detector: Dirbeam_I={4 values}**
## Input parameters
diff --git a/mcstas-comps/examples/Tests_samples/Test_Dispersion_relation_TAS/README.md b/mcstas-comps/examples/Tests_samples/Test_Dispersion_relation_TAS/README.md
index 75964742af..99b4299b1d 100644
--- a/mcstas-comps/examples/Tests_samples/Test_Dispersion_relation_TAS/README.md
+++ b/mcstas-comps/examples/Tests_samples/Test_Dispersion_relation_TAS/README.md
@@ -46,8 +46,6 @@ For the magnon, h, k, l are the MnF2 indices (a = b = 4.873 AA, c = 3.130 AA,
along x, y, z for both samples), and (h, l) = (1, 0) is the magnetic zone
centre MnF2 (1 0 0).
-Example: mcrun Test_Dispersion_relation_TAS.instr -M -N 21,21 -n 2e5 h=0.6,1.4 l=0.6,1.4 dE=5 sample_choice=0
-
The dispersion files are written by the SHELL command below when the
instrument is compiled, if they do not exist yet, by
generate_dispersion_files.py (Python with numpy).
@@ -60,6 +58,7 @@ generate_dispersion_files.py (Python with numpy).
- **Test: h=1.2 l=1 dE=5 sample_choice=0 primitive_cell=1 Detector: detector_I=1.46e-11**
- **Test: h=1.15 l=0 dE=3 T=2 sample_choice=2 Detector: detector_I=8.91e-10**
- **Test: h=1.15 l=0 dE=3 T=2 sample_choice=3 Detector: detector_I=9.41e-10**
+- **TestScan: mcrun Test_Dispersion_relation_TAS.instr -M -N 5,5 -n 2e5 h=0.8,1.2 l=1.1,1.3 dE=5 sample_choice=0 Detector: detector_I={25 values}**
## Input parameters
diff --git a/mcstas-comps/examples/Tests_samples/Test_Magnon_bcc_TAS/README.md b/mcstas-comps/examples/Tests_samples/Test_Magnon_bcc_TAS/README.md
index f1066af2eb..1abd453cfc 100644
--- a/mcstas-comps/examples/Tests_samples/Test_Magnon_bcc_TAS/README.md
+++ b/mcstas-comps/examples/Tests_samples/Test_Magnon_bcc_TAS/README.md
@@ -17,8 +17,8 @@ Generic TAS instrument for test of samples with dispersions. Modeled over the RI
## Examples
-- **Test: Test_Magnon_bcc_TAS.instr hw=0.5 Detector: e_monitor1_I=460000**
-- Example: Test_Magnon_bcc_TAS.instr hw=0,1 -N21
+- **Test: Test_Magnon_bcc_TAS.instr hw=0.5 Detector: e_monitor1_I=4.97e5**
+- **TestScan: mcrun Test_Magnon_bcc_TAS.instr hw=0,1 -N21 -n1e6 Detector: e_monitor_I={21 values}**
## Input parameters
diff --git a/mcstas-comps/examples/Tests_samples/Test_PowderN_Res/README.md b/mcstas-comps/examples/Tests_samples/Test_PowderN_Res/README.md
index 54f7be780b..a1f554fdc5 100644
--- a/mcstas-comps/examples/Tests_samples/Test_PowderN_Res/README.md
+++ b/mcstas-comps/examples/Tests_samples/Test_PowderN_Res/README.md
@@ -17,12 +17,11 @@ Idealized powder diffractometer, to illustrate the difference between 'banana,th
The beam from the source is very low-divergent, to allow studying effects at the sample "only".
By default, absorption in the sample is effectively suppressed.
-
-Example: Lambda0=2.5667 dLambda=0.01 radius=0.001,0.021 TT=71.8 D_PHI=6 SPLITS=117 Distance=30 sig_abs=1e-09 -N21
```
## Examples
+- **TestScan: mcrun Test_PowderN_Res.instr Lambda0=2.5667 dLambda=0.01 radius=0.001,0.021 TT=71.8 D_PHI=6 SPLITS=117 Distance=30 sig_abs=1e-09 -N21 Detector: DetectorSmall_I={21 values}**
- **Test: Lambda0=2.5667 dLambda=0.01 radius=0.01 TT=71.8 D_PHI=6 SPLITS=117 Distance=30 sig_abs=1e-09 Detector: DetectorSmall_I=288.57**
## Input parameters
diff --git a/mcstas-comps/examples/Tests_samples/Test_SANS/README.md b/mcstas-comps/examples/Tests_samples/Test_SANS/README.md
index 7617ddd7c6..7cc1a37302 100644
--- a/mcstas-comps/examples/Tests_samples/Test_SANS/README.md
+++ b/mcstas-comps/examples/Tests_samples/Test_SANS/README.md
@@ -31,7 +31,7 @@ SANSPDBFast SAMPLE=11
## Examples
-- **Test: SAMPLE=0 Detector: PSDMonitor_I=2.529e-09**
+- **Test: SAMPLE=0 Detector: PSDMonitor_I=2.9e-09**
- **Test: SAMPLE=1 Detector: PSDMonitor_I=2.486e-10**
- **Test: SAMPLE=2 Detector: PSDMonitor_I=2.297e-10**
- **Test: SAMPLE=3 Detector: PSDMonitor_I=8.720e-11**
diff --git a/mcstas-comps/examples/Tests_samples/Test_TasReso/README.md b/mcstas-comps/examples/Tests_samples/Test_TasReso/README.md
index 29f3288696..d196056dc6 100644
--- a/mcstas-comps/examples/Tests_samples/Test_TasReso/README.md
+++ b/mcstas-comps/examples/Tests_samples/Test_TasReso/README.md
@@ -33,7 +33,7 @@ along with this program. If not, see http://www.gnu.org/licenses/.
## Examples
-- **Test: src_lam=4.5 Detector: emon_I=887.137**
+- **Test: src_lam=4.5 Detector: emon_I=960**
## Input parameters
diff --git a/mcxtrace-comps/examples/BARC/Czerny_Turner/README.md b/mcxtrace-comps/examples/BARC/Czerny_Turner/README.md
index 8d61bfe86c..fce75b8183 100644
--- a/mcxtrace-comps/examples/BARC/Czerny_Turner/README.md
+++ b/mcxtrace-comps/examples/BARC/Czerny_Turner/README.md
@@ -23,6 +23,7 @@ Example: Do a scan (scan parameter =1) from x_screw=20 to 103 mm. The calculated
## Examples
- **Test: x_screw=60 Detector: w_monitor_I=1.10881e-06**
+- **TestScan: mxrun Czerny_Turner.instr -N21 x_screw=20,103 scan=1 -n1e6 Detector: Wavelength_I={21 values}**
## Input parameters
diff --git a/mcxtrace-comps/examples/MAXII/MAXII_711/README.md b/mcxtrace-comps/examples/MAXII/MAXII_711/README.md
index 4e4b6845d4..e0f7fc61a2 100644
--- a/mcxtrace-comps/examples/MAXII/MAXII_711/README.md
+++ b/mcxtrace-comps/examples/MAXII/MAXII_711/README.md
@@ -18,7 +18,7 @@ a monochromator, and a four-circle goniometer at the sample stage.
## Examples
-- **Test: MAXII_711.instr R=-100 tth=28 dphi=30 -n1e7 Detector: mono_exit_psd_I=5.1609e-06**
+- **Test: MAXII_711.instr R=-100 tth=28 dphi=30 Detector: mono_exit_psd_I=5.1609e-06**
## Input parameters
diff --git a/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd1d/README.md b/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd1d/README.md
index 464fbae7ed..b456b6a013 100644
--- a/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd1d/README.md
+++ b/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd1d/README.md
@@ -19,7 +19,7 @@ as the multilayer.
## Examples
-- **Test: MAXIV_DanMAX_pxrd1d.instr -c -n1e6 E0=15 PXRD_SIMPLE=1 Detector: dm_strip_banana_I=0.00081782**
+- **Test: MAXIV_DanMAX_pxrd1d.instr -c E0=15 PXRD_SIMPLE=1 Detector: dm_strip_banana_I=0.00081782**
## Input parameters
diff --git a/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd2d/README.md b/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd2d/README.md
index 7b399ccde6..ee6cb0a63f 100644
--- a/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd2d/README.md
+++ b/mcxtrace-comps/examples/MAXIV/MAXIV_DanMAX_pxrd2d/README.md
@@ -19,7 +19,7 @@ as the multilayer.
## Examples
-- **Test: MAXIV_DanMAX_pxrd2d.instr -c -n1e6 E0=15 Detector: Pilatus_2M_I=8.10837e-05**
+- **Test: MAXIV_DanMAX_pxrd2d.instr -c E0=15 Detector: Pilatus_2M_I=8.10837e-05**
## Input parameters
diff --git a/mcxtrace-comps/examples/NIST/DBD_IBM_Si_analyzer_BC/README.md b/mcxtrace-comps/examples/NIST/DBD_IBM_Si_analyzer_BC/README.md
index a6acd602ba..36190a05de 100644
--- a/mcxtrace-comps/examples/NIST/DBD_IBM_Si_analyzer_BC/README.md
+++ b/mcxtrace-comps/examples/NIST/DBD_IBM_Si_analyzer_BC/README.md
@@ -17,7 +17,7 @@ This is a preliminary setup of the DBD with the Ge111 Johansson IBM
## Examples
-- **Test: use_flat_source=0 -n1e7 Detector: focus_monitor_I=2.38803e+10**
+- **Test: use_flat_source=0 Detector: focus_monitor_I=2.38803e+10**
## Input parameters
diff --git a/mcxtrace-comps/examples/NSLS2/NSLS2_CHX/README.md b/mcxtrace-comps/examples/NSLS2/NSLS2_CHX/README.md
index aaed287782..1251ebc68b 100644
--- a/mcxtrace-comps/examples/NSLS2/NSLS2_CHX/README.md
+++ b/mcxtrace-comps/examples/NSLS2/NSLS2_CHX/README.md
@@ -22,7 +22,7 @@ high emittance (e=0.99nm).
## Examples
-- **Test: NSLS2_CHX -n1e6 L=33.5 L2=35.3 L3=44 Energy=10 Detector: Det_ff_I=2.82787e+16**
+- **Test: NSLS2_CHX L=33.5 L2=35.3 L3=44 Energy=10 Detector: Det_ff_I=2.82787e+16**
## Input parameters
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL/README.md
new file mode 100644
index 0000000000..39e5928947
--- /dev/null
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL/README.md
@@ -0,0 +1,36 @@
+# The `SOLEIL` Instrument
+
+*McXtrace: SOLEIL model*
+
+## Identification
+
+- **Site:** SOLEIL
+- **Author:** E. Farhi
+- **Origin:** SOLEIL
+- **Date:** Oct 2026
+
+## Description
+
+```text
+This is a model of the Synchrotron SOLEIL with a set of beam-lines.
+It has been assembled mostly for rendering purposes.
+For any beam-line study, you are encouraged to refer to its specific model.
+```
+
+## Examples
+
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| splits | 1 | shared SPLIT level. | 1 |
+
+## Links
+
+- [Source code](SOLEIL.instr) for `SOLEIL.instr`.
+
+---
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_ANATOMIX/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_ANATOMIX/README.md
index 706155e3c2..f22e6221b0 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_ANATOMIX/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_ANATOMIX/README.md
@@ -60,7 +60,7 @@ EH4 | 197.2-208.5 | Guard slits; microtomography sample stage; detec
## Examples
-- **Test: -n 1e5 E0=17 Detector: psd_monitor_after_cc_I=1e18**
+- **Test: -n 1e5 ANATOMIX_E0=17 Detector: ANATOMIX_psd_monitor_after_cc_I=1e18**
## Input parameters
@@ -68,11 +68,11 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Energy selected at the Undulator. | 11 |
-| Emono | keV | Energy selected at the monochromator. When 0, it is set to E0. | 0 |
-| dE | keV | Energy spread at the Undulator. | 1 |
-| ANGLE | deg | Rotation angle of the sample stage. | 0 |
-| sample | str | Sample geometry file, OFF/PLY format. | "wire.ply" |
+| ANATOMIX_E0 | keV | Energy selected at the Undulator. | 11 |
+| ANATOMIX_Emono | keV | Energy selected at the monochromator. When 0, it is set to E0. | 0 |
+| ANATOMIX_dE | keV | Energy spread at the Undulator. | 1 |
+| ANATOMIX_ANGLE | deg | Rotation angle of the sample stage. | 0 |
+| ANATOMIX_sample | | | "wire.ply" |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_CASSIOPEE/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_CASSIOPEE/README.md
index ca443ff59f..046937dcb9 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_CASSIOPEE/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_CASSIOPEE/README.md
@@ -33,7 +33,7 @@ Position | Element
## Examples
-- **Test: E0=0 Detector: PSD_M1out_I=2.74309e+15**
+- **Test: CASSIOPEE_E0=0 Detector: CASSIOPEE_PSD_M1out_I=2.74309e+15**
## Input parameters
@@ -41,16 +41,16 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| mirror_material | str | Mirror M1 coating (e.g. Pt.dat) | "Pt.dat" |
-| undulator_index | 1-2 | Undulator 1=HU60; 2=HU256 | 1 |
-| M1_angle | deg | M1 mirror angle. 0=auto | 0 |
-| PG_angle | deg | Reflective grating monochromator. 0=auto | 0 |
-| PM_angle | deg | M2 mirror angle. 0=auto | 0 |
-| E0 | keV | Undulator emission energy, e.g. 40e-3 or 300e-3 keV. 0=auto | 0 |
-| dE | keV | Undulator energy bandwidth, e.g. 1e-3. | 1e-3 |
-| lambda | Ang | Undulator emission wavelength. Used when E0=0. | 0 |
-| beta_mono | deg | Monochromator angle. 0=auto | 0 |
-| r_rho | /mm | Grating number of lines/mm. 0=auto. | 0 |
+| CASSIOPEE_mirror_material | str | Mirror M1 coating (e.g. Pt.dat) | "Pt.dat" |
+| CASSIOPEE_undulator_index | 1-2 | Undulator 1=HU60; 2=HU256 | 1 |
+| CASSIOPEE_M1_angle | deg | M1 mirror angle. 0=auto | 0 |
+| CASSIOPEE_PG_angle | deg | Reflective grating monochromator. 0=auto | 0 |
+| CASSIOPEE_PM_angle | deg | M2 mirror angle. 0=auto | 0 |
+| CASSIOPEE_E0 | keV | Undulator emission energy, e.g. 40e-3 or 300e-3 keV. 0=auto | 0 |
+| CASSIOPEE_dE | keV | Undulator energy bandwidth, e.g. 1e-3. | 1e-3 |
+| CASSIOPEE_lambda | Ang | Undulator emission wavelength. Used when CASSIOPEE_E0=0. | 0 |
+| CASSIOPEE_beta_mono | deg | Monochromator angle. 0=auto | 0 |
+| CASSIOPEE_r_rho | /mm | Grating number of lines/mm. 0=auto. | 0 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_CRISTAL/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_CRISTAL/README.md
index c8a816e93c..ec94d655ed 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_CRISTAL/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_CRISTAL/README.md
@@ -12,7 +12,7 @@
## Description
```text
-CRISTAL is a diffraction beam-line covering 5-30 keV (dE/E ~1e-4), fed by an
+CRISTAL is a diffraction beam-line covering 5-30 keV (CRISTAL_dE/E ~1e-4), fed by an
in-vacuum U20 undulator (98 periods, 20 mm period). The optical layout, in
beam order, is: primary slit, Si(111) double-crystal monochromator (DCM,
second crystal sagittally bent for horizontal focusing - not modelled here
@@ -27,7 +27,7 @@ omitted for simplicity.
## Examples
-- **Test: E0=12 Detector: detector_diffraction_I=700000.0**
+- **Test: CRISTAL_E0=12 Detector: CRISTAL_detector_diffraction_I=700000.0**
## Input parameters
@@ -35,14 +35,15 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Central energy of the beam | 12 |
-| dE | keV | Energy half-bandwidth at the photon source | 1e-4 |
-| M1_angle | mrad | Grazing angle of the first (bendable) horizontal mirror | 3 |
-| M2_angle | mrad | Grazing angle of the second horizontal mirror | 3 |
-| M1_radius | m | Bending radius of mirror M1 (0=flat) | 0 |
-| M2_radius | m | Bending radius of mirror M2 (0=flat) | 0 |
-| M_coating | str | Mirror coating (Rh or Pt stripe), e.g. "Rh.txt" or "Pt.dat" | "Rh.txt" |
-| reflections | str | Sample structure file, LAU/CIF format | "LaB6_660b_AVID2.hkl" |
+| CRISTAL_E0 | keV | Central energy of the beam | 12 |
+| CRISTAL_dE | keV | Energy half-bandwidth at the photon source | 1e-4 |
+| CRISTAL_M1_angle | mrad | Grazing angle of the first (bendable) horizontal mirror | 3 |
+| CRISTAL_M2_angle | mrad | Grazing angle of the second horizontal mirror | 3 |
+| CRISTAL_M1_radius | m | Bending radius of mirror M1 (0=flat) | 0 |
+| CRISTAL_M2_radius | m | Bending radius of mirror M2 (0=flat) | 0 |
+| CRISTAL_M_coating | str | Mirror coating (Rh or Pt stripe), e.g. "Rh.txt" or "Pt.dat" | "Rh.txt" |
+| CRISTAL_reflections | | | "LaB6_660b_AVID2.hkl" |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_DIFFABS/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_DIFFABS/README.md
index a943ec066d..40055722a6 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_DIFFABS/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_DIFFABS/README.md
@@ -38,11 +38,13 @@ Position | Element
31.227 | a KB mirror set M3/M4 for micro focusing. We ignore them here.
31.45 | sample stage with e.g. Fluorescence and/or PowderN components. At 13.99 from DCM.
32.09 | a set of detectors (transmission, XRD and XRF), radius 654 mm
+
+Example: DIFFABS_E0=13 Detector: DIFFABS_sample_stage_I=2.20096e+10
```
## Examples
-- **Test: E0=13 Detector: sample_stage_I=2.20096e+10**
+
## Input parameters
@@ -50,13 +52,14 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Central energy of the interval to be looked at | 13 |
-| dE | keV | Half-width of the energy interval | 1 |
-| M1_angle | mrad | Rotation angle of M1/M2 mirrors. When left as 0, it is set automatically from E0. | 0 |
-| M1_radius | m | Curvature radius of M1 mirror (Rh, 1300x100) longitudinal. Positive=mirror is focusing. 0=flat. | 1400 |
-| M2_radius | m | Curvature radius of M2 mirror (Rh, 1300x100) sagittal. Positive=mirror is focusing. 0=flat. | 1400 |
-| DCM_theta | deg | Rotation angle of DCM crystals. When left as 0, it is set automatically from E0. | 0 |
-| sample | str | Sample structure file, LAU/CIF format. | "LaB6_660b_AVID2.hkl" |
+| DIFFABS_E0 | keV | Central energy of the interval to be looked at | 13 |
+| DIFFABS_dE | keV | Half-width of the energy interval | 1 |
+| DIFFABS_M1_angle | mrad | Rotation angle of M1/M2 mirrors. When left as 0, it is set automatically from DIFFABS_E0. | 0 |
+| DIFFABS_M1_radius | m | Curvature radius of M1 mirror (Rh, 1300x100) longitudinal. Positive=mirror is focusing. 0=flat. | 1400 |
+| DIFFABS_M2_radius | m | Curvature radius of M2 mirror (Rh, 1300x100) sagittal. Positive=mirror is focusing. 0=flat. | 1400 |
+| DIFFABS_DCM_theta | deg | Rotation angle of DCM crystals. When left as 0, it is set automatically from DIFFABS_E0. | 0 |
+| DIFFABS_sample | str | Sample structure file, LAU/CIF format. | "LaB6_660b_AVID2.hkl" |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_DISCO/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_DISCO/README.md
index 25ed833ab4..5eed2352af 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_DISCO/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_DISCO/README.md
@@ -13,13 +13,14 @@
```text
DISCO beamline description here: https://hal.archives-ouvertes.fr/hal-01479318/document
-You may scan the grating monochromator with e.g.:
-mxrun -n 1e5 SOLEIL_DISCO.instr -N84 x_screw=20,103 scan=1
+You may DISCO_scan the grating monochromator with e.g.:
```
## Examples
-- **Test: grazing_angle_one=22.5 -n 1e5 Detector: second_HFP_I=2.08292e+11**
+- **TestScan: mxrun SOLEIL_DISCO.instr -N21 DISCO_x_screw=20,103 DISCO_scan=1 Detector: Wavelength_I={21 values}**
+-
+- **Test: DISCO_grazing_angle_one=22.5 -n 1e5 Detector: DISCO_second_HFP_I=2.08292e+11**
## Input parameters
@@ -27,12 +28,13 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| grazing_angle_one | deg | Mirrors M1/M2 rotation angle | 22.5 |
-| HFP_shift | m | z translation from the HFP position (horizontal focal point detector) | 0 |
-| VFP_shift | m | z translation from the VFP position (vertical focal point detector) | 0 |
-| second_HFP_shift | m | z translation second HFP position | 0 |
-| x_screw | mm | length of the screw | 50 |
-| scan | | if there is an x_screw scan [1], calculate the Wavelength(Angstroms) as a function of x_screw(mm) | 0 |
+| DISCO_grazing_angle_one | deg | Mirrors M1/M2 rotation angle | 22.5 |
+| DISCO_HFP_shift | m | z translation from the HFP position (horizontal focal point detector) | 0 |
+| DISCO_VFP_shift | m | z translation from the VFP position (vertical focal point detector) | 0 |
+| DISCO_second_HFP_shift | m | z translation second HFP position | 0 |
+| DISCO_x_screw | mm | length of the screw | 50 |
+| DISCO_scan | | if there is an DISCO_x_screw DISCO_scan [1], calculate the Wavelength(Angstroms) as a function of DISCO_x_screw(mm) | 0 |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_GALAXIES/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_GALAXIES/README.md
new file mode 100644
index 0000000000..cd6b7f14a3
--- /dev/null
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_GALAXIES/README.md
@@ -0,0 +1,78 @@
+# The `SOLEIL_GALAXIES` Instrument
+
+*McXtrace: The GALAXIES beam-line at Synchrotron SOLEIL - RIXS branch.*
+
+## Identification
+
+- **Site:** SOLEIL
+- **Author:** E. Farhi, from SOLEIL technical notes by T. Moreno
+- **Origin:** Synchrotron SOLEIL
+- **Date:** 2026
+
+## Description
+
+```text
+GALAXIES is dedicated to inelastic X-ray scattering (IXS/RIXS) and hard
+X-ray photoemission (HAXPES), in the 2.3-12 keV range, with high resolution
+and micro-beam. This model implements the RIXS station (35.5 m diffractometer
+with a 1-2 m radius IXS spectrometer, multi-analyzer 4x1 or 2x2 setup).
+The HAXPES branch ends at the secondary slits (28.2 m).
+
+Optical layout (distances from the undulator center, EXP-OPT-CDC-1029):
+
+Position | Element
+---------|--------------------------------------------------------------------
+0 | U20 undulator, 98 periods, lambda_u=20 mm, short section
+10 | Absorber 2.5 x 2.5 mm^2
+11.7 | Diaphragm 1.8 x 0.6 mm^2 (H x V): beamline acceptance
+17 | Primary slits 2.0 x 0.7 mm^2 (H x V)
+19 | Si(111) DCM, fixed exit, crystals 10x50 mm^2 (T x L)
+22 | M1 spherical mirror R=8.81 km, 5 mrad, face up, 200 mm, B4C/Pd
+23.5 | 2 channel-cuts (anti-symmetric) Si311 (1st order) / Si220 (2nd order)
+24.89 | M2A toroid (microfocus): focus at secondary slits 28.2 m [HAXPES]
+28.2 | Secondary slits 30x30 um^2 min (M2A focal plane, HAXPES sample)
+32.20 | M2B toroid (intermediate focus): focus at RIXS sample 35.5 m
+34.1 | VFM elliptical KB mirror, p=5.9 m, q=1.4 m, 320 mm, Pd
+34.5 | HFM elliptical KB mirror, p=6.3 m, q=1.0 m, 320 mm, Pd
+35.5 | RIXS sample / diffractometer
++R | IXS spectrometer: spherical Si analyzers (Rowland R=0.5-2 m)
+
+Toroid radii and M2 positions are the post-metrology (SESO measured) values
+from EXP-OPT-CDC-1936: Rt=1.335 km, Rs=30.47 mm, M2A at 24.89 m and M2B at
+32.20 m, grazing angle 4.95 mrad, so that the foci stay at 28.2 m (HAXPES)
+and 35.5 m (RIXS).
+
+The electron beam in the short section (EXP-OPT-CDC-0771):
+sigma_x=388 um, sigma_z=8.1 um, sigma'_x=14.5 urad, sigma'_z=4.6 urad.
+
+Expected performance (ray tracing, EXP-OPT-CDC-1029):
+- M2B focus: 75 x 35 um^2 FWHM (H x V), ~6e13 ph/s @ 8 keV
+- KB focus: 14 x 9 um^2 FWHM (open sec. slits), 5x7 um^2 (30x30 um^2 slits)
+```
+
+## Examples
+
+- **Test: GALAXIES_E0=10 Detector: GALAXIES_mon_dcm_xy_I=6.05992e+12**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| GALAXIES_E0 | keV | Nominal energy (2.3 - 12). | 10 |
+| GALAXIES_dE | keV | Energy half-bandwidth at the source. | 0.1 |
+| GALAXIES_hrm | 1 | 1 = insert the high resolution channel-cuts. | 0 |
+| GALAXIES_hrm_ref | str | "Si311" (1st order, >=5 keV) or "Si220" (2nd order, >=8 keV). | "Si311" |
+| GALAXIES_sec_slits | m | Secondary slits opening (H and V) at the M2A focus (28.2 m). | 0.1 |
+| GALAXIES_ana_R | m | Analyzer Rowland radius (0.5 - 2 m). | 1.0 |
+| GALAXIES_ana_deg | deg | Spectrometer scattering angle (2-theta at the sample). | 10 |
+| GALAXIES_sample | str | Sample LAU/CIF structure file for the RIXS sample. | "Si.lau" |
+| splits | | | 10 |
+
+## Links
+
+- [Source code](SOLEIL_GALAXIES.instr) for `SOLEIL_GALAXIES.instr`.
+- https://www.synchrotron-soleil.fr/en/beamlines/galaxies
+
+---
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_LUCIA/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_LUCIA/README.md
index 376bab5750..026b2cdb56 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_LUCIA/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_LUCIA/README.md
@@ -19,14 +19,14 @@ The sample is a kind of biological cell.
Position | Element
---------|--------------------------------------------------------------------
0 | HU52 undulator "Apple II" type, 32 periods, gap 15-150mm
-20 | Si(111) DCM, 40x40x10 mm^3 E0=5-16 keV
+20 | Si(111) DCM, 40x40x10 mm^3 LUCIA_E0=5-16 keV
29 | Sample location
29.1 | Fluorescence Detector at 90 deg
```
## Examples
-- **Test: -n 1e7 E0=3.09 Detector: mon_spl_SDD_I=9.69081e+09**
+- **Test: -n 1e7 LUCIA_E0=3.09 Detector: LUCIA_mon_spl_SDD_I=9.69081e+09**
## Input parameters
@@ -34,11 +34,12 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Nominal energy at the source, in 0.6-8 keV. | 3.09 |
-| dE | keV | Energy half-bandwidth at the source. | 0.02 |
-| dcm_theta | deg | Rotation angle of the DCM. 0=set from energy E0. | 38.9 |
-| sample_material | str | Absorption data file for the sample. | "CaCO3AlP" |
-| sample_geometry | str | OFF/PLY file name for sample 3D geometry, or NULL for a box. | "plant_cell.ply" |
+| LUCIA_E0 | keV | Nominal energy at the source, in 0.6-8 keV. | 3.09 |
+| LUCIA_dE | keV | Energy half-bandwidth at the source. | 0.02 |
+| LUCIA_dcm_theta | deg | Rotation angle of the DCM. 0=set from energy LUCIA_E0. | 38.9 |
+| LUCIA_sample_material | str | Absorption data file for the sample. | "CaCO3AlP" |
+| LUCIA_sample_geometry | str | OFF/PLY file name for sample 3D geometry, or NULL for a box. | "plant_cell.ply" |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_MARS/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_MARS/README.md
index 1cd7fb8687..a7eb00befa 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_MARS/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_MARS/README.md
@@ -28,7 +28,7 @@ This model implements the XRD station for powders.
## Examples
-- **Test: E0=16.99 Detector: detector_diffraction_I=2.56e+09**
+- **Test: MARS_E0=16.99 Detector: MARS_detector_diffraction_I=2.56e+09**
## Input parameters
@@ -36,11 +36,12 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Central energy to be emitted by the source | 16.99 |
-| reflec_material_M12 | str | reflecting coating on curved mirrors, e.g. Pt | "Pt.dat" |
-| reflections | str | Sample structure file, LAU/CIF format. | "LaB6_660b_AVID2.hkl" |
-| dEr | 1 | Relative half width to emitted by the source, e.g. 1e-4 | 1e-4 |
-| alpha | deg | Asymmetry angle for the crystals. | 0 |
+| MARS_E0 | keV | Central energy to be emitted by the source | 16.99 |
+| MARS_reflec_material_M12 | str | reflecting coating on curved mirrors, e.g. Pt | "Pt.dat" |
+| MARS_reflections | str | Sample structure file, LAU/CIF format. | "LaB6_660b_AVID2.hkl" |
+| MARS_dEr | 1 | Relative half width to emitted by the source, e.g. 1e-4 | 1e-4 |
+| MARS_alpha | deg | Asymmetry angle for the crystals. | 0 |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_NANOSCOPIUM/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_NANOSCOPIUM/README.md
new file mode 100644
index 0000000000..13d365b70b
--- /dev/null
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_NANOSCOPIUM/README.md
@@ -0,0 +1,61 @@
+# The `SOLEIL_NANOSCOPIUM` Instrument
+
+*McXtrace: The NANOSCOPIUM tomography beam-line at Synchrotron SOLEIL.*
+
+## Identification
+
+- **Site:** SOLEIL
+- **Author:** C.Gaudry
+- **Origin:** Synchrotron SOLEIL
+- **Date:** 10/2026
+
+## Description
+
+```text
+The beamline NANOSCOPIUM
+works at photon energies between 5 and 50 keV. It is dedicated to full-field
+radiography and tomography in absorption and phase contrast, with pixel sizes
+from 20 nm to 20 µm.
+
+List of beamline elements. Distances are given from the center of the undulator.
+
+Position (m) | Element
+-------------|---------------------------------------------
+0 | Undulator (source)
+18.109 | Primary slits
+22.655 | Mirror M1 (curved) : horizontal deviation, vertical focus
+24.471 | Mirror M2 (curved) : horizontal deviation, horizontal focus
+75.758 | Secondary slits
+77.224 | Monochromator (DCM)
+82.064 | Slits Secondary source
+148.893 | Slits JJ XRay 1 (entry Nanoprobe 1) (doesn't work)
+150.721 | Nano-probe 1 (doesn't work)
+154.353 | Slits JJ XRay 2 (entry Nanoprobe 2)
+154.856 | Mirror KB1 (elliptic) : vertical focus
+154.961 | Mirror KB2 (elliptic) : horizontal focus
+155.140 | Nano-probe 2
+```
+
+## Examples
+
+- **Test: NANO_E0=11 Detector: NANO_e_dcm_out_I=4.09492e+10**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| NANO_E0 | keV | Energy selected at the Undulator. | 11 |
+| NANO_dE | keV | Energy spread at the Undulator. | 1 |
+| NANO_Emono | keV | Energy to be selected by the monochromator, or E0 when unset. | 0 |
+| NANO_coating_m2 | 1 | 2 stripes on M2 : Rh (coated : 1) or Si (uncoated : 0) | 1 |
+| NANO_angle_m1_m2 | rad | Incidence angle on M1 and M2 mirrors | 2.5e-3 |
+| NANO_angle_kb1 | rad | Incidence angle on the first KB mirror (vertical focus) | 3e-3 |
+| NANO_angle_kb2 | rad | Incidence angle on the second KB mirror (horizontal focus) | 2.5e-3 |
+
+## Links
+
+- [Source code](SOLEIL_NANOSCOPIUM.instr) for `SOLEIL_NANOSCOPIUM.instr`.
+
+---
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_PSICHE/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PSICHE/README.md
index 3fa8d52399..fe2429128b 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_PSICHE/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PSICHE/README.md
@@ -26,7 +26,7 @@ The sample handles absorption, with edge contrast, as well as fluorescence.
## Examples
-- **Test: -n 1e6 E0=25 sample_material="Ag0.6In0.2Sn0.2" Detector: mon_spl_xy_I=7.61e+13**
+- **Test: -n 1e6 PSICHE_E0=25 PSICHE_sample_material="Ag0.6In0.2Sn0.2" Detector: PSICHE_mon_spl_xy_I=7.61e+13**
## Input parameters
@@ -34,13 +34,13 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Nominal energy at the Wiggler. Sets the monochromator angle when DCM_present | 31 |
-| dE | keV | Energy half-bandwidth at the Wiggler | 1 |
-| DCM_present | 1 | Allow the monochromator in place (1) or removed (0, white beam) | 0 |
-| sample_theta | deg | Rotation of the sample stage | 0 |
-| sample_material | str | Absorption data file for the sample | "Ag" |
-| sample_geometry | str | OFF/PLY file name for sample 3D geometry, or emty for a box | "wire.ply" |
-| dcm_theta | deg | Rotation angle of the DCM. 0=set from energy E0 | 0 |
+| PSICHE_E0 | keV | Nominal energy at the Wiggler. Sets the monochromator angle when PSICHE_DCM_present | 31 |
+| PSICHE_dE | keV | Energy half-bandwidth at the Wiggler | 1 |
+| PSICHE_DCM_present | 1 | Allow the monochromator in place (1) or removed (0, white beam) | 0 |
+| PSICHE_sample_theta | deg | Rotation of the sample stage | 0 |
+| PSICHE_sample_material | str | Absorption data file for the sample | "Ag" |
+| PSICHE_sample_geometry | str | OFF/PLY file name for sample 3D geometry, or emty for a box | "wire.ply" |
+| PSICHE_dcm_theta | deg | Rotation angle of the DCM. 0=set from energy PSICHE_E0 | 0 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_PUMA/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PUMA/README.md
index e0c2b9f0bf..87aa5f117b 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_PUMA/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PUMA/README.md
@@ -16,7 +16,7 @@ PUMA (an acronym for “Photons Used for Ancient Materials”)
is a hard X-ray beamline optimized for the heritage
science community, though not exclusively reserved for it.
Our microbeam terminal station offers a beam size of
-5 (v) x 7 (h) µm², in an energy range from 4 to 22 keV.
+5 (v) x 7 (PUMA_h) µm², in an energy range from 4 to 22 keV.
Available experimental techniques include X-ray
fluorescence spectroscopy (XRF), X-ray absorption
spectroscopy (XANES), X-ray diffraction (XRD), and
@@ -25,7 +25,7 @@ X-ray-excited optical luminescence spectroscopy (XEOL)
## Examples
-- **Test: E0=10 Detector: mon_sample_e_I=4.02276e+11**
+- **Test: PUMA_E0=10 Detector: PUMA_mon_sample_e_I=4.02276e+11**
## Input parameters
@@ -33,16 +33,16 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Central energy selected by the DCM. Set to 0 to derive it from DCM_theta. | 10 |
-| dE | keV | Half-width of the energy band emitted by the source. Reset to 3% of E0 if dE/E0 > 0.1. | 0.1 |
-| DCM_theta | deg | Bragg angle of the Si DCM. Set to 0 to derive it from E0 and (hkl). | 0 |
-| HFM_angle | mrad | Total deflection angle of the fixed horizontally focusing mirror (HFM, Ir coating) at 21 m. The grazing incidence angle is HFM_angle/2. | 1.3 |
-| HFM_focal | m | Image distance of the HFM, used for its bending radius. The source distance is fixed at 21 m. | 40 |
-| KB_angle | mrad | Total deflection angle of each KB mirror (VFM and HFM). The grazing incidence angle is KB_angle/2. | 2.9 |
-| KB_coating | str | Reflectivity file for the KB mirror coating, e.g. "Rh.txt" (Rh or B4C). | "Rh.txt" |
-| h | 1 | Miller index h of the Si DCM reflection. | 1 |
-| k | 1 | Miller index k of the Si DCM reflection. | 1 |
-| l | 1 | Miller index l of the Si DCM reflection. | 1 |
+| PUMA_E0 | keV | Central energy selected by the DCM. Set to 0 to derive it from PUMA_DCM_theta. | 10 |
+| PUMA_dE | keV | Half-width of the energy band emitted by the source. Reset to 3% of PUMA_E0 if PUMA_dE/PUMA_E0 > 0.1. | 0.1 |
+| PUMA_DCM_theta | deg | Bragg angle of the Si DCM. Set to 0 to derive it from PUMA_E0 and (hkl). | 0 |
+| PUMA_HFM_angle | mrad | Total deflection angle of the fixed horizontally focusing mirror (HFM, Ir coating) at 21 m. The grazing incidence angle is PUMA_HFM_angle/2. | 1.3 |
+| PUMA_HFM_focal | m | Image distance of the HFM, used for its bending radius. The source distance is fixed at 21 m. | 40 |
+| PUMA_KB_angle | mrad | Total deflection angle of each KB mirror (VFM and HFM). The grazing incidence angle is PUMA_KB_angle/2. | 2.9 |
+| PUMA_KB_coating | str | Reflectivity file for the KB mirror coating, e.g. "Rh.txt" (Rh or B4C). | "Rh.txt" |
+| PUMA_h | 1 | Miller index PUMA_h of the Si DCM reflection. | 1 |
+| PUMA_k | 1 | Miller index PUMA_k of the Si DCM reflection. | 1 |
+| PUMA_l | 1 | Miller index PUMA_l of the Si DCM reflection. | 1 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_PX1/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PX1/README.md
new file mode 100644
index 0000000000..223393adf1
--- /dev/null
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PX1/README.md
@@ -0,0 +1,121 @@
+# The `SOLEIL_PX1` Instrument
+
+*McXtrace: The PROXIMA-1 (PX1) MX beam-line at Synchrotron SOLEIL.*
+
+## Identification
+
+- **Site:** SOLEIL
+- **Author:** E. Farhi
+- **Origin:** Synchrotron SOLEIL
+- **Date:** 2026-10-03
+
+## Description
+
+```text
+PROXIMA-1 (PX1) is one of the two macromolecular crystallography (MX)
+beam-lines at Synchrotron SOLEIL, operational since March 2008. The
+end-station is dedicated to bio-molecular crystallography, with a layout
+designed to favour anomalous diffraction data recording and studies of
+crystals with large unit cell dimensions (thanks to the low horizontal
+divergence of the beam at the sample). The X-ray photons originate from an
+in-vacuum U20 undulator, and are modulated through a liquid-nitrogen-cooled
+Si(111) channel-cut monochromator and a pair of Kirkpatrick-Baez (KB)
+focusing mirrors. The standard energy range is 6.5-15 keV, with 12.67 keV
+set as the reference energy. The beam size at the sample is 120 (H) x 20 (V)
+um FWHM uncollimated (40 x 20 um when collimated), with a flux of
+3.8e11 photons/s at 12.67 keV for a 500 mA ring current (2.1e11 when
+collimated). The end-station hosts a chi-geometry three-axis goniometer
+(SmarGon), a KETEK silicon drift detector for X-ray spectroscopy, an Oxford
+Cryosystems 700-series cryo-stream, a CATS sample exchange robot (48 samples),
+and the fast single-photon-counting pixel-array detector EigerX-16M,
+routinely used at 100 Hz.
+
+This is a simplified model with an undulator, a Si(111) channel-cut
+monochromator, a KB mirror pair, a sample stage and a detector. It is
+adapted from the SOLEIL_PX2a.instr model (M. Savko, E. Farhi), using:
+- L.M.G. Chavas et al., "PROXIMA-1 beamline for macromolecular
+crystallography measurements at Synchrotron SOLEIL",
+J. Synchrotron Rad. (2021). 28, 970-976 (layout, Table 1, Fig. 1
+element distances);
+- the publication supporting information (measured U20 harmonics at the
+5.5 mm minimum gap);
+- the SOLEIL PROXIMA-1 web page (U20 with 100 periods of 20 mm);
+- the SOLEIL PX1 synoptique drawings (TEC-CI-PL-0356 and PX1_SYNOPTIQUE).
+
+List of important beamline elements. Distances are given from the center of
+the undulator (from Chavas et al. 2021, Fig. 1; hutch boundary C04/CX1 is
+approximate).
+
+Element | Distance (m) | Description | Hutch
+-------------------|--------------|-------------|--------------------
+U20 undulator | 0.0 | In-vacuum undulator, 100 periods x 20 mm (magnetic length 2 m), minimum gap 5.5 mm, K_max=1.66. Odd harmonics give access to 5-20 keV. Undulator is tapered (30 um) in operation. | Source/Front-end
+MBS, WBS | ~10-16 | Main beam shutter, white-beam slits, beam-defining mask 0.27 (H) x 0.47 (V) mrad. Not modeled. | Front-end
+CCM | 16.397 | Liquid-nitrogen-cooled Si(111) single-crystal channel-cut monochromator with piezo pitch fine tuning. First optical element seen by the beam. Channel gap 6 mm (assumed, as PX2a). | OH
+SeS | 18.5 | Secondary slits; define the footprint on the KB mirrors. | OH
+DSS | ~19 | Downstream safety shutter. Not modeled. | OH
+KB (V) | 21.45 | Vertical-focusing KB mirror, first-generation Rh-coated glass, grazing angle 4.1 mrad. | OH
+KB (H) | 21.9 | Horizontal-focusing KB mirror, same coating/angle. Beam at sample: 120 (H) x 20 (V) um FWHM uncollimated, 40 x 20 um collimated; divergence 0.26 (H) x 0.48 (V) mrad. Mirror separation 0.45 m assumed. | OH
+DT | ~22 | Diagnostic tools, diamond CVD X-ray beam positioning monitor. Not modeled. | OH/EH
+ES | ~23 | Experimental slits. Not modeled. | EH
+SaS | ~23.7 | Sample slits; collimation of the beam down to 40 x 20 um. Not modeled. | EH
+FS | ~23.8 | Fast shutter. Not modeled. | EH
+SG (sample) | 23.846 | Sample position: SmarGon chi-geometry 3-axis goniometer, Oxford Cryosystems 700 series, KETEK SDD, CATS sample changer (3 Unipucks, 48 samples). | EH
+PAD (detector) | 23.846+PX1_det_dist | EigerX-16M single-photon-counting pixel-array detector, 311 x 328 mm2, 75 um pixels, routinely used at 100 Hz. Sample-to-detector distance 0.096-1.55 m. | EH
+
+Notes:
+- Undulator harmonics: at the fixed minimum gap of 5.5 mm (K=1.66), the
+measured spectrum shows harmonics 4 to 10 at 6.006, 7.558, 9.026, 10.558,
+12.058, 13.622 and 15.084 keV, i.e. a fundamental at E1=1.507 keV. At the
+default E0=12.67 keV the undulator is tuned onto the 7th harmonic, which
+requires K=1.4028 (gap slightly opened). The K parameter is exposed; when
+changing E0, adjust K to stay on a harmonic: with lu=20 mm and Ee=2.75 GeV
+the fundamental is E1 = 3.591/(1+K*K/2) keV, i.e. K = sqrt(2*(3.591/E1 - 1))
+with E1=E0/harmonic. Available odd harmonics (3,5,7,...) cover 5-20 keV.
+- KB focusing: the default radii focus the source (undulator) onto the
+sample, using the cylindrical mirror formula R = 2*p*q/((p+q)*sin(grazing angle)):
+PX1_vfm_radius = 2*21.45*2.396/((21.45+2.396)*4.1e-3) = 1051 m
+PX1_hfm_radius = 2*21.90*1.946/((21.90+1.946)*4.1e-3) = 872 m
+In reality the KB pair focuses slightly downstream of the sample, onto
+the detector surface when placed at the most common distance (about
+0.46 m past the sample for a 2 A outer-shell resolution); use
+PX1_vfm_radius=1230 and PX1_hfm_radius=1058 to model this configuration.
+The real beam size is dominated by the mirror figure errors (first
+generation KB), not by the source demagnification, so the simulated
+focus is sharper than the measured 120 (H) x 20 (V) um.
+- The front-end mask, shutters, slits, attenuators, Be/Kapton windows,
+beam positioning monitors, the fast shutter and the undulator taper mode
+are not modeled. The transfocator listed in some PX1 synoptiques has no
+published parameters and is not modeled either.
+- Electron beam sizes are nominal SOLEIL short straight section values
+(beta_x=2.19 m, beta_y=1.09 m, emittance 3.74 nm rad, 1% coupling).
+```
+
+## Examples
+
+- **Test: PX1_E0=12.67 Detector: PX1_sample_monitor_I=1.232e+20**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| PX1_E0 | keV | Energy selected at the Undulator (reference energy 12.67 keV, standard range 6.5-15 keV). | 12.67 |
+| PX1_dE | keV | Energy half-bandwidth at the source. | 0.1 |
+| PX1_K | 1 | Undulator deflection parameter (K=1.4028: 7th harmonic at 12.67 keV; K_max=1.66 at 5.5 mm gap). | 1.4028 |
+| PX1_vfm_radius | m | vertically focusing mirror radius (tangential). | 1051 |
+| PX1_hfm_radius | m | horizontally focusing mirror radius (tangential). | 872 |
+| PX1_mirror_grazing_angle | rad | Tilt angle of the KB mirrors (4.1 mrad). | 4.1e-3 |
+| PX1_det_dist | m | Sample-to-detector distance (0.096-1.55 m). | 0.2 |
+| PX1_sample | str | Sample structure file, LAU/CIF format. | "adrenaline.lau" |
+| PX1_rotX | deg | Sample rotation around X | 0 |
+| PX1_rotY | deg | Sample rotation around Y | 0 |
+| PX1_rotZ | deg | Sample rotation around Z | 0 |
+| splits | 1 | Ray splitting factor at the sample. | 10 |
+
+## Links
+
+- [Source code](SOLEIL_PX1.instr) for `SOLEIL_PX1.instr`.
+- https://www.synchrotron-soleil.fr/en/beamlines/proxima-1
+
+---
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_PX2a/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PX2a/README.md
index 4d337d91c8..d43be5c534 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_PX2a/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_PX2a/README.md
@@ -33,8 +33,7 @@ monochromator, a sample stage and a detector.
## Examples
-- **Test: E0=12.65 sample="Mo.lau" SPLITs=1500 Detector: psd4pi_I=1.75e+12**
-- **Test: E0=12.65 sample="adrenaline.lau" SPLITs=4200 Detector: psd4pi_I=3.8e+15**
+- **Test: PX2a_E0=12.65 sample="Mo.lau" PX2a_SPLITs=1500 PX2a_sample_monitor_I=1.53453e+20**
## Input parameters
@@ -42,15 +41,15 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Energy selected at the Undulator. | 12.65 |
-| hfm_radius | m | horizontally focusing mirror radius | 495 |
-| vfm_radius | m | vertically focusing mirror radius | 859 |
-| mirror_grazing_angle | deg | Tilt angle of the mirrors. | 4e-3 |
-| sample | str | Sample structure file, LAU/CIF format. | "adrenaline.lau" |
-| rotX | deg | Sample rotation around X | 0 |
-| rotY | deg | Sample rotation around Y | 0 |
-| rotZ | deg | Sample rotation around Z | 0 |
-| SPLITs | 1 | Number of SPLIT repetitions at the sample | 10 |
+| PX2a_E0 | keV | Energy selected at the Undulator. | 12.65 |
+| PX2a_hfm_radius | m | horizontally focusing mirror radius | 495 |
+| PX2a_vfm_radius | m | vertically focusing mirror radius | 859 |
+| PX2a_mirror_grazing_angle | deg | Tilt angle of the mirrors. | 4e-3 |
+| PX2a_sample | str | Sample structure file, LAU/CIF format. | "adrenaline.lau" |
+| PX2a_rotX | deg | Sample rotation around X | 0 |
+| PX2a_rotY | deg | Sample rotation around Y | 0 |
+| PX2a_rotZ | deg | Sample rotation around Z | 0 |
+| splits | 1 | Number of SPLIT repetitions at the sample | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_ROCK/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_ROCK/README.md
index 7c1009edda..276519732e 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_ROCK/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_ROCK/README.md
@@ -41,14 +41,14 @@ Position | Element
32.44 | Sample
Examples:
-Copper scan: mxrun SOLEIL_ROCK.instr E0=8.500,9.500 scan=1 cc=2 -N100
-Manganese and chrome scan: mxrun SOLEIL_ROCK.instr E0=5.700,6.800 scan=1 sample_file=MnCr cc=2 -N100
-Pretty energy repartition monitor result: mxrun SOLEIL_ROCK.instr E0=17.000 cc=2 -n1e8
+Copper ROCK_scan: mxrun SOLEIL_ROCK.instr ROCK_E0=8.500,9.500 ROCK_scan=1 ROCK_cc=2 -N100
+Manganese and chrome ROCK_scan: mxrun SOLEIL_ROCK.instr ROCK_E0=5.700,6.800 ROCK_scan=1 ROCK_sample_file=MnCr ROCK_cc=2 -N100
+Pretty energy repartition monitor result: mxrun SOLEIL_ROCK.instr ROCK_E0=17.000 ROCK_cc=2 -n1e8
```
## Examples
-- **Test: E0=15.918 Detector: fluo_monitor_I=2e+09**
+- **Test: ROCK_E0=15.918 Detector: ROCK_fluo_monitor_I=2e+09**
## Input parameters
@@ -56,15 +56,16 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Energy to hit, i.e. selected by the channel-cut monochromator | 15.918 |
-| dE | keV | Energy spread at the source | 1 |
-| scan | 0-1 | 0 no energy scan, 1 energy scan | 0 |
-| angle_m2a_m2b | rad | M2A/M2B mirror's deviation angle, can vary from 0.0035 to 0.0104 | 0.008 |
-| angle_m1 | rad | M1 mirror's deviation angle | 0.0045 |
-| sample_file | string | Sample chemical formulae | "CuMo" |
-| reflec_material_M1 | str | Material reflectivity file name for M1 mirror, e.g. "Ir.dat" | "Ir.dat" |
-| reflec_material_M2A_M2B | str | Material reflectivity file name for M2A and M2B mirror. Use NULL for automatic setting. | "NULL" |
-| cc | 0-3 | Channel-cut monochromator type. 0 for Si 220 with an energy range of 5.62883-46.2834 eV/4-35 deg (hit-table:11.752-34.055 ev/5.44-15.94 deg); 1 for Si 111 long 3.44694-28.3427 eV/4-35 deg (hit-table:7.196-20.854 ev/5.44-15.94 deg); 2 for Si 111 short 3.44694-18.914.3 eV/6-35 deg (hittable:5.323-18.914 ev/6-21.8 deg); 3 changes cc dynamically | 0 |
+| ROCK_E0 | keV | Energy to hit, i.e. selected by the channel-cut monochromator | 15.918 |
+| ROCK_dE | keV | Energy spread at the source | 1 |
+| ROCK_scan | 0-1 | 0 no energy ROCK_scan, 1 energy ROCK_scan | 0 |
+| ROCK_angle_m2a_m2b | rad | M2A/M2B mirror's deviation angle, can vary from 0.0035 to 0.0104 | 0.008 |
+| ROCK_angle_m1 | rad | M1 mirror's deviation angle | 0.0045 |
+| ROCK_sample_file | string | Sample chemical formulae | "CuMo" |
+| ROCK_reflec_material_M1 | str | Material reflectivity file name for M1 mirror, e.g. "Ir.dat" | "Ir.dat" |
+| ROCK_reflec_material_M2A_M2B | str | Material reflectivity file name for M2A and M2B mirror. Use NULL for automatic setting. | "NULL" |
+| ROCK_cc | 0-3 | Channel-cut monochromator type. 0 for Si 220 with an energy range of 5.62883-46.2834 eV/4-35 deg (hit-table:11.752-34.055 ev/5.44-15.94 deg); 1 for Si 111 long 3.44694-28.3427 eV/4-35 deg (hit-table:7.196-20.854 ev/5.44-15.94 deg); 2 for Si 111 short 3.44694-18.914.3 eV/6-35 deg (hittable:5.323-18.914 ev/6-21.8 deg); 3 changes ROCK_cc dynamically | 0 |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SAMBA/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SAMBA/README.md
index 7de9fe9ee5..0e88d31f6f 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SAMBA/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SAMBA/README.md
@@ -34,7 +34,7 @@ Position | Element
## Examples
-- **Test: E0=15 Detector: det_fluo_I=1.23968e+10**
+- **Test: SAMBA_E0=15 Detector: SAMBA_det_fluo_I=1.23968e+10**
## Input parameters
@@ -42,11 +42,12 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Central energy | 15 |
-| dE | keV | Energy spread | 0.1 |
-| M1_angle | mrad | Incidence angle of M1 (vertical collimation) | 3 |
-| M2_angle | mrad | Incidence angle of M2 (vertical focusing) | 3 |
-| sample | str | Sample structure file | "LaB6.cif" |
+| SAMBA_E0 | keV | Central energy | 15 |
+| SAMBA_dE | keV | Energy spread | 0.1 |
+| SAMBA_M1_angle | mrad | Incidence angle of M1 (vertical collimation) | 3 |
+| SAMBA_M2_angle | mrad | Incidence angle of M2 (vertical focusing) | 3 |
+| SAMBA_sample | str | Sample structure file | "LaB6.cif" |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIRIUS/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIRIUS/README.md
index 5f8485fc96..008b20f8b3 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIRIUS/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIRIUS/README.md
@@ -30,7 +30,7 @@ Position | Element
## Examples
-- **Test: E0=8 Detector: def_loc_I=2.14522e+10**
+- **Test: SIRIUS_E0=8 Detector: SIRIUS_def_loc_I=2.14522e+10**
## Input parameters
@@ -38,13 +38,14 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Central energy (1.4 - 13 keV) | 8 |
-| dE | keV | Energy spread | 0.1 |
-| M1_angle | mrad | Incidence angle of M1 | 3 |
-| M2_angle | mrad | Incidence angle of M2 | 3 |
-| def_angle | mrad | Deflection mirror tilt (for grazing incidence) | 2.0 |
-| sample_pos | m | Distance to sample (30 for XAS, 35 for SEXAFS) | 30 |
-| sample | str | Sample structure file | "LaB6.cif" |
+| SIRIUS_E0 | keV | Central energy (1.4 - 13 keV) | 8 |
+| SIRIUS_dE | keV | Energy spread | 0.1 |
+| SIRIUS_M1_angle | mrad | Incidence angle of M1 | 3 |
+| SIRIUS_M2_angle | mrad | Incidence angle of M2 | 3 |
+| SIRIUS_def_angle | mrad | Deflection mirror tilt (for grazing incidence) | 2.0 |
+| SIRIUS_sample_pos | m | Distance to sample (30 for XAS, 35 for SEXAFS) | 30 |
+| SIRIUS_sample | str | Sample structure file | "LaB6.cif" |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIXS/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIXS/README.md
index 276d9c9440..bbfcac0b3e 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIXS/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SIXS/README.md
@@ -38,13 +38,13 @@ Position | Element
---------|--------------------------------------------------------------------
0 | the U20 undulator
15 | Slit S1 2x0.7 mm^2
-16.5 | a Si(111) DCM, 40x40x10 mm^3 E0=5-20 keV
+16.5 | a Si(111) DCM, 40x40x10 mm^3 SIXS_E0=5-20 keV
26 | Mirror M1 Si coated with Pd, elliptically vertical focusing 20x350x20 mm^3 Incident angle 0.175 deg (3 mrad)
28 | Mirror M2 at 20x550x20mm^3. (tilted 45 deg exchange horz/vert components for UHV)
33 | multipurpose diffractometer
42 | UHV diffractometer (not modelled here)
-Example: E0=10 Detector: mon_spl_fluo_I=3.66859e+14
+Example: SIXS_E0=13 Detector: SIXS_detector_bulk_I=3.37342e+09
```
## Examples
@@ -57,16 +57,17 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Nominal energy at the Wiggler. | 13 |
-| dE | keV | Energy half-bandwidth at the Wiggler | 0.1 |
-| dcm_theta | deg | Rotation angle of the DCM. 0=set from energy E0 | 0 |
-| M1_angle | mrad | Rotation angle of M1/M2 mirrors. When left as 0, it is set automatically from E0. | 3 |
-| M1_radius | m | Curvature radius of M1 mirror (Rh, 1300x100) longitudinal. Positive=mirror is focusing. 0=flat. | 1400 |
-| M2_radius | m | Curvature radius of M2 mirror (Rh, 1300x100) sagittal. Positive=mirror is focusing. 0=flat. | 1400 |
-| sample_coating | str | Reflection/structure data file for the single crystal thin layer coating | "Mo.lau" |
-| sample_bulk | str | Reflection/structure data file for the single crystal bulk | "Si.lau" |
-| sample_thickness | m | The single crystal thin layer coating thickness | 50e-10 |
-| sample_angle | deg | The sample tilt angle (around X axis) | 0.175 |
+| SIXS_E0 | keV | Nominal energy at the Wiggler. | 13 |
+| SIXS_dE | keV | Energy half-bandwidth at the Wiggler | 0.1 |
+| SIXS_dcm_theta | deg | Rotation angle of the DCM. 0=set from energy SIXS_E0 | 0 |
+| SIXS_M1_angle | mrad | Rotation angle of M1/M2 mirrors. When left as 0, it is set automatically from SIXS_E0. | 3 |
+| SIXS_M1_radius | m | Curvature radius of M1 mirror (Rh, 1300x100) longitudinal. Positive=mirror is focusing. 0=flat. | 1400 |
+| SIXS_M2_radius | m | Curvature radius of M2 mirror (Rh, 1300x100) sagittal. Positive=mirror is focusing. 0=flat. | 1400 |
+| SIXS_sample_coating | str | Reflection/structure data file for the single crystal thin layer coating | "Mo.lau" |
+| SIXS_sample_bulk | str | Reflection/structure data file for the single crystal bulk | "Si.lau" |
+| SIXS_sample_thickness | m | The single crystal thin layer coating thickness | 50e-10 |
+| SIXS_sample_angle | deg | The sample tilt angle (around X axis) | 0.175 |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SWING/README.md b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SWING/README.md
index 0c6f873e59..f73914fedd 100644
--- a/mcxtrace-comps/examples/SOLEIL/SOLEIL_SWING/README.md
+++ b/mcxtrace-comps/examples/SOLEIL/SOLEIL_SWING/README.md
@@ -26,18 +26,16 @@ Position | Element
---------|--------------------------------------------------------------------
0 | U20 undulator
11.7 | Diaphragm providing HxV=1x0.5 mm beam
-20 | Si(111) DCM, 40x40x10 mm^3 E0=5-16 keV
+20 | Si(111) DCM, 40x40x10 mm^3 SWING_E0=5-16 keV
22.5 | Focusing KB (HFM + VFM)
31 | Linear H-CRL (f=81 cm): 31 m
32 | Sample location
32.5-39 | Detector 162.5 x 155.2 mm
-
-Example: E0=13 Detector: Eiger4M_I=7.5752e+06
```
## Examples
-
+- **Test: SWING_E0=13 Detector: SWING_Eiger4M_I=128310**
## Input parameters
@@ -45,14 +43,15 @@ Parameters in **boldface** are required; the others are optional.
| Name | Unit | Description | Default |
|------|------|-------------|---------|
-| E0 | keV | Nominal energy at the Wiggler. | 13 |
-| dE | keV | Energy half-bandwidth at the Wiggler | 0.1 |
-| dcm_theta | deg | Rotation angle of the DCM. 0=set from energy E0 | 0 |
-| hfm_radius | m | Horizontally focusing mirror radius. | 495 |
-| vfm_radius | m | Vertically focusing mirror radius. | 859 |
-| mirror_grazing_angle | deg | Tilt angle of the mirrors. | 4e-3 |
-| sample | str | Sample given as a PDB file, or NULL for a 100A dilute Sphere model. | "6lyz.pdb" |
-| sample_det | m | Sample to detector distance in m. | 2 |
+| SWING_E0 | keV | Nominal energy at the Wiggler. | 13 |
+| SWING_dE | keV | Energy half-bandwidth at the Wiggler | 0.1 |
+| SWING_dcm_theta | deg | Rotation angle of the DCM. 0=set from energy SWING_E0 | 0 |
+| SWING_hfm_radius | m | Horizontally focusing mirror radius. | 495 |
+| SWING_vfm_radius | m | Vertically focusing mirror radius. | 859 |
+| SWING_mirror_grazing_angle | deg | Tilt angle of the mirrors. | 4e-3 |
+| SWING_sample | str | Sample given as a PDB file, or NULL for a 100A dilute Sphere model. | "6lyz.pdb" |
+| SWING_sample_det | m | Sample to detector distance in m. | 2 |
+| splits | | | 10 |
## Links
diff --git a/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_not_white_src/README.md b/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_not_white_src/README.md
index 487026cb42..3afd904006 100644
--- a/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_not_white_src/README.md
+++ b/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_not_white_src/README.md
@@ -19,14 +19,13 @@ SSRL glitch database found here: https://www-ssrl.slac.stanford.edu/smbin/dataex
Documentation and results of the .instr here: https://gitlab.synchrotron-soleil.fr/grades/beamlines/-/tree/main/glitches
A jupyter notebook will soon be available regrouping everything.
You may scan like so for example:
-mxrun -n 1e7 SSRL_bl_11_2_not_white_src.instr -N601 Etohit=6900,7500
-
-Example: Etohit=6900 Detector: EnergyMonitor_first_I=1.3e+10
```
## Examples
-
+- **TestScan: mxrun SSRL_bl_11_2_not_white_src.instr -N31 Etohit=6900,7500 -n1e6 Detector: EnergyMonitor_first_I={31 values}**
+-
+- Example: Etohit=6900 Detector: EnergyMonitor_first_I=1.3e+10
## Input parameters
diff --git a/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_white_src/README.md b/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_white_src/README.md
index 0afc5d3baa..aa5b185fd8 100644
--- a/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_white_src/README.md
+++ b/mcxtrace-comps/examples/SSRL/SSRL_bl_11_2_white_src/README.md
@@ -18,11 +18,12 @@ SSRL glitch database found here: https://www-ssrl.slac.stanford.edu/smbin/dataex
Documentation and results of the .instr here: https://gitlab.synchrotron-soleil.fr/grades/beamlines/-/tree/main/glitches
A jupyter notebook will soon be available regrouping everything.
You may scan like so for example:
-mxrun -n 1e7 SSRL_bl_11_2_white_src.instr -N601 Etohit=6900,7500 detuning_percentage=40
```
## Examples
+- **TestScan: mxrun SSRL_bl_11_2_white_src.instr -N31 Etohit=6900,7500 detuning_percentage=40 -n1e7 Detector: EnergyMonitor_first_I={31 values}**
+-
- **Test: Etohit=6900 Detector: EnergyMonitor_first_I=4.24366e+07**
## Input parameters
diff --git a/mcxtrace-comps/examples/Templates/Demo_shape_primitives/README.md b/mcxtrace-comps/examples/Templates/Demo_shape_primitives/README.md
new file mode 100644
index 0000000000..740531d946
--- /dev/null
+++ b/mcxtrace-comps/examples/Templates/Demo_shape_primitives/README.md
@@ -0,0 +1,34 @@
+# The `Demo_shape_primitives_simple` Instrument
+
+*McXtrace: Demonstration instrument of some shapes used for mcdisplay*
+
+## Identification
+
+- **Site:** Templates
+- **Author:** Erik B Knudsen
+- **Origin:** DTU Physics
+- **Date:** Feb 2018
+
+## Description
+
+```text
+This instrument will display a cylinder, a sphere, and a box,
+when run with mcdisplay. Otherwise does nothing.
+```
+
+## Examples
+
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Demo_shape_primitives.instr) for `Demo_shape_primitives.instr`.
+
+---
diff --git a/mcxtrace-comps/examples/Templates/Text2OFF/README.md b/mcxtrace-comps/examples/Templates/Text2OFF/README.md
new file mode 100644
index 0000000000..4f7d93aa35
--- /dev/null
+++ b/mcxtrace-comps/examples/Templates/Text2OFF/README.md
@@ -0,0 +1,55 @@
+# The `Text2OFF` Instrument
+
+*McXtrace: Render a text string as 3D geometry, e.g. for export to an OFF file*
+
+## Identification
+
+- **Site:** Templates
+- **Author:** Peter Willendrup (pkwi@fysik.dtu.dk)
+- **Origin:** DTU Physics
+- **Date:** October 2026
+
+## Description
+
+```text
+Draws the string given in "letters" with the Text component and nothing else -
+no particles are traced. Use it with mxdisplay-cad to turn a text into CAD
+geometry, for instance an OFF file that can be fed back into components that
+read OFF geometry (labels, logos, test shapes):
+
+mxdisplay-cad Text2OFF.instr -t 2 -f off letters="McXtrace" size=0.5
+
+Notes:
+- Use --trace 2 (-t 2): with the default trace level 1 Text draws thin lines,
+which carry no surfaces and give an empty OFF/STL file.
+- Each stroke is a cylinder and each stroke end/joint a sphere, so the
+resulting surfaces overlap - fine for display, not a closed single solid.
+- Letters are drawn upper-case; characters without a glyph are left blank.
+
+Example: letters="McXtrace" size=0.5 plane="XY"
+```
+
+## Examples
+
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| letters | str | Text to draw | "McXtrace" |
+| size | m | Letter height | 0.5 |
+| plane | str | Plane of the text: "XY", "YZ" or "XZ" | "XY" |
+| thickness | 1 | Stroke diameter as fraction of size | 0.1 |
+| rx | deg | Rotation of the text around the x axis | 0 |
+| ry | deg | Rotation of the text around the y axis | 0 |
+| rz | deg | Rotation of the text around the z axis | 0 |
+
+## Links
+
+- [Source code](Text2OFF.instr) for `Text2OFF.instr`.
+- Text.comp, mxdisplay-cad --help
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_DIAPHRAGM/README.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_DIAPHRAGM/README.md
new file mode 100644
index 0000000000..b937ef3da0
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_DIAPHRAGM/README.md
@@ -0,0 +1,47 @@
+# The `Unittest_INHERIT_DIAPHRAGM` Instrument
+
+*McXtrace: Whole-component INHERIT: Diaphragm (DEFINE COMPONENT Diaphragm INHERIT Slit)*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for whole-component inheritance, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+Diaphragm.comp is just "DEFINE COMPONENT Diaphragm INHERIT Slit" + END,
+so all of its code sections must come from Slit.
+
+One unit of intensity is emitted uniformly from a 1x1 m square:
+- a Slit of 0.5x0.5 m passes 1/4: AfterSlit_I = 0.25
+- a Diaphragm of 0.25x0.25 m passes 1/16 of the source: AfterDiaphragm_I = 0.0625
+
+Before the fix, a component inheriting all of its code got none of it, so
+the Diaphragm let everything through (AfterDiaphragm_I = 0.25).
+```
+
+## Examples
+
+- **Test: Detector: AfterSlit_I=0.25**
+- **Test: Detector: AfterDiaphragm_I=0.0625**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_INHERIT_DIAPHRAGM.instr) for `Unittest_INHERIT_DIAPHRAGM.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/README.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/README.md
new file mode 100644
index 0000000000..99d97d3f38
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/README.md
@@ -0,0 +1,57 @@
+# The `Unittest_INHERIT_OVERRIDE` Instrument
+
+*McXtrace: DEFINE COMPONENT X INHERIT Y: written sections (even empty) replace Y's*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for whole-component inheritance, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+(same rule as mccode-antlr, mccode-dev/mccode-antlr#321).
+
+Local components: Unittest_IO_parent absorbs particles with x>0. Its
+children, DEFINE COMPONENT ... INHERIT Unittest_IO_parent:
+- Unittest_IO_cancel writes an empty TRACE %{ %}: replaces the parent's
+TRACE, absorbs nothing. Before, an empty block counted as "not written"
+and the parent's TRACE was used.
+- Unittest_IO_keep writes no sections: inherits the parent's TRACE.
+- Unittest_IO_extend writes TRACE INHERIT Unittest_IO_parent EXTEND %{..%}:
+the parent's TRACE followed by more code (absorbs x>0 and y>0). It also
+uses INHERIT within USERVARS.
+- Unittest_IO_noinit writes an empty INITIALIZE EXTEND %{ %}: keeps the
+parent's DECLARE and TRACE but not its INITIALIZE (io_val stays 0, so
+its TRACE halves the weight). "Inherit everything but one section".
+
+One unit of intensity is emitted uniformly from a 1x1 m square:
+AfterCancel_I = 1, AfterKeep_I = 0.5, AfterExtend_I = 0.25,
+AfterNoInit_I = 0.125.
+```
+
+## Examples
+
+- **Test: Detector: AfterCancel_I=1**
+- **Test: Detector: AfterKeep_I=0.5**
+- **Test: Detector: AfterExtend_I=0.25**
+- **Test: Detector: AfterNoInit_I=0.125**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_INHERIT_OVERRIDE.instr) for `Unittest_INHERIT_OVERRIDE.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_cancel.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_cancel.md
new file mode 100644
index 0000000000..6aa4c69cac
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_cancel.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_cancel` Component
+
+*McXtrace: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Inherits everything from Unittest_IO_parent but cancels its TRACE with an
+explicitly written, empty TRACE section: absorbs nothing.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_cancel.comp) for `Unittest_IO_cancel.comp`.
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_extend.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_extend.md
new file mode 100644
index 0000000000..5bee351e6f
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_extend.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_extend` Component
+
+*McXtrace: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Writes TRACE as the parent's TRACE plus more code: absorbs x>0 and y>0.
+Also uses INHERIT within USERVARS.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_extend.comp) for `Unittest_IO_extend.comp`.
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_keep.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_keep.md
new file mode 100644
index 0000000000..91e2808bfb
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_keep.md
@@ -0,0 +1,30 @@
+# The `Unittest_IO_keep` Component
+
+*McXtrace: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Inherits everything from Unittest_IO_parent (writes no sections): absorbs x>0.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_keep.comp) for `Unittest_IO_keep.comp`.
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_noinit.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_noinit.md
new file mode 100644
index 0000000000..fe8a425d4e
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_noinit.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_noinit` Component
+
+*McXtrace: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Inherits everything from Unittest_IO_parent but cancels its INITIALIZE with
+an empty INITIALIZE EXTEND section: io_val stays 0, so TRACE halves the weight.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_noinit.comp) for `Unittest_IO_noinit.comp`.
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_parent.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_parent.md
new file mode 100644
index 0000000000..70fb3ee725
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_INHERIT_OVERRIDE/Unittest_IO_parent.md
@@ -0,0 +1,31 @@
+# The `Unittest_IO_parent` Component
+
+*McXtrace: Grammar unit test helper for Unittest_INHERIT_OVERRIDE*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Parent: absorbs particles with x>0, and declares a USERVAR. Its DECLARE/
+INITIALIZE set io_val=1; TRACE halves the weight if io_val is not set.
+See docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_IO_parent.comp) for `Unittest_IO_parent.comp`.
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_JUMP_RELATIVE/README.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_JUMP_RELATIVE/README.md
new file mode 100644
index 0000000000..767d484785
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_JUMP_RELATIVE/README.md
@@ -0,0 +1,50 @@
+# The `Unittest_JUMP_RELATIVE` Instrument
+
+*McXtrace: Relative JUMP targets: JUMP PREVIOUS(n) and JUMP NEXT(n)*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for relative JUMP targets, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+One unit of intensity is emitted from a 1x1 m square.
+- Back jumps to PREVIOUS(2), i.e. to Target, 'iter' times in total
+(JUMP ... ITERATE), so the Mon monitor in between is passed 'iter' times
+and reads Mon_I = iter.
+- Skip jumps to NEXT(2), i.e. over Skipped and onto Landed, so
+Skipped_I = 0 and Landed_I = 1.
+
+Before the fix, relative targets were used as absolute component indices:
+JUMP PREVIOUS(n) crashed the code generator and JUMP NEXT(n) went to
+component n. JUMP PREVIOUS is PREVIOUS(1) and JUMP NEXT is NEXT(1).
+```
+
+## Examples
+
+- **Test: iter=3 Detector: Mon_I=3**
+- **Test: iter=3 Detector: Landed_I=1**
+- **Test: iter=3 Detector: Skipped_I=0**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| iter | 1 | Number of passes through Mon (JUMP ITERATE count) | 3 |
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_JUMP_RELATIVE.instr) for `Unittest_JUMP_RELATIVE.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/README.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/README.md
new file mode 100644
index 0000000000..f1bf17b7f0
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/README.md
@@ -0,0 +1,52 @@
+# The `Unittest_USERVARS_TYPES` Instrument
+
+*McXtrace: USERVARS of non-double type, several declarations per line, USERVARS+EXTEND*
+
+## Identification
+
+- **Site:** Tests_grammar
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Unit test for USERVARS/DECLARE handling in the code generator, see
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+One unit of intensity is emitted from a 1x1 m square.
+- USERVARS declares "int flag; double wsum;" on ONE line. Before the fix
+only the first declaration on a line was found, so wsum was missing.
+- flag (an int) is set to 1 for x>0 and read by Monitor_nD (user1="flag")
+through particle_getvar(). Before the fix its memory was read as a
+double (garbage); now it is converted, and the [0.5 1.5] range holds
+half of the beam: Flag_I = 0.5. (2 bins: a 1-bin Monitor_nD is 0-D and
+ignores the limits.)
+Note: USERVARS used with Monitor_nD should still be declared double;
+int is used here only to test the conversion.
+- Unittest_UV_check (local component) tests %include "x.hpp", component
+USERVARS followed by EXTEND, and two DECLARE variables on one line. It
+absorbs the particle if its EXTEND-declared USERVAR is missing, so
+AfterCheck_I = 1.
+```
+
+## Examples
+
+- **Test: Detector: AfterCheck_I=1**
+- **Test: Detector: Flag_I=0.5**
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+| Pp0 | 1 | Dummy input parameter used internally | 0 |
+
+## Links
+
+- [Source code](Unittest_USERVARS_TYPES.instr) for `Unittest_USERVARS_TYPES.instr`.
+- docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md
+
+---
diff --git a/mcxtrace-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/Unittest_UV_check.md b/mcxtrace-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/Unittest_UV_check.md
new file mode 100644
index 0000000000..24055b37af
--- /dev/null
+++ b/mcxtrace-comps/examples/Tests_grammar/Unittest_USERVARS_TYPES/Unittest_UV_check.md
@@ -0,0 +1,39 @@
+# The `Unittest_UV_check` Component
+
+*McXtrace: Grammar unit test helper for Unittest_USERVARS_TYPES*
+
+## Identification
+
+- **Author:** Peter Willendrup
+- **Origin:** DTU
+- **Date:** Oct 7th, 2026
+
+## Description
+
+```text
+Exercises code-generator fixes from
+docs/GRAMMAR/ADR-records/ADR_20261007_GRAMMAR_FIXES.md:
+- %include "unittest_uv.hpp" (multi-character extension) in SHARE,
+- USERVARS followed by EXTEND: uv_b is declared in the EXTEND block and
+was silently dropped before the fix,
+- two DECLARE variables on one line: only the first was found before.
+
+In TRACE the component writes this instance's uv_b USERVAR (by name,
+"uv_b_", built in INITIALIZE as sprintf is a no-op on GPU) and
+reads it back. If that fails, the particle is
+absorbed, so a monitor after it reads 0 instead of the full intensity.
+```
+
+
+## Input parameters
+
+Parameters in **boldface** are required; the others are optional.
+
+| Name | Unit | Description | Default |
+|------|------|-------------|---------|
+
+## Links
+
+- [Source code](Unittest_UV_check.comp) for `Unittest_UV_check.comp`.
+
+---
diff --git a/mcxtrace-comps/examples/Tests_optics/Test_capillary/README.md b/mcxtrace-comps/examples/Tests_optics/Test_capillary/README.md
index 5a8801b6c4..e5aca6be06 100644
--- a/mcxtrace-comps/examples/Tests_optics/Test_capillary/README.md
+++ b/mcxtrace-comps/examples/Tests_optics/Test_capillary/README.md
@@ -18,7 +18,7 @@ It shows that implementations are equivalent.
## Examples
-- **Test: Test_capillary -n 1e6 TL=3 TR=0.001 L1=0.4 Detector: psd14_I=7.34669e-08**
+- **Test: Test_capillary TL=3 TR=0.001 L1=0.4 Detector: psd14_I=7.34669e-08**
## Input parameters
diff --git a/mcxtrace-comps/examples/Tests_samples/Test_FluoPowder/README.md b/mcxtrace-comps/examples/Tests_samples/Test_FluoPowder/README.md
index 1879ac7d3d..189820f6a1 100644
--- a/mcxtrace-comps/examples/Tests_samples/Test_FluoPowder/README.md
+++ b/mcxtrace-comps/examples/Tests_samples/Test_FluoPowder/README.md
@@ -19,16 +19,16 @@ The idea is to compare the fluorescence and diffraction patterns:
- index=2: use Single_crystal (no fluorescence, slower, powder mode)
- index=3: use FluoPowder (exact)
- index=4: use Fluorescence (no diffraction)
-- index=5: use Fluorescence+PowderN (under estimates contributions)
+- index=5: use Fluorescence+PowderN (exact)
```
## Examples
-- **Test: Test_FluoPowder.instr E0=15 index=1 Detector: Sph_mon_pow_I=2.23591e-18**
-- **Test: Test_FluoPowder.instr -n 1e5 E0=15 index=2 Detector: Sph_mon_pow_I=1.89664e-18**
-- **Test: Test_FluoPowder.instr E0=15 index=3 Detector: Sph_mon_I=2.8904e-18**
+- **Test: Test_FluoPowder.instr E0=15 index=1 Detector: Sph_mon_pow_I=1.77806e-19**
+- Example: Test_FluoPowder.instr E0=15 index=2 Detector: Sph_mon_pow_I=1.5129e-19
+- **Test: Test_FluoPowder.instr E0=15 index=3 Detector: Sph_mon_pow_I=1.77226e-19**
- **Test: Test_FluoPowder.instr E0=15 index=4 Detector: Sph_mon_flu_I=6.18074e-19**
-- Example: Test_FluoPowder.instr E0=15 index=5 Detector: Sph_mon_I=1.76094e-18
+- Example: Test_FluoPowder.instr E0=15 index=5 Detector: Sph_mon_pow_I=1.77403e-19
-
- (Fluorescence+PowderN GROUP is unstable on GPU, disable index=5 test for now)
diff --git a/mcxtrace-comps/examples/Tests_samples/Test_PowderN/README.md b/mcxtrace-comps/examples/Tests_samples/Test_PowderN/README.md
index f117b56dde..8cb555d012 100644
--- a/mcxtrace-comps/examples/Tests_samples/Test_PowderN/README.md
+++ b/mcxtrace-comps/examples/Tests_samples/Test_PowderN/README.md
@@ -13,15 +13,15 @@
```text
Simply a model source illuminating a powder sample.
-The default sample itself is an LaB6-powder.
+The default sample itself is a LaB6-powder.
Alternatively, the Single_crystal (powder mode) and FluoPowder components can also be tested.
```
## Examples
-- **Test: index=1 Detector: Sph_mon_I=1.26755e-11**
-- Example: index=2 Detector: Sph_mon_I=4.44793e-13
-- **Test: index=3 Detector: Sph_mon_I=1.98093e-11**
+- **Test: index=1 Detector: Sph_mon_I=1.29869e-12**
+- Example: index=2 Detector: Sph_mon_I=3.88313e-14
+- **Test: index=3 Detector: Sph_mon_I=6.29534e-12**
-
- (Unittest disabled for Single_crystal powder-mode, numerically unstable on GPU)
diff --git a/mcxtrace-comps/examples/Tests_samples/Test_SAXS/README.md b/mcxtrace-comps/examples/Tests_samples/Test_SAXS/README.md
index 946cdbca83..e89370d232 100644
--- a/mcxtrace-comps/examples/Tests_samples/Test_SAXS/README.md
+++ b/mcxtrace-comps/examples/Tests_samples/Test_SAXS/README.md
@@ -38,7 +38,7 @@ SAXSPDBFast SAMPLE=11
- **Test: SAMPLE=4 Detector: PSDMonitor_I=1.16433e-10**
- **Test: SAMPLE=5 Ncount=1e4 Detector: PSDMonitor_I=1.2001e-14**
- **Test: SAMPLE=6 Ncount=1e4 Detector: PSDMonitor_I=1.2400e-14**
-- **Test: SAMPLE=7 Ncount=1e4 Detector: PSDMonitor_I=7.07865e-14**
+- **Test: SAMPLE=7 Ncount=1e4 Detector: PSDMonitor_I=5.54e-14**
- **Test: SAMPLE=9 Detector: PSDMonitor_I=1.11073e-14**
- **Test: SAMPLE=10 Detector: PSDMonitor_I=1.02884e-14**
- **Test: SAMPLE=11 Detector: PSDMonitor_I=5.47707e-15**
diff --git a/mcxtrace-comps/examples/Tests_samples/Test_Saxs_spheres/README.md b/mcxtrace-comps/examples/Tests_samples/Test_Saxs_spheres/README.md
index 58a1b66537..3b92363cbb 100644
--- a/mcxtrace-comps/examples/Tests_samples/Test_Saxs_spheres/README.md
+++ b/mcxtrace-comps/examples/Tests_samples/Test_Saxs_spheres/README.md
@@ -20,7 +20,7 @@ The spheres are nominally made from Be in non-absorbing solution.*
## Examples
-- **Test: Test_Saxs_spheres.instr -n1e6 RR=20 Detector: detector2_I=5.0956e-16**
+- **Test: Test_Saxs_spheres.instr RR=20 Detector: detector2_I=5.0956e-16**
## Input parameters
diff --git a/mcxtrace-comps/examples/XFEL/XFEL_SPB/README.md b/mcxtrace-comps/examples/XFEL/XFEL_SPB/README.md
index fa1a671e5d..07e748e7d8 100644
--- a/mcxtrace-comps/examples/XFEL/XFEL_SPB/README.md
+++ b/mcxtrace-comps/examples/XFEL/XFEL_SPB/README.md
@@ -19,7 +19,7 @@ experimental hutch.
## Examples
-- **Test: XFEL_SPB.instr preCRL=0 -n1e7 L0=1.3051 DL=0.01 Detector: detector_I=0.00194989**
+- **Test: XFEL_SPB.instr preCRL=0 L0=1.3051 DL=0.01 Detector: detector_I=0.00194989**
## Input parameters
diff --git a/tools/Python/README.html b/tools/Python/README.html
index dcffb81522..c19de6b178 100644
--- a/tools/Python/README.html
+++ b/tools/Python/README.html
@@ -87,11 +87,11 @@ Tool-class pages
| mcplot family |
-mcplot / mxplot, mcplotdiff / mxplotdiff, mccoplot / mxcoplot — html / matplotlib / pyqtgraph / matlab variants |
+mcplot / mxplot, mcplotdiff / mxplotdiff, mccoplot / mxcoplot — html / matplotlib / pyqtgraph / plopp / matlab variants |
| mcdisplay family |
-mcdisplay / mxdisplay — pyqtgraph (default) / matplotlib / webgl / webgl-classic / cad / matlab variants |
+mcdisplay / mxdisplay — pyqtgraph (default) / matplotlib / webgl / webgl-classic / plopp / cad / mantid / matlab variants |
| mctest family |
@@ -134,7 +134,7 @@
| Plot one simulation's results |
-mcplot-{html,matplotlib,pyqtgraph}
mxplot-{html,matplotlib,pyqtgraph} |
+mcplot-{html,matplotlib,pyqtgraph,plopp}
mxplot-{html,matplotlib,pyqtgraph,plopp} |
Compare exactly two simulations (a - b) |
@@ -146,13 +146,17 @@
| Visualise instrument geometry + particle trajectories |
-mcdisplay-{pyqtgraph,matplotlib,webgl,webgl-classic}
mxdisplay-{pyqtgraph,matplotlib,webgl,webgl-classic} |
+mcdisplay-{pyqtgraph,matplotlib,webgl,webgl-classic,plopp}
mxdisplay-{pyqtgraph,matplotlib,webgl,webgl-classic,plopp} |
| Export instrument geometry to a CAD file |
mcdisplay-cad
mxdisplay-cad |
+Export instrument geometry to a Mantid IDF (.xml) |
+mcdisplay-mantid
mxdisplay-mantid |
+
+
| Plot/display results in Matlab, Octave, or iFit instead |
mcplot-matlab / mxplot-matlab
mcdisplay-matlab / mxdisplay-matlab |
@@ -168,6 +172,10 @@