Skip to content

README.md

Latest commit

 

History

History
187 lines (130 loc) · 5.44 KB

README.md

File metadata and controls

187 lines (130 loc) · 5.44 KB

PySATL Core

CI MIT License

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.

Project status
PySATL Core is currently in early alpha.
The public API may change between alpha releases.

✨ Key features

  • Parametric families of distributions with multiple parametrizations
    (e.g. Normal: meanStd, meanPrec).
  • 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, computation strategies, and characteristics.
  • Modern Python with strict static typing (PEP 695).

Requirements

  • Python 3.12+ (the project relies on PEP 695 syntax)
  • NumPy 2.x
  • SciPy 1.13+
  • A C toolchain when building from source or from an sdist:
    • 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)

Installation

Install from PyPI:

pip install pysatl-core

Linux wheels are not published yet. On Linux, pip builds the package from the source distribution and requires a working C toolchain.

For development, install from source.

Clone the repository:

git clone https://github.com/PySATL/pysatl-core.git
cd pysatl-core
git submodule update --init --recursive

Development install

poetry install --with dev,docs

Editable runtime install

pip install -e .

🚀 Quickstart

Below is a compact example demonstrating the use of a built-in Normal distribution. It mirrors the example shown in the documentation (examples/overview.ipynb).

from pysatl_core import (
    FamilyName,
    ParametricFamilyRegister,
    configure_normal_family,
)

configure_normal_family()
normal_family = ParametricFamilyRegister.get(FamilyName.NORMAL)

normal = normal_family.distribution(
    parametrization_name="meanStd",
    mu=0.0,
    sigma=1.0,
)

normal_alt = normal_family.distribution(
    parametrization_name="meanPrec",
    mu=0.0,
    tau=1.0,
)

samples = normal.sample(n=10_000)
print(samples[:5])

mean = normal.query_method("mean")()
variance = normal.query_method("variance")()

print(mean, variance)

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

👉 Online documentation:
https://pysatl.github.io/pysatl-core/

Documentation previews are automatically generated for pull requests and can be inspected via CI artifacts.

🧠 Concepts & design

  • ParametricFamily — a family of distributions sharing a common mathematical form.
  • Parametrization — a concrete coordinate system for a family.
  • Distribution — a probabilistic object instantiated from a family and parametrization.
  • Characteristic graph — a directed graph describing relationships between computable characteristics.
  • Registries — explicit global registries enabling controlled extensibility.

🛠 Development

poetry install --with dev
poetry run pytest
poetry run pre-commit run --all-files

Package sanity check

poetry run python -m build
poetry run twine check dist/*

These commands build the local distribution artifacts and validate their metadata. They do not publish anything.

🗺 Roadmap

  • Extension of the transformations module (functional transforms, performance improvements).
  • Extension of characteristic graphs.
  • Stabilization of APIs and publishing PySATL Core as an installable package.

License

Distributed under the MIT License. See LICENSE.