DepthMuun/gfn-gssm-xor-parity

G-SSM XOR Parity Solver (Official Checkpoint)

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

pip install gfn

2. Clone this repository

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:

python inference.py

Python API Example

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:

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:

@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
• Framework Source: GitHub: DepthMuun/gfn
• Official Paper: Zenodo