Controlling ray tracing execution

The function run_ray_tracing() has many options on the program flow.

xrt.runner.run_ray_tracing(plots=[], repeats=1, updateEvery=1, pickleEvery=None, energyRange=None, backend='raycing', beamLine=None, threads=1, processes=1, generator=None, generatorArgs=[], generatorKWargs='auto', globalNorm=0, afterScript=None, afterScriptArgs=[], afterScriptKWargs={})

This function is the entry point of xrt. Parameters are all optional except the 1st one. Please use them as keyword arguments because the list of parameters may change in future versions.

plots: instance of XYCPlot or a sequence of

instances or an empty sequence if no graphical output is wanted.

repeats: int

The number of ray tracing runs. It should be stressed that accumulated are not rays, which would be limited by the physical memory, but rather the histograms from each run are summed up. In this way the number of rays is unlimited.

updateEvery: int

Redrawing rate. Redrawing happens when the current iteration index is divisible by updateEvery.

pickleEvery: int

Saving rate. Applicable to plots with a defined persistentName. If None, the pickling will happen once at the end.

energyRange: [eMin: float, eMax: float]

Only in shadow backend: If not None, sets the energy range of shadow source. Alternatively, this can be done directly inside the generator.

backend: str

so far supported: {‘shadow’ | ‘raycing’ | ‘dummy’}

beamLine: instance of BeamLine, used

with raycing backend.

threads, processes: int or str

The number of parallel threads or processes, should not be greater than the number of cores in your computer, otherwise it gives no gain. The bigger of the two will be used as a signal for using either threading or multiprocessing. If they are equal, threading is used. See also performance tests. If ‘all’ is given then the number returned by multiprocessing.cpu_count() will be used.

Warning

You cannot use multiprocessing in combination with OpenCL because the resources (CPU or GPU) are already shared by OpenCL. You will get an error if processes > 1. You can still use threads > 1 but with a little gain.

Note

For the shadow backend you must create tmp0, tmp1 etc. directories (counted by threads or processes) in your working directory. Even if the execution is not parallelized, there must be tmp0 with the shadow files prepared in it.

generator: generator object

A generator for running complex ray-tracing studies. It must modify the optics, specify the graph limits, define the output file names etc. in a loop and return to xrt by yield. See the supplied examples.

generatorArgs, generatorKWargs: list and (dictionary or ‘auto’)

If generatorKWargs is ‘auto’, the following keyword dictionary will be used for the generator: kwargs = {} if generator is defined within the caller of run_ray_tracing() or if generatorArgs is not empty, otherwise kwargs = {‘plots’=pots, ‘beamLine’=beamLine}.

globalNorm: bool

If True, the intensity of the histograms will be normalized to the global maximum throughout the series of graphs. There are two flavors of normalization:

1. only the heights of 1D histograms are globally normalized while the brightness is kept with the normalization to the local maximum (i.e. the maximum in the given graph).

2. both the heights of 1D histograms and the brightness of 1D and 2D histograms are globally normalized.

The second way is physically more correct but sometimes is less visual: some of the normalized pictures may become too dark, e.g. when you compare focused and strongly unfocused images. Both normalizations are saved with suffixes _norm1 and _norm2 for you to select the better one.

Here is a normalization example where the intensity maximum was found throughout a series of images for filters of different thickness. The brightest image was for the case of no filter (not shown here) and the normalization shown below was done relative to that image:

normalized to local maximum
global normalization, type 1
global normalization, type 2

afterScript: function object

This function is executed at the end of the current script. For example, it may run the next ray-tracing script.

afterScriptArgs, afterScriptKWargs: list and dictionary

args and kwargs for afterScript.

Using multiprocessing and multithreading

Module multipro defines BackendProcess as a subclass of multiprocessing.Process or threading.Thread. You can opt between deriving from multiprocessing or threading by selecting the corresponding parameter in run_ray_tracing(). The multiprocessing is normally faster than multithreading but has an inconvenience when the user aborts the execution: the processes have to be killed manually.

See the performance tests.