Modules

class MaximaAPI(BaseModel):
    """Maxima API for optimization functions."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    f_x: float | UniversalArray = Field(
        ...,
        description="Value of the function at the maximum or maxima.",
    )
    x: UniversalArrayTuple | UniversalFloatTuple = Field(
        ...,
        description="Input data, where the maximum or maxima is located.",
    )

class MinimaAPI(BaseModel):
    """Minima API for optimization functions."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    f_x: float | UniversalArray = Field(
        ...,
        description="Value of the function at the minimum or minima.",
    )
    x: UniversalArrayTuple | UniversalFloatTuple = Field(
        ...,
        description="Input data, where the minimum or minima is located.",
    )

class ResultsChaoticOscillatorAPI(BaseModel):
    """Results API for chaotic oscillator functions."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    t: UniversalArrayTuple = Field(
        ...,
        description="Time array for the chaotic oscillator.",
    )
    initial_state: dict[str, UniversalArray] = Field(
        default=...,
        description="Initial conditions for the chaotic pendulum.",
    )
    result: UniversalArray = Field(
        default=...,
        description="Result of the chaotic oscillator.",
    )
    doc: str | None = Field(
        default=...,
        description="Function documentation string.",
    )

class ResultsDistributionAPI(BaseModel):
    """Results API for distribution functions."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    x: UniversalArrayTuple = Field(
        ...,
        description="Input data, which can be one, two, three, or higher dimensional.",
    )
    result: UniversalArray | MeshArray = Field(
        ...,
        description="Function value as numpy array or numpy mesh grid array.",
    )
    summary: SummaryStatisticsAPI = Field(
        ...,
        description="Summary statistics of the data.",
    )
    doc: str | None = Field(..., description="Function documentation string.")

class ResultsFractalAPI(BaseModel):
    """Results API for fractal functions.

    This class provides a standardized structure for returning fractal data,
    including the input parameters, resulting fractal representation, and metadata.

    Attributes:
        x (UniversalArrayTuple): Input data for the fractal generation.
        result (UniversalArray | MeshArray | list | dict): Fractal data, which may
            be iteration counts, coordinates, or other representations.
        parameters (dict | None): Parameters used to generate the fractal.
        dimension (float | None): Fractal dimension, if calculated.
        doc (str | None): Function documentation string.
    """

    model_config = ConfigDict(arbitrary_types_allowed=True)
    x: UniversalArrayTuple = Field(
        ...,
        description="Input data for the fractal generation.",
    )
    result: UniversalArray | MeshArray | list | dict = Field(
        ...,
        description="Fractal data, which may be iteration counts, coordinates,"
        " or other representations.",
    )
    parameters: dict | None = Field(
        default=None,
        description="Parameters used to generate the fractal.",
    )
    dimension: float | None = Field(
        default=None,
        description="Fractal dimension, if calculated.",
    )
    doc: str | None = Field(..., description="Function documentation string.")

    @model_validator(mode="after")
    def validate_dimension(self) -> ResultsFractalAPI:
        """Validate the fractal dimension.

        Checks that the provided fractal dimension is within a reasonable range
        (between 0 and 3 for most fractals).

        Returns:
            ResultsFractalAPI: The validated model instance
        """
        if self.dimension is not None and not (0 <= self.dimension <= __3d__):
            warnings.warn(
                message=f"Unusual fractal dimension: {self.dimension}. "
                f"Most fractals have dimensions between 0 and 3.",
                category=UserWarning,
                stacklevel=1,
            )
        return self

class ResultsFunctionAPI(BaseModel):
    """Results API for optimization functions."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    x: UniversalArrayTuple = Field(
        ...,
        description="Input data, which can be one, two, three, or higher dimensional.",
    )
    result: UniversalArray | MeshArray = Field(
        ...,
        description="Function value as numpy array or numpy mesh grid array.",
    )
    minima: MinimaAPI | None = Field(
        default=None,
        description="Tuple of minima as numpy arrays.",
    )
    maxima: MaximaAPI | None = Field(
        default=None,
        description="Tuple of maxima as numpy arrays.",
    )
    doc: str | None = Field(..., description="Function documentation string.")

class ResultsHyperbolicAPI(BaseModel):
    """Results API for hyperbolic functions."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    x: UniversalArrayTuple = Field(
        ...,
        description="Input data, which can be one, two, three, or higher dimensional.",
    )
    result: UniversalArray | MeshArray = Field(
        ...,
        description="Function value as numpy array or numpy mesh grid array.",
    )
    doc: str | None = Field(..., description="Function documentation string.")

