simcats 1.1.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

simcats/sensor/deformation/_sensor_peak_deformation_interface.py

@@ -0,0 +1,65 @@
+"""This module contains the interface for simulating deformations of sensor peaks in scans.
+
+@author: b.papajewski
+"""
+
+from abc import ABC, abstractmethod
+from typing import Union
+
+import numpy as np
+
+__all__ = []
+
+from simcats.sensor import SensorInterface
+
+
+class SensorPeakDeformationInterface(ABC):
+    """General interface for sensor peak deformations.
+
+    Classes that implement this abstract class realize different types of deformation of a single wavefront.
+    """
+
+    @abstractmethod
+    def calc_mu(self, dist: Union[float, np.ndarray], mu0: float) -> float:
+        """
+        Method that calculates the deformed potential value of mu0 of a sensor peak that is moved based on
+        the distance (`dist`) to a middle line from which the deformation originates. The middle line follows
+        the direction of the sensor peaks (i.e., the sensor dot potential) and is perpendicular to the wavefronts
+        defined by the peaks.
+
+        Args:
+            dist (Union[float, np.ndarray]): Distance from the middle line, from which the deformation originates. If a
+                point is above the middle line the distance is positive and if it is below, the distance is negative.
+                The parameter can either be a np.ndarray that contains multiple distances or a single distance as a
+                float.
+            mu0 (float): Potential offset for calculation of the deformed potential. Usually this should be the
+                potential offset of the sensor peak, that should be deformed.
+
+        Returns:
+             Union[float, np.ndarray]: Deformed potential value mu0 of a sensor peak. The same type as the type of
+             `dist` is returned.
+        """
+        raise NotImplementedError
+
+    @property
+    def sensor(self) -> SensorInterface:
+        """
+        Returns the sensor object to which the deformed sensor peak belongs.
+
+        Returns:
+            SensorInterface: Sensor object of the deformed sensor peak.
+        """
+        if self.__sensor:
+            return self.__sensor
+        else:
+            return None
+
+    @sensor.setter
+    def sensor(self, sensor: SensorInterface) -> None:
+        """
+        Sets the sensor object to which the deformed sensor peak belongs.
+
+        Args:
+            sensor (SensorInterface): Sensor object of the deformed sensor peak.
+        """
+        self.__sensor = sensor

simcats/sensor/deformation/_sensor_peak_deformation_linear.py

@@ -0,0 +1,77 @@
+"""This module contains the class for simulating a linear deformation of sensor peaks in a scan.
+
+@author: b.papajewski
+"""
+import math
+from typing import Union
+
+import numpy as np
+
+from simcats.sensor.deformation import SensorPeakDeformationInterface
+
+__all__ = []
+
+
+class SensorPeakDeformationLinear(SensorPeakDeformationInterface):
+    """Linear deformation implementation of the SensorPeakDeformationInterface."""
+
+    def __init__(self, angle: float) -> None:
+        """Initialization of an object of the class LinearSensorPeakDeformation.
+        This kind of deformation uses a single line for the deformation of a sensor peak (tilting the wavefront).
+
+        Args:
+            angle (float): Angle of the line that is used for the linear deformation of the sensor peak. This Angle
+                is specified in radians. The angle between the two straight lines is specified, which lies above the
+                deformation line and to the right of the middle line.
+        """
+        super().__init__()
+
+        self.angle = angle
+
+    @property
+    def angle(self) -> float:
+        """Returns the angle of the line used for deforming the sensor peak.
+
+        Returns:
+            float: Angle of the line that is used for the linear deformation of the sensor peak.
+        """
+        return self.__angle
+
+    @angle.setter
+    def angle(self, angle: float):
+        self.__angle = angle
+
+    def calc_mu(self, dist: Union[float, np.ndarray], mu0: float) -> Union[float, np.ndarray]:
+        """
+        Method that calculates the deformed potential value for mu0 of mu0 of a sensor peak that is moved based on the
+        distance (`dist`) to a middle line, from which the deformation originates, using a line. The middle line follows
+        the direction of the sensor peaks (i.e., the sensor dot potential) and is perpendicular to the wavefronts
+        defined by the peaks.
+
+        For the deformation, the potential value of the point of the line that has the given distance to the center line
+        is used.
+
+        Args:
+            dist (Union[float, np.ndarray]): Distance from the middle line, from which the deformation originates. If a
+                point is above the middle line the distance is positive and if it is below, the distance is negative.
+                The parameter can either be a np.ndarray that contains multiple distances or a single distance as a
+                float.
+            mu0 (float): Potential offset for calculation of the deformed potential. Usually this should be the
+                potential offset of the sensor peak, that should be deformed.
+
+        Returns:
+            Union[float, np.ndarray]: Deformed potential value mu0 of a sensor peak. The same type as the type of
+             `dist` is returned.
+        """
+
+        # Calculation of the gradient of the deformation line
+        m = 1 / math.tan(self.angle)
+
+        dif = m * dist
+        dif *= np.linalg.norm(self.sensor.alpha_sensor_gate[0])
+        return mu0 + dif
+
+    def __repr__(self):
+        return (
+            self.__class__.__name__ + f"(angle={self.angle})"
+        )

