simcats.distortions

SimCATS subpackage containing all functionalities related to the distortion simulation.

Package Contents

Classes

DistortionInterface	General interface for distortions.
OccupationDistortionInterface	Interface for distortions affecting the occupations and lead transitions ("the structure") of a simulated CSD.
SensorPotentialDistortionInterface	Interface for distortions affecting the potential of the sensor used to measure a simulated CSD.
SensorResponseDistortionInterface	Interface for distortions affecting the sensor response of a simulated CSD.
OccupationTransitionBlurringGaussian	Gaussian filter blurring implementation of the OccupationDistortionsInterface.
OccupationTransitionBlurringFermiDirac	Fermi-Dirac filter blurring implementation of the OccupationDistortionsInterface.
OccupationDotJumps	Dot jumps implementation of the OccupationDistortionsInterface.
SensorPotentialPinkNoise	Pink noise implementation of the SensorPotentialDistortionsInterface.
RandomTelegraphNoise	Random telegraph noise (RTN) implementation of the (general) DistortionsInterface.
SensorPotentialRTN	Random telegraph noise (RTN) implementation of the SensorPotentialDistortionInterface.
SensorResponseRTN	Random telegraph noise (RTN) implementation of the SensorResponseDistortionInterface.
SensorResponseWhiteNoise	White noise implementation of the SensorResponseDistortionsInterface.

Functions

dot_jumps_blockwise	Adds dot jumps to the original image.
pink_gaussian_noise	Adds pink Gaussian noise to the original image.
random_telegraph_noise	Adds random telegraph noise to the original image.
white_gaussian_noise	Adds white Gaussian noise to the original image.

Package Implementation Details

class simcats.distortions.DistortionInterface

Bases: abc.ABC

General interface for distortions.

Explicit distortion types are derived from this. The simulation class expects to receive objects of the explicit types, which are assigned to different stages.

abstract noise_function(*args, **kwargs)

This function has to be implemented for adding distortions in any stage of the simulation.

Parameters:

• *args – Specified in subclasses

• **kwargs – Specified in subclasses

Returns:

distorted data

class simcats.distortions.OccupationDistortionInterface

Bases: DistortionInterface

Interface for distortions affecting the occupations and lead transitions (“the structure”) of a simulated CSD.

abstract noise_function(occupations, lead_transitions, volt_limits_g1, volt_limits_g2, generate_csd=None, freeze=False)

This method has to be implemented for adding distortions to the occupations and lead transitions.

Parameters:

• occupations (np.ndarray) – Contains the original occupations to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the occupations.

• lead_transitions (np.ndarray) – Contains the original lead transition mask to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the lead transitions.

• volt_limits_g1 (np.ndarray) – Contains the beginning and ending of the swept range for the first (plunger) gate.

• volt_limits_g2 (np.ndarray) – Contains the beginning and ending of the swept range for the second (plunger) gate.

• generate_csd (Optional[Callable]) – Function which generates data points outside the swept gate range. This is especially required for distortions, which shift the CSD structure. The generated data points also have to contain the distortions, which have already been added to the occupation and lead_transitions before. Default is None.

• freeze (bool) – Indicates if the last used noise should be reused. This is important if there are noise types which need to generate data from outside the current CSD (for example if a part of the structure is shifted). This newly generated data also has to contain the noise which already has been applied to the CSD before.

Returns:

Occupation numbers and lead transition mask (in our case: total charge transitions) with added distortions. The occupation numbers are stored in a 3-dimensional numpy array. The first two dimensions map to the axis of the CSD, while the third dimension indicates the dot of the corresponding occupation value. The label mask for the lead-to-dot transitions is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

Tuple[np.ndarray, np.ndarray]

class simcats.distortions.SensorPotentialDistortionInterface

Bases: DistortionInterface

Interface for distortions affecting the potential of the sensor used to measure a simulated CSD.

abstract noise_function(mu_sens, volt_limits_g1, volt_limits_g2)

This method has to be implemented in every object which should be used to distort the sensor potential of a CSD.

Parameters:

• mu_sens (np.ndarray) – Contains the sensor potential to which the distortions are added. The potential is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis. If there are other types of distortions which appear first, they should already be included in the potential.

