Metadata-Version: 2.4
Name: mlx-hyp2f1
Version: 0.1.0
Summary: GPU-accelerated hypergeometric functions (2F1, 1F1, 0F1) for Apple MLX
Author-email: Sheng-Kai Huang <akai@fawstudio.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/akaiHuang/mlx-hyp2f1
Project-URL: Issues, https://github.com/akaiHuang/mlx-hyp2f1/issues
Keywords: mlx,hypergeometric,gpu,special-functions,physics,cosmology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mlx>=0.4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: scipy>=1.10; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: scipy>=1.10; extra == "benchmark"
Requires-Dist: numpy>=1.24; extra == "benchmark"
Requires-Dist: matplotlib>=3.7; extra == "benchmark"
Dynamic: license-file

# mlx-hyp2f1

GPU-accelerated hypergeometric functions for Apple MLX.

JAX has `hyp2f1` but PyTorch, CuPy, and MLX do not. This package fills the gap for MLX, providing vectorized implementations that run on Apple Silicon GPU.

## Features

- **`hyp2f1(a, b, c, z)`** -- Gauss hypergeometric function 2F1
- **`hyp1f1(a, b, z)`** -- Confluent (Kummer) hypergeometric function 1F1
- **`hyp0f1(b, z)`** -- Bessel-related hypergeometric function 0F1
- Fully vectorized: compute over arrays of parameters simultaneously on GPU
- Numerically stable via log-gamma Pochhammer symbols
- Analytic continuation for |z| >= 1 using linear transformation formulas
- Pure MLX -- no SciPy runtime dependency

## Installation

```bash
pip install mlx-hyp2f1
```

Or from source:

```bash
git clone https://github.com/akaiHuang/mlx-hyp2f1.git
cd mlx-hyp2f1
pip install -e ".[dev]"
```

## Usage

```python
import mlx.core as mx
from mlx_hyp2f1 import hyp2f1, hyp1f1, hyp0f1

# Scalar
result = hyp2f1(0.5, 1.0, 1.5, 0.3)

# Vectorized over z
z = mx.linspace(0.0, 0.95, 100)
result = hyp2f1(0.5, 1.0, 1.5, z)

# Vectorized over all parameters
a = mx.array([0.5, 1.0, 2.0])
b = mx.array([1.0, 1.5, 0.5])
c = mx.array([1.5, 2.0, 3.0])
z = mx.array([0.3, 0.5, 0.8])
result = hyp2f1(a, b, c, z)

# Confluent hypergeometric (Kummer)
result = hyp1f1(1.0, 2.0, mx.linspace(-5.0, 5.0, 100))

# Bessel-related
result = hyp0f1(1.0, mx.linspace(-10.0, 10.0, 100))
```

### Cosmological growth factor D(a)

```python
import mlx.core as mx
from mlx_hyp2f1 import hyp2f1

def growth_factor(a, omega_m=0.3):
    """Linear growth factor D(a) for flat LCDM."""
    omega_l = 1.0 - omega_m
    x = -omega_l / omega_m * a**3
    return a * hyp2f1(1.0/3.0, 1.0, 11.0/6.0, x)
```

## Benchmark

```bash
python -m mlx_hyp2f1.benchmark
```

## Testing

```bash
pip install -e ".[dev]"
pytest
```

## Applications

- Cosmological growth factor D(a)
- Beta distribution CDF / PDF
- Angular momentum coupling coefficients
- Legendre / Jacobi / Gegenbauer polynomials
- Scattering amplitudes in quantum mechanics

## License

MIT -- Sheng-Kai Huang
