axiom-t2 0.1.3

Geometry-aware ML toolkit for toroidal manifolds

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

pip install axiom-t2

Quick Start

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:

# 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()

Standalone Packages

Each of the primary geometry-aware algorithms in axiom-t2 can also be installed independently for minimal-dependency deployments:

pip install geokde-t2
pip install geoknn-t2
pip install geodbscan-t2
pip install geoscanner-t2

These standalone packages provide the exact same mathematical properties and use standard imports (e.g., from geokde import GeoKDE).

License

This project is licensed under the Apache License Version 2.0.