Setting functions¶

The follwing methods aim to set the relevant parameters for the scatman module.

Simulation of photons count¶

When the simulation involves also the photon statistics (i.e. when a detector is used that is not just the MSFT one), the number of scattered photons must be taken into account, to correctly simulate the Poisson statistics of photons that impinge on the detector. The number of scattered photons depend both on the photon density of the beam and on the optical properties of the sample. A highly absorbing material scatters much more photons than an almost transparent one.

The Scatman module is able to simulate the photon statistics, and the photon density (counts over area unit) can be set (see the list of setting functions). When the calculation of the photon count is performed, the following (probably wrong or highly simplifying) assumptions are made:

All the photons absorbed by the sample are scattered, and
All the scattered photons arrive on the detector, i.e. no photons fall outside the detector area.

Warning

please keep in mind these two assumptions if you try to get meaningful physical results from the Scatman. I decline any responsibility concerning the meaningfulness of what comes out from these assumptions.

List of functions¶

scatman.get_cpu_threads() → Tuple[int, int]¶

Get the maximum number of available CPU cores and the currently selected one.

Returns:	maximum number of available CPU cores and the amount of threads that the module is currently using.

scatman.get_gpu_ids() → Tuple[List[int], List[int]]¶

Get the IDs of available and selected GPUs.

Note

GPU IDs are integers that start from 0.

Returns:	A list of available GPU IDs and a list of selected GPU IDs.

scatman.info() → None¶

Print all the information about the current setup.

The provided information concerns both the current hardware configuration and the experimental parameters.

scatman.init() → None¶

Initialize the computational environment.

The function allocates memory and makes the hardware ready to compute the MSFT, depending on the current hardware configuration.

Note

An explicit call to this function is not mandatory. Each time that the hardware configuration is changed (GPUs, CPU threads, etc.), the function is automatically called before computing the first MSFT, if it wasn’t explicitly called before.

Warning

If the function is not called explicitly after having changed the hardware configuration, it is thus executed automatically before computing the first MSFT, introducing a slowdown in the first computation. When the code performance is tested, the function must be called explicitly before starting the timer, otherwise inconsistent timing results may happen.

scatman.set_angle(angle: float) → None¶

Set the maximum scattering angle $\theta_\text{max}$ .

Parameters:	angle (float) – Maximum scattering angle, in degrees.

scatman.set_cpu_threads(threads: int) → None¶

Set the number of computing CPU threads.

The function set the number of CPU threads. A higher number of threads corresponds to a faster computation. However, this holds only up to a number of threads equal to the number of CPU cores.

Parameters:	threads (int) – Number of threads

scatman.set_experiment(wavelength: float, angle: float, resolution: int, photon_density: float = 1000000.0, rescale: int = -1) → None¶

Set the parameters relevant for the simulation of the experiment.

This function enables to set in just one function call the three relevant parameters that define the experiment

Parameters:	wavelength (float) – radiation wavelength. angle (float) – Maximum scattering angle, in degrees. resolution (int) – linear resolution of the detector, in pixels. photon_density (float) – density of photons. For further information, see here.

scatman.set_fourier_oversampling(os: float) → None¶

Set the oversampling factor in Fourier space.

For a given pattern resolution $R_\text{pattern}$ (for a total number of pixels $R_\text{pattern}^2$ ), the actual resolution at which the MSFT is computed is defined by $R_\text{MSFT} = \texttt{os} \cdot R_\text{pattern}$ (for a total number of pixels $R_\text{MSFT}^2= \texttt{os}^2 \cdot R_\text{pattern}^2$ ). The final pattern is then cutted at the required resolution.

This feature is necessary to mitigate the Discrete Fourier Transform aritfacts at the boundaries. However, it comes at a computational cost. Values between 1.5 and 2 seem to be a good compromise between performance and artifact avoidance. The computational weight of the MSFT scales as $\texttt{os}^2$ .

Parameters:	os (float) – Oversampling factor in Fourier space.

scatman.set_gpu_ids(id: Union[int, List[int]]) → None¶

Set the GPUs to use for the computation. More than one GPU can be selected, by providing a list of IDs.

Note

GPU IDs are integers that start from 0.

Parameters:	id – GPU ID(s).

scatman.set_oversampling(os: int) → None¶

Set the rendering oversapling.

When a shape is rendered on a 3D grid in the real space, before performing the MSFT, the value for each voxel is assigned by sampling the shape in multiple points. For example, setting the value to 3 implies that a total of $3 \times 3 \times 3 = 27$ sample values are taken, within the voxel size, to assign its final value. Higher values mitigate the discretization artifacts, but increase the rendering computational cost.

Parameters:	os (int) – oversampling factor for each axis

scatman.set_photon_density(photon_density: float) → None¶

Set the peak photon density. For further information, see here.

Args:

photon_density (float): photon density.

scatman.set_resolution(resolution: int) → None¶

Set the resolution of the diffraction pattern, in pixel.

Note

For the current implementation, only square patterns are available. This means that the parameter provided as input defines both the size in the two dimensions.

Parameters:	resolution (int) – linear resolution of the detector, in pixels.

scatman.set_verbose(verbosity: bool = 1) → None¶

Set the verbosity level

This function enables to set verbosity level of the module. If set to 1 (True), information about what is going on during the function calls is displayed. If 0 (False), the functions execute silently.

Parameters:	verbosity (bool) – Set verbosity.

scatman.set_wavelength(wavelength: float) → None¶

Set the wavelength of the experiment

Parameters:	wavelength (float) – radiation wavelength.

scatman.use_cpu() → bool¶: Move the computation to the CPU.

Note

It is the default module behavior when the module is imported.

scatman.use_gpu() → bool¶: Move the computation to the GPU.

Note

In case that no GPUs are present on your system, are not detected or the module wasn’t compiled with GPU support, a warning meassge is diplayed and the function has no effect (the computation is performed on the CPU).