feat: transformations base primitives

README.md

@@ -8,7 +8,7 @@
 [![CI][status-shield]][status-url]
 [![MIT License][license-shield]][license-url]
 
-**PySATL Core** is the computational core of the PySATL project, providing abstractions and infrastructure for probability distributions, parametric families, characteristic-based computations, and sampling.
+**PySATL Core** is the computational core of the PySATL project, providing abstractions and infrastructure for probability distributions, parametric families, characteristic-based computations, transformations, and sampling.
 
 The library is designed as a **foundational kernel** rather than a ready-to-use end-user package. Its primary goals are explicit probabilistic structure, extensibility, and suitability as a basis for further stochastic and statistical tooling.
 
@@ -26,6 +26,9 @@ The library is designed as a **foundational kernel** rather than a ready-to-use
 - A global **family registry** for configuring, querying, and extending available distribution families.
 - **Characteristic computation graph** (`CharacteristicRegistry`) that allows computing
   arbitrary characteristics by specifying only a minimal analytical subset.
+- **Transformations module** for derived distributions:
+  affine transformations (`aX + b`), binary operations (`X ± Y`, `X * Y`, `X / Y`),
+  finite weighted mixtures, and characteristic-level approximations.
 - Distribution objects exposing common probabilistic operations
   (sampling, analytical and fitted computations).
 - Clear separation between *distribution definitions*, *parametrizations*,
@@ -110,6 +113,16 @@ This example uses a **predefined family** and **predefined parametrizations**.
 PySATL Core also supports defining custom families, parametrizations,
 and characteristic graphs.
 
+For transformation workflows, see `examples/transformations_overview.ipynb`.
+
+---
+
+## 📓 Notebooks
+
+- `examples/overview.ipynb` — base walkthrough for families, parametrizations, and characteristic queries.
+- `examples/transformations_overview.ipynb` — affine, binary, finite-mixture, and approximation workflows.
+- `examples/example_sampling_methods.ipynb` — sampling backends and UNURAN-oriented scenarios.
+
 ---
 
 ## 📖 Documentation
@@ -143,7 +156,7 @@ poetry run pre-commit run --all-files
 
 ## 🗺 Roadmap
 
-- **Transformations module** for mixtures and distribution transformations.
+- Extension of the transformations module (functional transforms, performance improvements).
 - Extension of characteristic graphs.
 - Stabilization of APIs and **publishing PySATL Core as an installable package**.
 

src/pysatl_core/__init__.py

@@ -16,6 +16,8 @@
 from .families import __all__ as _family_all
 from .sampling import *
 from .sampling import __all__ as _sampling_all
+from .transformations import *
+from .transformations import __all__ as _transformations_all
 from .types import *
 from .types import __all__ as _types_all
 
@@ -26,9 +28,11 @@
     *_family_all,
     *_types_all,
     *_sampling_all,
+    *_transformations_all,
 ]
 
 del _distr_all
 del _family_all
 del _types_all
+del _transformations_all
 del _sampling_all

src/pysatl_core/distributions/distribution.py

@@ -57,7 +57,10 @@ class Distribution(ABC):
             | Mapping[LabelName, AnalyticalComputation[Any, Any]]
         ),
     ]
-        Direct analytical computations provided by the distribution.
+        Distribution-provided characteristic methods.
+        For non-transformed distributions every method in this mapping is
+        fully analytical, so this mapping matches the set of loops with
+        ``is_analytical=True`` in the graph view.
     sampling_strategy : SamplingStrategy
         Strategy for generating random samples.
     computation_strategy : ComputationStrategy
@@ -92,7 +95,9 @@ def __init__(
                     | Mapping[LabelName, AnalyticalComputation[Any, Any]]
                 ),
             ]
-            Analytical computations provided by the distribution.
+            Distribution-provided characteristic methods.
+            For non-transformed distributions these methods are fully
+            analytical.
         support : Support or None, default=None
             Support of the distribution.
         sampling_strategy : SamplingStrategy or None, default=None
@@ -141,9 +146,45 @@ def distribution_type(self) -> DistributionType:
     def analytical_computations(
         self,
     ) -> Mapping[GenericCharacteristicName, Mapping[LabelName, AnalyticalComputation[Any, Any]]]:
-        """Return analytical computations provided directly by this distribution."""
+        """
+        Return distribution-provided characteristic methods.
+
+        For non-transformed distributions this mapping coincides with
+        graph loops marked as ``is_analytical=True``.
+        """
         return self._analytical_computations
 
+    def loop_is_analytical(
+        self,
+        characteristic_name: GenericCharacteristicName,
+        label_name: LabelName,
+    ) -> bool:
+        """
+        Tell whether a self-loop method is fully analytical in the graph.
+
+        Parameters
+        ----------
+        characteristic_name : GenericCharacteristicName
+            Characteristic name of the self-loop.
+        label_name : LabelName
+            Label of the analytical computation variant.
+
+        Returns
+        -------
+        bool
+            ``True`` when every required predecessor in the transformation
+            chain is analytical.
+
+        Notes
+        -----
+        Presence in ``analytical_computations`` means that a characteristic
+        has at least one analytical ancestor in its derivation chain.
+        For non-transformed distributions these notions coincide, therefore
+        this method always returns ``True``.
+        """
+        _ = characteristic_name, label_name
+        return True
+
     @property
     def sampling_strategy(self) -> SamplingStrategy:
         """Return the currently attached sampling strategy."""