⚜️ Sovereign-Metal

A zero-dependency, high-throughput Python-to-Metal GPGPU advection engine and local transformer pipeline. Program custom MSL (Metal Shading Language) kernels directly from Python with zero-copy unified memory alignment and zero PCIe bus latency.

🔱 Core Features

• Zero-Copy Unified Memory: Directly maps NumPy arrays into shared CPU/GPU buffers (MTLResourceStorageModeShared), completely bypassing PCIe transfer bottlenecks.
• Branchless Toroidal Boundary Wrapping: Implements hardware-level bitwise wrapping (x - 1u) & (dim - 1u) inside MSL shaders, avoiding thread divergence and division stalls on integrated Apple/Intel GPUs.
• Zero-Latency Reduction Tree: Runs a dedicated Shannon entropy, localization intensity, and energy proxy reduction kernel entirely in threadgroup scratchpad memory.
• Standalone GPGPU Transformer: Runs FP16 BERT-style embeddings (all-MiniLM-L6-v2) locally on Metal with strict GPGPU acceleration.

📐 Mathematical Framework

Toroidal Fluid Dynamics (Soliton Advection)

The advection advects a continuous scalar field $S$ through a density field $\rho$ on a conjoined toroidal manifold:

$$\frac{\partial S}{\partial t} = -\nu \nabla^2 S - \alpha (\nabla \rho) \cdot \nabla S + \kappa |S|^2 S$$

Where:

• $\nu$ represents the dissipation/damping coefficient.
• $\alpha$ is the advection coupling strength.
• $\kappa$ is the non-linear soliton crystallization rate.

🚀 Quick Start

1. Installation

Clone the repository and install the dependencies:

cd sovereign-metal
pip install -e .

2. Run Semantic Embeddings Demo

Verify the local GPGPU transformer inference:

python examples/local_embeddings.py

3. Run Toroidal Advection Benchmark

Execute the soliton advection simulation and watch the real-time crystallization metrics stream from the GPU:

python examples/benchmark_advection.py

⚜️ License

MIT License. Crafted for the GPGPU developer community.