feat: transformations base primitives

Author: LeonidElkin

src/pysatl_core/__init__.py

@@ -14,6 +14,8 @@
 from .distributions import __all__ as _distr_all
 from .families import *
 from .families import __all__ as _family_all
+from .transformations import *
+from .transformations import __all__ as _transformations_all
 from .types import *
 from .types import __all__ as _types_all
 
@@ -23,8 +25,10 @@
     *_distr_all,
     *_family_all,
     *_types_all,
+    *_transformations_all,
 ]
 
 del _distr_all
 del _family_all
 del _types_all
+del _transformations_all

src/pysatl_core/distributions/distribution.py

@@ -74,6 +74,24 @@ def computation_strategy(self) -> ComputationStrategy: ...
     @property
     def support(self) -> Support | None: ...
 
+    def _new_computation_strategy(
+        self, computation_strategy: ComputationStrategy | None | object = _KEEP
+    ) -> ComputationStrategy | None:
+        return (
+            self.computation_strategy
+            if computation_strategy is _KEEP
+            else cast(ComputationStrategy | None, computation_strategy)
+        )
+
+    def _new_sampling_strategy(
+        self, sampling_strategy: SamplingStrategy | None | object = _KEEP
+    ) -> SamplingStrategy | None:
+        return (
+            self.sampling_strategy
+            if sampling_strategy is _KEEP
+            else cast(SamplingStrategy | None, sampling_strategy)
+        )
+
     def _clone_with_strategies(
         self,
         *,

src/pysatl_core/families/distribution.py

@@ -197,25 +197,13 @@ def _clone_with_strategies(
         computation_strategy: ComputationStrategy | None | object = _KEEP,
     ) -> ParametricFamilyDistribution:
         """Return a copy of this distribution with updated strategies."""
-        new_sampling: SamplingStrategy | None = (
-            self._sampling_strategy
-            if sampling_strategy is _KEEP
-            else cast(SamplingStrategy | None, sampling_strategy)
-        )
-
-        new_computation: ComputationStrategy | None = (
-            self._computation_strategy
-            if computation_strategy is _KEEP
-            else cast(ComputationStrategy | None, computation_strategy)
-        )
-
         return ParametricFamilyDistribution(
             family_name=self._family_name,
             distribution_type=self._distribution_type,
             parametrization=self._parametrization,
             support=self._support,
-            sampling_strategy=new_sampling,
-            computation_strategy=new_computation,
+            sampling_strategy=self._new_sampling_strategy(sampling_strategy),
+            computation_strategy=self._new_computation_strategy(computation_strategy),
         )
 
     @property

src/pysatl_core/transformations/__init__.py

@@ -0,0 +1,35 @@
+"""
+Transformations framework for derived probability distributions.
+
+This package provides the base primitives for constructing distributions
+obtained from other distributions, together with approximation interfaces
+and concrete transformation implementations.
+"""
+
+__author__ = "Leonid Elkin, Mikhail Mikhailov, Fedor Myznikov"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from .approximations import *
+from .approximations import __all__ as _approximations_all
+from .distribution import *
+from .distribution import __all__ as _distribution_all
+from .operations import *
+from .operations import __all__ as _operations_all
+from .transformation_method import *
+from .transformation_method import __all__ as _methods_all
+
+__all__ = [
+    *_approximations_all,
+    *_distribution_all,
+    *_operations_all,
+    *_methods_all,
+]
+
+del _approximations_all
+
+del _distribution_all
+
+del _operations_all
+
+del _methods_all

src/pysatl_core/transformations/approximations/__init__.py

@@ -0,0 +1,25 @@
+"""
+Approximation utilities for transformed distributions.
+
+This subpackage contains approximation interfaces and concrete
+approximators that can materialize analytical characteristics for
+complex transformation trees.
+"""
+
+__author__ = "Leonid Elkin"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from .approximation import *
+from .approximation import __all__ as _approximation_all
+from .chebyshev import *
+from .chebyshev import __all__ as _chebyshev_all
+
+__all__ = [
+    *_approximation_all,
+    *_chebyshev_all,
+]
+
+del _approximation_all
+
+del _chebyshev_all

src/pysatl_core/transformations/approximations/approximation.py

@@ -0,0 +1,59 @@
+"""
+Approximation interfaces for derived distributions.
+
+This module intentionally keeps the approximation layer minimal.
+At this stage the public abstraction is a single protocol describing
+objects that can materialize an :class:`ApproximatedDistribution`
+from a :class:`DerivedDistribution`.
+"""
+
+from __future__ import annotations
+
+__author__ = "Leonid Elkin"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from pysatl_core.transformations.distribution import (
+        ApproximatedDistribution,
+        DerivedDistribution,
+    )
+
+
+class DistributionApproximator(Protocol):
+    """
+    Protocol for objects approximating a derived distribution.
+
+    Implementations may use interpolation, tabulation, polynomial
+    approximation, or any other technique, as long as they return a new
+    derived distribution with materialized analytical computations.
+    """
+
+    def approximate(
+        self,
+        distribution: DerivedDistribution,
+        **options: Any,
+    ) -> ApproximatedDistribution:
+        """
+        Build an approximated distribution.
+
+        Parameters
+        ----------
+        distribution : DerivedDistribution
+            Distribution to approximate.
+        **options : Any
+            Extra approximation options.
+
+        Returns
+        -------
+        ApproximatedDistribution
+            Materialized approximation of the input distribution.
+        """
+        ...
+
+
+__all__ = [
+    "DistributionApproximator",
+]