Metadata-Version: 2.4
Name: alienx-labs
Version: 1.0.0
Summary: AlienX (Isomorphic Spatial Net): rotation/scale-equivariant neural operators for Darcy flow, Gross-Pitaevskii, and 3D Navier-Stokes, with pretrained weights bundled and a one-call model zoo.
Author: Eric Yaka
License: AGPL-3.0
Project-URL: Homepage, https://huggingface.co/ElBalor/AlienX-2D-Isotropic-Stencil
Project-URL: 2D-Model, https://huggingface.co/ElBalor/AlienX-2D-Isotropic-Stencil
Project-URL: 3D-Model, https://huggingface.co/ElBalor/AlienX-3D-ISN-Operator
Keywords: neural-operator,equivariance,pde,navier-stokes,darcy,gross-pitaevskii,turbulence,so3,so2,rotation-invariance,physics,zero-shot
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: torch>=2.0
Dynamic: license-file

# AlienX Labs — `pip install alienx-labs`

**Isomorphic Spatial Net (ISN): neural operators that operate on continuous
geometric manifolds instead of fixed grids** — native rotation and scale
invariance, zero-shot across resolutions and Reynolds numbers.

> The grid is dead. The manifold is awake.

Three pretrained operators, weights bundled in the wheel (no downloads,
no setup — install and call):

| Model | Physics | Parameters | Party trick |
|---|---|---|---|
| `load_darcy2d()` | Darcy flow (2D pressure solve) | 415,509 | rotate the field to **any angle** — bitwise-flat error; same weights from 16² to 128²+ nodes |
| `load_gp2d()` | Gross–Pitaevskii (quantum superfluid) | 415,634 | cross-PDE transfer: trained on Darcy, walked onto a different equation |
| `load_turb3d()` | 3D Navier–Stokes (Taylor–Green vortex) | 421,507 | zero-shot Reynolds numbers; divergence-free **by construction** (Biot–Savart) |

## Install

```bash
pip install alienx-labs
```

## 60-second tour

```python
import torch, alienx_labs as ax

dev = "cuda" if torch.cuda.is_available() else "cpu"

# ── 1. Darcy flow: rotate the world, the operator does not notice ─────────
model = ax.load_darcy2d().to(dev)
sample = ax.data2d.generate_darcy_sample_gpu(64, dev, angle_deg=37.0, seed=7)
coords, k, gkm, gkv, p_true = sample
knn = ax.model2d.get_cached_iso_knn(64, dev)
p_pred = model(coords.unsqueeze(0), k.unsqueeze(0), gkv.unsqueeze(0),
               gkm.unsqueeze(0), knn).squeeze(0)
# p_pred is (64*64,) pressure — compare to p_true

# ── 2. Gross–Pitaevskii: complex wavefunction evolution ────────────────────
gp = ax.load_gp2d().to(dev)
psi0, psi_t = ax.gp2d.generate_gp_pair(64, dev, angle_deg=0.0, seed=1003)
d_r, d_i = gp(ax.gp2d.model_coords(64, dev).reshape(-1, 2),  # see docstring
              psi0.real.flatten().unsqueeze(0),
              psi0.imag.flatten().unsqueeze(0),
              ax.model2d.get_cached_iso_knn(64, dev), 64)
psi_pred = torch.complex(psi0.real.flatten() + d_r, psi0.imag.flatten() + d_i)

# ── 3. 3D turbulence: 32³ Taylor–Green, a Reynolds it never trained on ────
op3 = ax.load_turb3d().to(dev)      # trained on Re ∈ {300, 628, 1200}
print(op3.G)                        # 32 — pass Re it has NEVER seen
```

Full runnable scripts (Darcy sweep, GP rollout, 3D TGV rollout with the
spectral solver as ground truth) ship inside the package:
`python -m alienx_labs.examples` — or lift them from
[`examples/`](https://github.com/ElBalor/AlienX) in the repo.

## What makes it invariant (the architecture in one paragraph)

Each node lives on a spatial graph with an **isotropic 24-neighbor circular
stencil** (radius √8 — uniform angular coverage, no cardinal spikes). A
**local SO(2)/SO(3) frame** (gradient primary, inertia-tensor fallback with a
`sign_lock` that makes `eigh`'s arbitrary eigenvector sign deterministic and
equivariant) makes displacements rotation-equivariant. Edge features encode
the local angle as **even complex harmonics** (cos 2θ, sin 2θ, cos 4θ,
sin 4θ) — message weights invariant under θ → θ + π. A **constant physical
scale depth** makes the operator scale-blind by construction — exactly what
produces zero-shot resolution transfer. The 3D operator runs on the
**QSA block**: complex-valued (Hermitian-scored) attention whose phase channel
carries real predictive signal — ablate it (`sever_phase(True)`) and
zero-shot error grows 4.7×. No data augmentation. No learned geometry.

## Hand-verified numbers (rerun from the bundled checkpoints)

| Claim | Verified |
|---|---|
| D4 equivariance, 2D Darcy | **bitwise exact** (`pred(R·k) = R·pred(k)`) |
| 2D rotation sweep, interior L1 | flat across all angles (0.0052 @ every probe) |
| 2D zero-shot 64² | interior L1 = **0.0044** |
| 3D zero-shot Re=900 (never trained) | rel RMSE **~0.5%** single step; energy err **< 4.5%** |
| 3D divergence, every step | max \|∇·u\| ≈ **2e−6** (float32 round-off) |

## Gradio / Spaces

The labs are live (no install needed):
- **Sigil Lab 2D (Darcy):** https://huggingface.co/spaces/ElBalor/AlienX-Sigil-Lab-2D
- **GP Lab:** https://huggingface.co/spaces/ElBalor/AlienX-GP-Lab
- **Flow Lab 3D (Navier–Stokes):** https://huggingface.co/spaces/ElBalor/AlienX-Flow-Lab-3D

## Papers

- 2D (v3, with the Gross–Pitaevskii cross-PDE demonstration):
  [`ElBalor/AlienX-2D-Isotropic-Stencil`](https://huggingface.co/ElBalor/AlienX-2D-Isotropic-Stencil/blob/main/PAPER.md)
- 3D: [`ElBalor/AlienX-3D-ISN-Operator`](https://huggingface.co/ElBalor/AlienX-3D-ISN-Operator/blob/main/PAPER.md)

## Citation

```bibtex
@software{yaka2026alienx,
  author = {Yaka, Eric Heylel Danjuma},
  title  = {AlienX: Isomorphic Spatial Nets - Equivariant Neural Operators for Physical Fields},
  year   = {2026},
  url    = {https://huggingface.co/ElBalor/AlienX-2D-Isotropic-Stencil}
}
```

## License

AGPL-3.0 — see [LICENSE](LICENSE).

---
Eric Yaka (Elbàlor / The Digital Necromancer) · Capital Software · Abuja, Nigeria
