[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.

[Lomholy]

Is the idea for a common user to be able to use this verbal settings?

If so then it definitely should be in the instrument. But, otherwise wouldn't it be fine to make a #define Union_trace_verbal_setting inside the union-lib.c, if the intent is that it is a debugging tool for the developers?

[mads-bertelsen]

The verbal setting is intended to be for super-users, which is a compromise with performance as that avoids a large number of if statements. With a little documentation it will be fine, it's best to enable / disable in the instrument so the handle to do that by removing a comment within Union_master should be removed. Just a little thing that needs doing in connection with this change.

[Lomholy]

Should we make a Test_Union_master_verbose.instr example instrument that does this?

I just tried running a #define Union_trace_verbal_setting from the declare scope of an instrument, and this seems to be the correct position for it.

[willend]

@Lomholy I think it is maybe a bit much to add a whole instr for that? All that is required for verbosity to be compiled in is

DEPENDENCY “ -DUnion_trace_verbal_setting “

in the instr file… - But an option would be to include that commented, i.e. something like

// Uncomment the below line to enable verbosity in Union master - e.g. for debugging purposses
// DEPENDENCY “ -DUnion_trace_verbal_setting “

[Lomholy]

@willend good point. Adding an entire test instrument for one specific piece of documentation is misplaced.

Since it is such a small thing to include in an instrument, I propose that we add a few lines about it in the Union_master header:

    * Algorithm:
    * Described elsewhere
    *
    * Debugging:
    * Union_master includes three parameters for debugging through its component interface. 
    * These debugs should be enough for most users. However, if it is necessary to debug the trace loop
    * of Union_master.comp this can be done by adding the following dependency to your instrument file:
    * DEPENDENCY “ -DUnion_trace_verbal_setting “
    *

What do you guys think?

[Lomholy]

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.

This is true. We might also think about grouping them together, such that all functions "belonging" to a type of logic, sit close to each other in union-lib. Looking forward to hearing your ideas regarding naming!

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.

I was considering if we should make som helper structs, such that the function calls inside the union_master wouldn't have to be so lengthy. By doing this I also believe these dereferencing issues could be adressed to some degree.

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

Sounds like a good plan. You never know what operations you are by accident performing!

[mads-bertelsen]

Why does this depend on the needs_cross_section_focus part of the struct?

Do we even support processes that need focusing in the cross section calculation, and thus get a forced scattering position to use if the material choose that process, simultaneously being inhomogenous?

[Lomholy]

It does so, because if a material contains both an inhomogenous process, and a focusing process, then the focusing process will need to be sampled as often as the inhomogenous sample.

Do we even support processes that need focusing in the cross section calculation, and thus get a forced scattering position to use if the material choose that process, simultaneously being inhomogenous?

By this, I take it you mean a material that uses both an inhomogenous process and a focusing process. If this is the case then I am quite sure that yes, we do support it (It was at least my intention to do so!)

But still there is an error here. The if statement should be separated, such that we first check if the material has sampling points, then if the process is either inhomogenous, or needs cross section focus, we should return 1.

[Lomholy]

I moved this function all the way up (line 97), but I have implemented the logic in the comment above.

[willend]

@Lomholy the macOS test will very likely run through OK if you update the branch against current main.

(Seems to be a specific issue with mpi that I will resolve separately later.)