mccode-dev · mads-bertelsen-agentic · Sep 3, 2026 · Sep 4, 2026 · Sep 7, 2026 · Sep 8, 2026
diff --git a/docs/GRAMMAR/ADR-records/ADR_20260909_UNION_GLOBALS.md b/docs/GRAMMAR/ADR-records/ADR_20260909_UNION_GLOBALS.md
@@ -0,0 +1,62 @@
+# Union libraries and globals handled by code generator
+
+## Status
+
+This is a proposed change
+
+## Context
+
+The original Union components were developed under McStas 2.X and used global variables for a number 
+of lists that were used to transfer information between components. 
+In McStas and McXtrace 3.X that was no longer possible, so the `Union_init` and `Union_stop` component were 
+added. They were required to surround all the Union components used in an instrument. The `Union_init` 
+loaded the required libraries and set up the global variables, then all other Union components would read the
+variables from that component, needing the name on it as the init parameter. The init parameter had a default
+of `init` so if the `Union_init` instance was given that name, there was no need to specify that parameter. 
+`Union_stop` component added switch statements for process functions, avoiding cases that are not actually in
+the current instrument using the preprocessor. The included files are in share and do need updating when new 
+processes / geometries are added. They are called `union-init.c`, `union-lib.c` and `union-suffix.c`.
+
+## Decision
+
+Let the code generator insert the `union-init.c`, `union-lib.c` and `union-suffix.c` files at the
+appropriate positions if a `Union_master` or a `Union_master_GPU` is detected. It works by searching
+for a `Union_master`/`Union_master_GPU` component, if found it adds `read_table-lib.h`, `union-lib.c` 
+and `union-init.c` before all component SHARE sections and `union-suffix.c` after all component SHARE
+sections. It also creates a Union preprocessor macro that can be used to detect whether Union is active 
+in this instrument.
+
+All Union components emit compile errors if the Union preprocessor macro is not defined, this is done 
+in each component. 
+
+Keep the `Union_init` and `Union_stop` components for a transition period, but they now only contain
+the code emitting the deprecation warning.
+
+Remove the init input on all Union components.
+
+## Consequences
+
+It becomes easier to use the Union components as there is no need to place `Union_init` or `Union_stop`.
+
+Instruments using the `init` parameter in any Union component will need that removed as the parameter
+was removed.
+
+Existing instruments that do not use the init parameter for individual components but have the `Union_init`
+and/or `Union_stop` components still work and only show the deprecation warnings. A mismatch between 
+version of the components and code generator could lead to problems, but the same preprocessor guards are used.
+Main issue would be an instrument using a folder of new Union components with an old code generator, in that case 
+the intentional compile errors would be triggered.
+
+No change the location of .c files in share that needs to be easily accesible to developers.
+
+Cogen would need to be updated if `Union_master` or `Union_master_GPU` name is changed.
+
+## Behaviour
+
+- In valid use, Union systems no longer need the `Union_init` and `Union_stop`
+- Using the `Union_init` and `Union_stop` won't break instruments, but show deprecation warnings
+- Using the init parameter in Union components will fail as the parameter is removed
+- Compilation fails if any Union component is used without a `Union_master` or `Union_master_GPU`
+
+
+
diff --git a/docs/manuals/mcstas/union/AF_HB_1D_process.tex b/docs/manuals/mcstas/union/AF_HB_1D_process.tex
@@ -47,12 +47,11 @@ \subsection*{Input parameters}
 J\_interaction & meV & Exchange constant & 1 \\
 packing\_factor & 1 & How dense is the material compared to optimal 0-1 & 1 \\
 interact\_fraction & 1 & How large a part of the scattering events should use this process 0-1 (sum of all processes in material = 1) & -1 \\
-init & string & name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/AF_HB_1D_process.comp}{Source code} for \texttt{AF\_HB\_1D\_process.comp}.
 \end{itemize}
