example: example updated to use it in docs

LeonidElkin · LeonidElkin · commit f45d60b41e66 · 2026-01-03T21:24:53.000+03:00
diff --git a/examples/example-parametric.ipynb b/examples/example-parametric.ipynb
diff --git a/examples/overview.ipynb b/examples/overview.ipynb
diff --git a/src/pysatl_core/distributions/distribution.py b/src/pysatl_core/distributions/distribution.py
@@ -11,14 +11,15 @@
 __copyright__ = "Copyright (c) 2025 PySATL project"
 __license__ = "SPDX-License-Identifier: MIT"
 
-from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, cast, runtime_checkable
+
+from pysatl_core.types import NumericArray
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
     from typing import Any
 
     from pysatl_core.distributions.computation import AnalyticalComputation
-    from pysatl_core.distributions.sampling import Sample
     from pysatl_core.distributions.strategies import (
         ComputationStrategy,
         Method,
@@ -113,7 +114,7 @@ def calculate_characteristic(
         """
         return self.query_method(characteristic_name, **options)(value)
 
-    def sample(self, n: int, **options: Any) -> Sample:
+    def sample(self, n: int, **options: Any) -> NumericArray:
         """
         Generate random samples from the distribution.
 
@@ -122,11 +123,14 @@ def sample(self, n: int, **options: Any) -> Sample:
         n : int
             Number of samples to generate.
         **options : Any
-            Additional sampling options.
+            Additional sampling options forwarded to the underlying
+            sampling strategy.
 
         Returns
         -------
-        Sample
-            Container with the generated samples.
+        NumericArray
+            NumPy array containing ``n`` generated samples.
+            The exact array shape depends on the distribution and
+            the sampling strategy.
         """
-        return self.sampling_strategy.sample(n, distr=self, **options)
+        return cast(NumericArray, self.sampling_strategy.sample(n, distr=self, **options))
diff --git a/src/pysatl_core/distributions/sampling.py b/src/pysatl_core/distributions/sampling.py
@@ -22,6 +22,7 @@
     import numpy.typing as npt
 
 
+# TODO: This is probably a stillborn idea, it's better to just use NumPy arrays.
 class Sample(Protocol):
     """
     Protocol for sample containers.
@@ -41,6 +42,7 @@ def array(self) -> npt.NDArray[np.floating[Any]]: ...
     def shape(self) -> tuple[int, ...]: ...
 
 
+# TODO: This is probably a stillborn idea, it's better to just use NumPy arrays.
 class ArraySample:
     """
     Array-backed sample container.
diff --git a/src/pysatl_core/distributions/strategies.py b/src/pysatl_core/distributions/strategies.py
@@ -11,19 +11,18 @@
 __copyright__ = "Copyright (c) 2025 PySATL project"
 __license__ = "SPDX-License-Identifier: MIT"
 
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Protocol, cast
 
 import numpy as np
 
 from pysatl_core.distributions.registry import characteristic_registry
-from pysatl_core.distributions.sampling import ArraySample
+from pysatl_core.types import CharacteristicName, NumericArray
 
 if TYPE_CHECKING:
     from typing import Any
 
     from pysatl_core.distributions.computation import AnalyticalComputation, FittedComputationMethod
     from pysatl_core.distributions.distribution import Distribution
-    from pysatl_core.distributions.sampling import Sample
     from pysatl_core.types import GenericCharacteristicName
 
 type Method[In, Out] = AnalyticalComputation[In, Out] | FittedComputationMethod[In, Out]
@@ -186,25 +185,27 @@ def query_method(
 class SamplingStrategy(Protocol):
     """Protocol for strategies that generate samples from distributions."""
 
-    def sample(self, n: int, distr: Distribution, **options: Any) -> Sample: ...
+    def sample(self, n: int, distr: Distribution, **options: Any) -> NumericArray: ...
 
 
 class DefaultSamplingUnivariateStrategy(SamplingStrategy):
     """
-    Default univariate sampler using inverse transform sampling.
+    Default univariate sampler based on inverse transform sampling.
 
     This strategy generates samples by applying the PPF (inverse CDF)
-    to uniform random variables.
+    to uniformly distributed random variables.
 
     Notes
     -----
     - Requires the distribution to provide a PPF computation method.
-    - Returns samples as a 2D array of shape (n, 1).
+    - Assumes that the PPF follows NumPy semantics (vectorized evaluation).
+    - Graph-derived PPFs (scalar-only) are currently not supported.
+    - Returns a NumPy array containing the generated samples.
     """
 
-    def sample(self, n: int, distr: Distribution, **options: Any) -> ArraySample:
+    def sample(self, n: int, distr: Distribution, **options: Any) -> NumericArray:
         """
-        Generate n samples from the distribution.
+        Generate samples from the distribution.
 
         Parameters
         ----------
@@ -213,15 +214,19 @@ def sample(self, n: int, distr: Distribution, **options: Any) -> ArraySample:
         distr : Distribution
             Distribution to sample from.
         **options : Any
-            Additional options passed to the PPF computation.
+            Additional options forwarded to the PPF computation.
 
         Returns
         -------
-        ArraySample
-            Samples as a 2D array of shape (n, 1).
+        NumericArray
+            NumPy array containing ``n`` generated samples.
+            The exact array shape depends on the distribution and sampling strategy.
         """
-        ppf = distr.query_method("ppf", **options)
+        ppf = distr.query_method(CharacteristicName.PPF, **options)
         rng = np.random.default_rng()
         U = rng.random(n)
-        vals = np.array([ppf(Ui) for Ui in U], dtype=np.float64).reshape(n, 1)
-        return ArraySample(vals)
+        # TODO: Now it will be based on the fact that the characteristic
+        #  has NumPy semantics (It is much more faster), that is,
+        #  it will not work with the graph computed characteristics currently.
+        samples = ppf(U)
+        return cast(NumericArray, samples)
diff --git a/src/pysatl_core/families/__init__.py b/src/pysatl_core/families/__init__.py
@@ -10,6 +10,8 @@
 __license__ = "SPDX-License-Identifier: MIT"
 
 
+from .builtins import *  # noqa: UP029
+from .builtins import __all__ as _builtins_all
 from .configuration import configure_families_register
 from .distribution import ParametricFamilyDistribution
 from .parametric_family import ParametricFamily
@@ -30,4 +32,8 @@
     "constraint",
     "parametrization",
     "configure_families_register",
+    # builtins
+    *_builtins_all,
 ]
+
+del _builtins_all
diff --git a/src/pysatl_core/families/builtins/__init__.py b/src/pysatl_core/families/builtins/__init__.py
@@ -10,14 +10,11 @@
 __license__ = "SPDX-License-Identifier: MIT"
 
 
-from pysatl_core.families.builtins.continuous import (
-    configure_exponential_family,
-    configure_normal_family,
-    configure_uniform_family,
-)
+from .continuous import *
+from .continuous import __all__ as _continuous_all
 
 __all__ = [
-    "configure_normal_family",
-    "configure_uniform_family",
-    "configure_exponential_family",
+    *_continuous_all,
 ]
+
+del _continuous_all
diff --git a/src/pysatl_core/families/builtins/continuous/exponential.py b/src/pysatl_core/families/builtins/continuous/exponential.py
@@ -14,7 +14,6 @@
 
 import numpy as np
 
-from pysatl_core.distributions.strategies import DefaultSamplingUnivariateStrategy
 from pysatl_core.distributions.support import ContinuousSupport
 from pysatl_core.families.parametric_family import ParametricFamily
 from pysatl_core.families.parametrizations import (
@@ -39,6 +38,10 @@ def configure_exponential_family() -> None:
     """
     Configure and register the Exponential distribution family.
     """
+
+    if ParametricFamilyRegister.contains(FamilyName.EXPONENTIAL):
+        return
+
     EXPONENTIAL_DOC = """
     Exponential distribution.
 
@@ -215,7 +218,6 @@ def _support(_: Parametrization) -> ContinuousSupport:
             CharacteristicName.SKEW: skew_func,
             CharacteristicName.KURT: kurt_func,
         },
-        sampling_strategy=DefaultSamplingUnivariateStrategy(),
         support_by_parametrization=_support,
     )
     Exponential.__doc__ = EXPONENTIAL_DOC
