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
ormultiprocessing
. 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 createtmp0
,tmp1
etc. directories (counted by threads or processes) in your working directory. Even if the execution is not parallelized, there must betmp0
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:
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).
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.
- plots: instance of
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.