-\IfFileExists{AF_HB_1D_process_static.tex}{\input{AF_HB_1D_process_static.tex}}{}
+\IfFileExists{AF_HB_1D_process_static.tex}{\input{AF_HB_1D_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/IncoherentPhonon_process.tex b/docs/manuals/mcstas/union/IncoherentPhonon_process.tex
@@ -49,7 +49,6 @@ \subsection*{Input parameters}
 kabsmin & A\textasciicircum{}-1 & Lower cut-off for the neutron wave-vector k & 0.1 \\
 kabsmax & A\textasciicircum{}-1 & Higher cut-off for the neutron wave-vector k & 25 \\
 interact\_fraction & 1 & How large a part of the scattering events should use this process 0-1 (sum of all processes in material = 1) & -1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
@@ -58,4 +57,4 @@ \subsection*{Links}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/IncoherentPhonon_process.comp}{Source code} for \texttt{IncoherentPhonon\_process.comp}.
   \item See \textless{}a href="https://doi.org/10.3233/JNR-190117"\textgreater{}https://doi.org/10.3233/JNR-190117\textless{}/a\textgreater{}
 \end{itemize}
-\IfFileExists{IncoherentPhonon_process_static.tex}{\input{IncoherentPhonon_process_static.tex}}{}
+\IfFileExists{IncoherentPhonon_process_static.tex}{\input{IncoherentPhonon_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Incoherent_process.tex b/docs/manuals/mcstas/union/Incoherent_process.tex
@@ -46,7 +46,6 @@ \subsection*{Input parameters}
 packing\_factor & 1 & How dense is the material compared to optimal 0-1 & 1 \\
 unit\_cell\_volume & AA\textasciicircum{}3 & Unit cell volume & 13.8 \\
 interact\_fraction & 1 & How large a part of the scattering events should use this process 0-1 (sum of all processes in material = 1) & -1 \\
-init & string & name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
@@ -55,4 +54,4 @@ \subsection*{Links}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Incoherent_process.comp}{Source code} for \texttt{Incoherent\_process.comp}.
   \item The test/example instrument \textless{}a href="../examples/Test\_Phonon.instr"\textgreater{}Test\_Phonon.instr\textless{}/a\textgreater{}.
 \end{itemize}
-\IfFileExists{Incoherent_process_static.tex}{\input{Incoherent_process_static.tex}}{}
+\IfFileExists{Incoherent_process_static.tex}{\input{Incoherent_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Mirror_surface.tex b/docs/manuals/mcstas/union/Mirror_surface.tex
@@ -51,12 +51,11 @@ \subsection*{Input parameters}
 alpha & AA & Slope of reflectivity & 6.07 \\
 m & 1 & m-value of material. Zero means completely absorbing. & 2 \\
 W & AA-1 & Width of supermirror cut-off & 0.003 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Mirror_surface.comp}{Source code} for \texttt{Mirror\_surface.comp}.
 \end{itemize}
-\IfFileExists{Mirror_surface_static.tex}{\input{Mirror_surface_static.tex}}{}
+\IfFileExists{Mirror_surface_static.tex}{\input{Mirror_surface_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/NCrystal_process.tex b/docs/manuals/mcstas/union/NCrystal_process.tex
@@ -61,12 +61,11 @@ \subsection*{Input parameters}
 cfg & str & NCrystal material configuration string (details \textless{}a href="https://github.com/mctools/ncrystal/wiki/Using-NCrystal"\textgreater{}on this page\textless{}/a\textgreater{}). & "" \\
 packing\_factor & 1 & Material packing factor & 1 \\
 interact\_fraction & 1 & How large a part of the scattering events should use this process 0-1 (sum of all processes in material = 1) & -1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/NCrystal_process.comp}{Source code} for \texttt{NCrystal\_process.comp}.
 \end{itemize}
-\IfFileExists{NCrystal_process_static.tex}{\input{NCrystal_process_static.tex}}{}
+\IfFileExists{NCrystal_process_static.tex}{\input{NCrystal_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Non_process.tex b/docs/manuals/mcstas/union/Non_process.tex
@@ -44,12 +44,11 @@ \subsection*{Input parameters}
 packing\_factor & 1 & How dense is the material compared to optimal 0-1 & 1 \\
 unit\_cell\_volume & AA\textasciicircum{}3 & Unit cell volume & 13.8 \\
 interact\_fraction & 1 & How large a part of the scattering events should use this process 0-1 (sum of all processes in material = 1) & -1 \\
-init & string & name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Non_process.comp}{Source code} for \texttt{Non\_process.comp}.
 \end{itemize}
-\IfFileExists{Non_process_static.tex}{\input{Non_process_static.tex}}{}
+\IfFileExists{Non_process_static.tex}{\input{Non_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/PhononSimple_process.tex b/docs/manuals/mcstas/union/PhononSimple_process.tex
@@ -52,12 +52,11 @@ \subsection*{Input parameters}
 DW & 1 & Debye-Waller factor & 1 \\
 longitudinal & 0/1 & Simulate longitudinal branches & 1 \\
 transverse & 0/1 & Simulate transverse branches & 1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/PhononSimple_process.comp}{Source code} for \texttt{PhononSimple\_process.comp}.
 \end{itemize}
-\IfFileExists{PhononSimple_process_static.tex}{\input{PhononSimple_process_static.tex}}{}
+\IfFileExists{PhononSimple_process_static.tex}{\input{PhononSimple_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Template_process.tex b/docs/manuals/mcstas/union/Template_process.tex
@@ -47,12 +47,11 @@ \subsection*{Input parameters}
 packing\_factor & 1 & How dense is the material compared to optimal 0-1 & 1 \\
 unit\_cell\_volume & AA\textasciicircum{}3 & Unit\_cell\_volume & 13.8 \\
 interact\_fraction & 1 & How large a part of the scattering events should use this process 0-1 (sum of all processes in material = 1) & -1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Template_process.comp}{Source code} for \texttt{Template\_process.comp}.
 \end{itemize}
-\IfFileExists{Template_process_static.tex}{\input{Template_process_static.tex}}{}
+\IfFileExists{Template_process_static.tex}{\input{Template_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Template_surface.tex b/docs/manuals/mcstas/union/Template_surface.tex
@@ -53,12 +53,11 @@ \subsection*{Input parameters}
 alpha & AA & Slope of reflectivity & 6.07 \\
 m & 1 & m-value of material. Zero means completely absorbing. & 2 \\
 W & AA-1 & Width of supermirror cut-off & 0.003 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Template_surface.comp}{Source code} for \texttt{Template\_surface.comp}.
 \end{itemize}
-\IfFileExists{Template_surface_static.tex}{\input{Template_surface_static.tex}}{}
+\IfFileExists{Template_surface_static.tex}{\input{Template_surface_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Texture_process.tex b/docs/manuals/mcstas/union/Texture_process.tex
@@ -42,7 +42,6 @@ \subsection*{Input parameters}
 interact\_fraction & 1 & How large a part of the scattering events should use this process 0-1 (sum of all processes in material = 1) & -1 \\
 packing\_factor & 1 & How dense is the material compared to optimal 0-1 & 1 \\
 maxNeutronSaved & 1 & Maximum number of neutron cross sections saved for reusing & 1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
@@ -51,4 +50,4 @@ \subsection*{Links}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Texture_process.comp}{Source code} for \texttt{Texture\_process.comp}.
   \item See \textless{}a href="https://doi.org/10.3233/JNR-190117"\textgreater{}https://doi.org/10.3233/JNR-190117\textless{}/a\textgreater{}
 \end{itemize}
-\IfFileExists{Texture_process_static.tex}{\input{Texture_process_static.tex}}{}
+\IfFileExists{Texture_process_static.tex}{\input{Texture_process_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Union_abs_logger_1D_space.tex b/docs/manuals/mcstas/union/Union_abs_logger_1D_space.tex
@@ -72,12 +72,11 @@ \subsection*{Input parameters}
 order\_total & 1 & Only log rays that have scattered n times, -1 for all orders & -1 \\
 order\_volume & 1 & Only log rays that have scattered n times in the same geometry, -1 for all orders & -1 \\
 logger\_conditional\_extend\_index & 1 & If a conditional is used with this logger, the result of each conditional calculation can be made available in extend as a array called "logger\_conditional\_extend", and one would then access logger\_conditional\_extend[n] if logger\_conditional\_extend\_index is set to n & -1 \\
-init & string & name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Union_abs_logger_1D_space.comp}{Source code} for \texttt{Union\_abs\_logger\_1D\_space.comp}.
 \end{itemize}
-\IfFileExists{Union_abs_logger_1D_space_static.tex}{\input{Union_abs_logger_1D_space_static.tex}}{}
+\IfFileExists{Union_abs_logger_1D_space_static.tex}{\input{Union_abs_logger_1D_space_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Union_abs_logger_1D_space_event.tex b/docs/manuals/mcstas/union/Union_abs_logger_1D_space_event.tex
@@ -82,12 +82,11 @@ \subsection*{Input parameters}
 order\_total & 1 & Only log rays that have scattered n times, -1 for all orders & -1 \\
 order\_volume & 1 & Only log rays that have scattered n times in the same geometry, -1 for all orders & -1 \\
 logger\_conditional\_extend\_index & 1 & If a conditional is used with this logger, the result of each conditional calculation can be made available in extend as a array called "logger\_conditional\_extend", and one would then access logger\_conditional\_extend[n] if logger\_conditional\_extend\_index is set to n & -1 \\
-init & string & name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Union_abs_logger_1D_space_event.comp}{Source code} for \texttt{Union\_abs\_logger\_1D\_space\_event.comp}.
 \end{itemize}
-\IfFileExists{Union_abs_logger_1D_space_event_static.tex}{\input{Union_abs_logger_1D_space_event_static.tex}}{}
+\IfFileExists{Union_abs_logger_1D_space_event_static.tex}{\input{Union_abs_logger_1D_space_event_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Union_abs_logger_1D_space_tof.tex b/docs/manuals/mcstas/union/Union_abs_logger_1D_space_tof.tex
@@ -75,12 +75,11 @@ \subsection*{Input parameters}
 order\_total & 1 & Only log rays that have scattered n times, -1 for all orders & -1 \\
 order\_volume & 1 & Only log rays that have scattered n times in the same geometry, -1 for all orders & -1 \\
 logger\_conditional\_extend\_index & 1 & If a conditional is used with this logger, the result of each conditional calculation can be made available in extend as a array called "logger\_conditional\_extend", and one would then access logger\_conditional\_extend[n] if logger\_conditional\_extend\_index is set to n & -1 \\
-init & string & name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Union_abs_logger_1D_space_tof.comp}{Source code} for \texttt{Union\_abs\_logger\_1D\_space\_tof.comp}.
 \end{itemize}
-\IfFileExists{Union_abs_logger_1D_space_tof_static.tex}{\input{Union_abs_logger_1D_space_tof_static.tex}}{}
+\IfFileExists{Union_abs_logger_1D_space_tof_static.tex}{\input{Union_abs_logger_1D_space_tof_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Union_abs_logger_1D_space_tof_to_lambda.tex b/docs/manuals/mcstas/union/Union_abs_logger_1D_space_tof_to_lambda.tex
@@ -106,12 +106,11 @@ \subsection*{Input parameters}
 order\_total & 1 & Only log rays that have scattered n times, -1 for all orders & -1 \\
 order\_volume & 1 & Only log rays that have scattered n times in the same geometry, -1 for all orders & -1 \\
 logger\_conditional\_extend\_index & 1 & If a conditional is used with this logger, the result of each conditional calculation can be made available in extend as a array called "logger\_conditional\_extend", and one would then access logger\_conditional\_extend[n] if logger\_conditional\_extend\_index is set to n & -1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Union_abs_logger_1D_space_tof_to_lambda.comp}{Source code} for \texttt{Union\_abs\_logger\_1D\_space\_tof\_to\_lambda.comp}.
 \end{itemize}
-\IfFileExists{Union_abs_logger_1D_space_tof_to_lambda_static.tex}{\input{Union_abs_logger_1D_space_tof_to_lambda_static.tex}}{}
+\IfFileExists{Union_abs_logger_1D_space_tof_to_lambda_static.tex}{\input{Union_abs_logger_1D_space_tof_to_lambda_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Union_abs_logger_1D_time.tex b/docs/manuals/mcstas/union/Union_abs_logger_1D_time.tex
@@ -73,12 +73,11 @@ \subsection*{Input parameters}
 order\_total & 1 & Only log rays that have scattered n times, -1 for all orders & -1 \\
 order\_volume & 1 & Only log rays that have scattered n times in the same geometry, -1 for all orders & -1 \\
 logger\_conditional\_extend\_index & 1 & If a conditional is used with this logger, the result of each conditional calculation can be made available in extend as a array called "logger\_conditional\_extend", and one would then access logger\_conditional\_extend[n] if logger\_conditional\_extend\_index is set to n & -1 \\
-init & string & name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Union_abs_logger_1D_time.comp}{Source code} for \texttt{Union\_abs\_logger\_1D\_time.comp}.
 \end{itemize}
-\IfFileExists{Union_abs_logger_1D_time_static.tex}{\input{Union_abs_logger_1D_time_static.tex}}{}
+\IfFileExists{Union_abs_logger_1D_time_static.tex}{\input{Union_abs_logger_1D_time_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Union_abs_logger_2D_space.tex b/docs/manuals/mcstas/union/Union_abs_logger_2D_space.tex
@@ -82,12 +82,11 @@ \subsection*{Input parameters}
 order\_total & 1 & Only log rays that have scattered n times, -1 for all orders & -1 \\
 order\_volume & 1 & Only log rays that have scattered n times in the same geometry, -1 for all orders & -1 \\
 logger\_conditional\_extend\_index & 1 & If a conditional is used with this logger, the result of each conditional calculation can be made available in extend as a array called "logger\_conditional\_extend", and one would then access logger\_conditional\_extend[n] if logger\_conditional\_extend\_index is set to n & -1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Union_abs_logger_2D_space.comp}{Source code} for \texttt{Union\_abs\_logger\_2D\_space.comp}.
 \end{itemize}
-\IfFileExists{Union_abs_logger_2D_space_static.tex}{\input{Union_abs_logger_2D_space_static.tex}}{}
+\IfFileExists{Union_abs_logger_2D_space_static.tex}{\input{Union_abs_logger_2D_space_static.tex}}{}
diff --git a/docs/manuals/mcstas/union/Union_abs_logger_event.tex b/docs/manuals/mcstas/union/Union_abs_logger_event.tex
@@ -72,12 +72,11 @@ \subsection*{Input parameters}
 order\_total & 1 & Only log rays that have scattered n times, -1 for all orders & -1 \\
 order\_volume & 1 & Only log rays that have scattered n times in the same geometry, -1 for all orders & -1 \\
 logger\_conditional\_extend\_index & 1 & If a conditional is used with this logger, the result of each conditional calculation can be made available in extend as a array called "logger\_conditional\_extend", and one would then access logger\_conditional\_extend[n] if logger\_conditional\_extend\_index is set to n & -1 \\
-init & string & Name of Union\_init component (typically "init", default) & "init" \\
 \bottomrule
 \end{longtable}
 
 \subsection*{Links}
 \begin{itemize}
   \item \href{run:/home/willend/willend-McCode/mcstas-comps/union/Union_abs_logger_event.comp}{Source code} for \texttt{Union\_abs\_logger\_event.comp}.
 \end{itemize}
-\IfFileExists{Union_abs_logger_event_static.tex}{\input{Union_abs_logger_event_static.tex}}{}
+\IfFileExists{Union_abs_logger_event_static.tex}{\input{Union_abs_logger_event_static.tex}}{}