• volt_limits_g1 (np.ndarray) – Contains the beginning and ending of the swept range for the first (plunger) gate.

• volt_limits_g2 (np.ndarray) – Contains the beginning and ending of the swept range for the second (plunger) gate.

Returns:

The sensor potential with added distortions. The potential is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

np.ndarray

class simcats.distortions.SensorResponseDistortionInterface

Bases: DistortionInterface

Interface for distortions affecting the sensor response of a simulated CSD.

This includes every effect which happens after the sensor.

abstract noise_function(sensor_response, volt_limits_g1, volt_limits_g2)

Method which has to be implemented by every object used to distort the sensor response of a CSD.

Parameters:

• sensor_response (np.ndarray) – Contains the sensor response to which the distortions are added. The sensor response is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis. If there are other types of distortions which appear first, they should already be included in the response.

• volt_limits_g1 (np.ndarray) – Contains the beginning and ending of the swept range for the first (plunger) gate.

• volt_limits_g2 (np.ndarray) – Contains the beginning and ending of the swept range for the second (plunger) gate.

Returns:

The sensor response with added distortions. The sensor response is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

np.ndarray

class simcats.distortions.OccupationTransitionBlurringGaussian(sigma)

Bases: simcats.distortions.OccupationDistortionInterface

Gaussian filter blurring implementation of the OccupationDistortionsInterface.

Initializes an object of the class used to blur lead transitions and occupations changes.

Parameters:

sigma (Union[float, ParameterSamplingInterface]) – The sigma of the gaussian blur, defining the strength of the blurring. If sigma is of type ParameterSampling a new sigma is sampled accordingly per call of noise_function.

property sigma: float | ParameterSamplingInterface

The sigma of the gaussian blur, defining the strength of the blurring.

Return type:

Union[float, ParameterSamplingInterface]

property latest_sigma: float | None

The sigma that was used for the latest simulation.

This is necessary because, depending on the setting, a sampler can be used instead of a fixed sigma.

Return type:

Optional[float]

noise_function(occupations, lead_transitions, volt_limits_g1, volt_limits_g2, generate_csd=None, freeze=False)

This function is used to add blurring to the supplied occupations and lead transitions.

The distortion parameter is adjusted to the resolution, as it is specified in voltage space but must be applied in pixel space. Warning: This function changes the supplied occupation and lead_transitions arrays. If you want to keep the original ones, please give a copy of them into this function.

Parameters:

• occupations (np.ndarray) – Contains the original occupation to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the occupations. Warning: this argument is changed during the execution of the function.

• lead_transitions (np.ndarray) – Contains the original lead transition mask to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the lead transitions. Warning: this argument is changed during the execution of the function.

• volt_limits_g1 (np.ndarray) – Contains the beginning and ending of the swept range for the first (plunger) gate.

• volt_limits_g2 (np.ndarray) – Contains the beginning and ending of the swept range for the second (plunger) gate.

• generate_csd (Optional[Callable]) – Function which generates data points outside the swept gate range. This is especially required for distortions, which shift the CSD structure. The generated data points also have to contain the distortions, which have already been added to the occupation and lead_transitions before.

• freeze (bool) – Indicates if the last used noise should be reused. This is important if there are noise types which need to generate data from outside the current CSD (for example if a part of the structure is shifted). This newly generated data also has to contain the noise which already has been applied to the CSD before.

Returns:

Occupation numbers and lead transition mask (in our case: total charge transitions) with added distortions. The occupation numbers are stored in a 3-dimensional numpy array. The first two dimensions map to the axis of the CSD, while the third dimension indicates the dot of the corresponding occupation value. The label mask for the lead-to-dot transitions is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

Tuple[np.ndarray, np.ndarray]

class simcats.distortions.OccupationTransitionBlurringFermiDirac(sigma)

Bases: simcats.distortions.OccupationDistortionInterface

Fermi-Dirac filter blurring implementation of the OccupationDistortionsInterface.

Initializes an object of the class used to blur lead transitions and occupations changes.

Parameters:

sigma (Union[float, ParameterSamplingInterface]) – The sigma of the Fermi-Dirac blur, defining the strength of the blurring. If sigma is of type ParameterSampling a new sigma is sampled accordingly per call of noise_function.

