Metadata-Version: 2.4
Name: axiom-t2
Version: 0.1.1
Summary: Geometry-aware ML toolkit for toroidal manifolds
Author-email: Liviu Ioan Cadar <lee@axiom-corp.com>
License: Apache-2.0
Project-URL: Homepage, https://axiom-corp.com
Project-URL: Repository, https://github.com/axiom-corp-ltd/axiom-t2
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-learn
Dynamic: license-file

# axiom-t2

**Geometry-aware ML toolkit for toroidal manifolds**

Standard spatial machine learning algorithms (like KDE, DBSCAN, and LOF) assume a flat Euclidean metric. When applied to cyclic dimensions like Earth's surface (longitude/latitude), standard tools suffer from boundary artefacts (e.g., Dateline tearing) and phase-compression distortions.

`axiom-t2` replaces standard Euclidean metrics with exact continuous Toroidal geodesics incorporating continuous Gaussian curvature penalisation.

## Installation

```bash
pip install axiom-t2
```

## Quick Start

```python
import numpy as np
from axiom.manifold.torus import TorusManifold
from axiom.geodbscan.dbscan import GeoDBSCAN

# Initialise dataset (u: longitude radians, v: latitude radians)
X = np.array([
    [3.14, 0.5], 
    [-3.14, 0.5], # Across the dateline!
    [1.57, -0.2]
])

# Standard DBSCAN splits the first two points.
# GeoDBSCAN connects them across the periodic boundary seamlessly.
model = GeoDBSCAN(eps=0.25, min_pts=2)
model.fit(X)

print(model.labels_)
# Output: [0, 0, -1]
```

## Tools & Algorithms

| Tool | Euclidean Artefact Fixed | Key Result (Validation on Tectonic Earthquakes) |
|---|---|---|
| **GeoKDE** | Dateline splits & Polar volume compression | Solves density underestimation near the dateline and $K=0$ bands. Log-likelihood significantly improved over Euclidean KDE. |
| **GeoDBSCAN** | Geographic cluster fracturing | Accurately spans Pacific tectonic plates across longitude $\pm 180^\circ$ without splitting. |
| **GeoKNN** | Nearest-neighbour distortions | Provides highly accurate true geographic neighbours across periodic boundaries. |
| **GeoScanner** | Coordinate volume artefacts | Implements MLE surface-area boundary detection over the poloidal dimensions. |

*(Note: GeoLOF was theoretically evaluated, but experiments showed LOF's inherent density-ratio mathematics are inherently resistant to Cartesian slice artefacts, yielding equivalent performance to Flat LOF).*

## Domain Presets

The toolkit includes presets tailored for specific topological applications:

```python
# Earth Geography (Standard R=3, r=1 proportion)
manifold = TorusManifold.geographic()

# Financial Market Cycles (R=10, r=1)
manifold = TorusManifold.financial()

# Protein Folding Topology (R=1, r=0.5)
manifold = TorusManifold.protein()
```

## License

This project is licensed under the Apache License Version 2.0.
