Skip to content

Commit 00e4f98

Browse files
LeonidElkinLeonidElkin
committed
chore: README update
1 parent cbc6188 commit 00e4f98

File tree

1 file changed

+78
-100
lines changed

1 file changed

+78
-100
lines changed

‎README.md‎

Lines changed: 78 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,42 @@
88
[![CI][status-shield]][status-url]
99
[![MIT License][license-shield]][license-url]
1010

11-
**PySATL Core** is a minimal kernel for probability distributions: a distribution protocol, computation strategies, numeric converters between characteristics, and a dependency graph of characteristics. The kernel is designed as a foundation for other PySATL modules (CPD, etc.), with a focus on strict typing, extensibility, and reproducible computations.
11+
**PySATL Core** is the computational core of the PySATL project, providing abstractions and infrastructure for probability distributions, parametric families, characteristic-based computations, and sampling.
1212

13-
## Features
13+
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.
1414

15-
- `Distribution` protocol with the minimal implementation `StandaloneEuclideanUnivariateDistribution`.
16-
- Analytical and fitted computations for characteristics (`pdf`, `cdf`, `ppf`, etc.).
17-
- Conversions between characteristics: `ppf↔cdf`, `cdf↔pdf` and their compositions.
18-
- Characteristic registry as a directed graph with invariants and path-based planning.
19-
- Sampling strategies (by default sampling via `ppf`).
20-
- Strict typing (`mypy --strict`), modern Python 3.12+.
15+
> **Project status**
16+
> PySATL Core is currently in **early alpha**.
17+
> It is **not published** to package managers such as `pip` yet.
18+
> To experiment with the library, clone the repository and work with it locally.
19+
20+
---
21+
22+
## ✨ Key features
23+
24+
- **Parametric families of distributions** with multiple parametrizations
25+
(e.g. Normal: `meanStd`, `meanPrec`).
26+
- A global **family registry** for configuring, querying, and extending available distribution families.
27+
- **Characteristic computation graph** (`CharacteristicRegistry`) that allows computing
28+
arbitrary characteristics by specifying only a minimal analytical subset.
29+
- Distribution objects exposing common probabilistic operations
30+
(sampling, analytical and fitted computations).
31+
- Clear separation between *distribution definitions*, *parametrizations*,
32+
*computation strategies*, and *characteristics*.
33+
- Modern Python with strict static typing (PEP 695).
2134

2235
---
2336

2437
## Requirements
2538

26-
- Python **3.12+**
39+
- Python **3.12+** (the project relies on **PEP 695** syntax)
2740
- NumPy **2.x**
2841
- SciPy **1.13+**
29-
- Poetry (for development)
42+
- Poetry (recommended for development)
3043

31-
## Installation
44+
---
45+
46+
## Installation (from source)
3247

3348
Clone the repository:
3449