class ResultsPathologicalAPI(BaseModel):
    """Results API for pathological functions."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    x: UniversalArrayTuple = Field(
        ...,
        description="Input data, which can be one, two, three, or higher dimensional.",
    )
    result: UniversalArray | MeshArray = Field(
        ...,
        description="Function value as numpy array or numpy mesh grid array.",
    )

    doc: str | None = Field(..., description="Function documentation string.")

class SummaryStatisticsAPI(BaseModel):
    """API for summary statistics."""

    model_config = ConfigDict(arbitrary_types_allowed=True)
    mean: float | None = Field(
        default=...,
        description="Mean value of the data.",
    )
    variance: float | None = Field(
        default=...,
        description="Variance of the data.",
    )
    mode: float | UniversalFloatTuple | None = Field(
        default=...,
        description="Mode or modes of the data.",
    )
    doc: str | None = Field(
        default=...,
        description="Documentation string for the summary statistics.",
    )

class ComplexFractalFunction(FractalFunction):
    """Base class for complex fractal functions.

    This class extends the FractalFunction to handle complex numbers in the input data.
    It provides common functionality for fractals like the Mandelbrot set and Julia set.

    Args:
        *x (UniversalArray): Input data, which can vary depending on the specific
            fractal.
        max_iter (int, optional): Maximum number of iterations. Defaults to 100.
        escape_radius (float, optional): Escape radius. Defaults to 2.0.

    Raises:
        MissingXError: If no input data is specified.
    """

    def __init__(
        self, *x: UniversalArray, max_iter: int = 100, escape_radius: float = 2.0
    ) -> None:
        """Initialize the complex fractal function."""
        super().__init__(*x, max_iter=max_iter)

        self.escape_radius = escape_radius

    def iterate_complex_function(
        self, z_start: np.ndarray, c: np.ndarray | complex, shape: tuple
    ) -> np.ndarray:
        """Common iteration method for complex fractals.

        Implements the $z = z^2 + c$ iteration common to both Mandelbrot and Julia sets.

        Args:
            z_start (np.ndarray): Starting z values
            c (np.ndarray | complex): Parameter c values
            shape (tuple): Original shape of the array

        Returns:
            np.ndarray: Iteration counts
        """
        z = z_start.flatten()
        if isinstance(c, np.ndarray):
            c = c.flatten()

        iterations = np.zeros(z.shape, dtype=int)
        escape_radius_squared = self.escape_radius**2

        # Points still iterating
        mask = np.full(shape=z.shape, fill_value=True, dtype=bool)

        for i in range(self.max_iter):
            # Update z for points still iterating
            z[mask] = (
                z[mask] ** 2 + c[mask]
                if isinstance(c, np.ndarray)
                else z[mask] ** 2 + c
            )
            # Find points that escape
            escaped = np.abs(z) ** 2 > escape_radius_squared

            # Update iterations for newly escaped points
            iterations[mask & escaped] = i + 1

            # Update mask to exclude escaped points
            mask[escaped] = False

            # If all points have escaped, break
            if not np.any(mask):
                break

        return iterations.reshape(shape)

class ContinousAsymmetricPseudo(ContinousPseudo):
    r"""Base class for continuous distributions for asym. pseudo Voigt like functions.

    Note:
        In terms of pseudo Voigt like functions, the $\gamma$ parameter is used to
        provide an asymetric line shape. The $\gamma$ parameter is defined as the ratio
        of the Lorentzian contribution to the Gaussian contribution. In case of
        **XPS** and **XAS**, these type of functions are popular to model the line shape
        of the photoemission and absorption spectra.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        sigma (float): Standard deviation of the distribution. Defaults to 1.
        eta (float): Shape parameter of the distribution. Defaults to 0.5.
        gamma (float): Asymmetry parameter of the distribution. Defaults to 0.0.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
        OutOfRangeError: If the input data is not in the interval $[0, 1]$.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        sigma: float = 1,
        eta: float = 0.5,
        gamma: float = 0.0,
    ) -> None:
        """Initialize the function."""
        super().__init__(*x, mu=mu, sigma=sigma, eta=eta, cumulative=False)
        self.gamma = gamma

