Add UNURAN sampling

.github/workflows/ci.yml

@@ -1,5 +1,4 @@
 name: CI
-
 on:
   push:
   pull_request:
@@ -12,7 +11,6 @@ jobs:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
         python-version: [ "3.12", "3.13" ]
     runs-on: ${{ matrix.os }}
-
     defaults:
       run:
         shell: bash
@@ -21,6 +19,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Sync submodules to tracked branches
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --remote --recursive
+
       - name: Setup Python
         id: setup-python
         uses: actions/setup-python@v5
@@ -34,6 +37,35 @@ jobs:
           virtualenvs-create: true
           virtualenvs-in-project: true
 
+      - name: Clean up PATH on Windows
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $clean = ($env:PATH -split ';' | Where-Object {
+            $_ -notlike '*Git\usr\bin*' -and
+            $_ -notlike '*Strawberry*'
+          }) -join ';'
+          echo "PATH=$clean" >> $env:GITHUB_ENV
+
+      - name: Set up MSVC dev cmd
+        if: runner.os == 'Windows'
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          toolset: '14.29'
+          arch: x64
+
+      - name: Remove Git link.exe from PATH
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $gitLink = "C:\Program Files\Git\usr\bin\link.exe"
+          if (Test-Path $gitLink) {
+            Rename-Item $gitLink "link_gnu_backup.exe"
+            Write-Host "Renamed Git link.exe -> link_gnu_backup.exe"
+          } else {
+            Write-Host "Git link.exe not found, nothing to do"
+          }
+
       - name: Cache pip wheels
         uses: actions/cache@v4
         with:

.github/workflows/docs_deploy.yml

@@ -23,6 +23,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Sync submodules to tracked branches
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --remote --recursive
+
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"

.github/workflows/docs_preview.yml

@@ -13,6 +13,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Sync submodules to tracked branches
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --remote --recursive
+
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"

.gitignore

@@ -5,6 +5,7 @@ __pycache__/
 
 # C extensions
 *.so
+*.o
 
 # Distribution / packaging
 .Python
@@ -127,7 +128,12 @@ poetry.lock
 .cursorindexingignore
 
 # Docs
-
 docs/build/*
 docs/source/api/*
 docs/source/examples/*
+
+# Log files
+*.log
+
+# Unuran build artifacts
+src/pysatl_core/sampling/unuran/bindings/_unuran_cffi.c

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "vendor/unuran-pysatl"]
+	path = vendor/unuran-pysatl
+	url = https://github.com/PySATL/unuran.git
+	branch = wrdxwrdxwrdx/lib_build

.pre-commit-config.yaml

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

README.md

@@ -39,6 +39,9 @@ The library is designed as a **foundational kernel** rather than a ready-to-use
 - Python **3.12+** (the project relies on **PEP 695** syntax)
 - NumPy **2.x**
 - SciPy **1.13+**
+- A C toolchain for compiling the UNURAN bindings:
+  - **Linux/macOS:** GCC (or Clang) plus standard build utilities.
+  - **Windows:** Microsoft Visual C++ Build Tools (MSVC) from Visual Studio or the standalone Build Tools installer.
 - Poetry (recommended for development)
 
 ---
@@ -50,6 +53,7 @@ Clone the repository:
 ```bash
 git clone https://github.com/PySATL/pysatl-core.git
 cd pysatl-core
+git submodule update --init --remote --recursive
 ```
 
 ### Using Poetry (recommended)

pyproject.toml

@@ -1,7 +1,13 @@
 [build-system]
 build-backend = "poetry.core.masonry.api"
 
-requires = [ "poetry-core>=1.9" ]
+requires = [
+  "cffi>=1.16",
+  "meson>=0.64",
+  "ninja>=1.10",
+  "poetry-core>=1.9",
+  "setuptools>=69",
+]
 
 [tool.poetry]
 name = "pysatl-core"
@@ -41,10 +47,15 @@ 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/sampling/unuran/bindings/_cffi_build.py"
+
 [tool.poetry.dependencies]
 python = ">=3.12"
 numpy = "^2.0.0"
 scipy = ">=1.13"
+cffi = "^1.16.0"
+mypy_extensions = ">=1.0.0"
 
 [tool.poetry.group.dev.dependencies]
 ruff = ">=0.6"
@@ -55,6 +66,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"
@@ -70,6 +82,7 @@ linkify-it-py = "^2.0.3"
 [tool.ruff]
 target-version = "py312"
 line-length = 100
+exclude = [ "vendor" ]
 
 format.line-ending = "lf"
 
@@ -84,6 +97,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" ]

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/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 .api import (
+    UnuranMethod,
+    UnuranMethodConfig,
+)
+from .core import (
+    DefaultUnuranSampler,
+    DefaultUnuranSamplingStrategy,
+)
+
+__all__ = [
+    "UnuranMethod",
+    "UnuranMethodConfig",
+    "DefaultUnuranSampler",
+    "DefaultUnuranSamplingStrategy",
+]