--- language: en license: cc-by-nc-nd-4.0 library_name: gfn pipeline_tag: tabular-classification tags: - gfn - physics-informed - geometric-deep-learning - g-ssm - parity - xor model-index: - name: gfn-gssm-xor-parity results: - task: type: tabular-classification name: XOR Parity dataset: name: synthetic-bitstreams type: synthetic metrics: - name: Accuracy type: accuracy value: 100.0 --- # G-SSM XOR Parity Solver (Official Checkpoint) [![DOI: 10.5281/zenodo.19141133](https://img.shields.io/badge/DOI-10.5281/zenodo.19141133-blue.svg)](https://doi.org/10.5281/zenodo.19141133) [![Models: Hugging Face](https://img.shields.io/badge/Models-Hugging%20Face-orange.svg)](https://huggingface.co/DepthMuun) [![GitHub: GFN Framework](https://img.shields.io/badge/GitHub-GFN--Framework-black.svg?logo=github)](https://github.com/DepthMuun/gfn) This repository contains the weights and configuration for the **Geodesic State Space Model (G-SSM)** specialized for XOR parity logic over arbitrary sequence lengths. ## Highlights - **Architecture**: Geodesic State Space Model (G-SSM). - **Parameters**: **3,164** (PyTorch verified). - **Inductive Bias**: Compact 1-torus ($S^1$) manifold embedding. - **Memory Scaling**: Constant O(1) VRAM regardless of sequence length. - **Time Scaling**: Linear O(L) total, constant O(1) per-token step. - **Length Generalization**: Exact generalization to long bitstreams (1M+ bits) via symplectic phase integration. ## Inductive Bias and Physical Mechanism XOR parity over long bitstreams is an inherently periodic problem characterized by the discrete cyclic group $\mathbb{Z}_2 = \{0, 1\}$. Standard Euclidean architectures (RNNs, LSTMs, Transformers) struggle with length generalization on this task due to numerical floating-point drift, vanishing gradients, or attention context degradation. G-SSM solves this by embedding the latent state into a compact circular manifold ($S^1$ / 1-torus): 1. **Phase Rotation**: Trained via gradient descent, the model learns physical parameters such that each input bit `1` imparts a geodesic impulse corresponding to a rotation of $\pi$ radians ($180^\circ$), while bit `0` imparts zero impulse. 2. **Dynamical Flip-Flop**: Two consecutive `1` bits rotate the state by $2\pi \equiv 0 \pmod{2\pi}$, returning to the initial parity state. Symplectic integration (Yoshida) preserves phase coherence indefinitely. 3. **Geometric Decoding**: State $+\pi/2$ encodes parity 1, while state $-\pi/2$ (or $3\pi/2$) encodes parity 0. Decoding is performed by computing the geodesic distance on $S^1 \pmod{2\pi}$ rather than Euclidean softmax classification. ## Technical Usage (Inference) To run inference locally, install the **GFN Framework**. ### 1. Install GFN Framework ```bash pip install gfn ``` ### 2. Clone this repository ```bash git lfs install git clone https://huggingface.co/DepthMuun/gfn-gssm-xor-parity cd gfn-gssm-xor-parity ``` ### 3. Run Inference Script Use the included `inference.py` script for an interactive test: ```bash python inference.py ``` ### Python API Example ```python import math import torch from gfn import gssm device = torch.device("cuda" if torch.cuda.is_available() else "cpu") # 1. Load model (resolves config.json in the same directory) model = gssm.load("xor_best_model.bin", device=device) model.eval() # 2. Generate test sequence (e.g., 100,000 bits) L = 100000 bits = torch.randint(0, 2, (1, L), device=device) target_parity = (bits.sum() % 2).item() # 3. Forward Pass with torch.no_grad(): # G-SSM forward returns (logits, (pos, vel), info) logits, (pos, vel), info = model(bits) # 4. Geometric Decoding on S^1 PI = math.pi TWO_PI = 2.0 * PI half_pi = PI * 0.5 final_state = logits[0, -1, :] # State coordinates at final step # Circular distance modulo 2*pi to +PI/2 (Parity 1) dist_pos = torch.min( torch.abs(final_state - half_pi) % TWO_PI, TWO_PI - (torch.abs(final_state - half_pi) % TWO_PI) ).mean().item() # Circular distance modulo 2*pi to -PI/2 (Parity 0) dist_neg = torch.min( torch.abs(final_state + half_pi) % TWO_PI, TWO_PI - (torch.abs(final_state + half_pi) % TWO_PI) ).mean().item() prediction = 1 if dist_pos < dist_neg else 0 print(f"Target Parity: {target_parity}") print(f"Predicted : {prediction}") print(f"Geom. Dist : +PI/2: {dist_pos:.4f}, -PI/2: {dist_neg:.4f}") print("Status :", "CORRECT" if prediction == target_parity else "FAILED") ``` #### Manual Assembly Fallback (Optional) If loading raw checkpoints or customized configurations without `gssm.load`: ```python import json import torch from gfn import gssm with open("config.json", "r") as f: config = json.load(f) model = gssm.create(config=config).to(device) checkpoint = torch.load("xor_best_model.bin", map_location=device) state_dict = checkpoint.get("state_dict") or checkpoint.get("model") or checkpoint model_state = model.state_dict() filtered_state = {k: v for k, v in state_dict.items() if k in model_state} model.load_state_dict(filtered_state, strict=False) model.eval() ``` ## Citation If you use this work, please cite: ```latex @article{sturtz2026gfn, title={Geometric Flow Networks: A Physics-Informed Paradigm for Sequential Intelligence}, author={Stürtz, Joaquín}, journal={Zenodo Preprints}, year={2026}, doi={10.5281/zenodo.19141133}, url={https://doi.org/10.5281/zenodo.19141132} } ``` ## Resources - **Interactive Demo**: [Hugging Face Space](https://huggingface.co/spaces/DepthMuun/g-ssm-xor) - **Framework Source**: [GitHub: DepthMuun/gfn](https://github.com/DepthMuun/gfn) - **Official Paper**: [Zenodo](https://doi.org/10.5281/zenodo.19141133)