from __future__ import annotations
from abc import ABC, abstractmethod
from dataclasses import dataclass
from enum import IntEnum
import numpy as np
import inspect
from numbers import Real
from typing import Dict, Type, Union, Optional, Tuple, Callable
from ._utils import formatTextDist
def _make_affine(base, s, t):
from ._affine import Affine
return Affine(base, s, t)
def _make_deterministic(value):
from ._deterministic import Deterministic
return Deterministic(value)
# ===============================================================
# ENUM & PARAMS
# ===============================================================
[docs]
class DistributionID(IntEnum):
"""
Enum for supported probability distribution types.
"""
NOTDEFINED = 0
NONE = 1
NORMAL = 2
UNIFORM = 3
TRIANGULAR = 4
BETA = 5
EXPONENTIAL = 6
LOGNORMAL = 7
GAMMA = 8
[docs]
class DistributionParameters:
def __init__(
self,
id: int | DistributionID,
loc: float,
scale: float,
min_raw: float,
max_raw: float,
relative: bool,
) -> None:
if id == int(DistributionID.NOTDEFINED):
raise ValueError("Distribution id 0 (NOTDEFINED) is reserved and cannot be used.")
self.__id = int(id)
self.__loc = float(loc)
self.__scale = float(scale)
self.__min_raw = float(min_raw)
self.__max_raw = float(max_raw)
self.__relative = bool(relative)
[docs]
@staticmethod
def relative(
id: int | DistributionID,
loc: float,
scale: float,
rel_min: float,
rel_max: float,
) -> "DistributionParameters":
"""
min/max are interpreted as OFFSETS relative to loc.
"""
return DistributionParameters(
id=id,
loc=loc,
scale=scale,
min_raw=rel_min,
max_raw=rel_max,
relative=True,
)
[docs]
@staticmethod
def absolute(
id: int | DistributionID,
loc: float,
scale: float,
abs_min: float,
abs_max: float,
) -> "DistributionParameters":
"""min/max are interpreted as absolute values."""
return DistributionParameters(
id=id,
loc=loc,
scale=scale,
min_raw=abs_min,
max_raw=abs_max,
relative=False,
)
@property
def id(self) -> int: return self.__id
@property
def loc(self) -> float: return self.__loc
@property
def mean(self) -> float: return self.__loc
@property
def scale(self) -> float: return self.__scale
@property
def std(self) -> float: return self.__scale
@property
def is_relative(self) -> bool: return self.__relative
@property
def abs_min(self) -> float:
return (self.__loc - self.__min_raw) if self.__relative else self.__min_raw
@property
def abs_max(self) -> float:
return (self.__loc + self.__max_raw) if self.__relative else self.__max_raw
@property
def rel_min(self) -> float:
return self.__min_raw if self.__relative else (self.__loc - self.__min_raw)
@property
def rel_max(self) -> float:
return self.__max_raw if self.__relative else (self.__max_raw - self.__loc)
@property
def a(self) -> float: return self.abs_min
@property
def b(self) -> float: return self.abs_max
[docs]
def toTxt(self, relative=True):
txt=''
txt += f'{self.id}, '
txt += f'{self.loc}, '
txt += f'{self.scale}, '
if relative:
txt += f'{self.rel_min}, '
txt += f'{self.rel_max}'
else:
txt += f'{self.abs_min}, '
txt += f'{self.abs_max}'
return txt
# ===============================================================
# REGISTRY & DECORATOR
# ===============================================================
_DISTRIBUTION_REGISTRY: Dict[int, Type["Distribution"]] = {}
[docs]
def registerDistribution(id_: DistributionID):
"""Decorator to register concrete distributions."""
dist_id = int(id_)
def deco(cls):
if inspect.isabstract(cls):
raise TypeError(f"{cls.__name__} is abstract and cannot be registered.")
if dist_id == int(DistributionID.NOTDEFINED):
raise ValueError("ID 0 (NOTDEFINED) cannot be registered.")
if dist_id in _DISTRIBUTION_REGISTRY:
prev = _DISTRIBUTION_REGISTRY[dist_id].__name__
raise ValueError(f"Distribution ID {dist_id} already registered by {prev}.")
_DISTRIBUTION_REGISTRY[dist_id] = cls
cls.DistID = dist_id
return cls
return deco
# ===============================================================
# BASE CLASS
# ===============================================================
[docs]
class Distribution(ABC):
"""
Abstract base class for random variables.
Defines the API for all random variable classes in pyrockfall.
"""
DistID: DistributionID = DistributionID.NOTDEFINED # set by @registerDistribution
# ---- required interface ----
[docs]
@abstractmethod
def rvs(self, size: int = 1, random_state: Optional[Union[int, np.random.Generator]] = None) -> np.ndarray:
"""Random variates"""
raise NotImplementedError
[docs]
@abstractmethod
def pdf(self, x) -> np.ndarray:
"""Probability density function"""
raise NotImplementedError
[docs]
@abstractmethod
def cdf(self, x) -> np.ndarray:
"""Cumulative distribution function"""
raise NotImplementedError
[docs]
def sf(self, x) -> np.ndarray:
"""Survival function (1 - CDF)"""
return 1.0 - self.cdf(x)
[docs]
@abstractmethod
def ppf(self, q) -> np.ndarray:
"""Percent point function (inverse of cdf)"""
raise NotImplementedError
[docs]
def isf(self, q) -> np.ndarray:
"""Inverse survival function (inverse of sf)"""
return self.ppf(1.0 - q)
[docs]
@abstractmethod
def expect(self, func:Callable, lb: float = -np.inf, ub: float = np.inf) -> float:
"""Expected value of a function of the random variable over [lb, ub]"""
raise NotImplementedError
[docs]
@abstractmethod
def mean(self) -> float:
"""Mean of the distribution"""
raise NotImplementedError
[docs]
@abstractmethod
def var(self) -> float:
"""Variance of the distribution"""
raise NotImplementedError
[docs]
def std(self) -> float:
"""Standard deviation of the distribution"""
return np.sqrt(self.var())
[docs]
@abstractmethod
def interval(self, confidence: float = 1.0) -> Tuple[float, float]:
"""Confidence interval having equal areas around the median"""
raise NotImplementedError
# ---- Arithmetic operators (returns Affine wrappers) ----------
def __add__(self, other):
if isinstance(other, Real):
return _make_affine(self, 1.0, float(other))
return NotImplemented
def __radd__(self, other):
if isinstance(other, Real):
return _make_affine(self, 1.0, float(other))
return NotImplemented
def __sub__(self, other):
if isinstance(other, Real):
return _make_affine(self, 1.0, -float(other))
return NotImplemented
def __rsub__(self, other):
if isinstance(other, Real):
# other - X == (-1)*X + other
return _make_affine(self, -1.0, float(other))
return NotImplemented
def __mul__(self, other):
if isinstance(other, Real):
s = float(other)
if s == 0.0:
return _make_deterministic(0.0)
return _make_affine(self, s, 0.0)
return NotImplemented
def __rmul__(self, other):
return self.__mul__(other)
def __truediv__(self, other):
if isinstance(other, Real):
s = float(other)
if s == 0.0:
raise ValueError("Division by zero.")
return _make_affine(self, 1.0 / s, 0.0)
return NotImplemented
def __neg__(self):
return _make_affine(self, -1.0, 0.0)
def __pos__(self):
return self
# ---- Representation ----
def __repr__(self) -> str:
params = self.native_params()
# Stable key order for readability
body = ", ".join(f"{k}={formatTextDist(v)}" for k, v in params.items())
return f"{self.__class__.__name__}({body})"
# make __str__ the same
__str__ = __repr__
# ---- Parameter access ----
[docs]
@abstractmethod
def native_params(self) -> dict[str, float]:
"""Constructor-ready, family-specific parameters (e.g., {'mu':..., 'sigma':...})."""
raise NotImplementedError
[docs]
@abstractmethod
def generic_params(self) -> DistributionParameters:
"""Family-agnostic summary: loc, scale, rel_min, rel_max"""
raise NotImplementedError