UNURAN sampling integration

.github/CODEOWNERS

@@ -0,0 +1 @@
+/vendor/

.gitignore

@@ -5,6 +5,7 @@ __pycache__/
 
 # C extensions
 *.so
+*.o
 
 # Distribution / packaging
 .Python
@@ -125,3 +126,6 @@ poetry.lock
 #  refer to https://docs.cursor.com/context/ignore-files
 .cursorignore
 .cursorindexingignore
+
+# Log files
+*.log

.pre-commit-config.yaml

@@ -19,6 +19,7 @@ exclude: >
     | \.gitignore$
     | LICENSE$
     | .*\.md$
+    | vendor/.*
   )$
 
 repos:
@@ -67,3 +68,4 @@ repos:
           - scipy>=1.13
           - pytest>=8
           - scipy-stubs>=1.13
+          - types-setuptools>=75

README.md

@@ -37,10 +37,11 @@ git clone https://github.com/PySATL/pysatl-core.git
 cd pysatl-core
 ```
 
-Install dependencies (via Poetry):
+Install dependencies and build project (via Poetry):
 
 ```bash
 poetry install
+poetry build
 ```
 
 Or install the package locally with `pip` (editable):

pyproject.toml

@@ -1,7 +1,11 @@
 [build-system]
 build-backend = "poetry.core.masonry.api"
 
-requires = [ "poetry-core>=1.9" ]
+requires = [
+  "cffi>=1.16",
+  "poetry-core>=1.9",
+  "setuptools>=69",
+]
 
 [tool.poetry]
 name = "pysatl-core"
@@ -41,10 +45,14 @@ homepage = "https://github.com/PySATL/pysatl-core"
 repository = "https://github.com/PySATL/pysatl-core"
 urls.Issues = "https://github.com/PySATL/pysatl-core/issues"
 
+[tool.poetry.build]
+script = "src/pysatl_core/stats/_unuran/bindings/_cffi_build.py"
+
 [tool.poetry.dependencies]
 python = ">=3.12"
 numpy = "^2.0.0"
 scipy = ">=1.13"
+cffi = "^1.16.0"
 
 [tool.poetry.group.dev.dependencies]
 ruff = ">=0.6"
@@ -55,6 +63,7 @@ coverage = { version = ">=7.5", extras = [ "toml" ] }
 pre-commit = ">=3.6"
 types-setuptools = "*"
 scipy-stubs = ">=1.13.0.0"
+types-cffi = ">=1.17.0.0"
 
 [tool.poetry.group.docs.dependencies]
 jupyter = "^1.1.1"
@@ -63,6 +72,7 @@ matplotlib = "^3.10.6"
 [tool.ruff]
 target-version = "py312"
 line-length = 100
+exclude = [ "vendor" ]
 
 format.line-ending = "lf"
 
@@ -77,6 +87,9 @@ lint.isort.force-single-line = false
 lint.isort.known-first-party = [ "pysatl_core" ]
 lint.isort.order-by-type = true
 
+[tool.codespell]
+skip = "vendor/**"
+
 [tool.pytest.ini_options]
 addopts = "-q --cov=pysatl_core --cov-report=term-missing"
 testpaths = [ "tests" ]

setup.py

@@ -0,0 +1,13 @@
+"""
+Setup script for pysatl-core with CFFI support.
+
+This file is needed to integrate CFFI modules with Poetry.
+"""
+
+from setuptools import setup
+
+setup(
+    cffi_modules=[
+        "src/pysatl_core/stats/_unuran/bindings/_cffi_build.py:ffi",
+    ],
+)

src/pysatl_core/stats/_unuran/__init__.py

@@ -0,0 +1,57 @@
+"""
+UNU.RAN Integration API
+=======================
+
+This module defines the API for UNU.RAN (Universal Non-Uniform Random Number
+Generator) integration. UNU.RAN provides efficient methods for generating
+non-uniform random variates from various distributions.
+
+The API described here will be implemented through C bindings to the UNU.RAN
+library in the future. Currently, this module only provides the interface
+specification for integration with the distribution sampling system.
+
+Notes
+-----
+- UNU.RAN supports multiple sampling methods (inversion, rejection, etc.)
+- Methods can be selected automatically or specified explicitly
+- The API integrates with the :class:`~pysatl_core.distributions.strategies.SamplingStrategy`
+  protocol
+- Currently, only univariate distributions are supported
+
+Examples
+--------
+Create a UNU.RAN sampling strategy for a distribution:
+
+    >>> from pysatl_core.stats._unuran import (
+    >>>     create_unuran_strategy, UnuranMethodConfig, UnuranMethod
+    >>> )
+    >>> config = UnuranMethodConfig(method=UnuranMethod.AUTO)
+    >>> strategy = create_unuran_strategy(config)
+    >>> sample = strategy.sample(n=1000, distr=my_distribution)
+"""
+
+from __future__ import annotations
+
+__author__ = "Artem Romanyuk"
+__copyright__ = "Copyright (c) 2025 PySATL project"
+__license__ = "SPDX-License-Identifier: MIT"
+
+from pysatl_core.stats._unuran.api import (
+    UnuranMethod,
+    UnuranMethodConfig,
+    UnuranSampler,
+    UnuranSamplingStrategy,
+)
+from pysatl_core.stats._unuran.bindings import (
+    DefaultUnuranSampler,
+    DefaultUnuranSamplingStrategy,
+)
+
+__all__ = [
+    "UnuranMethod",
+    "UnuranMethodConfig",
+    "UnuranSampler",
+    "UnuranSamplingStrategy",
+    "DefaultUnuranSampler",
+    "DefaultUnuranSamplingStrategy",
+]