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 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 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 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 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__,
        )

class DiscreteP(DiscreteDistributionBase):
    """Base class for discrete distributions with a probability parameter.

    Args:
        x (UniversalArray): Input data, which currently must be one dimensional.
        p (float): Probability 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.
    """

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

class DiscretePure(DiscreteDistributionBase):
    """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.
    """

class OptFunction(ABC, metaclass=CoreElements):
    """Base class for functions for optimization.

    Args:
        x: Input data, which can be one, two, three, or higher dimensional.
        kwargs: Keyword arguments for the function.

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

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

        self._x: tuple[UniversalArray, ...] = x
        self.dimension: int = len(x)

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

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

    @property
    @abstractmethod
    def __minima__(self) -> MinimaAPI:
        """Return the zero function."""

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

class OscillatorsFunc2D(OscillatorsFuncBase):
    """Base class for two-dimensional chaotic oscillators."""

    @property
    def to_position(self) -> UniversalArrayTuple:
        """Return the position of the oscillator."""
        y = self.solve()
        return y[:, 0], y[:, 2]

    @property
    def to_velocity(self) -> UniversalArrayTuple:
        """Return the velocity of the oscillator."""
        y = self.solve()
        return y[:, 1], y[:, 3]

class OscillatorsFunc3D(OscillatorsFuncBase):
    """Base class for three-dimensional chaotic oscillators."""

    @property
    def to_position(self) -> UniversalArrayTuple:
        """Return the position of the oscillator."""
        y = self.solve()
        return y[:, 0], y[:, 1], y[:, 2]

    @property
    def to_velocity(self) -> UniversalArrayTuple:
        """Return the velocity of the oscillator."""
        y = self.solve()
        return y[:, 3], y[:, 4], y[:, 5]

class OscillatorsFuncBase(ABC, metaclass=CoreElements):
    """Base class for chaotic oscillators.

    Args:
        *time_points (UniversalArray): The array of time points at which the
            oscillator's state is evaluated.
        time_format (str): The format of the time data. Defaults to "seconds".
        velocity (bool): Whether to return the velocity of the oscillator.
            Defaults to False.

    Raises:
        MissingXError: If no input data is specified.
        OutOfDimensionError: If the input data has more than one dimension.
        TimeFormatError: If the time format is not valid.
    """

    def __init__(
        self,
        *t: UniversalArray,
        time_format: str = "seconds",
        velocity: bool = False,
    ) -> None:
        """Initialize the function."""
        if t[0] is None:
            raise MissingXError

        if len(t) != __1d__:
            raise OutOfDimensionError(
                function_name=self.__class__.__name__,
                dimension=__1d__,
            )

        self.time_format = time_format
        self.t = self.convert2sec(t[0])
        self.velocity = velocity

    def convert2sec(self, t: UniversalArray) -> UniversalArray:
        """Convert the time data to seconds.

        Args:
            t (UniversalArray): The initial time data as input.

        Returns:
            UniversalArray: The time data converted to seconds.
        """
        conversion_factors = {"seconds": 1, "minutes": 60, "hours": 3600, "days": 86400}

        if self.time_format in conversion_factors:
            return t * conversion_factors[self.time_format]
        raise TimeFormatError(
            time_format=self.time_format,
            valid_formats=list(conversion_factors.keys()),
        )

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

    def setup_initial_state(self) -> UniversalArray:
        """Setup the initial state of the oscillator."""
        raise NotImplementedError

    @property
    @abstractmethod
    def __initial_configuration__(self) -> dict[str, UniversalArray]:
        """Initialize the state of the oscillator."""

    @property
    @abstractmethod
    def initial_state(self) -> list[float]:
        """Return the initial state of the oscillator."""

    @abstractmethod
    def equation_of_motion(self, initial_state: list[float], t: float) -> tuple:
        """Return the equation of motion of the oscillator."""

    def solve(self, **kwargs: dict[str, Any]) -> UniversalArrayTuple:
        """Solve the equation of motion of the oscillator."""
        return odeint(
            func=self.equation_of_motion,
            y0=self.initial_state,
            t=self.t,
            **kwargs,
        )

    @property
    @abstractmethod
    def to_position(self) -> UniversalArray:
        """Return the position of the oscillator."""

    @property
    @abstractmethod
    def to_velocity(self) -> UniversalArray:
        """Return the velocity of the oscillator."""

    @property
    def __eval__(self) -> UniversalArray:
        """Evaluate the function."""
        return self.to_velocity if self.velocity else self.to_position

    def __call__(self) -> ResultsChaoticOscillatorAPI:
        """Return the results of the function."""
        return ResultsChaoticOscillatorAPI(
            t=self.__input__,
            result=self.__eval__,
            initial_state=self.__initial_configuration__,
            doc=self.__doc__,
        )