FlowCyPy 0.7.0__py3-none-any.whl

FlowCyPy/distribution/lognormal.py

@@ -0,0 +1,124 @@
+from FlowCyPy.distribution.base_class import Base, config_dict
+import numpy as np
+from typing import Tuple
+from scipy.stats import lognorm
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+
+@dataclass(config=config_dict)
+class LogNormal(Base):
+    r"""
+    Represents a log-normal distribution for particle sizes.
+
+    The log-normal distribution is described by its mean and standard deviation of the logarithm of the values:
+
+    .. math::
+        f(x) = \frac{1}{x \sigma \sqrt{2 \pi}} \exp \left( - \frac{(\ln(x) - \mu)^2}{2 \sigma^2} \right)
+
+    where:
+    - :math:`\mu` is the mean of the natural logarithm of the particle sizes.
+    - :math:`\sigma` is the standard deviation of the logarithm of particle sizes.
+
+    Parameters
+    ----------
+    mean : Quantity
+        The mean particle size in meters.
+    std_dev : Quantity
+        The standard deviation of the logarithm of particle sizes.
+    scale_factor : float, optional
+        A scaling factor applied to the PDF (not the sizes).
+    """
+
+    mean: Quantity
+    std_dev: Quantity
+
+    @property
+    def _units(self) -> Quantity:
+        return self.mean.units
+
+    @property
+    def _mean(self) -> Quantity:
+        return self.mean.to(self._units)
+
+    @property
+    def _std_dev(self) -> Quantity:
+        return self.std_dev.to(self._units)
+
+    @Base.pre_generate
+    def generate(self, n_samples: int) -> Quantity:
+        """
+        Generates a log-normal distribution of scatterer sizes.
+
+        The generated sizes follow a log-normal distribution, where the logarithm of the sizes is normally distributed.
+
+        Parameters
+        ----------
+        n_samples : Quantity
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        Quantity
+            An array of scatterer sizes in meters.
+        """
+        return np.random.lognormal(
+            mean=self._mean.magnitude,
+            sigma=self._std_dev.magnitude,
+            size=n_samples
+        )
+
+    def _generate_default_x(self, x_min: float = 0.01, x_max: float = 5, n_samples: int = 40) -> np.ndarray:
+        """
+        Generates a range of x-values based on the log-normal distribution parameters.
+
+        Parameters
+        ----------
+        x_min : float, optional
+            Factor for the minimum x-value as a multiple of the mean. Default is 0.01.
+        x_max : float, optional
+            Factor for the maximum x-value as a multiple of the mean. Default is 5.
+        n_samples : int, optional
+            Number of points in the generated range. Default is 500.
+
+        Returns
+        -------
+        np.ndarray
+            A range of x-values with appropriate units.
+        """
+        if x_min <= 0:
+            raise ValueError("x_min must be greater than 0.")
+        if x_min >= x_max:
+            raise ValueError("x_min must be less than x_max.")
+
+        scale = self.mean.magnitude
+        x_min_value = x_min * scale
+        x_max_value = x_max * scale
+        return np.linspace(x_min_value, x_max_value, n_samples) * self._units
+
+    def get_pdf(self, x_min: float = 0.9, x_max: float = 1.1, n_samples: int = 40) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the x-values and the PDF values for the log-normal distribution.
+
+        Parameters
+        ----------
+        x_min : float, optional
+            Factor for the minimum x-value as a multiple of the mean. Default is 0.01.
+        x_max : float, optional
+            Factor for the maximum x-value as a multiple of the mean. Default is 5.
+        n_samples : int, optional
+            Number of points in the generated range. Default is 500.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding PDF values.
+        """
+        x = self._generate_default_x(x_min=x_min, x_max=x_max, n_samples=n_samples)
+
+        pdf = lognorm.pdf(x.magnitude, s=self._std_dev, scale=self._mean.magnitude)
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Log-Normal({self.mean:.3f~P}, {self.std_dev:.3f~P})"

FlowCyPy/distribution/normal.py

@@ -0,0 +1,128 @@
+from FlowCyPy.distribution.base_class import Base, config_dict
+import numpy as np
+from typing import Tuple
+from scipy.stats import norm
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+
+@dataclass(config=config_dict)
+class Normal(Base):
+    r"""
+    Represents a normal (Gaussian) distribution for particle sizes.
+
+    The normal distribution is described by its mean and standard deviation:
+
+    .. math::
+        f(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp \left( - \frac{(x - \mu)^2}{2 \sigma^2} \right)
+
+    where:
+    - :math:`\mu` is the mean of the distribution (average particle size).
+    - :math:`\sigma` is the standard deviation (width of the distribution).
+    - :math:`x` represents particle sizes.
+
+    Parameters
+    ----------
+    mean : Quantity
+        The mean (average) particle size in meters.
+    std_dev : Quantity
+        The standard deviation of particle sizes in meters.
+    """
+
+    mean: Quantity
+    std_dev: Quantity
+
+    @property
+    def _units(self) -> Quantity:
+        return self.mean.units
+
+    @property
+    def _mean(self) -> Quantity:
+        return self.mean.to(self._units)
+
+    @property
+    def _std_dev(self) -> Quantity:
+        return self.std_dev.to(self._units)
+
+    @Base.pre_generate
+    def generate(self, n_samples: int) -> np.ndarray:
+        """
+        Generates a normal distribution of scatterer sizes.
+
+        The generated sizes are based on the normal distribution's mean and standard deviation.
+
+        Parameters
+        ----------
+        n_samples : int
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of scatterer sizes in meters.
+        """
+        return np.random.normal(
+            loc=self._mean.magnitude,
+            scale=self._std_dev.magnitude,
+            size=n_samples
+        )
+
+    def _generate_default_x(self, x_min: float = -3, x_max: float = 3, n_samples: int = 20) -> np.ndarray:
+        """
+        Generates a range of x-values based on the mean and standard deviation.
+
+        Parameters
+        ----------
+        x_min : float, optional
+            Factor for the minimum x-value as a multiple of the standard deviation from the mean. Default is -3.
+        x_max : float, optional
+            Factor for the maximum x-value as a multiple of the standard deviation from the mean. Default is 3.
+        n_samples : int, optional
+            Number of points in the generated range. Default is 500.
+
+        Returns
+        -------
+        np.ndarray
+            A range of x-values with appropriate units.
+        """
+        if x_min >= x_max:
+            raise ValueError("x_min must be less than x_max.")
+
+        mu = self._mean.magnitude
+        sigma = self._std_dev.magnitude
+        x_min_value = mu + x_min * sigma
+        x_max_value = mu + x_max * sigma
+        return np.linspace(x_min_value, x_max_value, n_samples) * self._units
+
+    def get_pdf(self, x: np.ndarray = None, x_min: float = -3, x_max: float = 3, n_samples: int = 20) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the x-values and the scaled PDF values for the normal distribution.
+
+        Parameters
+        ----------
+        x : np.ndarray, optional
+            The input x-values (particle sizes) over which to compute the PDF. If not provided, a range is generated.
+        x_min : float, optional
+            Factor for the minimum x-value as a multiple of the standard deviation from the mean. Default is -3.
+        x_max : float, optional
+            Factor for the maximum x-value as a multiple of the standard deviation from the mean. Default is 3.
+        n_samples : int, optional
+            Number of points in the generated range. Default is 500.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding PDF values.
+        """
+        x = self._generate_default_x(x_min=x_min, x_max=x_max, n_samples=n_samples)
+
+        pdf = norm.pdf(
+            x.magnitude,
+            loc=self.mean.magnitude,
+            scale=self.std_dev.magnitude
+        )
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Normal({self.mean:.3f~P}, {self.std_dev:.3f~P})"

FlowCyPy/distribution/particle_size_distribution.py

@@ -0,0 +1,132 @@
+from FlowCyPy.distribution.base_class import Base, config_dict
+import numpy as np
+from typing import Tuple
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+
+@dataclass(config=config_dict)
+class RosinRammler(Base):
+    r"""
+    Represents a Particle Size Distribution using the Rosin-Rammler model.
+
+    The Rosin-Rammler distribution is described by its characteristic size and
+    spread parameter, and is used to model particle sizes in systems such as
+    powders or granular materials.
+
+    The distribution function is given by:
+
+    .. math::
+        F(x) = 1 - \exp \left( - \left( \frac{x}{d} \right)^k \right)
+
+    where:
+        - :math:`x` is the particle size.
+        - :math:`d` is the characteristic particle size.
+        - :math:`k` is the spread parameter.
+
+    Parameters
+    ----------
+    characteristic_size : Quantity
+        The characteristic particle size in meters.
+    spread : float
+        The spread parameter (shape factor).
+    """
+
+    characteristic_size: Quantity
+    spread: float
+
+    @property
+    def _units(self) -> Quantity:
+        return self.characteristic_size.units
+
+    @Base.pre_generate
+    def generate(self, n_samples: int) -> Quantity:
+        """
+        Generates a particle size distribution based on the Rosin-Rammler model.
+
+        Parameters
+        ----------
+        n_samples : Quantity
+            The number of particle sizes to generate (dimensionless).
+
+        Returns
+        -------
+        Quantity
+            An array of particle sizes in meters (or other units).
+        """
+        # Convert characteristic size to main units
+        d = self.characteristic_size.magnitude
+
+        # Generate uniform random samples in [0, 1)
+        u = np.random.uniform(size=n_samples)
+        u = np.clip(u, 1e-10, 1 - 1e-10)  # Avoid numerical issues
+
+        # Apply inverse CDF of Rosin-Rammler distribution
+        return d * (-np.log(1 - u))**(1 / self.spread)
+
+    def _generate_default_x(self, x_min: float, x_max: float, n_samples: int = 20) -> np.ndarray:
+        """
+        Generates a default range for x-values based on the characteristic size
+        and spread of the Rosin-Rammler distribution.
+
+        Parameters
+        ----------
+        x_min : float
+            Factor for the minimum x-value as a fraction of the characteristic size.
+        x_max : float
+            Factor for the maximum x-value as a multiple of the characteristic size.
+        n_samples : int, optional
+            Number of points in the generated range. Default is 500.
+
+        Returns
+        -------
+        np.ndarray
+            A default range of x-values with appropriate units.
+        """
+        if x_min <= 0:
+            raise ValueError("x_min must be greater than 0.")
+        if x_max <= x_min:
+            raise ValueError("x_max must be greater than x_min.")
+
+        d = self.characteristic_size.magnitude  # Characteristic size in base units
+        x_min = d * x_min  # Scale x_min by characteristic size
+        x_max = d * x_max  # Scale x_max by characteristic size
+        return np.linspace(x_min, x_max, n_samples) * self._units
+
+    def get_pdf(self, x_min: float = 0.01, x_max: float = 2, n_samples: int = 20) -> Tuple[np.ndarray, np.ndarray]:
+        r"""
+        Returns the x-values and the scaled PDF values for the particle size distribution.
+
+        The PDF for the Rosin-Rammler distribution is derived from the CDF:
+
+        .. math::
+            f(x) = \frac{k}{d} \left( \frac{x}{d} \right)^{k-1} \exp \left( - \left( \frac{x}{d} \right)^k \right)
+
+        Parameters
+        ----------
+        x_min : float, optional
+            Factor for the minimum x-value as a fraction of the characteristic size. Default is 0.01.
+        x_max : float, optional
+            Factor for the maximum x-value as a multiple of the characteristic size. Default is 5.
+        n_samples : int, optional
+            Number of points in the generated range. Default is 500.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding scaled PDF values.
+        """
+        # Generate x-values based on user-defined or default parameters
+        x = self._generate_default_x(x_min=x_min, x_max=x_max, n_samples=n_samples)
+
+        common_units = x.units
+        d = self.characteristic_size.to(common_units).magnitude
+        k = self.spread
+
+        # Rosin-Rammler PDF formula
+        pdf = (k / d) * (x.magnitude / d)**(k - 1) * np.exp(-(x.magnitude / d)**k)
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"RR({self.characteristic_size:.3f~P}, {self.spread:.3f})"

FlowCyPy/distribution/uniform.py

@@ -0,0 +1,117 @@
+from FlowCyPy.distribution.base_class import Base, config_dict
+import numpy as np
+from typing import Tuple
+from scipy.stats import uniform
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+@dataclass(config=config_dict)
+class Uniform(Base):
+    r"""
+    Represents a uniform distribution for particle sizes.
+
+    The uniform distribution assigns equal probability to all particle sizes within a specified range:
+
+    .. math::
+        f(x) = \frac{1}{b - a} \quad \text{for} \quad a \leq x \leq b
+
+    where:
+    - :math:`a` is the lower bound of the distribution.
+    - :math:`b` is the upper bound of the distribution.
+
+    Parameters
+    ----------
+    lower_bound : Quantity
+        The lower bound for particle sizes in meters.
+    upper_bound : Quantity
+        The upper bound for particle sizes in meters.
+    """
+
+    lower_bound: Quantity
+    upper_bound: Quantity
+
+    @property
+    def _units(self) -> Quantity:
+        return self.lower_bound.units
+
+    @property
+    def _lower_bound(self) -> Quantity:
+        return self.lower_bound.to(self._units)
+
+    @property
+    def _upper_bound(self) -> Quantity:
+        return self.upper_bound.to(self._units)
+
+    def __post_init__(self):
+        self.lower_bound = self.lower_bound.to(self.upper_bound.units)
+
+    def _generate_default_x(self, n_samples: int = 100) -> Quantity:
+        """
+        Generates a default range of x-values for the uniform distribution.
+
+        Parameters
+        ----------
+        n_points : int, optional
+            Number of points in the generated range. Default is 100.
+
+        Returns
+        -------
+        Quantity
+            A range of x-values with appropriate units.
+        """
+        x_min = self._lower_bound.magnitude / 1.1
+        x_max = self._upper_bound.magnitude * 1.1
+
+        return np.linspace(x_min, x_max, n_samples) * self._units
+
+    @Base.pre_generate
+    def generate(self, n_samples: int) -> Quantity:
+        """
+        Generates a uniform distribution of scatterer sizes.
+
+        The generated sizes are uniformly distributed between the specified `lower_bound` and `upper_bound`.
+
+        Parameters
+        ----------
+        n_samples : int
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        Quantity
+            An array of scatterer sizes in meters.
+        """
+        return np.random.uniform(
+            self._lower_bound.magnitude,
+            self._upper_bound.magnitude,
+            n_samples
+        )
+
+    def get_pdf(self, n_samples: int = 100) -> Tuple[Quantity, np.ndarray]:
+        """
+        Returns the x-values and the PDF values for the uniform distribution.
+
+        If `x` is not provided, a default range of x-values is generated.
+
+        Parameters
+        ----------
+        n_samples : int, optional
+            Number of points in the generated range if `x` is not provided. Default is 100.
+
+        Returns
+        -------
+        Tuple[Quantity, np.ndarray]
+            The input x-values and the corresponding PDF values.
+        """
+        x = self._generate_default_x(n_samples=n_samples)
+
+        pdf = uniform.pdf(
+            x.magnitude,
+            loc=self._lower_bound.magnitude,
+            scale=self._upper_bound.magnitude - self._lower_bound.magnitude
+        )
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Uniform(lower_bound={self.lower_bound:.3f~P}, upper_bound={self.upper_bound:.3f~P})"

FlowCyPy/distribution/weibull.py

@@ -0,0 +1,115 @@
+from FlowCyPy.distribution.base_class import Base, config_dict
+import numpy as np
+from typing import Tuple
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+
+@dataclass(config=config_dict)
+class Weibull(Base):
+    r"""
+    Represents a Weibull distribution for particle sizes.
+
+    The Weibull distribution is commonly used for modeling size distributions in biological systems.
+
+    Parameters
+    ----------
+    shape : Quantity
+        The shape parameter (k), controls the skewness of the distribution.
+    scale : Quantity
+        The scale parameter (λ), controls the spread of the distribution.
+    """
+
+    shape: Quantity
+    scale: Quantity
+
+    @property
+    def _units(self) -> Quantity:
+        return self.shape.units
+
+    @property
+    def _shape(self) -> Quantity:
+        return self.shape.to(self._units)
+
+    @property
+    def _scale(self) -> Quantity:
+        return self.scale.to(self._units)
+
+    def _generate_default_x(self, n_samples: int, x_min_factor: float, x_max_factor: float) -> Quantity:
+        """
+        Generates a default range of x-values for the Weibull distribution.
+
+        Parameters
+        ----------
+        n_samples : int, optional
+            Number of points in the generated range.
+        x_min_factor : float, optional
+            Factor for the minimum x-value relative to the scale parameter.
+        x_max_factor : float, optional
+            Factor for the maximum x-value relative to the scale parameter.
+
+        Returns
+        -------
+        Quantity
+            A range of x-values with appropriate units.
+        """
+
+        if x_min_factor <= 0:
+            raise ValueError("x_min_factor must be greater than 0.")
+
+        x_min = self.scale.magnitude * x_min_factor
+        x_max = self.scale.magnitude * x_max_factor
+        return np.linspace(x_min, x_max, n_samples) * self.scale.units
+
+    @Base.pre_generate
+    def generate(self, n_samples: int) -> Quantity:
+        """
+        Generates a Weibull distribution of scatterer sizes.
+
+        Parameters
+        ----------
+        n_samples : int
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        Quantity
+            An array of particle sizes in meters.
+        """
+        return np.random.weibull(
+            self.shape.magnitude,
+            size=n_samples
+        )
+
+    def get_pdf(self, n_samples: int = 100) -> Tuple[Quantity, np.ndarray]:
+        """
+        Returns the x-values and the PDF values for the Weibull distribution.
+
+        If `x` is not provided, a default range of x-values is generated.
+
+        Parameters
+        ----------
+        x : Quantity, optional
+            The input x-values (particle sizes) over which to compute the PDF. If not provided, a range is generated.
+        n_points : int, optional
+            Number of points in the generated range if `x` is not provided. Default is 100.
+
+        Returns
+        -------
+        Tuple[Quantity, np.ndarray]
+            The input x-values and the corresponding PDF values.
+        """
+        x = self._generate_default_x(n_samples=n_samples)
+
+        common_units = self.scale.units
+        scale_magnitude = self.scale.to(common_units).magnitude
+        shape_magnitude = self.shape.to(common_units).magnitude
+
+        pdf = (shape_magnitude / scale_magnitude) * \
+              ((x.to(common_units).magnitude / scale_magnitude) ** (shape_magnitude - 1)) * \
+              np.exp(-(x.to(common_units).magnitude / scale_magnitude) ** shape_magnitude)
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Weibull(shape={self.shape:.3f~P}, scale={self.scale:.3f~P})"