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.


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.


GPU IDs are integers that start from 0.

Returns:A list of available GPU IDs and a list of selected GPU IDs. → 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.


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.


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

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


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.

photon_density (float): photon density.


scatman.set_resolution(resolution: int) → None

Set the resolution of the diffraction pattern, in pixel.


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.


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

scatman.use_gpu() → bool

Move the computation to the GPU.


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