qjax 0.1.0__tar.gz

qjax-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev --python 3.12
+      - name: Lint with ruff
+        run: uv run ruff check qjax tests examples
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+      - name: Run tests
+        run: uv run pytest --cov=qjax --cov-report=term-missing
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra docs --python 3.12
+      - name: Build documentation (warnings as errors)
+        run: uv run sphinx-build -b html docs docs/_build/html -W --keep-going

qjax-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,27 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version tag (e.g., 0.1.0)"
+        required: true
+        type: string
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yaml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

qjax-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+
+# Sphinx build output
+docs/_build/
+
+# Example outputs
+examples/figures/*.png

qjax-0.1.0/.plan/PLAN.md

@@ -0,0 +1,171 @@
+# qjax — Implementation Plan
+
+> **qjax** is a research-oriented Python library built on [JAX](https://github.com/google/jax)
+> whose mission is to spread the research and capabilities of **Tsallis statistics**
+> (non-extensive statistical mechanics) in **artificial intelligence**.
+
+## 1. Vision
+
+Tsallis statistics generalizes Boltzmann–Gibbs statistics through a single
+*entropic index* `q`. As `q → 1` every construction collapses back to its classical
+counterpart (Shannon entropy, Gaussian, softmax, KL divergence, …). `qjax` exposes
+these `q`-deformed primitives as **pure, differentiable, `jit`/`vmap`-friendly JAX
+functions** so that researchers can:
+
+- treat `q` as a *learnable parameter* and let models discover their own statistics;
+- explore heavy-tailed / sparse alternatives to standard AI building blocks;
+- reproduce and extend Tsallis-statistics results across ML domains.
+
+## 2. Design principles
+
+1. **Purity & composability** — every primitive is a pure function of `(x, q)`;
+   no hidden state. Everything works under `jax.jit`, `jax.grad`, `jax.vmap`.
+2. **Numerically safe `q → 1` limit** — use the double-`where` trick so gradients
+   are finite exactly at `q = 1`.
+3. **Single source of truth** — `core/` holds the math; `plots/`, `examples/`,
+   and `tests/` only consume the public API.
+4. **Precise docstrings** — every public function documents its math (with the
+   defining formula and the `q → 1` limit), args, shapes, and returns.
+5. **Consistent visuals** — all plots use the **`magma`** colormap via a single
+   style module.
+
+## 3. Target package structure
+
+```
+qjax/
+├── __init__.py            # curated public API
+├── core/
+│   ├── __init__.py        # re-exports core primitives
+│   ├── functions.py       # q_log, q_exp + q-algebra (q_add, q_diff, q_prod, q_div)
+│   ├── entropy.py         # tsallis_entropy, tsallis_cross_entropy, tsallis_divergence
+│   ├── distributions.py   # q-Gaussian: pdf, logpdf, sample, normalization C_q
+│   └── activations.py     # tsallis_entmax (q-softmax / sparsemax family)
+├── shared/
+│   ├── __init__.py
+│   ├── types.py           # Array / Scalar type aliases
+│   └── validation.py      # q-range checks, broadcasting helpers
+└── plots/
+    ├── __init__.py
+    ├── style.py           # magma palette + rcParams + qcolors(n)
+    ├── functions.py       # plot q-log / q-exp families
+    └── distributions.py   # plot q-Gaussian family
+examples/                  # runnable scripts (save figures with magma palette)
+tests/                     # pytest suite (limits, gradients, jit/vmap, shapes)
+docs/                      # theory note + API overview
+pyproject.toml             # uv-managed project (jax, matplotlib, pytest, ruff)
+```
+
+## 4. Mathematical scope (core)
+
+| Primitive | Formula | `q → 1` limit |
+|-----------|---------|---------------|
+| `q_log(x, q)` | `(x**(1-q) - 1) / (1-q)` | `log(x)` |
+| `q_exp(x, q)` | `[1 + (1-q)x]_+ ** (1/(1-q))` | `exp(x)` |
+| `q_add(a, b, q)` | `a + b + (1-q) a b` | `a + b` |
+| `tsallis_entropy(p, q)` | `(1 - Σ p**q) / (q-1)` | `-Σ p log p` |
+| `tsallis_cross_entropy(p, y, q)` | `-Σ y · q_log(p, q)` | `-Σ y log p` |
+| `tsallis_divergence(p, r, q)` | `(Σ p**q r**(1-q) - 1)/(q-1)` | `KL(p‖r)` |
+| `q_gaussian_pdf(x, q, β)` | `√β/C_q · q_exp(-β x², q)` | `√(β/π)·exp(-βx²)` |
+| `tsallis_entmax(z, q)` | argmax over simplex of `⟨p,z⟩ + Sᵀ_q(p)` | `softmax(z)` |
+
+q-Gaussian sampling uses the **generalized Box–Muller** transform (valid for `q < 3`).
+
+## 5. Enhancements over the bare skeleton
+
+- Add `pyproject.toml` (uv) — the project currently has no build/dependency config.
+- Add `shared/validation.py` for consistent `q` handling and clear errors.
+- Centralize plot styling on **magma** (`plots/style.py`) instead of ad-hoc colors.
+- Fill the six example stubs with runnable, figure-producing demos.
+- Add a real pytest suite covering `q → 1` limits, gradient finiteness, `jit`/`vmap`.
+- Add a concise theory note in `docs/`.
+
+## 6. Checklist
+
+### Project setup
+- [x] `pyproject.toml` for uv (jax, matplotlib, pytest, ruff) + tool config
+- [x] `README.md` with install + quickstart
+- [x] `docs/theory.md` — concise Tsallis-statistics primer
+
+### Core — math
+- [x] `core/functions.py` — `q_log`, `q_exp`, `q_add`, `q_diff`, `q_prod`, `q_div`
+- [x] `core/entropy.py` — `tsallis_entropy`, `tsallis_cross_entropy`, `tsallis_divergence`
+- [x] `core/distributions.py` — q-Gaussian `pdf`, `logpdf`, `sample`, `normalization`
+- [x] `core/activations.py` — `tsallis_entmax` (q-softmax / sparsemax family)
+- [x] `core/__init__.py` — re-export core primitives
+
+### Shared
+- [x] `shared/types.py` — `Array`, `Scalar` aliases
+- [x] `shared/validation.py` — `as_scalar_q`, range checks
+- [x] `shared/__init__.py` — re-exports
+
+### Plots (magma palette)
+- [x] `plots/style.py` — `use_qjax_style()`, `qcolors(n)`, magma default
+- [x] `plots/functions.py` — `plot_q_log`, `plot_q_exp`
+- [x] `plots/distributions.py` — `plot_q_gaussian`
+- [x] `plots/__init__.py` — re-exports
+
+### Public API
+- [x] `qjax/__init__.py` — curated exports + `__version__`
+
+### Examples (runnable, save figures)
+- [x] `examples/q_gaussian.py` — q-Gaussian family figure
+- [x] `examples/learnable_q.py` — fit `q` by gradient descent to data
+- [x] `examples/classification.py` — Tsallis cross-entropy classifier
+- [x] `examples/optimization.py` — q-exp annealing / q-deformed objective
+- [x] `examples/reinforcement_learning.py` — Tsallis-entmax policy on bandit
+- [x] `examples/graph_learning.py` — Tsallis-entropy node attention on a graph
+
+### Tests
+- [x] `tests/test_functions.py` — limits, inverses, gradients, jit/vmap
+- [x] `tests/test_entropy.py` — Shannon/KL limits, non-negativity
+- [x] `tests/test_distributions.py` — normalization, sampling variance
+- [x] `tests/test_activations.py` — simplex, softmax/sparsemax limits
+
+### Verification
+- [x] `uv run pytest` passes (69 tests)
+- [x] `uv run ruff check` passes on `qjax`, `tests`, `examples`
+- [x] Run every example end-to-end (6 figures saved to `examples/figures/`)
+
+## 7. Notes from execution
+
+- **Sampler correctness.** The first sampler used a generalized Box–Muller with an
+  incorrect scale (variance was ~20% off). Replaced with the exact Student-``t``
+  construction ``X = Z / sqrt(W/ν) / sqrt((3-q)β)``, which reproduces the family
+  variance ``1/((5-3q)β)`` exactly. Supported range is ``1 <= q < 3``.
+- **Gradient bug in `normalization`.** The piecewise ``C_q`` closures captured the
+  raw ``q`` instead of their sanitized argument, so the unused branch evaluated
+  ``log(1-q)`` with ``q > 1`` and poisoned the gradient via ``0 * NaN``. Fixed and
+  covered by `test_normalization_gradient_finite`. This is why `learnable_q` now
+  converges (recovers ``q ≈ 1.62`` from ``q_true = 1.6``).
+- **`logpdf`.** Must use the ordinary ``log`` of the density, not ``q_log`` (which
+  would collapse to ``-βx²`` and drop the normalization curvature).
+- All plots default to the **`magma`** colormap via `qjax.plots.use_qjax_style`.
+
+## 8. Publication-grade revision
+
+- **Vector PDF output.** `use_qjax_style` now configures a research-grade style
+  (serif body + Computer-Modern math via `mathtext`, embedded fonts with
+  `pdf.fonttype=42`, in-pointing major/minor ticks, top/right spines off, magma
+  color cycle). Added `qjax.plots.save_figure`, and every example saves a tight
+  vector **PDF** to `examples/figures/`.
+- **Example rename.** `graph_learning.py` → `attention_mlp.py` (Tsallis-entmax
+  sparse attention).
+- **Classification redesigned as a baseline study.** Now compares the **Shannon
+  baseline** (`q=1`, standard cross-entropy) against robust **Tsallis** losses
+  (`q=0.7`, `q=0.4`) across increasing label-noise levels, averaged over seeds on
+  a clean test set. Key correction: the *robust* Tsallis cross-entropy regime is
+  ``q < 1`` (where ``-ln_q`` is bounded — the generalized cross-entropy), not
+  ``q > 1``; all methods share softmax outputs and differ only in the loss `q`.
+  Result: clean-test accuracy degrades far more gracefully for `q<1`
+  (`q=0.4`: 0.84→0.68) than for Shannon (`q=1`: 0.82→0.59) as `η` rises to 0.5.
+
+## 9. Documentation site
+
+- **Sphinx + Furo.** `docs/` is a full MyST-Markdown documentation site:
+  `index`, `installation`, `quickstart`, `theory`, `examples`, and an autodoc
+  `api` reference (Napoleon Google-style docstrings, viewcode, intersphinx to
+  python/numpy/jax/matplotlib). Math via MyST `dollarmath` + MathJax; magma
+  accent colors matching the plot palette.
+- Added a `docs` optional-dependency group (`sphinx`, `furo`, `myst-parser`) and
+  a `docs/Makefile`. Build: `uv run sphinx-build -b html docs docs/_build/html`
+  (clean under `-W`, warnings-as-errors).

qjax-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+sphinx:
+   configuration: docs/conf.py
+
+# python:
+#   install:
+#     - requirements: docs/requirements.txt

qjax-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to qjax
+
+Thanks for your interest in `qjax`! It is a research library for **Tsallis
+statistics in AI**, built on JAX. Contributions of all kinds are welcome: new
+`q`-deformed primitives, examples, documentation, tests, and bug fixes.
+
+This guide explains how to set up the project, the conventions we follow, and
+how to get a change merged.
+
+## Development setup
+
+`qjax` is managed with [uv](https://docs.astral.sh/uv/) and targets
+**Python 3.10+**.
+
+```bash
+git clone <repo-url> qjax
+cd qjax
+uv sync --extra dev          # runtime + tests + linter
+```
+
+Useful commands (these mirror what CI runs):
+
+```bash
+uv run pytest                                   # test suite
+uv run pytest --cov=qjax --cov-report=term-missing   # with coverage
+uv run ruff check qjax tests examples           # lint
+uv run python examples/q_gaussian.py            # run an example
+```
+
+To work on the documentation:
+
+```bash
+uv sync --extra docs
+uv run sphinx-build -b html docs docs/_build/html -W   # -W = warnings are errors
+```
+
+## Project layout
+
+```
+qjax/
+├── core/        # the math: functions, entropy, distributions, activations
+├── shared/      # type aliases and q validation helpers
+└── plots/       # magma-themed, publication-grade plotting helpers
+examples/        # runnable scripts that save figures to examples/figures/
+tests/           # pytest suite
+docs/            # Sphinx + Furo documentation (MyST Markdown)
+```
+
+`core/` is the single source of truth for the math; `plots/`, `examples/`, and
+`tests/` only consume the public API.
+
+## Design principles
+
+New primitives should follow the conventions already in `core/`:
+
+1. **Pure functions of `(x, q)`.** No hidden state. Every primitive must work
+   under `jax.jit`, `jax.grad`, and `jax.vmap`.
+2. **Recover the classical limit.** As `q → 1`, the primitive must reduce to its
+   Boltzmann–Gibbs–Shannon counterpart (log, exp, Shannon entropy, KL, …).
+3. **Finite gradients at `q = 1`.** Closed forms are typically `0/0` at `q = 1`.
+   Use the *double-`where`* trick: select the analytic limit with
+   `jnp.where(near_one(q), limit, deformed)`, and sanitize the unused branch's
+   inputs so it produces neither a `NaN` value nor a `NaN` gradient (a `0 * NaN`
+   from the unused branch will still poison `jax.grad`). See `qjax.core.functions`
+   and `qjax.core.distributions.normalization` for worked examples.
+4. **Validate `q` consistently.** Use the helpers in `qjax.shared.validation`
+   (`as_scalar_q`, `near_one`, `Q_EPS`).
+
+## Code style
+
+- **Formatting/linting:** [ruff](https://github.com/astral-sh/ruff), line length
+  **100**. Run `uv run ruff check qjax tests examples` before committing; CI
+  enforces it.
+- **Docstrings:** Google style (enforced by ruff's pydocstyle and rendered by
+  Sphinx/napoleon). Every public function documents its **formula**, its
+  **`q → 1` limit**, args (with shapes), and returns.
+- **Type hints:** use the aliases in `qjax.shared.types` (`Array`, `Scalar`).
+- Keep the public API curated in `qjax/__init__.py` and the relevant
+  `__init__.py` re-exports.
+
+## Tests
+
+Every new primitive needs tests in `tests/`. At minimum, cover:
+
+- the **`q → 1` limit** (matches the classical function to tolerance);
+- **gradient finiteness** with `jax.grad`, including at and near `q = 1`;
+- **`jit` / `vmap`** compatibility and output shapes;
+- any **mathematical identities** or domain edges (e.g. the Tsallis cut-off,
+  normalization, simplex constraints).
+
+Tests run with float64 enabled (`jax.config.update("jax_enable_x64", True)`).
+
+```bash
+uv run pytest
+```
+
+## Plots and examples
+
+- Use `qjax.plots.use_qjax_style()` and save with `qjax.plots.save_figure(...)`,
+  which writes vector **PDF** with the project's publication style.
+- All figures use the **`magma`** colormap — get colors from
+  `qjax.plots.qcolors(n)` or the `CMAP` constant rather than hard-coding.
+- Examples should be self-contained, reproducible (fixed PRNG seeds), and save
+  their output to `examples/figures/`.
+
+## Submitting a change
+
+1. Create a branch from `main`.
+2. Make your change with tests and docstrings.
+3. Ensure the full CI set passes locally:
+   ```bash
+   uv run ruff check qjax tests examples
+   uv run pytest --cov=qjax --cov-report=term-missing
+   uv run sphinx-build -b html docs docs/_build/html -W
+   ```
+4. Open a pull request describing the change and the maths behind it. Link any
+   relevant references (the README and `docs/theory.md` cite the key papers).
+
+CI (`.github/workflows/ci.yaml`) runs lint, the test matrix on Python
+3.10–3.13, and the documentation build on every push and pull request.
+
+## Reporting issues
+
+When filing a bug, please include a **minimal reproducible example**, the
+expected vs. actual behaviour, and your `jax` / `jaxlib` versions
+(`uv run python -c "import jax; print(jax.__version__)"`).
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

qjax-0.1.0/LICENSE

@@ -0,0 +1,11 @@
+MIT License
+
+Copyright (c) 2026 Kleyton da Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

qjax-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: qjax
+Version: 0.1.0
+Summary: Tsallis statistics for artificial intelligence, built on JAX.
+Author-email: Kleyton Costa <kleyton.costa@holisticai.com>
+License: MIT
+License-File: LICENSE
+Keywords: entropy,jax,machine-learning,statistics,tsallis
+Requires-Python: >=3.10
+Requires-Dist: jax>=0.4.30
+Requires-Dist: matplotlib>=3.8
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.1; extra == 'docs'
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/logo_qjax.svg" alt="qjax logo" width="340"/>
+
+# qjax
+
+**Tsallis statistics for artificial intelligence, built on [JAX](https://github.com/jax-ml/jax).**
+
+[![PyPI](https://img.shields.io/pypi/v/qjax.svg)](https://pypi.org/project/qjax/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-22863a.svg)](LICENSE)
+[![Built on JAX](https://img.shields.io/badge/built%20on-JAX-b73779.svg)](https://github.com/jax-ml/jax)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg)](https://github.com/astral-sh/ruff)
+
+[Quickstart](#quickstart) • [Building blocks](#building-blocks) • [Example](#label-noise-robustness) • [Installation](#installation)
+
+</div>
+
+## What is qjax?
+
+Tsallis (non-extensive) statistics generalizes Boltzmann–Gibbs–Shannon statistics through a single *entropic index* $q$. As $q \to 1$ every construction collapses back to its classical counterpart — Shannon entropy, the Gaussian, softmax, the Kullback–Leibler divergence — while $q \neq 1$ opens up heavy tails, sparse attention, and tunable exploration.
+
+`qjax` exposes these $q$-deformed primitives as **pure, differentiable, `jit`/`vmap`-friendly** JAX functions. Because $q$ is just another argument, you can hold it fixed *or* **learn it end-to-end by gradient descent**.
+
+Every primitive is a single closed form in the entropic index $q$, and each recovers its Boltzmann–Gibbs–Shannon counterpart in the $q \to 1$ limit:
+
+| `qjax` | Definition | Limit $q \to 1$ |
+| --- | --- | --- |
+| `q_log` | $\ln_q x = \dfrac{x^{1-q} - 1}{1 - q}$ | $\ln x$ |
+| `q_exp` | $\exp_q x = \big[1 + (1-q)\,x\big]_+^{\frac{1}{1-q}}$ | $e^{x}$ |
+| `tsallis_entropy` | $S_q(p) = \dfrac{1 - \sum_i p_i^{\,q}}{q - 1}$ | $-\sum_i p_i \ln p_i$ |
+| `tsallis_cross_entropy` | $H_q(y, p) = -\sum_i y_i \ln_q p_i$ | $-\sum_i y_i \ln p_i$ |
+| `tsallis_divergence` | $D_q(p \,\Vert\, r) = \dfrac{\sum_i p_i^{\,q}\, r_i^{\,1-q} - 1}{q - 1}$ | $\mathrm{KL}(p \,\Vert\, r)$ |
+| `q_gaussian_pdf` | $\mathcal{G}_q(x) = \dfrac{\sqrt{\beta}}{C_q}\,\exp_q(-\beta x^2)$ | $\sqrt{\tfrac{\beta}{\pi}}\,e^{-\beta x^2}$ |
+| `tsallis_entmax` | $entmax_q(z) = \arg\max_{p \in \Delta}\,\langle p, z\rangle + S_q(p)$ | $softmax(z)$ |
+
+where $[\,\cdot\,]_+ = \max(\cdot, 0)$ is the Tsallis cut-off, $C_q$ the $q$-Gaussian normalization, and $\Delta$ the probability simplex
+(`tsallis_entmax` is exactly **sparsemax** at $q = 2$).
+
+> `qjax` is a research library. The numerics are tested across the $q \to 1$
+> limit, gradients, and `jit`/`vmap`, but the API may still evolve.
+
+## Contents
+
+- [Quickstart](#quickstart)
+- [Building blocks](#building-blocks)
+- [A learnable `q`](#a-learnable-q)
+- [Label-noise robustness](#label-noise-robustness)
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Citing](#citing)
+- [License](#license)
+
+## Quickstart
+
+```python
+import jax, jax.numpy as jnp
+import qjax
+
+# q-deformed functions (recover log / exp as q -> 1)
+qjax.q_log(2.0, q=1.5)
+qjax.q_exp(1.0, q=1.5)
+
+# Tsallis information measures
+p = jnp.array([0.5, 0.3, 0.2])
+qjax.tsallis_entropy(p, q=2.0)         # -> Shannon entropy as q -> 1
+qjax.tsallis_divergence(p, p, q=2.0)   # -> KL divergence as q -> 1
+
+# q-Gaussian distribution (heavy-tailed for 1 < q < 3)
+x = jnp.linspace(-4, 4, 100)
+qjax.q_gaussian_pdf(x, q=1.5, beta=1.0)
+samples = qjax.sample(jax.random.PRNGKey(0), q=1.5, beta=1.0, shape=(1000,))
+
+# Sparse softmax: q=1 -> softmax, q=2 -> sparsemax (exact zeros)
+qjax.tsallis_entmax(jnp.array([2.0, 1.0, -1.0]), q=2.0)
+```
+
+## Building blocks
+
+`qjax` is organized as a small set of composable, fully differentiable primitives. Each is a pure function of $(x, q)$.
+
+### Deformed functions and $q$-algebra
+
+`q_log` and `q_exp` are inverse deformations of `log`/`exp`; the accompanying $q$-algebra turns them into homomorphisms (`q_log(a·b) = q_add(q_log a, q_log b)`).
+
+```python
+qjax.q_log(x, q=1.5)                                   # (x**(1-q) - 1) / (1-q)
+qjax.q_add(qjax.q_log(2.0, 1.4), qjax.q_log(3.0, 1.4), 1.4)   # == q_log(6.0, 1.4)
+```
+
+### Information measures
+
+```python
+p = jnp.array([0.5, 0.3, 0.2])
+r = jnp.array([0.25, 0.25, 0.5])
+
+qjax.tsallis_entropy(p, q=2.0)           # -> Shannon entropy as q -> 1
+qjax.tsallis_cross_entropy(p, r, q=2.0)  # q-deformed cross-entropy loss
+qjax.tsallis_divergence(p, r, q=2.0)     # -> KL(p || r) as q -> 1
+```
+
+### The $q$-Gaussian
+
+A maximum-Tsallis-entropy distribution: heavy-tailed (Student-$t$) for $1 < q < 3$, compactly supported for $q < 1$, Gaussian at $q = 1$.
+
+```python
+x = jnp.linspace(-4, 4, 100)
+qjax.q_gaussian_pdf(x, q=1.5, beta=1.0)
+qjax.q_gaussian_logpdf(x, q=1.5, beta=1.0)
+qjax.sample(jax.random.PRNGKey(0), q=1.5, beta=1.0, shape=(1000,))
+```
+
+### Sparse activations
+
+`tsallis_entmax` interpolates between dense softmax ($q = 1$) and sparsemax
+($q = 2$), producing exact zeros for $q > 1$ — a drop-in for sparse attention.
+
+```python
+z = jnp.array([2.0, 1.0, 0.1, -1.0])
+qjax.tsallis_entmax(z, q=1.0)   # softmax (dense)
+qjax.tsallis_entmax(z, q=2.0)   # sparsemax (exact zeros)
+```
+
+## A learnable $q$
+
+Because $q$ is an ordinary differentiable argument, it is finite everywhere — including the $q = 1$ limit — so it can be optimized like any other parameter:
+
+```python
+import jax
+
+x = jnp.linspace(-3, 3, 200)
+nll = lambda q: -jnp.mean(qjax.q_gaussian_logpdf(x, q, 1.0))
+grad_q = jax.grad(nll)(1.5)     # well-defined gradient w.r.t. the entropic index
+```
+
+This is what makes $q$ more than a hyperparameter: the right amount of non-extensivity can be *discovered* from data.
+
+## Label-noise robustness
+
+When training labels are noisy, ordinary softmax **cross-entropy** is unbounded — a confidently mislabeled example incurs an arbitrarily large loss, so an over-parameterized network ends up *memorizing* the noise. Replacing the logarithm with the deformed $q$-logarithm gives the **Tsallis cross-entropy**, which is *bounded* for $q < 1$: its gradient saturates on unfittable points, so the model ignores label noise instead of fitting it.
+
+For a one-hot target with true class $c$ and softmax probabilities $p$,
+
+$$\mathcal{L}_q(p, c) = -\ln_q p_c = \frac{1 - p_c^{\,1-q}}{1 - q}, \qquad \ln_q x = \frac{x^{1-q} - 1}{1 - q}.$$
+
+As $q \to 1$ this is exactly the standard cross-entropy $-\log p_c$; for $q < 1$ the per-example loss is bounded above by $1/(1-q)$, so mislabeled points cannot dominate the gradient.
+
+The figure trains a small 3-class classifier on two shapes (blobs, spiral) from clean data up to 40% label noise, comparing the Boltzmann–Gibbs–Shannon baseline ($q = 1$) with Tsallis ($q = 0.3$). The comparison is fair — both share the same initialization, data, noisy labels and optimizer; only $q$ differs. Without noise the two match (≈98–99%); as noise grows the baseline carves spurious wrong-class islands while Tsallis keeps clean regions and higher accuracy.
+
+<img src="docs/_static/examples/classification_boundaries.png" alt="Decision boundaries for blobs and spiral across noise levels: Tsallis vs the Boltzmann-Gibbs-Shannon baseline" width="960"/>
+
+See the [classification example](docs/examples/classification.md) for the full setup.
+
+## Installation
+
+`qjax` requires Python 3.10+ and depends only on `jax` and `matplotlib`. It is managed with [uv](https://docs.astral.sh/uv/).
+
+| Use case            | Command                                              |
+| ------------------- | ---------------------------------------------------- |
+| As a dependency     | `uv add qjax`                                        |
+| Development         | `uv sync --extra dev`    (tests + linter)            |
+| Building the docs   | `uv sync --extra docs`   (Sphinx + Furo)             |
+
+For GPU/TPU acceleration, install the matching JAX build by following the [JAX installation guide](https://docs.jax.dev/en/latest/installation.html).
+
+## Contributing
+
+Contributions are welcome — new $q$-deformed primitives, examples, docs, and fixes. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, design principles (purity, the $q \to 1$ limit, finite gradients), and the checks CI runs.
+
+## License
+
+Released under the [MIT License](LICENSE).