McXtrace - An X-ray ray-trace simulation package

A.2  Component classes

A Union simulation is assembled from components of several distinct classes, always used in the same overall order:

1. Process components – define a scattering process (section A.2.2).

2. Union_make_material – collect processes and an absorption cross section into a named material (section A.2.3).

3. Geometry components – place a volume with a given material in the simulation (section A.2.4).

4. Union_master – performs the actual ray tracing for all volumes defined since the previous master (section A.2.5).

A.2.1  Loading the Union library

Union components need no setup or cleanup components. Each one loads the Union library itself, and the library keeps the internal bookkeeping lists (of processes, materials, geometries, …) that the components communicate through, freeing them once the last Union component has finished.

An instrument that uses Union components must contain at least one Union_master; without one it fails to compile, with an error naming Union_components_need_a_Union_master_in_the_instrument. Union components placed after the last Union_master have no effect, and the simulation warns about each of them when it finishes.

Union_init and Union_stop, which older instruments place first and last among their Union components, are no longer needed. They are kept without effect, apart from a deprecation warning, so that such instruments still compile. For the same reason every Union component still accepts the string parameter init, which older instruments set to the name of their Union_init component; its value is ignored.

A.2.2  Scattering processes

A process component has no physical shape of its own. It describes a single physical scattering mechanism: a function giving the inverse penetration depth (macroscopic cross section) as a function of incoming wavevector, and a function describing what happens to a ray in a scattering event. Table A.1 lists the processes currently available. Note that x-ray-specific processes (Compton_xrl_process, KN_xrl_process, Rayleigh_xrl_process) take a density and an atomic number atomno rather than a cross section, and use the external xraylib library for the underlying physics.

Every process has an interact_fraction setting parameter, in the range \([0,1]\) or \(-1\) to disable, which can be used to artificially force a certain fraction of scattering events to that process (an importance sampling technique, entirely analogous to p_interact discussed below); the resulting ray weight is corrected automatically so the simulation remains unbiased. If left at \(-1\) for every process in a material, the interact fractions default to the actual, physical scattering probabilities.

A minimal example defining a Compton scattering process for copper:

1COMPONENT compton1 = Compton_xrl_process(density=8.92, atomno=29) 
2AT (0,0,0) ABSOLUTE

A process component’s position in the instrument file is irrelevant to the physics (it has no shape); its name is what matters, since materials refer to processes by name.

A.2.3  Union_make_material

Union_make_material collects one or more previously defined processes into a named material, together with the absorption cross section (as the inverse penetration depth, my_absorption, in m\(^{-1}\)):

1COMPONENT cmpton1 = Union_make_material( 
2    process_string="compton1", my_absorption=0) 
3AT (0,0,0) ABSOLUTE

As x-ray absorption and scattering are often already captured by the xrl-based processes’ own physics, it is common to see my_absorption=0 in practice, as in the example above and the complete worked example in section A.4. If process_string is left unset, all processes defined since the previous Union_make_material are collected automatically; giving it explicitly is recommended, since it makes the resulting material self-documenting. Two material names are reserved and always available without being explicitly defined: "Vacuum" (no processes, no absorption) and "Exit" (behaves like vacuum, but see section A.2.4.0 below). Setting absorber=1 instead of giving a process_string creates a purely absorbing material with no scattering processes at all.

A.2.4  Geometry components

A geometry component places a volume of a given shape and material in the simulation, using the material name from Union_make_material and the ordinary AT/ROTATED keywords for position and orientation. The currently available shapes are Union_box, Union_cylinder, Union_sphere and Union_cone (which can also represent a plain cylinder by setting radius_top=radius_bottom, or a full cone by leaving one of them at its default of 0). No ray tracing happens in a geometry component itself – it only registers the volume with the following Union_master.

Every geometry component shares a common set of setting parameters, summarized in table A.2, in addition to its own shape-specific dimensions (e.g. radius/yheight for Union_cylinder; xwidth/yheight/zdepth for Union_box; radius_top/radius_bottom/ yheight for Union_cone).

Unlike the McStas Union components, the McXtrace geometry components do not yet have any surface/cut_surface-style parameters – there is no reflection/refraction (surface) support in the McXtrace port (section A.1).

p_interact and multiple scattering

Unlike p_interact in an ordinary McXtrace sample component, p_interact on a Union volume applies at every step of the multiple scattering loop, not just once. Setting it to 50%, for instance, gives a 25% chance of two scattering events in that volume. It is therefore best kept well below 1; values close to 1 lead to very high probabilities of high-order multiple scattering and correspondingly large statistical weight corrections.

Masks

A mask volume restricts one or more other (masked) volumes: a ray only sees the masked volume’s material where the masked volume and the mask volume(s) both cover the same space. This gives additional geometric freedom beyond what overlap-by-priority alone provides. A masked volume can have several masks; mask_setting ("All" or "Any", default "All") controls whether every mask or just any one of them must cover a point for the masked volume to apply there. A mask volume is set via mask_string (a comma-separated list of the geometry names it masks) rather than material_string.

Exit volumes and number_of_activations

Normally, once a ray enters the region of space covered by a Union_master, it stays inside the Union ray-tracing loop until it escapes all defined volumes. Sometimes it is useful to break out of this loop early – for example to place an ordinary McXtrace monitor or component somewhere inside an otherwise Union-simulated geometry. Assigning a volume the special material "Exit" achieves this: once a ray enters an exit volume, the current master stops and the next McXtrace component in the instrument sequence runs as normal.

number_of_activations (default 1) controls how many subsequent Union_master components will simulate a given volume, which is useful when a static piece of geometry should be present across more than one master section of the instrument without redefining it.

A.2.5  Union_master

Union_master is where the actual ray tracing happens – it is the component that is placed into the ordinary linear McXtrace component sequence, and by default it simulates every volume defined since the previous master (or, for the first master, since the start of the instrument). If a volume is defined after the last Union_master in the file, it will never be simulated – remember to place a master after your geometry.

1COMPONENT master = Union_master() 
2AT (0,0,0) RELATIVE sample_position

Union_master also has an allow_inside_start setting (set to 1 if rays are expected to start already inside a volume at this master) and verbal/list_verbal/finally_verbal settings for diagnostic terminal output; see the Component Manual entry for the complete list. Unlike McStas’s Union components, there is currently no separate GPU-enabled master variant for McXtrace.