simcats/support_functions/__init__.py

@@ -3,14 +3,22 @@ SimCATS subpackage with support functions that are not assigned to any specific
 """
 
 from simcats.support_functions._parameter_sampling import ParameterSamplingInterface, NormalSamplingRange, \
-    LogNormalSamplingRange, UniformSamplingRange
+    LogNormalSamplingRange, UniformSamplingRange, ExponentialSamplingRange
 from simcats.support_functions._fermi_filter1d import fermi_filter1d, fermi_dirac_derivative
 from simcats.support_functions._cumulative_distribution_functions import cauchy_cdf, multi_cauchy_cdf, sigmoid_cdf, \
     multi_sigmoid_cdf
+from simcats.support_functions._generalized_logistic_function import glf, inverse_glf, multi_glf
+from simcats.support_functions._reset_offset_mu_sens import reset_offset_mu_sens
 from simcats.support_functions._signed_dist_points_line import signed_dist_points_line
+from simcats.support_functions._linear_algebra import line_line_intersection
+from simcats.support_functions._linear_algebra import line_circle_intersection
+from simcats.support_functions._linear_algebra import is_point_below_line
+from simcats.support_functions._pixel_volt_transformation import pixel_to_volt_1d
 from simcats.support_functions._rotate_points import rotate_points
 from simcats.support_functions._plotting import plot_csd
 
 __all__ = ["ParameterSamplingInterface", "NormalSamplingRange", "LogNormalSamplingRange", "UniformSamplingRange",
-           "fermi_filter1d", "fermi_dirac_derivative", "cauchy_cdf", "multi_cauchy_cdf", "sigmoid_cdf",
-           "multi_sigmoid_cdf", "signed_dist_points_line", "rotate_points", "plot_csd"]
+           "ExponentialSamplingRange", "fermi_filter1d", "fermi_dirac_derivative", "cauchy_cdf", "multi_cauchy_cdf",
+           "sigmoid_cdf", "multi_sigmoid_cdf", "glf", "inverse_glf", "multi_glf", "reset_offset_mu_sens",
+           "signed_dist_points_line", "line_line_intersection", "line_circle_intersection", "is_point_below_line",
+           "pixel_to_volt_1d", "rotate_points", "plot_csd"]

simcats/support_functions/_generalized_logistic_function.py

@@ -0,0 +1,146 @@
+"""This module contains an implementation of the generalized logistic function (GLF) used for sensor barriers.
+
+@author: b.papajewski
+"""
+
+from typing import Union
+
+import numpy as np
+
+
+def glf(potential: Union[float, np.ndarray],
+        asymptote_left: float,
+        asymptote_right: float,
+        growth_rate: float,
+        asymmetry: float,
+        shape_factor: float,
+        denominator_offset: float = 1,
+        offset: float = 0
+        ) -> Union[float, np.ndarray]:
+    """Function implementing the generalized logistic function.
+    For further information see: https://en.wikipedia.org/wiki/Generalised_logistic_function
+
+    Args:
+        potential (Union[float, np.ndarray]): Originally called t. The potential is the variable of the GLF for which
+            the value of the function should be calculated.
+        asymptote_left (float): Originally called A. This parameter is the left horizontal asymptote of the function.
+            Any rational number can be used as the left asymptote. This parameter may take any rational number.
+        asymptote_right (float): Originally called K. Specifies the right horizontal asymptote of the function
+            when denominator_offset=1. If asymptote_left=0 and denominator_offset=1 then this parameter is also called
+            the carrying capacity. This parameter may take any rational number.
+        growth_rate (float): Originally called B. The growth rate of the function. The value must be a float and can be
+            any rational number. Be careful with negative values, because the function is mirrored on a vertical
+            straight line for these. This line passes through the point where the potential equals `offset`.
+        asymmetry (float): Originally called nu. This parameter introduces skew and affects symmetry. It also affects
+            near which asymptote maximum growth occurs. The value of asymmetry must be a rational number greater than
+            zero. \n
+            - `asymmetry > 1`: the curve rises more gradually before the midpoint and more sharply after. \n
+            - `asymmetry < 1`: the curve rises quickly early on and levels off more slowly.
+        shape_factor (float): Originally called Q. is related to the value Y(0) and adjusts the curve’s value at the
+            y-intercept. Thereby it changes the shape of the function without changing the asymptotes. The shape factor
+            can be any rational number.
+        denominator_offset (float): Originally called C. A constant added to the denominator inside the power. Controls
+            the initial level of the denominator.This parameter must be a rational number.
+            It typically takes a value of 1. Otherwise, the upper asymptote is
+            asymptote_left + (asymptote_right-asymptote_left)/(denominator_offset^(1/asymmetry)).
+        offset (float): Parameter that shifts the function starting from the zero point. If the offset is positive, the
+            function is shifted to the right and if it is negative, it is shifted to the left.
+
+    Returns:
+        Union[float, np.ndarray]: Value of the GLF at the given potential (originally time t) for a given set of
+        parameters. The returned datatype is the same as the type of `potential`.
+    """
+
+    return asymptote_left + ((asymptote_right - asymptote_left) / (
+        np.power(denominator_offset + shape_factor * np.exp(-growth_rate * (potential - offset)), (1 / asymmetry))))
+
+
+def inverse_glf(
+        value: Union[float, np.ndarray],
+        asymptote_left: float,
+        asymptote_right: float,
+        growth_rate: float,
+        asymmetry: float,
+        shape_factor: float,
+        denominator_offset: float = 1,
+        offset: float = 0
+) -> Union[float, np.ndarray]:
+    """
+    Inverse of the function `glf` which computes the inverse of a generalized logistic function for a set of parameters.
+
+    Args:
+        value: The input value(s) for which to compute the inverse GLF. Can be a single float or a numpy array.
+        asymptote_left (float): Originally called A. This parameter is the left horizontal asymptote of the function.
+            Any rational number can be used as the left asymptote. This parameter may take any rational number.
+        asymptote_right (float): Originally called K. Specifies the right horizontal asymptote of the function
+            when denominator_offset=1. If asymptote_left=0 and denominator_offset=1 then this parameter is also called
+            the carrying capacity. This parameter may take any rational number.
+        growth_rate (float): Originally called B. The growth rate of the function. The value must be a float and can be
+            any rational number. Be careful with negative values, because the function is mirrored on a vertical
+            straight line for these. This line passes through the point where the potential equals `offset`.
+        asymmetry (float): Originally called nu. This parameter introduces skew and affects symmetry. It also affects
+            near which asymptote maximum growth occurs. The value of asymmetry must be a rational number greater than
+            zero. \n
+            - `asymmetry > 1`: the curve rises more gradually before the midpoint and more sharply after. \n
+            - `asymmetry < 1`: the curve rises quickly early on and levels off more slowly.
+        shape_factor (float): Originally called Q. is related to the value Y(0) and adjusts the curve’s value at the
+            y-intercept. Thereby it changes the shape of the function without changing the asymptotes. The shape factor
+            can be any rational number.
+        denominator_offset (float): Originally called C. A constant added to the denominator inside the power. Controls
+            the initial level of the denominator.This parameter must be a rational number.
+            It typically takes a value of 1. Otherwise, the upper asymptote is \n
+            asymptote_left + (asymptote_right-asymptote_left)/(denominator_offset^(1/asymmetry)).
+        offset (float): Parameter that shifts the function starting from the zero point. If the offset is positive, the
+            function is shifted to the right and if it is negative, it is shifted to the left.
+
+    Returns:
+        Union[float, np.ndarray]: Potential (originally time t) of the inverse GLF at the given value for a given set of
+        parameters. The returned datatype is the same as the type of `value`.
+    """
+    return (growth_rate * offset - np.log((((asymptote_left - asymptote_right) / (
+            asymptote_left - value)) ** asymmetry - denominator_offset) / shape_factor)) / growth_rate
+
+
+def multi_glf(potential: Union[float, np.ndarray], *params: float) -> Union[float, np.ndarray]:
+    """Function that combines several GLFs as a sum into one function.
+    For further information see: https://en.wikipedia.org/wiki/Generalised_logistic_function
+
+    Each GLF has the following parameters: \n
+    - asymptote_left (float): Originally called A. This parameter is the left horizontal asymptote of the function.
+      Any rational number can be used as the left asymptote.
+    - asymptote_right (float): Originally called K. Specifies the right horizontal asymptote of the function
+      when denominator_offset=1. If asymptote_left=0 and denominator_offset=1 then this parameter is also called the
+      carrying capacity. This parameter may take any rational number.
+    - growth_rate (float): Originally called B. The growth rate of the function. The value must be a float and can be
+      any rational number. Be careful with negative values, because the function is mirrored on a vertical straight
+      line for these. This line passes through the point where the potential equals `offset`.
+    - asymmetry (float): Originally called nu. This parameter introduces skew and affects symmetry. It also affects
+      near which asymptote maximum growth occurs. The value of asymmetry must be a rational number greater than zero. \n
+      - If `asymmetry > 1`: the curve rises more gradually before the midpoint and more sharply after. \n
+      - If `asymmetry < 1`: the curve rises quickly early on and levels off more slowly.
+    - shape_factor (float):  Originally called Q. is related to the value Y(0) and adjusts the curve’s value at the
+      y-intercept. Thereby it changes the shape of the function without changing the asymptotes. The shape factor
+      can be any rational number.
+    - denominator_offset (float):  Originally called C. A constant added to the denominator inside the power. Controls
+      the initial level of the denominator.This parameter must be a rational number.
+      It typically takes a value of 1. Otherwise, the upper asymptote is \n
+      asymptote_left + (asymptote_right - asymptote_left) / (denominator_offset^(1 / asymmetry)).
+    - offset (float): Potential offset, that shifts the function starting from the zero point. If the offset is
+      positive, the function is shifted to the right and if it is negative, it is shifted to the left.
+
+    The number of GLFs is specified by the number of parameters. To do this, the parameter count must be divisible by
+    seven and a GLF is added for every seven other parameters.
+
+    Args:
+        potential (Union[float, np.ndarray]): Originally called t. The potential is the variable of the GLF for which
+            the value of the function should be calculated.
+        *params: Additional positional arguments representing the GLF parameters. The number of additional parameters
+            must be divisible by seven and determines the number of GLFs that are used for the Multi-GLF. All parameters
+            consist of sequential groups of seven floats that each represent a single GLF. All individual parameters are
+            described above and are in the same order as they are described.
+
+    Returns:
+        Union[float, np.ndarray]: Value of the GLF at the given potential (originally time t).
+    """
+    assert not (len(params) % 7)
+    return sum([glf(potential, *params[i: i + 7]) for i in range(0, len(params), 7)])

simcats/support_functions/_linear_algebra.py

@@ -0,0 +1,171 @@
+"""This module provides functionality based on linear algebra for evaluating geometric relationships, such as between
+two lines or between a point and a line.
+
+@author: b.papajewski
+"""
+
+import numbers
+from typing import Union, Sequence, Tuple, List
+
+import numpy as np
+
+
+def is_point_below_line(point: Tuple[float, float], line: Union[Tuple[float, float], float]) -> bool:
+    """Method for evaluating whether a point is below a line.
+
+    Args:
+        point (Tuple[float, float]): Point to be evaluated.
+        line (Union[Tuple[float, float], float]: Either a straight line (m*x+b) given as a tuple (m,b) or as a single
+            value if it is a horizontal line. This then specifies the height b of the line.
+
+    Returns:
+        bool: True if the point is below the line, False otherwise.
+    """
+    x, y = point
+
+    # If the straight line is specified as a single float, it is a horizontal line
+    if isinstance(line, int):
+        b = line
+        return y < b
+    # If the straight line is specified as a tuple (m, b)
+    elif isinstance(line, tuple) and len(line) == 2:
+        m, b = line
+        y_line = m * x + b
+        return y < y_line
+    else:
+        raise ValueError(
+            "The straight line must be specified either as a tuple (m, b) or as a single integer for a horizontal line.")
+
+
+def line_line_intersection(line1: Union[Sequence, np.ndarray, numbers.Real],
+                           line2: Union[Sequence, np.ndarray, numbers.Real]):
+    """Method for calculating the intersection of two lines.
+    Both lines can be specified either by a straight line equation (m*x+b) or by a single number if it is a vertical
+    line. The single number gives the x coordinate of the vertical line.
+
+    Args:
+        line1 (Union[Sequence, np.ndarray, numbers.Real]): A two element sequence when it's a straight line equation
+            (m,b) or a single number when line1 is a vertical line. In this case, the number indicates the x coordinate
+            of the vertical line.
+        line2 (Union[Sequence, np.ndarray, numbers.Real]): A two element sequence when it's a straight line equation
+            (m,b) or a single number when line1 is a vertical line. In this case, the number indicates the x coordinate
+            of the vertical line.
+
+    Returns:
+        The x and y coordinates of the intersection of the two lines. If there is no intersection, an exception
+        is thrown.
+    """
+    for i, line in enumerate((line1, line2), start=1):
+        if not (isinstance(line, numbers.Real) or len(line) == 2):
+            raise ValueError(f"Invalid parameter - line{i} must either be a single number or an sequence with two elements!")
+
+    # Both lines are straight line equations
+    if isinstance(line1, (Sequence, np.ndarray)) and isinstance(line2, (Sequence, np.ndarray)):
+        m1, b1 = line1
+        m2, b2 = line2
+
+        # Check if lines are parallel
+        if m1 == m2:
+            if b1 == b2:
+                raise ValueError("The lines are the same.")
+            else:
+                raise ValueError("The lines are parallel and do not intersect.")
+
+        # Compute intersection point
+        x = (b2 - b1) / (m1 - m2)
+        y = m1 * x + b1
+
+        return np.array([x, y])
+
+    # Line1 is a straight line equation and line2 is a vertical line
+    elif isinstance(line1, (Sequence, np.ndarray)):
+        m1, b1 = line1
+        return np.array([line2, m1 * line2 + b1])
+
+    # Line1 is a vertical line and line2 is a straight line equation
+    elif isinstance(line2, (Sequence, np.ndarray)):
+        m2, b2 = line2
+        return np.array([line1, m2 * line1 + b2])
+
+    # Both lines are vertical lines und therefore also parallel
+    else:
+        if line1 == line2:
+            raise ValueError("The lines are the same.")
+        else:
+            raise ValueError("The lines are parallel and do not intersect.")
+
+
+def line_circle_intersection(line: Union[float, Tuple], circle_center: Tuple, radius: float):
+    """Method for calculating the intersection of a line and a circle.
+
+    Args:
+        line (Union(float,Tuple)): The line with which the intersection points are to be calculated. This line can
+            either be given as a tuple with the slope and y-intercept in the form (m,b) or as a float if it is a
+            vertical line.
+        circle_center (Tuple): The center of the circle. The center is specified as a tuple (x-center, y-center).
+        radius (float): The radius of the circle. The radius is specified as float that can be any rational number
+            greater than 0.
+
+    Returns:
+        List[Tuple]: This method returns a list of the intersection points of the line and a circle. The points are
+        returned as a tuple with the form (x-coordinate,y-coordinate). The list of intersection points can contain zero
+        to two tuples. Accordingly, an empty list is returned if the line and the circle have no intersection.
+    """
+    if radius <= 0:
+        raise ValueError("The radius of the circle must be greater than 0.")
+
+    center_x, center_y = circle_center
+
+    # Check whether the line is a vertical line
+    if isinstance(line, tuple):
+        m, b = line
+
+        # Calculation of the coefficients of the quadratic equation system
+        A = 1 + m ** 2
+        B = 2 * (m * b - m * center_y - center_x)
+        C = center_x ** 2 + center_y ** 2 + b ** 2 - 2 * b * center_y - radius ** 2
+
+        # Calculation of the discriminant
+        discriminant = B ** 2 - 4 * A * C
+
+        if discriminant < 0:
+            # No intersection
+            return []
+        elif discriminant == 0:
+            # Single intersection
+            x = -B / (2 * A)
+            y = m * x + b
+            return [(x, y)]
+        else:
+            # Two intersections
+            sqrt_discriminant = np.sqrt(discriminant)
+            x1 = (-B + sqrt_discriminant) / (2 * A)
+            y1 = m * x1 + b
+            x2 = (-B - sqrt_discriminant) / (2 * A)
+            y2 = m * x2 + b
+            return [(x1, y1), (x2, y2)]
+    else:
+        # Vertical line x = c
+        c = line
+
+        # Calculation of the y-values
+        A = 1
+        B = -2 * center_y
+        C = center_y ** 2 + (c - center_x) ** 2 - radius ** 2
+
+        # Calculation of the discriminant
+        discriminant = B ** 2 - 4 * A * C
+
+        if discriminant < 0:
+            # No intersection
+            return []
+        elif discriminant == 0:
+            # Single intersection
+            y = -B / (2 * A)
+            return [(c, y)]
+        else:
+            # Two intersections
+            sqrt_discriminant = np.sqrt(discriminant)
+            y1 = (-B + sqrt_discriminant) / (2 * A)
+            y2 = (-B - sqrt_discriminant) / (2 * A)
+            return [(c, y1), (c, y2)]