diff --git a/src/pysatl_core/families/builtins/continuous/normal.py b/src/pysatl_core/families/builtins/continuous/normal.py
@@ -16,7 +16,6 @@
 import numpy as np
 from scipy.special import erf, erfinv
 
-from pysatl_core.distributions.strategies import DefaultSamplingUnivariateStrategy
 from pysatl_core.distributions.support import ContinuousSupport
 from pysatl_core.families.parametric_family import ParametricFamily
 from pysatl_core.families.parametrizations import (
@@ -41,6 +40,10 @@ def configure_normal_family() -> None:
     """
     Configure and register the Normal distribution family.
     """
+
+    if ParametricFamilyRegister.contains(FamilyName.NORMAL):
+        return
+
     NORMAL_DOC = """
     Normal (Gaussian) distribution.
 
@@ -218,7 +221,6 @@ def _support(_: Parametrization) -> ContinuousSupport:
             CharacteristicName.SKEW: skew_func,
             CharacteristicName.KURT: kurt_func,
         },
-        sampling_strategy=DefaultSamplingUnivariateStrategy(),
         support_by_parametrization=_support,
     )
     Normal.__doc__ = NORMAL_DOC
diff --git a/src/pysatl_core/families/builtins/continuous/uniform.py b/src/pysatl_core/families/builtins/continuous/uniform.py
@@ -14,7 +14,6 @@
 
 import numpy as np
 
-from pysatl_core.distributions.strategies import DefaultSamplingUnivariateStrategy
 from pysatl_core.distributions.support import ContinuousSupport
 from pysatl_core.families.parametric_family import ParametricFamily
 from pysatl_core.families.parametrizations import (
@@ -39,6 +38,10 @@ def configure_uniform_family() -> None:
     """
     Configure and register the Uniform distribution family.
     """
+
+    if ParametricFamilyRegister.contains(FamilyName.CONTINUOUS_UNIFORM):
+        return
+
     UNIFORM_DOC = """
     Uniform (continuous) distribution.
 
@@ -250,7 +253,6 @@ def _support(parameters: Parametrization) -> ContinuousSupport:
             CharacteristicName.SKEW: skew_func,
             CharacteristicName.KURT: kurt_func,
         },