@@ -37,136 +52,99 @@ git clone https://github.com/PySATL/pysatl-core.git
3752
cd pysatl-core
3853
```
3954

40-
Install dependencies (via Poetry):
55+
### Using Poetry (recommended)
4156

4257
```bash
43-
poetry install
58+
poetry install --with docs
4459
```
4560

46-
Or install the package locally with `pip` (editable):
61+
### Using pip (editable install)
4762

4863
```bash
49-
pip install -e .
64+
pip install -e ".[docs]"
5065
```
5166

5267
---
5368

54-
## Quickstart
69+
## 🚀 Quickstart
5570

56-
Below is a minimal example: define an analytical `ppf`, draw a sample, compute `cdf` and `pdf` through the kernel’s converters, and evaluate log-likelihood for a simple uniform case.
71+
Below is a compact example demonstrating the use of a **built-in Normal distribution**.
72+
It mirrors the example shown in the documentation (`examples/overview.ipynb`).
5773

5874
```python
59-
from pysatl_core.types import Kind
60-
from pysatl_core.distributions import (
61-
AnalyticalComputation,
62-
StandaloneEuclideanUnivariateDistribution,
75+
from pysatl_core import (
76+
FamilyName,
77+
ParametricFamilyRegister,
78+
configure_normal_family,
6379
)
64-
from pysatl_core.distributions.characteristics import GenericCharacteristic
65-
66-
# Characteristic names
67-
PDF = "pdf"
68-
CDF = "cdf"
69-
PPF = "ppf"
70-
71-
# 1) A distribution with analytical PPF (identity on [0,1] for demo)
72-
dist_ppf = StandaloneEuclideanUnivariateDistribution(
73-
kind=Kind.CONTINUOUS,
74-
analytical_computations=[
75-
AnalyticalComputation[float, float](PPF, lambda q: q) # x := ppf(q)
76-
],
77-
)
78-
79-
# 2) Sample 5 points (shape (n, d) = (5, 1))
80-
sample = dist_ppf.sample(5)
81-
print(sample.shape) # -> (5, 1)
8280

83-
# 3) Compute characteristics via generic dispatch:
84-
CDF_ = GenericCharacteristic[float, float](CDF)
85-
PDF_ = GenericCharacteristic[float, float](PDF)
81+
configure_normal_family()
82+
normal_family = ParametricFamilyRegister.get(FamilyName.NORMAL)
8683

87-
x = 0.5
88-
print("cdf(0.5) =", CDF_(dist_ppf, x)) # cdf reconstructed from ppf
89-
print("pdf(0.5) =", PDF_(dist_ppf, x)) # pdf reconstructed from cdf
90-
91-
# 4) Log-likelihood: define an analytical uniform pdf on [0,1]
92-
dist_uniform_pdf = StandaloneEuclideanUnivariateDistribution(
93-
kind=Kind.CONTINUOUS,
94-
analytical_computations=[
95-
AnalyticalComputation[float, float](PDF, lambda t: 1.0 if 0.0 <= t <= 1.0 else 0.0)
96-
],
84+
normal = normal_family.distribution(
85+
parametrization_name="meanStd",
86+
mu=0.0,
87+
sigma=1.0,
9788
)
9889

99-
ll = dist_uniform_pdf.log_likelihood(sample)
100-
print("log-likelihood =", ll) # for uniform on [0,1]: log(1) == 0
101-
```
102-
103-
The idea is simple:
104-
- The **what** is defined by the characteristic name (`"pdf"`, `"cdf"`, `"ppf"`).
105-
- The **how** is decided by the computation strategy: it either picks an analytical implementation or reconstructs it from other characteristics using the registry graph (with optional caching).
106-
107-
---
108-
109-
## Concepts & Design
110-
111-
- **Distribution protocol.** A minimal stable interface for downstream PySATL modules.
112-
- **Analytical vs Fitted.** You can provide analytical functions; otherwise the kernel composes fitted methods from other available characteristics.
113-
- **Characteristic graph.** A directed graph over characteristic names for a fixed distribution type; path search yields a pipeline of converters.
114-
- **Sampling via PPF.** In the 1D Euclidean case, default sampling uses `ppf` with i.i.d. `U(0,1)`.
115-
- **Strict typing.** The codebase targets `mypy --strict` and static analysis.
116-
117-
---
90+
normal_alt = normal_family.distribution(
91+
parametrization_name="meanPrec",
92+
mu=0.0,
93+
tau=1.0,
94+
)
11895

119-
## Development
96+
samples = normal.sample(n=10_000)
97+
print(samples[:5])
12098

121-
Set up the dev environment:
99+
mean = normal.query_method("mean")()
100+
variance = normal.query_method("variance")()
122101

123-
```bash
124-
poetry install --with dev
102+
print(mean, variance)
125103
```
126104

127-
Run tests:
105+
This example uses a **predefined family** and **predefined parametrizations**.
106+
PySATL Core also supports defining custom families, parametrizations,
107+
and characteristic graphs.
128108

129-
```bash
130-
poetry run pytest -q
131-
```
109+
---
132110

133-
Coverage:
111+
## 📖 Documentation
134112

135-
```bash
136-
poetry run pytest --cov=pysatl_core --cov-report=term-missing
137-
```
113+
👉 **Online documentation:**
114+
https://pysatl.github.io/pysatl-core/
138115

139-
Static checks and style:
116+
Documentation previews are automatically generated for pull requests and can be inspected via CI artifacts.
140117

141-
```bash
142-
poetry run ruff check .
143-
poetry run mypy src
144-
```
118+
---
145119

146-
### Pre-commit
120+
## 🧠 Concepts & design
147121

148-
Install hooks:
122+
- **ParametricFamily** — a family of distributions sharing a common mathematical form.
123+
- **Parametrization** — a concrete coordinate system for a family.
124+
- **Distribution** — a probabilistic object instantiated from a family and parametrization.
125+
- **Characteristic graph** — a directed graph describing relationships between computable characteristics.
126+
- **Registries** — explicit global registries enabling controlled extensibility.
149127

150-
```bash
151-
poetry run pre-commit install
152-
```
128+
---
153129

154-
Run manually:
130+
## 🛠 Development
155131

156132
```bash
157-
poetry run pre-commit run --all-files --color always --verbose --show-diff-on-failure
133+
poetry install --with dev
134+
poetry run pytest
135+
poetry run pre-commit run --all-files
158136
```
159137

160138
---
161139

162-
## Roadmap
140+
## 🗺 Roadmap
163141

164-
- Multivariate Euclidean distributions and sampling strategies.
165-
- Expanded converter registry and stronger invariants in the characteristic graph.
166-
- Mixtures and compositional operations in the core.
142+
- **Transformations module** for mixtures and distribution transformations.
143+
- Extension of characteristic graphs.
144+
- Stabilization of APIs and **publishing PySATL Core as an installable package**.
167145

168146
---
169147

170148
## License
171149

172-
Distributed under the **MIT** License. See [LICENSE](LICENSE).
150+
Distributed under the **MIT License**. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)