property sigma: float | ParameterSamplingInterface

The sigma of the Fermi-Dirac blur, defining the strength of the blurring.

Return type:

Union[float, ParameterSamplingInterface]

property latest_sigma: float | None

The sigma that was used for the latest simulation.

This is necessary because, depending on the setting, a sampler can be used instead of a fixed sigma.

Return type:

Optional[float]

noise_function(occupations, lead_transitions, volt_limits_g1, volt_limits_g2, generate_csd=None, freeze=False)

This function is used to add blurring to the supplied occupations and lead transitions.

The distortion parameter is adjusted to the resolution, as it is specified in voltage space but must be applied in pixel space. Warning: This function changes the supplied occupation and lead_transitions arrays. If you want to keep the original ones, please give a copy of them into this function.

Parameters:

• occupations (np.ndarray) – Contains the original occupation to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the occupations. Warning: this argument is changed during the execution of the function.

• lead_transitions (np.ndarray) – Contains the original lead transition mask to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the lead transitions. Warning: this argument is changed during the execution of the function.

• volt_limits_g1 (np.ndarray) – Contains the beginning and ending of the swept range for the first (plunger) gate.

• volt_limits_g2 (np.ndarray) – Contains the beginning and ending of the swept range for the second (plunger) gate.

• generate_csd (Optional[Callable]) – Function which generates data points outside the swept gate range. This is especially required for distortions, which shift the CSD structure. The generated data points also have to contain the distortions, which have already been added to the occupation and lead_transitions before.

• freeze (bool) – Indicates if the last used noise should be reused. This is important if there are noise types which need to generate data from outside the current CSD (for example if a part of the structure is shifted). This newly generated data also has to contain the noise which already has been applied to the CSD before.

Returns:

Occupation numbers and lead transition mask (in our case: total charge transitions) with added distortions. The occupation numbers are stored in a 3-dimensional numpy array. The first two dimensions map to the axis of the CSD, while the third dimension indicates the dot of the corresponding occupation value. The label mask for the lead-to-dot transitions is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

Tuple[np.ndarray, np.ndarray]

class simcats.distortions.OccupationDotJumps(scale, lam, axis, ratio=1, rng=np.random.default_rng())

Bases: simcats.distortions.OccupationDistortionInterface

Dot jumps implementation of the OccupationDistortionsInterface.

Dot jumps are simulated by adding shifts in the occupations.

Initializes an object of the class used to generate dot jumps.

Parameters:

• scale (Union[float, ParameterSamplingInterface]) – Specifies the length of the shifts, gives the mathematical expectation for their length. In this case, scale specifies the width of the block in which a shift is present. Given in volt per pixel. If the scale is of type ParameterSampling a new scale is sampled accordingly per call of noise_function.

• lam (Union[float, ParameterSamplingInterface]) – Lambda for the poisson distribution which specifies the height of the jumps. Given in volt per pixel. If lam is of type ParameterSampling a new lam is sampled accordingly per call of noise_function.

• axis (int) – The axis along which dot jumps will be generated. That means, the values are also shifted along this axis. For axis=0 this results into shifts along the y/g2-axis and for axis=1 into shifts along the x/g1-axis.

• ratio (float) – The ratio defining how often this type of distortion should be active. For each simulation a random number decides if the distortion type is active, based on the supplied ratio. Default is 1.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

property scale: float | ParameterSamplingInterface

Specifies the length of the shifts, gives the mathematical expectation for their length.

In this case, scale specifies the width of the block in which a shift is present. Given in volt per pixel.

Return type:

Union[float, ParameterSamplingInterface]

property lam: float | ParameterSamplingInterface

Lambda for the poisson distribution which specifies the height of the jumps. Given in volt per pixel.

Return type:

Union[float, ParameterSamplingInterface]

property axis: int

The axis along which dot jumps will be generated.

That means, the values are also shifted along this axis. For axis=0 this results into shifts along the y/g2-axis and for axis=1 into shifts along the x/g1-axis.

Return type:

int

property ratio: float

The ratio defining how often this type of distortion should be active.

Return type:

float

property rng: numpy.random.Generator

The random number generator used for the simulation of random numbers.

Return type:

numpy.random.Generator

property activated: bool | None

This is true if the noise was activated during the last call of noise function.

Return type:

Optional[bool]

noise_function(occupations, lead_transitions, volt_limits_g1, volt_limits_g2, generate_csd=None, freeze=False)

This function is used to add dot jumps to the supplied occupations and lead transitions.

The distortion parameters are adjusted to the resolution, as they are specified in voltage space but must be applied in pixel space. Warning: This function changes the supplied occupation and lead_transitions arrays. If you want to keep the original ones, please give a copy of them into this function.

Parameters:

• occupations (np.ndarray) – Contains the original occupations to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the occupations. Warning: this argument is changed during the execution of the function.

• lead_transitions (np.ndarray) – Contains the original lead transition mask to which the distortions are added. If there are other types of distortions which appear first, they should already be included in the lead transitions. Warning: this argument is changed during the execution of the function.

• volt_limits_g1 (np.ndarray) – Contains the beginning and ending of the swept range for the first (plunger) gate.

• volt_limits_g2 (np.ndarray) – Contains the beginning and ending of the swept range for the second (plunger) gate.

• generate_csd (Optional[Callable]) – Function which generates data points outside the swept gate range. This is especially required for distortions, which shift the CSD structure. The generated data points also have to contain the distortions, which have already been added to the occupation and lead_transitions before. Defaults to None.

• freeze (bool) – Indicates if the last used noise should be reused. This is important if there are noise types which need to generate data from outside the current CSD (for example if a part of the structure is shifted). This newly generated data also has to contain the noise which already has been applied to the CSD before. A use case for that is the application of dot jumps in vertical direction after the application in horizontal direction. Due to the jumps in vertical direction new data might have to be generated with generate_csd. In this data, the horizontal jumps also have to be applied.

Returns:

Occupation numbers and lead transition mask (in our case: total charge transitions) with added distortions. The occupation numbers are stored in a 3-dimensional numpy array. The first two dimensions map to the axis of the CSD, while the third dimension indicates the dot of the corresponding occupation value. The label mask for the lead-to-dot transitions is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

Tuple[np.ndarray, np.ndarray]

simcats.distortions.dot_jumps_blockwise(original, scale, lam, noise=None, axis=1, rng=np.random.default_rng())

Adds dot jumps to the original image.

In this case that means, that a whole block of columns can be shifted in x direction (axis=1) or a block of lines can be shifted in y direction (axis=0).

When this is applied to charge stability diagrams (CSDs) it should be applied before any other distortion type directly to the occupation of the dots. It can be applied for the occupation of the first dot and after that the generated distortion which is returned can be used for the second dot. This should be done because otherwise different blocks are shifted for the occupations of the first and the second dot.

Parameters:

• original (np.ndarray) – Original image where the distortions should be added. Can be lead transition mask or occupations.

• scale (float) – Specifies the length of the shifts, gives the mathematical expectation for their length. In this case, scale specifies the width of the block in which a shift is present. Given in pixels.

• lam (float) – Lambda for the poisson distribution which specifies the height of the jumps. Given in pixels.

• noise (np.ndarray) – Noise which was generated with this method for a prior image and should be reapplied for this image. Default is None.

• axis (int) – The axis along which dot jumps will be generated. That means the values are shifted along this axis.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

Returns:

Distorted version of the original image and pure distortion which was used for this image and could be used again for the second dot of the dataset.

Return type:

np.ndarray, np.ndarray

class simcats.distortions.SensorPotentialPinkNoise(sigma, fmin=0, rng=np.random.default_rng())

Bases: simcats.distortions.SensorPotentialDistortionInterface

Pink noise implementation of the SensorPotentialDistortionsInterface.

Initializes an object of the class used to generate pink noise.

Parameters:

• sigma (Union[float, ParameterSamplingInterface]) – The sigma for the pink noise distribution. If sigma is of type ParameterSampling a new sigma is sampled accordingly per call of noise_function.

• fmin (float) – Minimal frequency which can be present in the generated noise. The maximal possible value is 0.5 which generates white noise. The minimal value is 1/(number of pixels). The default is 0, which results in the same as 1/(number of pixels).

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

property sigma: float | ParameterSamplingInterface

