Metadata-Version: 2.4
Name: irrepx
Version: 0.5.4
Summary: Minimal O(3) irreducible representations with optional JAX support. A lightweight, pure-Python replacement for the core of e3nn-jax.
Author-email: DeepH team <deeph-pack@outlook.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/kYangLi/irrepx
Project-URL: Documentation, https://github.com/kYangLi/irrepx#readme
Project-URL: Repository, https://github.com/kYangLi/irrepx.git
Project-URL: Issues, https://github.com/kYangLi/irrepx/issues
Keywords: irreps,irreducible representations,O(3),SO(3),e3nn,equivariance,JAX,symmetry,spherical harmonics,deep learning,neural networks,physics
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: click>=8.0
Provides-Extra: jax
Requires-Dist: jax>=0.9.2; extra == "jax"
Provides-Extra: jax-cpu
Requires-Dist: jax[cpu]>=0.9.2; extra == "jax-cpu"
Provides-Extra: jax-cuda12
Requires-Dist: jax[cuda12]>=0.9.2; extra == "jax-cuda12"
Provides-Extra: jax-cuda13
Requires-Dist: jax[cuda13]>=0.9.2; extra == "jax-cuda13"
Provides-Extra: jax-tpu
Requires-Dist: jax[tpu]>=0.9.2; extra == "jax-tpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: ruff>=0.1.0; extra == "test"
Requires-Dist: black>=23.0; extra == "test"
Requires-Dist: jax>=0.9.2; extra == "test"
Requires-Dist: e3nn-jax>=0.21.0; extra == "test"
Requires-Dist: e3nn>=0.5.0; extra == "test"
Dynamic: license-file

<h1 align="center">irrepx</h1>

<div align="center">

[![CI](https://github.com/kYangLi/irrepx/actions/workflows/ci.yaml/badge.svg)](https://github.com/kYangLi/irrepx/actions/workflows/ci.yaml)
[![PyPI Version](https://img.shields.io/pypi/v/irrepx.svg)](https://pypi.org/project/irrepx/)
[![Python Versions](https://img.shields.io/badge/python-3.12|3.13|3.14-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/pypi/l/irrepx.svg)](https://pypi.org/project/irrepx/)
[![GitHub Issues](https://img.shields.io/github/issues/kYangLi/irrepx.svg)](https://github.com/kYangLi/irrepx/issues)
[![GitHub Stars](https://img.shields.io/github/stars/kYangLi/irrepx.svg?style=social)](https://github.com/kYangLi/irrepx/stargazers)

*Minimal O(3) irreducible representations with optional JAX support.*

</div>

## Install

```bash
pip install irrepx               # Light mode: representation algebra only
pip install irrepx[jax]          # Full mode: JAX (any platform, pre-installed)
```

One-step install with the right JAX backend:

```bash
pip install irrepx[jax-cpu]      # CPU
pip install irrepx[jax-cuda12]   # CUDA 12
pip install irrepx[jax-cuda13]   # CUDA 13
pip install irrepx[jax-tpu]      # TPU
```

## Quick Start

```python
from irrepx import Irrep, Irreps

# Structural algebra (no JAX needed)
irreps = Irreps("32x0e + 16x1o + 8x2e")
assert irreps.dim == 32 + 48 + 40
assert Irrep("2e") in Irrep("1o") * Irrep("1o")
```

With JAX installed:

```python
import jax.numpy as jnp
from irrepx import IrrepsArray, spherical_harmonics

x = IrrepsArray("1o", jnp.array([[1.0, 0.0, 0.0]]))
sh = spherical_harmonics([0, 1, 2], x, normalize=True)
print(sh.irreps)  # 1x0e+1x1o+1x2e
```

## Wigner D from direction

Compute Wigner D matrices from edge direction vectors (Gram-Schmidt → Euler
angles → JD-seed formula).  Available in both numpy (light) and JAX (full) modes.

```python
import numpy as np
from irrepx import wigner_D_from_direction

edge = np.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])  # (E, 3) unit vectors
D = wigner_D_from_direction(edge, l_range=[0, 1, 2])
# D[l] is (E, 2l+1, 2l+1)
```

With JAX, the same call is JIT-compatible and operates on `jnp.ndarray`.

## Pre-computed constants

irrepx ships pre-computed Clebsch-Gordan coefficients, JD seed matrices,
and spherical Bessel roots as npz files.  These are loaded lazily on first access.
The loaders take no arguments and return the full shipped table; callers slice
or filter the subset they need.

```python
from irrepx import load_cg, load_jd, load_sb_roots

cg = load_cg()         # dict keyed by "l1=N,l2=M", shipped lmax=7 (+SOC rows)
jd = load_jd()         # list of (2l+1, 2l+1) matrices, shipped lmax=13
sb = load_sb_roots()   # list of 1-D root arrays, shipped lmax=13
```

Inspect the shipped capacity with `irrepx constants status`.  If your work
needs larger tables than shipped, rebuild them with the CLI:

```bash
irrepx constants status
irrepx constants update --cg-lmax 10 --jd-lmax 15 --sb-lmax 20
```

For per-triplet CG access (used internally by `spherical_harmonics` and
`tensor_product`), use the computational function:

```python
from irrepx import clebsch_gordan

cg = clebsch_gordan(1, 1, 2)   # returns dense (3, 3, 5) array
```

## License

GPL-3.0-or-later
