Metadata-Version: 2.4
Name: hermite-algebra
Version: 0.1.0
Summary: Hermite tensor algebra (SymPy-based) for kinetic theory
Project-URL: Homepage, https://github.com/wme7/hermite-algebra
Project-URL: Repository, https://github.com/wme7/hermite-algebra
Project-URL: Issues, https://github.com/wme7/hermite-algebra/issues
Author: Manuel A. Diaz
License: MIT
License-File: LICENSE
Keywords: hermite,kinetic-theory,sympy,tensors
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Requires-Dist: sympy>=1.14.0
Description-Content-Type: text/markdown

# hermite-algebra

[![CI](https://github.com/wme7/hermite-algebra/actions/workflows/ci.yml/badge.svg)](https://github.com/wme7/hermite-algebra/actions/workflows/ci.yml)
[![Publish](https://github.com/wme7/hermite-algebra/actions/workflows/publish.yml/badge.svg)](https://github.com/wme7/hermite-algebra/actions/workflows/publish.yml)
[![PyPI](https://img.shields.io/pypi/v/hermite-algebra)](https://pypi.org/project/hermite-algebra/)

SymPy-based **Hermite tensor algebra** for kinetic theory.

Rather than treating Hermite polynomials as fixed formulas, this package treats
multidimensional Hermite tensors as basis elements of a polynomial space that
you generate, project onto, and take moments of symbolically. That makes Grad-
and Shakhov-style expansions mechanical instead of algebraic busywork.

Collision models (BGK, ES-BGK, Shakhov, semiclassical Bose/Fermi) live in the
related package **hermite-kinetics**.

## What you can do

- Generate Grad Hermite tensors recursively with `hermite(n)`
- Evaluate Gaussian moments via Wick’s theorem with `moment` / `inner` (no symbolic integration)
- Project velocity polynomials onto the Hermite basis with `project` and `PolynomialSpace.decompose`
- Work in arbitrary velocity dimension with `VelocitySpace(d)`
- Use the results as building blocks for Grad / Shakhov expansions (in `hermite-kinetics`)

## Quick examples

### Symbolic Hermite tensors

Generate $H^{(n)}$ recursively and print the symbolic expressions:

```python
from hermite_algebra import hermite
import sympy as sp

for n in range(3):
    print(f"H^({n}) =")
    sp.pprint(hermite(n))
    print()
```
```txt
H^(0) =
1

H^(1) =
[ξ₀  ξ₁  ξ₂]

H^(2) =
⎡  2                      ⎤
⎢ξ₀  - 1   ξ₀⋅ξ₁    ξ₀⋅ξ₂ ⎥
⎢                         ⎥
⎢           2             ⎥
⎢ ξ₀⋅ξ₁   ξ₁  - 1   ξ₁⋅ξ₂ ⎥
⎢                         ⎥
⎢                    2    ⎥
⎣ ξ₀⋅ξ₂    ξ₁⋅ξ₂   ξ₂  - 1⎦
```
Alternative for single component:
```python
H2 = hermite(2)
sp.pprint(H2[0, 0])
```
```txt
ξ₀² - 1
```

### Contracted third-order Hermite tensor

In three dimensions, the contracted $H^{(3)}$ is $\xi_i(\xi^2 - 5)$:

```python
from hermite_algebra import vector_part, xi, xi2
import sympy as sp

H3c = vector_part(3)
assert all(sp.simplify(H3c[i] - xi[i] * (xi2 - 5)) == 0 for i in range(3))
```

### Orthogonality under the Gaussian weight

```python
from hermite_algebra import hermite, inner

H1, H2, H3 = hermite(1), hermite(2), hermite(3)
inner(H2, H1)  # 0
inner(H3, H2)  # 0
```

### Projection used in kinetic derivations

The identity $\xi_i\xi^2 = H_i^{(3)} + 5 H_i^{(1)}$ falls out of orthogonal projection:

```python
from hermite_algebra import xi, xi2, project, format_projection, PolynomialSpace

format_projection(project(xi * xi2))  # "H3 + 5 H1"
PolynomialSpace().decompose(xi[0] * xi2)  # same decomposition, component-wise API
```

### Dimension-generic velocity space

```python
from hermite_algebra import VelocitySpace

V = VelocitySpace(2)
V.project_xi_cubic()  # ξ_i ξ² = H³_i + (d+2) ξ_i  with d = 2
```

See [`examples/verify_classical.py`](examples/verify_classical.py) for a runnable smoke check.

## Installation

Requires **Python ≥ 3.11**.

### Users (PyPI)

```bash
pip install hermite-algebra
# or
uv add hermite-algebra
```

```python
from hermite_algebra import VelocitySpace, hermite, project, inner
```

### Developers (uv, from source)

```bash
git clone https://github.com/wme7/hermite-algebra.git
cd hermite-algebra
uv sync --group dev
uv run pre-commit install
uv run pytest
uv run python examples/verify_classical.py
```

For an editable install into another environment:

```bash
uv pip install -e .
```

### CI and releases

Pull requests and pushes to `main` run lint (ruff, ty) and tests on Python 3.11–3.14.

To publish a new version to PyPI:

1. Bump `project.version` in `pyproject.toml` (e.g. `0.1.0`).
2. Commit, tag `v0.1.0` (tag should match the version), and create a GitHub Release.
3. The `publish.yml` workflow builds the package and uploads it via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC; no API token in secrets).

One-time setup before the first release:

1. On [PyPI](https://pypi.org), create/claim the project `hermite-algebra` and add a Trusted Publisher:
   - Owner: `wme7`
   - Repository: `hermite-algebra`
   - Workflow: `publish.yml`
   - Environment: `pypi`
2. In the GitHub repo, create an Environment named `pypi` (optional: require reviewers).

## Package layout

```
src/hermite_algebra/
├── symbols.py      # global d=3 velocity symbols (ξ, δ, ξ²)
├── tensors.py      # outer, contract, symmetrize, …
├── hermite.py      # recursive Hermite tensors
├── gaussian.py     # Wick theorem
├── moments.py      # moment / inner / norm
├── project.py      # project onto Hermite basis
├── space.py        # PolynomialSpace
└── velocity.py     # dimension-generic VelocitySpace
```

## License

MIT
