[NOT READY FOR MERGE] Union refactoring of scattering while loop

[Lomholy]

Free-form text area

Please describe what your PR is adding in terms of features or bugfixes:
This PR aims to improve the readability of the Union_master component. The PR is limited in scope to only the scattering while loop inside Union_master.comp.

To perform this refactoring I propose two things:

1. We separate all non-primary logic paths, out into separate functions (Currently placed in Union_master for my own simplicity, but will be moved to union-lib.c).

2. When determining a non-primary logic paths, we use wrapper functions, that clearly indicate the intent of the branching in logic path.
   An example of this is using:
   if (volume_is_only_absorber(Volumes[current_volume])) {
   Instead of
   if (Volumes[current_volume]->p_physics->number_of_processes == 0) { // If there are no processes, the volume could be vacuum or an absorber
if (Volumes[current_volume]->p_physics->is_vacuum == 0) {

3. (Maybe) We attempt to adhere to a standardized naming scheme for the functions implemented, such that all inhomogenous paths are called "inhomogenous_insert_what_function_does();".

---

Declaration of use of AI-tools

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

---

Development OS / boundary conditions

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

---

PR Checklist for contributing to McStas/McXtrace

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

• My contribution includes patches to an existing component file

  • I have used the mcdoc utility and rendered a reasonable documentation page for the component (please attach as screenshot in comments!)
  • I have ensured that basic use of the component is OK (e.g. an instrument using it compiles?)
  • I have used the mctest utility to test one or more instruments making use of the component (please attach mcviewtest report as screenshot in comments)
  • I have used the mccode-clangformat tool to apply the standard McCode component indentation scheme
  • I have used the mcrun --c-lint "linter" and followed advice to remove most / all warnings that are raised

• My contribution includes patches to an existing instrument file

  • I have used the mcdoc utility and rendered a reasonable documentation page for the instrument (please attach as screenshot in comments!)
  • I have used the mctest utility to test the instrument (please attach mcviewtest report as screenshot in comments)
  • I have used the mcrun --c-lint "linter" and followed advice to remove most / all warnings that are raised

• My work touches / adds to the runtime lib code (.c,.h etc in multiple locations

  • I am have added reasoning and documentation for the change below
  • I am attaching test output in the comments

• My contribution contains something else

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

---

[mads-bertelsen]

This is an ongoing review, but want to get some information across!

The trace loop is certainly easier to read with this. Naming the functions in this complex system is difficult, will think more about how exactly that would be the most intuitive. It's mainly confusing when reading the functions before reading the trace section, which of course is not often done and can be alleviated with a header.

The function calls use pointers for everything, that reduce the overhead on function calls as nothing needs to be copied. It does make the syntax in the functions a bit harder to understand due to all the dereference operations. When a parameter is not updated in a function, one can make a local variable for the dereferenced value and use that in the equations, it should be optimized out by the compiler while being slightly more readable.

Even with the fast function calls, I do want to check the performance impact, although I don't expect it to be significant.

[mads-bertelsen]

The verbal setting will need to change if we support it within union-lib.c, as that setting is currently used by editing Union_master.comp, which is read after union-lib and thus none of the trace_verbal sections of the union-lib.c would trigger. It is better to set this in the instrument, which is possible with a define in the right place, just needs to be documented.

[mads-bertelsen]

As far as I remember this code only runs when a process that requires a forced position due to focusing is included, but the name of the function sounds like the main way of choosing scattering point. Should make that clear in the name.