The sigma for the pink noise distribution.

Return type:

Union[float, ParameterSamplingInterface]

property fmin: float

Minimal frequency which can be present in the generated noise.

Return type:

float

property rng: numpy.random.Generator

The random number generator used for the simulation of random numbers.

Return type:

numpy.random.Generator

property latest_sigma: float

The sigma that was used for the latest simulation.

This is necessary because, depending on the setting, a sampler can be used instead of a fixed sigma.

Return type:

float

noise_function(mu_sens, volt_limits_g1, volt_limits_g2)

This function is used to add pink noise to the sensor potential of a CSD.

Parameters:

• mu_sens (np.ndarray) – Contains the sensor potential to which the distortions are added. The potential is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis. If there are other types of distortions which appear first, they should already be included in the potential.

• volt_limits_g1 (np.ndarray) – Contains the beginning and ending of the swept range for the first (plunger) gate.

• volt_limits_g2 (np.ndarray) – Contains the beginning and ending of the swept range for the second (plunger) gate.

Returns:

The sensor potential with added noise. The potential is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

np.ndarray

simcats.distortions.pink_gaussian_noise(original, scale, fmin, rng=np.random.default_rng())

Adds pink Gaussian noise to the original image.

Parameters:

• original (np.ndarray) – Original image where the noise should be added.

• scale (float) – Scaling factor with which the generated noise is multiplied. This is also the standard deviation (STD) for the noise.

• fmin (float) – Minimal frequency which can be present in the generated noise. The maximal possible value is 0.5 which generates white noise. The minimal value is 1/(number of pixels).

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

Returns:

Original image distorted by pink noise.

Return type:

np.ndarray

class simcats.distortions.RandomTelegraphNoise(scale, std, height, ratio=1, rng=np.random.default_rng())

Bases: simcats.distortions.DistortionInterface

Random telegraph noise (RTN) implementation of the (general) DistortionsInterface.

This general implementation is independent of the distortion step/type (occupations, sensor potential, or sensor response). Specific implementations are derived from this generic one.

Initializes an object of the class used to simulate random telegraph noise.

Parameters:

• scale (Union[float, ParameterSamplingInterface]) – Specifies the length of the bursts/mathematical expectation for their length and also the length of regions without bursts. If the scale is of type ParameterSampling a new scale is sampled accordingly per call of noise_function.

• std (Union[float, ParameterSamplingInterface]) – The standard deviation of the magnitude of the jumps. If std is of type ParameterSampling a new std is sampled accordingly per call of noise_function.

• height (Union[float, ParameterSamplingInterface]) – The mean of the magnitude of the jumps. If the height is of type ParameterSampling a new height is sampled accordingly per call of noise_function.

• ratio (float) – The ratio defining how often this type of noise should be active. For each simulation a random number decides if the noise type is active, based on the supplied ratio. Default is 1.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

property scale: float | ParameterSamplingInterface

Specifies the length of the bursts/mathematical expectation for their length and also the length of regions without bursts.

Return type:

Union[float, ParameterSamplingInterface]

property std: float | ParameterSamplingInterface

The standard deviation of the magnitude of the jumps.

Return type:

Union[float, ParameterSamplingInterface]

property height: float | ParameterSamplingInterface

The mean of the magnitude of the jumps.

Return type:

Union[float, ParameterSamplingInterface]

property ratio: float

The ratio defining how often this type of noise should be active.

Return type:

float

property rng: numpy.random.Generator

The random number generator used for the simulation of random numbers.

Return type:

numpy.random.Generator

property activated: bool | None

This is true if the noise was activated during the last call of noise function.

Return type:

Optional[bool]

noise_function(original, volt_limits_g1, volt_limits_g2)

Adds random telegraph noise to the original image.

The distortion parameter scale is adjusted to the resolution, as it is specified in voltage space but must be applied in pixel space.

Parameters:

• original (np.ndarray) – Original image. Can be a sensor potential or a sensor response

• volt_limits_g1 (np.ndarray) –

  Voltage sweep range of (plunger) gate 1 (second-/x-axis).

  Example:

  [min_V1, max_V1]

• volt_limits_g2 (np.ndarray) –

  Voltage sweep range of (plunger) gate 2 (first-/y-axis).

  Example:

  [min_V2, max_V2]

