Metadata-Version: 2.4
Name: raglu
Version: 0.1.0
Summary: Pure Rational GLU (RaGLU) and RaLU activations for PyTorch, Triton CUDA and Apple MLX.
Author: Ömer Faruk Solmaz
License-Expression: MIT
Keywords: activation,glu,ralu,rational,pytorch,triton,mlx,deep-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Provides-Extra: triton
Requires-Dist: triton>=2.0.0; extra == "triton"
Provides-Extra: mlx
Requires-Dist: mlx>=0.1.0; extra == "mlx"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# RaGLU

**Pure Rational GLU (RaGLU)** ve **RaLU** aktivasyon fonksiyonları için platform
bağımsız PyTorch kütüphanesi. NVIDIA CUDA'da isteğe bağlı **Triton** çekirdekleri,
Apple Silicon'da ise yerel **MLX** desteği sunar.

Paket iki `nn.Module` sınıfı sunar:

| Sınıf | Görevi |
| --- | --- |
| `RaGLU()` | Kapılı (GLU) katman: `Linear` çıktısını gate/val olarak ikiye böler, `f(g) * v` uygular. |
| `RaLU()` | Kapısız, element-wise aktivasyon: `f(x)` uygular, şekli değiştirmez. |

## Fonksiyonlar

Kapılı (gated) varyant:

$$
\operatorname{RaGLU}(g, v) = \frac{g^3 + g}{g^2 + 3} \cdot v
$$

Kapısız varyant:

$$
\operatorname{RaLU}(x) = \frac{x^3 + x}{x^2 + 3}
$$

Türev (her iki varyantın çekirdeği):

$$
\frac{d}{dx}\left(\frac{x^3 + x}{x^2 + 3}\right)
= \frac{x^4 + 8x^2 + 3}{(x^2 + 3)^2}
$$

Fonksiyon tek (odd) bir fonksiyondur: `f(-x) = -f(x)`. Payda her zaman
`>= 3` olduğundan sayısal olarak kararlıdır.

## Kurulum

```bash
pip install raglu
```

İsteğe bağlı hızlandırıcılar:

```bash
pip install "raglu[triton]"   # NVIDIA CUDA için Triton çekirdekleri
pip install "raglu[mlx]"      # Apple Silicon için MLX
pip install "raglu[dev]"      # test + derleme araçları
```

## Kullanım

### Fonksiyonel PyTorch API

```python
import torch
from raglu import fused_pure_rational_glu, fused_pure_rational

gate = torch.randn(32, 128)
val = torch.randn(32, 128)

y = fused_pure_rational_glu(gate, val)  # (32, 128)
z = fused_pure_rational(gate)           # (32, 128)
```

`fused_pure_rational_glu`, CUDA + Triton mevcutsa füzyonlu çekirdeği kullanır.
Aksi halde otomatik olarak CPU/MPS uyumlu PyTorch fallback'ine döner.
Her iki yol da autograd desteklidir.

### Katmanlar

```python
import torch
from raglu import RaGLU, RaLU

# Girdiyi 2 * out_features boyutuna genişletip gate/val olarak böler.
layer = RaGLU(in_features=768, out_features=768)
x = torch.randn(8, 128, 768)
y = layer(x)  # (8, 128, 768)

# Kapısız aktivasyon
act = RaLU()
z = act(x)    # (8, 128, 768)
```

Hazır `gate` ve `val` modülleri de kullanılabilir:

```python
from torch import nn
from raglu import RaGLU

layer = RaGLU(
    gate=nn.Linear(768, 1024),
    val=nn.Linear(768, 1024),
)
```

### Apple MLX

```python
import mlx.core as mx
from raglu import mlx_pure_rational_glu, mlx_pure_rational

gate = mx.random.normal((32, 128))
val = mx.random.normal((32, 128))

y = mlx_pure_rational_glu(gate, val)
z = mlx_pure_rational(gate)
```

MLX kurulu değilse bu semboller dışa aktarılmaz; `raglu.HAS_MLX` ile kontrol
edebilirsiniz.

## API

| Sembol | Açıklama |
| --- | --- |
| `raglu.fused_pure_rational_glu(gate, val)` | Kapılı Pure Rational GLU (Triton/CUDA veya PyTorch fallback) |
| `raglu.fused_pure_rational(x)` | Kapısız RaLU aktivasyonu |
| `raglu.RaGLU` | Doğrusal katman + Pure Rational GLU `nn.Module`'ü |
| `raglu.RaLU` | Element-wise RaLU `nn.Module`'ü |
| `raglu.mlx_pure_rational_glu` | MLX kapılı varyant (MLX varsa) |
| `raglu.mlx_pure_rational` | MLX kapısız varyant (MLX varsa) |
| `raglu.HAS_TRITON` | Triton çekirdeklerinin kullanılabilirliği |
| `raglu.HAS_MLX` | MLX'in kullanılabilirliği |

### Not: CUDA clamp

Triton çekirdekleri sayısal kararlılık için kapı değerini `[-50, 50]` aralığına
kırpar. Bu aralığın dışındaki değerlerde Triton ve fallback çıktıları
farklılaşabilir; pratik aktivasyon girdilerinde fark yoktur.

## Geliştirme

```bash
git clone <repo-url>
cd RaGLU
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
```

Triton testleri yalnızca CUDA + Triton mevcut olduğunda, MLX testleri ise
yalnızca MLX kurulu olduğunda çalışır; diğer ortamlarda otomatik atlanır.

### Paket derleme

```bash
python -m build
python -m twine check dist/*
```

## Lisans

MIT — bkz. [LICENSE](LICENSE).

Copyright (c) 2026 Ömer Faruk Solmaz
