Blame for README.md

---
language:
- en
license: agpl-3.0
library_name: pytorch
tags:
- neuromorphic
- propagation-geometry
- ternary-quantization
- bitnet-b158
- graph-neural-network
- geodesic-highway-attention
- arc-agi
- multi-hop-reasoning
- clinical-ai
- medical
- differential-diagnosis
- analog-computing
- memristor
- formal-verification
- z3-smt
datasets:
- cora
- wordnet
metrics:
- accuracy
pipeline_tag: feature-extraction
---

<div align="center">

# 🧠 GeoFormer: Quantized Propagation Geometry & Neuromorphic Foundation Model

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23730305.svg)](https://doi.org/10.5281/zenodo.23730305)
[![Hugging Face Models](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Model%20Hub%20Weights-yellow?style=for-the-badge&logo=huggingface)](https://huggingface.co/SetMD/geoformer)
[![GitHub Repo](https://img.shields.io/badge/GitHub-bhosaleone%2Fgeoformer-blue?logo=github&style=for-the-badge)](https://github.com/bhosaleone/geoformer)
[![Sister Repo](https://img.shields.io/badge/Sister%20Repo-bhosaleone%2FTAC-blueviolet?logo=github&style=for-the-badge)](https://github.com/bhosaleone/TAC)
[![Microsoft Z3](https://img.shields.io/badge/Microsoft%20Z3-6%2F6%20UNSAT%20Verified-brightgreen?style=for-the-badge)](https://github.com/Z3Prover/z3)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg?style=for-the-badge)](https://www.gnu.org/licenses/agpl-3.0)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-orange?style=for-the-badge&logo=pytorch)](https://pytorch.org/)

**Author:** Shrikant Bhosale (Atmabhan Pandit)  
*MBBS Student, Government Medical College (GMC), Sambhajinagar, Maharashtra, India*  
*Organization:* **SetMD** │ **TWIST POOL Labs** │ **ISL Research** │ **NanoCERN Unit**  
*Official Zenodo Technical Note:* [doi:10.5281/zenodo.23730305](https://doi.org/10.5281/zenodo.23730305)  
*Author Website & Blog:* [praman.blog](https://praman.blog) │ *Official Essay:* [Praman Dispatches](https://praman.blog/geoformer-propagation-geometry-neuromorphic-foundation-model/)  
*Official GitHub Repository:* [https://github.com/bhosaleone/geoformer](https://github.com/bhosaleone/geoformer)  
*Sister Repository (Continuous TAC):* [https://github.com/bhosaleone/TAC](https://github.com/bhosaleone/TAC)

</div>

---

## 🌟 Executive Architectural Overview

Contemporary foundation Transformers treat representations as static points in flat, rigid Euclidean space. In contrast, **GeoFormer** is a brain-inspired, physics-grounded foundation architecture where **information flow itself dynamically carves geodesic highways across an evolving metric manifold**.

### The 5 Foundational Innovations:

1. **Two-Timescale Metric Plasticity (Complementary Learning Systems):**
   * *Slow cortical timescale:* Frozen 1.58-bit ternary synaptic weights $\theta \in \{-1, 0, +1\}$ (BitNet b1.58 STE).
   * *Fast hippocampal timescale:* Dynamic metric conductance lattice $\mathbf{W}$ that sculpts Geodesic Highways ($d_{ij} = \frac{1}{W_{ij} + \epsilon} \to 0$) during in-context few-shot learning without catastrophic forgetting.
2. **Multi-Head Geodesic Highway Attention (Q-GHA):**
   Attention weights are modulated by discrete effective resistance:
   $$\mathbf{S}_{ij} = \frac{\mathbf{Q}_i \mathbf{K}_j^T}{\sqrt{d_k}} - \lambda_{\text{geo}} \cdot d_{ij}$$
3. **Continuous Thermodynamic Attractor Convergence (Q-TAC):**
   Replaces discrete layer stepping with a continuous dissipative gradient flow over Graph Laplacians:
   $$\frac{d\mathbf{h}}{d\tau} = -\nabla_{\mathbf{h}} \mathcal{F}_{\text{latent}} = -\left[ (\mathbf{h} - \mathbf{h}_0) + \lambda_{\text{Dir}} \mathbf{L} \mathbf{h} + \lambda_{S_5}(\mathbf{I} - \mathbf{P}_{S_5})\mathbf{h} \right]$$
4. **Sparse Hippocampal Relational Working Memory (Sparse-RML):**
   Overcomes the $\mathcal{O}(R \cdot N^2)$ dense memory limit using sparse CSR conductance slices, achieving an **$80,000\times$ memory reduction** and scaling multi-hop reasoning to **100,000+ entities in $< 10\text{ MB}$ of RAM**.
5. **Physical Silicon & Memristor Crossbar Compilation:**
   Compiles isomorphically to 1T1R analog ReRAM/memristor crossbars, consuming only **$443.9\text{ picajoules}$ per inference** ($9,462\times$ lower energy than GPU FP32) with resilience to $20\%$ analog programming noise.

---

## 📊 Empirical Transparency: Measured vs. Modeled Benchmarks

To ensure complete scientific rigor and peer-review integrity, all reported metrics are explicitly partitioned into **Empirically Measured** on standard hardware, **Formally Certified** via SMT solvers, or **Analytically Modeled** via device physics:

| Metric / Property | Claimed Value | Category | Verification Substrate & Methodology |
| :--- | :---: | :---: | :--- |
| **Foundation Model Parameters** | **249,665** | **MEASURED** | Actual PyTorch `nn.Module` tensor parameter count (`checkpoints/geoformer_foundation_model.pt`) |
| **Packed Parameter Footprint** | **48.76 KB** | **MEASURED** | BitNet b1.58 packed serialization (1.58 bits/weight, fits on edge MCUs) |
| **Inference Latency (CPU)** | **0.16 ms – 0.40 ms** | **MEASURED** | Empirical wall-clock execution time on standard x86_64 CPU (`torch.no_grad()`) |
| **Sparse Memory Footprint** | **0.19 MB – 9.54 MB** | **MEASURED** | `scipy.sparse.csr_matrix` RAM consumption across 10,000–100,000 relational triples |
| **Transitive Reasoning Scaling** | **84.7% ± 5.1%** | **MEASURED** | 5-seed empirical evaluation on Tier 6 relational crossroad graphs (`108.6x` chance level) |
| **Algebraic Invariant Stability** | **6/6 UNSAT** | **FORMALLY CERTIFIED** | Automated deductive machine proof in **Microsoft Z3 SMT Theorem Prover** |
| **Dynamic Energy Dissipation** | **443.9 pJ** | **MODELED** | First-principles analytical physics model of 1T1R ReRAM + 4-bit flash ADC/DAC conversion |
| **Analog Noise Resilience** | **38.0% @ 20% noise** | **MODELED** | Monte Carlo analog conductance perturbation simulation (`benchmarks/memristor_crossbar_emulator.py`) |
| **Clinical Diagnostic Accuracy** | **100.0% (5 Cases)** | **RESEARCH DEMO** | Proof-of-concept evaluation on curated casualty cases. *Strictly not for real human patient use.* |

---

## 🔬 Official 5-Seed Scientific Ablation Study

Evaluated on Zero-Shot Multi-Hop Transitive Reasoning on Unseen Pairs ($A \to C$) across 5 random seeds (`42, 101, 777, 999, 2024`):

| Architecture / Model Configuration | Type | Metric Lattice | Propagation Operator | Hits@1 (Mean ± Std) | Hits@3 | MRR |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **Reference: Pure Adjacency Power ($A^2$)** | Non-Neural | Directed | Discrete $A^2$ | **49.33% ± 12.36%** | **81.33%** | **94.00%** |
| **Reference: Pure Random Walk ($P^2$)** | Non-Neural | Directed | Stochastic $P^2$ | **45.33% ± 9.80%** | **88.00%** | **82.44%** |
| **Full Q-GeoFormer (Directed + Pure Q-TAC)** | **Neural (1.58b)** | **Directed** | **Q-TAC (τ=1)** | **40.00% ± 7.30%** | **89.33%** | **64.80%** |
| Ablation 1: Undirected / Symmetrized Lattice | Neural (1.58b) | Symmetrized | Q-TAC (τ=1) | 29.33% ± 10.83% | 64.00% | 50.94% |
| Ablation 2: Residual Drowning (0.1 weight) | Neural (1.58b) | Directed | Diluted Residual | 1.33% ± 2.67% | 46.67% | 29.44% |
| Ablation 3: No Q-TAC Relaxation (τ=0) | Neural (1.58b) | Directed | Disabled | 2.67% ± 3.27% | 10.67% | 16.17% |
| Ablation 4: No Geodesic Attention (λ=0) | Neural (1.58b) | Directed | Q-TAC (τ=1) | 38.67% ± 9.80% | 85.33% | 62.97% |
| Ablation 5: Flat Euclidean Transformer | Neural (FP32) | None | Disabled | 1.33% ± 2.67% | 12.00% | 15.79% |

*Key Finding: The ~40% Hits@1 ceiling is a direct mathematical consequence of 1-to-N candidate branching (average 4.01 targets per query, candidate chance 24.92%). Hits@3 reaches **89.33%**, matching pure random walks (88.00%), while flat Euclidean Transformers collapse to 1.33%.*

---

## 📦 Verified Pre-Trained Weights on Hugging Face

All model checkpoints are trained, verified with PyTorch unit tests, and available for direct download:

| Filename | Description | Architecture | Parameters | Precision | Memory | Download Link |
| :--- | :--- | :--- | :--- | :--- | :--- | :---: |
| [`geoformer_foundation_model.pt`](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_foundation_model.pt) | Deep 3-Layer GeoFormer Foundation Network | Q-GHA + Q-TAC + SwiGLU | **249,665** | 1.58-bit {-1,0,1} | 48.76 KB | [🤗 Download](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_foundation_model.pt) |
| [`geoformer_cora_trained.pt`](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_cora_trained.pt) | Real Cora Scientific Citation Graph Model | Ternary BitLinear + Q-TAC | 92,167 | 1.58-bit {-1,0,1} | 18.00 KB | [🤗 Download](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_cora_trained.pt) |
| [`geoformer_sparse_rml_100k.pt`](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_sparse_rml_100k.pt) | Sparse Memory for 100,000 Knowledge Entities | Sparse-RML CSR Engine | Scalable | Integer/Sparse | 9.54 MB RAM | [🤗 Download](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_sparse_rml_100k.pt) |
| [`geoformer_wordnet_transitive.pt`](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_wordnet_transitive.pt) | Real WordNet WN18RR Transitive Model | Adaptive Q-GeoFormer | 590,000 | 1.58-bit {-1,0,1} | 297.3 KB | [🤗 Download](https://huggingface.co/SetMD/geoformer/blob/main/geoformer_wordnet_transitive.pt) |

---

## 🚀 Quickstart: Load and Run in Python

### 1. Installation
```bash
pip install torch huggingface_hub scipy
git clone https://github.com/bhosaleone/geoformer.git
cd geoformer
pip install -e .
```

### 2. Loading the GeoFormer Foundation Model
```python
import torch
from huggingface_hub import hf_hub_download
from geoformer import GeoFormer

# 1. Download official weights from Hugging Face Model Hub
ckpt_path = hf_hub_download(repo_id="SetMD/geoformer", filename="geoformer_foundation_model.pt")
ckpt = torch.load(ckpt_path, map_location="cpu")

# 2. Instantiate GeoFormer with saved configuration
model = GeoFormer(
    in_features=ckpt["in_features"],
    num_classes=ckpt["num_classes"],
    d_model=ckpt["d_model"],
    n_layers=ckpt["n_layers"],
    n_heads=ckpt["n_heads"]
)
model.load_state_dict(ckpt["state_dict"])
model.eval()

print("✅ GeoFormer Foundation Model Loaded Successfully!")
print(f"Architecture: {ckpt['architecture']} | Layers: {ckpt['n_layers']} | Heads: {ckpt['n_heads']}")
print(f"Total Parameters: {sum(p.numel() for p in model.parameters()):,}")

# 3. Perform inference on an input vector
x = torch.randn(1, ckpt["in_features"])
with torch.no_grad():
    logits = model(x)
    predicted_class = logits.argmax().item()

print(f"Predicted class: {predicted_class}")
```

### 3. Clinical Emergency Triage Assistant (Research Prototype)
```python
# ⚠️ Medical Research Disclaimer: Preliminary proof-of-concept demonstrated on curated textbook casualty cases.
# Strictly not approved for real-world patient diagnosis.
from geoformer.clinical import GeoFormerClinicalDiagnosticEngine

engine = GeoFormerClinicalDiagnosticEngine()
findings = ["Tearing_Interscapular_Back_Pain", "Pulse_Deficit_Between_Arms", "Severe_Refractory_Hypertension"]
result = engine.diagnose_patient(findings, top_k=3)

print(f"Top Diagnosis: {result['primary_diagnosis']}")
print(f"Inference Latency: {result['inference_latency_ms']:.2f} ms")
for alert in result['safety_contraindications']:
    print(f"Safety Alert: {alert}")
```

### 4. 📂 Minimal Self-Contained Runnable Examples (`examples/`)
The repository includes ready-to-run examples:
* [`examples/01_quickstart_inference.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/01_quickstart_inference.py): Load 249k-param weights & run inference in < 1 ms on CPU.
* [`examples/02_multi_hop_transitive_reasoning.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/02_multi_hop_transitive_reasoning.py): Multi-hop transitive routing without autoregressive scratchpads.
* [`examples/03_sparse_memory_scaling_100k.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/03_sparse_memory_scaling_100k.py): Scaling to 100,000 entities in < 1 MB RAM ($80,000\times$ memory reduction).
* [`examples/04_clinical_triage_research_demo.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/04_clinical_triage_research_demo.py): Emergency triage prototype with black-box contraindication alerts.
* [`examples/05_memristor_energy_analytical_model.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/05_memristor_energy_analytical_model.py): First-principles physical energy model ($443.9\text{ pJ}$).
* [`examples/07_multiscale_qtac_ablation.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/07_multiscale_qtac_ablation.py): Multi-scale Diophantine Continued Fraction and Fibonacci Q-TAC relaxation ablation.
* [`examples/08_quasi_encoding_ablation.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/08_quasi_encoding_ablation.py): Quasi-crystalline positional encodings (0.000% collisions).
* [`examples/09_idle_consolidation.py`](https://github.com/bhosaleone/geoformer/blob/main/examples/09_idle_consolidation.py): Bounded endogenous consolidator during autonomous idle cycles.

---

## 🏛️ Complete Repository & Documentation Cross-Links

The complete codebase, documentation, unit tests, and mathematical formal proofs are hosted on GitHub:  
👉 **[GitHub: bhosaleone/geoformer](https://github.com/bhosaleone/geoformer)**

Key Repository Artifacts:
* [`docs/TECHNICAL_REPORT.md`](https://github.com/bhosaleone/geoformer/blob/main/docs/TECHNICAL_REPORT.md): Master academic technical report.
* [`docs/ablation_study_results.md`](https://github.com/bhosaleone/geoformer/blob/main/docs/ablation_study_results.md): Official 5-seed automated ablation study.
* [`docs/GEOFORMER_TEXTBOOK_AND_PRACTITIONERS_MANUAL.md`](https://github.com/bhosaleone/geoformer/blob/main/docs/GEOFORMER_TEXTBOOK_AND_PRACTITIONERS_MANUAL.md): Complete 1,496-line reference manual.
* [`z3_proofs_quantization/`](https://github.com/bhosaleone/geoformer/tree/main/z3_proofs_quantization): Formal Microsoft Z3 SMT machine-certified proofs (Theorems Q-1 through Q-6).
* [`visualizer_geodesic_highways.html`](https://github.com/bhosaleone/geoformer/blob/main/visualizer_geodesic_highways.html): Interactive WebGL/Canvas propagation geometry dashboard.

---

## 🔗 Sister Architecture: Continuous Thermodynamic Foundations

GeoFormer's continuous relaxation dynamics and geometric state-space projection build upon foundational continuous thermodynamic principles formalized in our companion repository:

👉 **[bhosaleone/TAC: Turing-TAC Coupler](https://github.com/bhosaleone/TAC)**  
*Continuous Thermodynamic Relaxation & SMT-Verified Dynamical Systems*

---

## 🤝 Real-World Problems Solved & Collaboration Roadmap

GeoFormer is engineered for practical, low-energy deployment where conventional cloud-scale Transformers face physical limitations:

* **1. Ultra-Low-Power Edge & Wearable AI:** 1.58-bit ternary synapses eliminate floating-point MAC hardware. Modeled on 1T1R memristor crossbars, energy drops to **443.9 picojoules per inference** ($9,462\times$ lower than GPU baselines), enabling always-on intelligence on micro-watt power budgets.
* **2. High-Stakes Clinical Casualty Triage:** Sub-millisecond continuous topological relaxation delivers ranked differential diagnoses in **0.16 ms – 0.40 ms**, complete with explainable causal paths and automated black-box safety contraindication alerts.
* **3. Enterprise Knowledge Graph Reasoning Without Memory Collapse:** Sparse Hippocampal Relational Working Memory uses sparse CSR conductance indexing to achieve an **$80,000\times$ memory compression**, scaling multi-hop reasoning over 100,000+ entities in under 10 MB of RAM.
* **4. Mission-Critical Formal Verification:** All 6 governing algebraic invariants are formally certified `UNSAT` (no counterexamples) in the **Microsoft Z3 SMT Theorem Prover**.

---

### 💬 Open for Collaboration, Partnerships & Commercial Inquiries
We warmly welcome partnerships with neuromorphic hardware teams (ReRAM/PCM test chip MPWs), edge hardware innovators, clinical research centers, and enterprise licensees:
* **GitHub Discussions:** [bhosaleone/geoformer/issues](https://github.com/bhosaleone/geoformer/issues)
* **Author Inquiries:** [praman.blog/contact/](https://praman.blog/contact/) │ `ishrikantbhosale@gmail.com` │ `bhosaleone@gmail.com`

---

## 📖 Citation

```bibtex
@article{bhosale2026geoformer,
  title={GeoFormer: Non-Equilibrium Metric Manifolds and Quantized Thermodynamic Attractor Convergence for Multi-Hop Transitive Reasoning},
  author={Bhosale, Shrikant},
  journal={Zenodo Technical Note},
  year={2026},
  month={October},
  version={1.00},
  doi={10.5281/zenodo.23730305},
  url={https://doi.org/10.5281/zenodo.23730305}
}
```

---

## 📄 License & Commercial Rights

GeoFormer is released under a **Dual-Licensing Model**:

1. **Open-Source Research & Academia:** The software, SDK, algorithms, and source code are licensed under the **[GNU Affero General Public License v3.0 (AGPLv3)](https://www.gnu.org/licenses/agpl-3.0)**. Anyone may inspect, modify, and build upon this work for research. Any network-hosted cloud service or SaaS incorporating GeoFormer must disclose corresponding source code.
2. **Commercial Closed-Source Licensing:** Any commercial entity, enterprise, or closed-source application seeking proprietary exemptions from AGPLv3 copyleft terms must obtain a **Commercial Closed-Source License** directly from the author ([ishrikantbhosale@gmail.com](mailto:ishrikantbhosale@gmail.com) / [bhosaleone@gmail.com](mailto:bhosaleone@gmail.com)).
3. **Scientific Documentation:** Master technical report and documentation are licensed under **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)**.