Returns:

Original image distorted by random telegraph noise.

Return type:

np.ndarray

class simcats.distortions.SensorPotentialRTN(scale, std, height, ratio=1, rng=np.random.default_rng())

Bases: RandomTelegraphNoise, simcats.distortions.SensorPotentialDistortionInterface

Random telegraph noise (RTN) implementation of the SensorPotentialDistortionInterface.

Initializes an object of the class used to simulate random telegraph noise affecting the sensor potential.

Parameters:

• scale (Union[float, ParameterSamplingInterface]) – Specifies the length of the bursts/mathematical expectation for their length and also the length of regions without bursts. If the scale is of type ParameterSampling a new scale is sampled accordingly per call of noise_function.

• std (Union[float, ParameterSamplingInterface]) – The standard deviation of the magnitude of the jumps. If std is of type ParameterSampling a new std is sampled accordingly per call of noise_function.

• height (Union[float, ParameterSamplingInterface]) – The mean of the magnitude of the jumps. If the height is of type ParameterSampling a new height is sampled accordingly per call of noise_function.

• ratio (float) – The ratio defining how often this type of noise should be active. For each simulation a random number decides if the noise type is active, based on the supplied ratio. Default is 1.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

noise_function(mu_sens, volt_limits_g1, volt_limits_g2)

Adds random telegraph noise to the sensor potential.

The distortion parameters are adjusted to the resolution, as they are specified in voltage space but must be applied in pixel space.

Parameters:

• mu_sens (np.ndarray) – Contains the sensor potential to which the noise is added. The potential is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis. If there are other types of distortions which appear first, they should already be included in the potential.

• volt_limits_g1 (np.ndarray) –

  Voltage sweep range of (plunger) gate 1 (second-/x-axis).

  Example:

  [min_V1, max_V1]

• volt_limits_g2 (np.ndarray) –

  Voltage sweep range of (plunger) gate 2 (first-/y-axis).

  Example:

  [min_V2, max_V2]

Returns:

The sensor potential with added noise. The potential is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

np.ndarray

property scale: float | ParameterSamplingInterface

Specifies the length of the bursts/mathematical expectation for their length and also the length of regions without bursts.

Return type:

Union[float, ParameterSamplingInterface]

property std: float | ParameterSamplingInterface

The standard deviation of the magnitude of the jumps.

Return type:

Union[float, ParameterSamplingInterface]

property height: float | ParameterSamplingInterface

The mean of the magnitude of the jumps.

Return type:

Union[float, ParameterSamplingInterface]

property ratio: float

The ratio defining how often this type of noise should be active.

Return type:

float

property rng: numpy.random.Generator

The random number generator used for the simulation of random numbers.

Return type:

numpy.random.Generator

property activated: bool | None

This is true if the noise was activated during the last call of noise function.

Return type:

Optional[bool]

class simcats.distortions.SensorResponseRTN(scale, std, height, ratio=1, rng=np.random.default_rng())

Bases: RandomTelegraphNoise, simcats.distortions.SensorResponseDistortionInterface

Random telegraph noise (RTN) implementation of the SensorResponseDistortionInterface.

Initializes an object of the class used to simulate random telegraph noise affecting the sensor response.

Parameters:

• scale (Union[float, ParameterSamplingInterface]) – Specifies the length of the bursts/mathematical expectation for their length and also the length of regions without bursts. If the scale is of type ParameterSampling a new scale is sampled accordingly per call of noise_function.

• std (Union[float, ParameterSamplingInterface]) – The standard deviation of the magnitude of the jumps. If std is of type ParameterSampling a new std is sampled accordingly per call of noise_function.

• height (Union[float, ParameterSamplingInterface]) – The mean of the magnitude of the jumps. If the height is of type ParameterSampling a new height is sampled accordingly per call of noise_function.

• ratio (float) – The ratio defining how often this type of noise should be active. For each simulation a random number decides if the distortions type is active, based on the supplied ratio. Default is 1.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

noise_function(sensor_response, volt_limits_g1, volt_limits_g2)

Adds random telegraph noise to the sensor response.