-        sampling_strategy=DefaultSamplingUnivariateStrategy(),
         support_by_parametrization=_support,
     )
     Uniform.__doc__ = UNIFORM_DOC
diff --git a/src/pysatl_core/families/distribution.py b/src/pysatl_core/families/distribution.py
@@ -13,17 +13,17 @@
 
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from pysatl_core.distributions.distribution import Distribution
 from pysatl_core.families.registry import ParametricFamilyRegister
+from pysatl_core.types import NumericArray
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
     from typing import Any
 
     from pysatl_core.distributions.computation import AnalyticalComputation
-    from pysatl_core.distributions.sampling import Sample
     from pysatl_core.distributions.strategies import (
         ComputationStrategy,
         SamplingStrategy,
@@ -167,20 +167,23 @@ def support(self) -> Support | None:
         """Get the support of this distribution."""
         return self._support
 
-    def sample(self, n: int, **options: Any) -> Sample:
+    def sample(self, n: int, **options: Any) -> NumericArray:
         """
-        Generate samples from this distribution.
+        Generate random samples from the distribution.
 
         Parameters
         ----------
         n : int
             Number of samples to generate.
         **options : Any
-            Additional options for sampling.
+            Additional sampling options forwarded to the underlying
+            sampling strategy.
 
         Returns
         -------
-        Sample
-            Generated samples.
+        NumericArray
+            NumPy array containing ``n`` generated samples.
+            The exact array shape depends on the distribution and
+            the sampling strategy.
         """
-        return self.sampling_strategy.sample(n, distr=self, **options)
+        return cast(NumericArray, self.sampling_strategy.sample(n, distr=self, **options))
diff --git a/src/pysatl_core/families/registry.py b/src/pysatl_core/families/registry.py
@@ -83,6 +83,26 @@ def register(cls, family: ParametricFamily) -> None:
             raise ValueError(f"Family {family.name} already found in register")
         self._registered_families[family.name] = family
 
+    @classmethod
+    def contains(cls, name: str) -> bool:
+        """
+        Check whether a parametric family with the given name
+        is registered in the registry.
+
+        Parameters
+        ----------
+        name : str
+            Name of the parametric family.
+
+        Returns
+        -------
+        bool
+            ``True`` if the family is present in the registry,
+            ``False`` otherwise.
+        """
+        self = cls()
+        return name in self._registered_families
+
     @classmethod
     def _reset(cls) -> None:
         """
diff --git a/tests/unit/distributions/test_sampling.py b/tests/unit/distributions/test_sampling.py
@@ -15,12 +15,15 @@ def test_sample_uniform_ppf_only_shape_bounds_and_mean(self) -> None:
         distr = self.make_uniform_ppf_distribution()
 
         n = 1000
-        sample = distr.sample(n)
+        samples = distr.sample(n)
 
-        assert sample.shape == (n, 1)
-        arr = sample.array
-        assert np.isfinite(arr).all()
-        assert ((arr >= 0.0) & (arr <= 1.0)).all()
+        assert isinstance(samples, np.ndarray)
 
-        mean = float(arr.mean())
+        flat = np.asarray(samples, dtype=np.float64).reshape(-1)
+        assert flat.shape == (n,)
+
+        assert np.isfinite(flat).all()
+        assert ((flat >= 0.0) & (flat <= 1.0)).all()
+
+        mean = float(flat.mean())
         assert mean == pytest.approx(0.5, abs=0.1)
diff --git a/tests/unit/families/test_family_and_distribution.py b/tests/unit/families/test_family_and_distribution.py
@@ -4,6 +4,7 @@
 __copyright__ = "Copyright (c) 2025 PySATL project"
 __license__ = "SPDX-License-Identifier: MIT"
 
+import numpy as np
 import pytest
 
 from pysatl_core.families import ParametricFamilyRegister
@@ -28,10 +29,14 @@ def test_family_registration_and_distribution_sampling(self) -> None:
         distr = fam.distribution("base", value=0.0)
 
         n = 128
-        sample = distr.sample(n)
-        assert sample.shape == (n, 1)
-        arr = sample.array
-        assert (arr >= 0.0).all() and (arr <= 1.0).all()
+        samples = distr.sample(n)
+
+        assert isinstance(samples, np.ndarray)
+
+        flat = np.asarray(samples, dtype=np.float64).reshape(-1)
+        assert flat.shape == (n,)
+
+        assert ((flat >= 0.0) & (flat <= 1.0)).all()
 
         computations = distr.analytical_computations
         assert set(computations) == {
diff --git a/tests/utils/mocks.py b/tests/utils/mocks.py