class ContinousPseudo(ContinuousWSigma):
    """Base class for continuous distributions for pseudo Voigt like functions.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        sigma (float): Standard deviation of the distribution. Defaults to 1.
        eta (float): Shape parameter of the distribution. Defaults to 0.5.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
        OutOfRangeError: If the input data is not in the interval $[0, 1]$.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        sigma: float = 1,
        eta: float = 0.5,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        super().__init__(*x, mu=mu, sigma=sigma, cumulative=cumulative)
        if eta < 0 or eta > 1:
            raise OutOfRangeError(
                function_name=self.__class__.__name__,
                start_range=0,
                end_range=1,
            )
        self.eta = eta

class Continuous2PiInterval(ContinuousDistributionBase):
    r"""Base class for continuous distributions with fixed interval of $2\pi$.

    Args:
        *x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        OutOfRangeError: If the input data is not in the interval $[-\pi, \pi]$.
        MissingXError: If no input data is specified.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        kappa: float = 1,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        if np.min(x) < -np.pi or np.max(x) > np.pi:
            raise OutOfRangeError(
                function_name=self.__class__.__name__,
                start_range=-np.pi,
                end_range=np.pi,
            )
        super().__init__(*x, mu=mu, cumulative=cumulative)
        self.kappa = kappa

class ContinuousBoundedInterval(ContinuousDistributionBase):
    """Base class for continuous distributions with a bounded interval.

    Args:
        *x (UniversalArray): Input data, which currently must be one dimensional.
        start (float): Start of the interval. Defaults to 0.
        end (float): End of the interval. Defaults to 1.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        OutOfRangeError: If the input data is not in the interval $[start, end]$.
        MissingXError: If no input data is specified.
    """

    def __init__(
        self,
        *x: UniversalArray,
        start: float = 0,
        end: float = 1,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        if np.min(x) < start or np.max(x) > end:
            raise OutOfRangeError(
                function_name=self.__class__.__name__,
                start_range=start,
                end_range=end,
            )
        super().__init__(*x, cumulative=cumulative)

class ContinuousDistributionBase(ABC, metaclass=CoreElements):
    """Base class for distributions with a standard deviation and beta parameter.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float ): Mean of the distribution. Defaults to 0.
        beta (float): Shape parameter of the distribution. Defaults to 1.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        if x[0] is None:
            raise MissingXError

        if len(x) != __1d__:
            raise OutOfDimensionError(
                function_name=self.__class__.__name__,
                dimension=__1d__,
            )
        self._x = x[0]
        self.mu = mu
        self.cumulative = cumulative

    @property
    def __input__(self) -> UniversalArrayTuple:
        """Return the input data."""
        return (np.array(self._x),)

    @property
    def __eval__(self) -> UniversalArray:
        """Evaluate the function."""
        return (
            self.cumulative_distribution_function()
            if self.cumulative
            else self.probability_density_function()
        )

    @abstractmethod
    def probability_density_function(self) -> UniversalArray:
        """Return the probability density function."""

    @property
    @abstractmethod
    def __summary__(self) -> SummaryStatisticsAPI:
        """Return the summary statistics."""

    def cumulative_distribution_function(self) -> UniversalArray:
        """Return the cumulative distribution function."""
        raise NoCumulativeError

    def __call__(self) -> ResultsDistributionAPI:
        """Return the results of the function."""
        return ResultsDistributionAPI(
            x=self.__input__,
            result=self.__eval__,
            summary=self.__summary__,
            doc=self.__doc__,
        )

class ContinuousMixed(ContinuousWSigma):
    r"""Base class for continuous distributions with mixed parameters.

    Args:
        x (UniversalArray): Input data, which can be one, two, three, or higher
            dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        sigma (float): Standard deviation of the distribution. Defaults to 1.
        zeta (float): Shape parameter of the distribution. Defaults to 0.0.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        sigma: float = 1,
        zeta: float = 0.0,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        super().__init__(*x, mu=mu, sigma=sigma, cumulative=cumulative)
        self.zeta = zeta

class ContinuousPure(ContinuousDistributionBase):
    """Base class for continuous distributions with a standard deviation.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
    """

class ContinuousWBeta(ContinuousDistributionBase):
    """Base class for continuous distributions with beta parameter.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        beta (float): Shape parameter of the distribution. Defaults to 1.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        NotAPositiveNumberError: If the beta parameter is not a positive number.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        beta: float = 1,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        super().__init__(*x, mu=mu, cumulative=cumulative)
        if beta <= 0:
            raise NotAPositiveNumberError(var_number="beta", number=beta)
        self.beta = beta

class ContinuousWLambda(ContinuousDistributionBase):
    """Base class for continuous distributions with beta parameter.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        beta (float): Shape parameter of the distribution. Defaults to 1.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
    """

    def __init__(
        self,
        *x: UniversalArray,
        lambda_: float = 1,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        super().__init__(*x, cumulative=cumulative)
        if lambda_ <= 0:
            raise NotAPositiveNumberError(var_number="lambda_", number=lambda_)
        self.lambda_ = lambda_

class ContinuousWSigma(ContinuousDistributionBase):
    """Base class for continuous distributions with a standard deviation.

    Args:
        x (UniversalArray): Input data, which can be one, two, three, or higher
            dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        sigma (float): Standard deviation of the distribution. Defaults to 1.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
    """

    def __init__(
        self,
        *x: UniversalArray,
        mu: float = 0,
        sigma: float = 1,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        super().__init__(*x, mu=mu, cumulative=cumulative)
        self.sigma = sigma

class CoreElements(ABCMeta):
    """Metaclass for functions."""

    @property
    @abstractmethod
    def __eval__(cls) -> UniversalArray:
        """Evaluate the function."""

    @property
    @abstractmethod
    def __input__(cls) -> UniversalArrayTuple:
        """Return the input data."""

class CurveFractalFunction(FractalFunction):
    """Base class for curve-based fractals.

    This class extends FractalFunction to handle fractals based on iterative curve
    generation, like the Cantor set, Dragon curve, and space-filling curves.

    Args:
        *x (UniversalArray): Input points defining the curve space
        max_iter (int, optional): Maximum number of iterations. Defaults to 100.
        scale_factor (float, optional): Scale factor between iterations.
            Defaults to 0.5.
        fractal_dimension (float, optional): Fractal dimension of the curve.
            Defaults to 2.0.
    """

    def __init__(
        self,
        *x: UniversalArray,
        max_iter: int = 100,
        scale_factor: float = 0.5,
        fractal_dimension: float = 2.0,
    ) -> None:
        """Initialize the curve fractal function."""
        super().__init__(*x, max_iter=max_iter)
        self.scale_factor = scale_factor
        self.fractal_dimension = fractal_dimension

    def generate_points(self) -> np.ndarray:
        """Generate points for the curve at the current iteration.

        Returns:
            np.ndarray: Array of points defining the curve
        """
        raise NotImplementedError

class DiscreteDistributionBase(ABC, metaclass=CoreElements):
    """Base class for discrete distributions.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        mu (float): Mean of the distribution. Defaults to 0.
        cumulative (bool): Whether to return the cumulative distribution function.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
    """

    def __init__(
        self,
        *x: UniversalArray,
        cumulative: bool = False,
    ) -> None:
        """Initialize the function."""
        if x is None:
            raise MissingXError

        if len(x) != __1d__:
            raise OutOfDimensionError(
                function_name=self.__class__.__name__,
                dimension=__1d__,
            )
        self._x = x[0]
        self.cumulative = cumulative

    @property
    def __input__(self) -> UniversalArrayTuple:
        """Return the input data."""
        return (np.array(self._x),)

    @property
    def __eval__(self) -> UniversalArray:
        """Evaluate the function."""
        return (
            self.cumulative_distribution_function()
            if self.cumulative
            else self.probability_mass_function()
        )

    @abstractmethod
    def probability_mass_function(self) -> UniversalArray:
        """Return the probability mass function."""

    @property
    @abstractmethod
    def __summary__(self) -> SummaryStatisticsAPI:
        """Return the summary statistics."""

    def cumulative_distribution_function(self) -> UniversalArray:
        """Return the cumulative distribution function."""
        raise NoCumulativeError

    def __call__(self) -> ResultsDistributionAPI:
        """Return the results of the function."""
        return ResultsDistributionAPI(
            x=self.__input__,
            result=self.__eval__,
            summary=self.__summary__,
            doc=self.__doc__,
        )