The distortion parameters are adjusted to the resolution, as they are specified in voltage space but must be applied in pixel space.

Parameters:

• sensor_response (np.ndarray) – Contains the sensor response to which the noise is added. The sensor response is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis. If there are other types of distortions which appear first, they should already be included in the response.

• volt_limits_g1 (np.ndarray) –

  Voltage sweep range of plunger gate 1 (second-/x-axis).

  Example:

  [min_V1, max_V1]

• volt_limits_g2 (np.ndarray) –

  Voltage sweep range of plunger gate 2 (first-/y-axis).

  Example:

  [min_V2, max_V2]

Returns:

The sensor response with added noise. The sensor response is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

np.ndarray

property scale: float | ParameterSamplingInterface

Specifies the length of the bursts/mathematical expectation for their length and also the length of regions without bursts.

Return type:

Union[float, ParameterSamplingInterface]

property std: float | ParameterSamplingInterface

The standard deviation of the magnitude of the jumps.

Return type:

Union[float, ParameterSamplingInterface]

property height: float | ParameterSamplingInterface

The mean of the magnitude of the jumps.

Return type:

Union[float, ParameterSamplingInterface]

property ratio: float

The ratio defining how often this type of noise should be active.

Return type:

float

property rng: numpy.random.Generator

The random number generator used for the simulation of random numbers.

Return type:

numpy.random.Generator

property activated: bool | None

This is true if the noise was activated during the last call of noise function.

Return type:

Optional[bool]

simcats.distortions.random_telegraph_noise(original, scale, std, height, rng=np.random.default_rng())

Adds random telegraph noise to the original image.

Parameters:

• original (np.ndarray) – Original image where the noise should be added.

• scale (float) – Specifies the length of the bursts/mathematical expectation for their length and also the length of regions without bursts.

• std (float) – The standard deviation of the magnitude of the jumps.

• height (float) – The mean of the magnitude of the jumps.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

Returns:

Original image with noisy added to it.

Return type:

np.ndarray

class simcats.distortions.SensorResponseWhiteNoise(sigma, rng=np.random.default_rng())

Bases: simcats.distortions.SensorResponseDistortionInterface

White noise implementation of the SensorResponseDistortionsInterface.

Initializes an object of the class used to generate white noise.

Parameters:

• sigma (Union[float, ParameterSamplingInterface]) – Standard deviation for the Gaussian distribution of the noise, determines the strength of the noise. If sigma is of type ParameterSampling a new sigma is sampled accordingly per call of noise_function.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

property rng: numpy.random.Generator

The random number generator used for the simulation of random numbers.

Return type:

numpy.random.Generator

property sigma: float | ParameterSamplingInterface

Standard deviation for the Gaussian distribution of the noise, determines the strength of the noise.

Return type:

Union[float, ParameterSamplingInterface]

property latest_sigma: float | None

The sigma that was used for the latest simulation.

This is necessary because, depending on the setting, a sampler can be used instead of a fixed sigma.

Return type:

Optional[float]

noise_function(sensor_response, volt_limits_g1, volt_limits_g2)

Adds white noise to the sensor response.

Parameters:

• sensor_response (np.ndarray) – Contains the sensor response to which the noise are added. The sensor response is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis. If there are other types of distortions which appear first, they should already be included in the response.

• volt_limits_g1 (np.ndarray) –

  Voltage sweep range of (plunger) gate 1 (second-/x-axis).

  Example:

  [min_V1, max_V1]

• volt_limits_g2 (np.ndarray) –

  Voltage sweep range of (plunger) gate 2 (first-/y-axis).

  Example:

  [min_V2, max_V2]

Returns:

The sensor response with added noise. The sensor response is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis.

Return type:

np.ndarray

simcats.distortions.white_gaussian_noise(original, sigma, rng=np.random.default_rng())

Adds white Gaussian noise to the original image.

Parameters:

• original (np.ndarray) – Original image where the noise should be added.

• sigma (float) – Standard deviation for the Gaussian distribution of the noise, determines the strength of the noise. For an array, the entries determine the different noise strength in x and y direction.

• rng (np.random.Generator) – The random number generator used for the simulation of random numbers. Default is np.random.default_rng().

Returns:

Original image with added noise.

Return type:

np.ndarray