README.md

---
license: apache-2.0
tags:
  - flow-matching
  - diffusion
  - geometric-deep-learning
  - constellation
  - geolip
---

# Verdict based on Analysis
The geometric structure does contribute to the output, about 6-7%. It's essentially a small nudge improvement system.

As it stands, this system is TOPICAL at best, and it still helped. Just not enough.

This can be gradually or greatly improved with the correct steps, including expanded control, more encoding curation, and a full battery of analysis.

# Automodel Now Available


![image](https://cdn-uploads.huggingface.co/production/uploads/630cf55b15433862cfc9556f/92PPQUxtHkYnyNQgF9Wtm.png)


```
# ── Test AutoModel loading + generation ──
from transformers import AutoModel
from torchvision.utils import save_image, make_grid

model = AutoModel.from_pretrained(
    "AbstractPhil/geolip-diffusion-proto", trust_remote_code=True
).cuda()

print(f"Params: {sum(p.numel() for p in model.parameters()):,}")
print(f"Relay diagnostics: {model.get_relay_diagnostics()}")

# Generate per-class samples
class_names = ['plane','auto','bird','cat','deer','dog','frog','horse','ship','truck']
all_imgs = []
for c in range(10):
    imgs = model.sample(n_samples=4, class_label=c)
    all_imgs.append(imgs)

grid = make_grid(torch.cat(all_imgs), nrow=4)
save_image(grid, "automodel_test.png")
print("✓ Saved automodel_test.png — 4 per class, 10 classes")
```

# GeoLIP Diffusion Prototype

**Flow matching diffusion with constellation relay as geometric regulator.**

This is an experimental prototype exploring whether fixed geometric reference frames
(constellation anchors on the unit hypersphere) can regulate the internal geometry
of a diffusion model's denoising network during generation.

## Architecture

```
Flow Matching ODE:  x_t = (1-t)·x_0 + t·ε  →  predict v = ε - x_0
Sampler:            Euler integration, t=1→0, 50 steps

UNet:
  Encoder:  [64@32×32] → [128@16×16] → [256@8×8]
  Middle:   ConvBlock + ★ Constellation Relay ★
            Self-Attention (8×8 spatial)
            ConvBlock + ★ Constellation Relay ★
  Decoder:  [256@8×8] → [128@16×16] → [64@32×32]
  Output:   Conv → 3×32×32 velocity prediction
```

## Constellation Relay

The relay operates at the bottleneck (256 channels at 8×8 spatial resolution).
It works in **channel mode**:

1. Global average pool the spatial dims → (B, 256) channel vector
2. Chunk into 16 patches of d=16
3. L2-normalize each patch to S^15 (the natural CV=0.20 dimension)
4. Multi-phase triangulation: 3 phases × 16 anchors = 48 distances per patch
5. Patchwork MLP processes triangulation → correction vector
6. Gated residual (gate init ≈ 0.047) scales the feature map

**Key property:** the relay preserves 99.4% geometric fidelity through 16
stacked layers where vanilla attention preserves only 7.4%. It acts as a
geometric checkpoint that prevents representation drift at the normalized
manifold boundaries between network blocks.

## What This Tests

The hypothesis: diffusion models discover that noise is a deterministic
routing system (DDIM proved this — same seed always produces same image).
The constellation operates on the same principle — fixed geometric anchors
as a reference frame that noise/data routes through. By inserting the relay
at the bottleneck, we test whether explicit geometric regulation improves
or changes the flow matching dynamics.

## Empirical Findings (from this research session)

| Finding | Result |
|---|---|
| CV ≈ 0.20 is the natural pentachoron volume regularity of S^15 | Confirmed across all precisions, 1-bit to fp64 |
| Effective geometric dimension of trained models ≈ 16 | Confirmed across 17+ architectures |
| Relay preserves 99.4% cos_to_orig through 16 layers | vs 7.4% for attention alone |
| fp8 triangulation preserves geometry perfectly | CV identical to fp32 at d=16 |
| Noise transforms are classifiable as deterministic routing | 100% accuracy on 8/10 transform families |

## Parameters

- Total: ~6.1M
- Relay: ~76K (1.2% of total)
- 2 relay modules at the bottleneck

## Training

- Dataset: CIFAR-10 (50K images)
- Flow matching: conditional ODE with class labels
- Optimizer: AdamW, lr=3e-4, cosine schedule
- 50 epochs, batch size 128

## Files

- `flow_match_relay.py` — complete training script
- `checkpoints/flow_match_best.pt` — best checkpoint
- `samples/` — generated samples at various epochs

## Part of the GeoLIP Ecosystem

- [geolip-constellation-core](https://huggingface.co/AbstractPhil/geolip-constellation-core) — classification with constellation
- [glip-autoencoder](https://github.com/AbstractEyes/glip-autoencoder) — source repository