feat: UNURAN Sampler realization

Author: wrdxwrdxwrdx

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 .sampling import *
+from .sampling import __all__ as _sampling_all
 from .types import *
 from .types import __all__ as _types_all
 
@@ -23,8 +25,10 @@
     *_distr_all,
     *_family_all,
     *_types_all,
+    *_sampling_all,
 ]
 
 del _distr_all
 del _family_all
 del _types_all
+del _sampling_all

src/pysatl_core/distributions/distribution.py

@@ -23,7 +23,7 @@
     from collections.abc import Mapping
     from typing import Any
 
-    from pysatl_core.distributions.computation import AnalyticalComputation, Method
+    from pysatl_core.distributions.computation import AnalyticalComputation
     from pysatl_core.distributions.strategies import (
         ComputationStrategy,
         SamplingStrategy,
@@ -32,6 +32,7 @@
     from pysatl_core.types import (
         DistributionType,
         GenericCharacteristicName,
+        Method,
     )
 
 

src/pysatl_core/distributions/strategies.py

@@ -16,12 +16,12 @@
 import numpy as np
 
 from pysatl_core.distributions.registry import characteristic_registry
-from pysatl_core.types import CharacteristicName, NumericArray
+from pysatl_core.types import CharacteristicName, Method, NumericArray
 
 if TYPE_CHECKING:
     from typing import Any
 
-    from pysatl_core.distributions.computation import FittedComputationMethod, Method
+    from pysatl_core.distributions.computation import FittedComputationMethod
     from pysatl_core.distributions.distribution import Distribution
     from pysatl_core.types import GenericCharacteristicName
 

src/pysatl_core/sampling/__init__.py

@@ -0,0 +1,26 @@
+"""
+Public sampling interface re-exporting UNURAN-based defaults.
+"""
+
+__author__ = "Artem Romanyuk"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from .unuran import (
+    DefaultUnuranSampler,
+    DefaultUnuranSamplingStrategy,
+    UnuranMethod,
+    UnuranMethodConfig,
+)
+
+SamplingMethod = UnuranMethod
+SamplingMethodConfig = UnuranMethodConfig
+DefaultSampler = DefaultUnuranSampler
+DefaultSamplingStrategy = DefaultUnuranSamplingStrategy
+
+__all__ = [
+    "SamplingMethod",
+    "SamplingMethodConfig",
+    "DefaultSampler",
+    "DefaultSamplingStrategy",
+]

src/pysatl_core/sampling/unuran/__init__.py

@@ -0,0 +1,26 @@
+"""
+Expose the UNU.RAN sampling API interfaces alongside their default
+implementations backed by our C bindings.
+"""
+
+from __future__ import annotations
+
+__author__ = "Artem Romanyuk"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from .core import (
+    DefaultUnuranSampler,
+    DefaultUnuranSamplingStrategy,
+)
+from .method_config import (
+    UnuranMethod,
+    UnuranMethodConfig,
+)
+
+__all__ = [
+    "UnuranMethod",
+    "UnuranMethodConfig",
+    "DefaultUnuranSampler",
+    "DefaultUnuranSamplingStrategy",
+]

src/pysatl_core/sampling/unuran/core/__init__.py

@@ -0,0 +1,20 @@
+"""Core UNU.RAN sampler and sampling strategy implementations.
+
+Exposes :class:`DefaultUnuranSampler`, which wraps the UNU.RAN C library via
+CFFI and automatically selects a sampling method (PINV, NINV, DGT, …) based on
+the available distribution characteristics, and
+:class:`DefaultUnuranSamplingStrategy`, the high-level strategy that integrates
+the sampler with the PySATL distribution protocol.
+"""
+
+__author__ = "Artem Romanyuk"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from .unuran_sampler import DefaultUnuranSampler
+from .unuran_sampling_strategy import DefaultUnuranSamplingStrategy
+
+__all__ = [
+    "DefaultUnuranSampler",
+    "DefaultUnuranSamplingStrategy",
+]

src/pysatl_core/sampling/unuran/core/_unuran_sampler/__init__.py

@@ -0,0 +1,28 @@
+"""
+PySATL Core — UNU.RAN Sampler Internals
+=========================================
+
+Internal sub-package that wires together the two building blocks of the
+UNU.RAN sampler:
+
+- ``UnuranSamplerInitializer`` — creates the UNU.RAN distribution object,
+  registers distribution callbacks (PDF, CDF, PMF, …) and initialises
+  the generator for a pre-selected sampling method (PINV, NINV, DGT, …).
+- ``ensure_default_urng`` — registers a NumPy-backed uniform RNG as the
+  UNU.RAN default URNG so that seeding and reproducibility work through
+  the standard NumPy interface.
+"""
+
+from __future__ import annotations
+
+__author__ = "Artem Romanyuk"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from .initialization import UnuranSamplerInitializer
+from .urng import ensure_default_urng
+
+__all__ = [
+    "UnuranSamplerInitializer",
+    "ensure_default_urng",
+]

src/pysatl_core/sampling/unuran/core/_unuran_sampler/callbacks.py

@@ -0,0 +1,234 @@
+"""
+Callback creation utilities for UNU.RAN sampler bindings.
+
+Provides callback function creation for PDF/PMF evaluation needed during
+UNU.RAN distribution setup.
+"""
+
+from __future__ import annotations
+
+__author__ = "Artem Romanyuk"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from pysatl_core.types import CharacteristicName, Kind
+
+if TYPE_CHECKING:
+    from pysatl_core.types import Method
+
+_CONT_SIG = "double(double, const struct unur_distr*)"
+_DISCR_SIG = "double(int, const struct unur_distr*)"
+
+
+class UnuranCallback:
+    """
+    Factory and registry for CFFI callbacks wired into a UNU.RAN distribution object.
+
+    Creates closures over distribution characteristic functions (PDF, dPDF, CDF,
+    PPF, PMF) and registers them with the corresponding UNU.RAN setter. All live
+    callback objects are kept in an internal list so the garbage collector cannot
+    reclaim them while the UNU.RAN generator is alive.
+    """
+
+    def __init__(
+        self,
+        unuran_distr: Any,
+        kind: Kind,
+        lib: Any,
+        ffi: Any,
+        characteristics: Mapping[CharacteristicName, Method[Any, Any]],
+    ) -> None:
+        """
+        Parameters
+        ----------
+        unuran_distr : Any
+            CFFI pointer to the UNU.RAN distribution object.
+        kind : Kind
+            Whether the distribution is continuous or discrete.
+        lib : Any
+            CFFI library handle.
+        ffi : Any
+            CFFI FFI instance used to create callbacks.
+        characteristics : Mapping[CharacteristicName, Method[Any, Any]]
+            Map of available characteristic names to their callables.
+        """
+        self._unuran_distr = unuran_distr
+        self._kind = kind
+        self._lib = lib
+        self._ffi = ffi
+        self._characteristics = dict(characteristics)
+        self._callbacks: list[Any] = []
+
+    @property
+    def callbacks(self) -> list[Any]:
+        """Live CFFI callback objects that must remain referenced for UNU.RAN."""
+        return self._callbacks
+
+    def _create_callback(self, char_name: CharacteristicName, signature: str) -> Any | None:
+        """
+        Create a CFFI callback for the given characteristic and UNU.RAN signature.
+
+        The wrapper converts the scalar input to a 1-D ``float64`` numpy array
+        before calling the characteristic, then converts the result to ``float``.
+        This ensures compatibility with characteristics that use numpy array
+        methods internally, while satisfying UNU.RAN's ``double`` return type.
+
+        Parameters
+        ----------
+        char_name:
+            Characteristic to look up in the distribution.
+        signature:
+            CFFI function type string, e.g. ``"double(double, const struct unur_distr*)"``.
+
+        Returns
+        -------
+        CFFI callback or None
+            None if the characteristic is not available.
+        """
+        func = self._characteristics.get(char_name)
+        if func is None:
+            return None
+
+        def cb(x: Any, _: Any) -> float:
+            return float(func(np.asarray(x, dtype=float)))
+
+        return self._ffi.callback(signature, cb)
+
+    def setup_callback(self, func: Any | None, cffi_func: Any, error_text: str) -> None:
+        """
+        Register a single CFFI callback with its UNU.RAN setter.
+
+        Parameters
+        ----------
+        func : Any or None
+            CFFI callback to register. Skipped silently when ``None``.
+        cffi_func : Any
+            UNU.RAN setter function (e.g. ``unur_distr_cont_set_pdf``).
+        error_text : str
+            Message template passed to :class:`RuntimeError` on failure; must
+            contain one ``{}`` placeholder for the error code.
+
+        Raises
+        ------
+        RuntimeError
+            If the setter returns a non-zero error code.
+        """
+        if func:
+            self._callbacks.append(func)
+            result = cffi_func(self._unuran_distr, func)
+            if result != 0:
+                raise RuntimeError(error_text.format(result))
+
+    def setup_continuous_callbacks(self) -> None:
+        """
+        Set up callbacks for continuous distributions.
+
+        Configures PDF, dPDF (if available), CDF, and PPF callbacks for the UNURAN
+        continuous distribution object.
+
+        Raises
+        ------
+        RuntimeError
+            If setting any callback fails (non-zero return code).
+
+        Notes
+        -----
+        All created callbacks are appended to ``_callbacks`` list to prevent
+        garbage collection. Only available callbacks are set (missing
+        characteristics are skipped).
+        """
+        self.setup_callback(
+            self._create_callback(CharacteristicName.PDF, _CONT_SIG),
+            self._lib.unur_distr_cont_set_pdf,
+            "Failed to set PDF callback (error code: {})",
+        )
+        self.setup_callback(
+            self._create_callback(CharacteristicName.DPDF, _CONT_SIG),
+            self._lib.unur_distr_cont_set_dpdf,
+            "Failed to set dPDF callback (error code: {})",
+        )
+        self.setup_callback(
+            self._create_callback(CharacteristicName.CDF, _CONT_SIG),
+            self._lib.unur_distr_cont_set_cdf,
+            "Failed to set CDF callback (error code: {})",
+        )
+        self.setup_callback(
+            self._create_callback(CharacteristicName.PPF, _CONT_SIG),
+            self._lib.unur_distr_cont_set_invcdf,
+            "Failed to set PPF callback (error code: {})",
+        )
+
+    def _create_indexed_pmf_callback(self, points: np.ndarray) -> Any | None:
+        """
+        Create a CFFI PMF callback that maps integer indices to support values.
+
+        UNU.RAN will call this with indices ``0, 1, ..., n-1``.  The callback
+        converts each index to the corresponding support value via ``points[i]``
+        before evaluating the PMF, enabling DGT to work with arbitrary
+        (non-integer, sparse) supports.
+
+        Parameters
+        ----------
+        points : np.ndarray
+            Array of support values; ``points[i]`` is the actual value for index ``i``.
+
+        Returns
+        -------
+        CFFI callback or None
+            None if PMF is not available.
+        """
+        func = self._characteristics.get(CharacteristicName.PMF)
+        if func is None:
+            return None
+
+        def cb(i: Any, _: Any) -> float:
+            return float(func(np.asarray(points[i], dtype=float)))
+
+        return self._ffi.callback(_DISCR_SIG, cb)
+
+    def setup_discrete_callbacks(self, index_remap_points: np.ndarray | None = None) -> None:
+        """
+        Set up callbacks for discrete distributions.
+
+        Configures PMF and CDF callbacks for the UNURAN discrete distribution
+        object.
+
+        Parameters
+        ----------
+        index_remap_points : np.ndarray or None
+            When provided, the PMF callback treats its integer argument as an
+            index into this array and evaluates the PMF at ``points[i]`` instead
+            of at ``i`` directly.  Use this when the UNU.RAN domain is set to
+            ``[0, n-1]`` (index space) rather than the actual support values.
+
+        Raises
+        ------
+        RuntimeError
+            If setting any callback fails (non-zero return code).
+
+        Notes
+        -----
+        All created callbacks are appended to ``_callbacks`` list to prevent
+        garbage collection. Only available callbacks are set (missing
+        characteristics are skipped).
+        """
+        if index_remap_points is not None:
+            pmf_cb = self._create_indexed_pmf_callback(index_remap_points)
+        else:
+            pmf_cb = self._create_callback(CharacteristicName.PMF, _DISCR_SIG)
+
+        self.setup_callback(
+            pmf_cb,
+            self._lib.unur_distr_discr_set_pmf,
+            "Failed to set PMF callback (error code: {})",
+        )
+        self.setup_callback(
+            self._create_callback(CharacteristicName.CDF, _DISCR_SIG),
+            self._lib.unur_distr_discr_set_cdf,
+            "Failed to set CDF callback (error code: {})",
+        )