AbstractPhil / vit-beatrix

ViT-Beatrix: Fractal PE + Geometric Simplex Vision Transformer

This repository contains Vision Transformers integrating Devil's Staircase positional encoding with geometric simplex features for vision tasks.

Key Features

• Fractal Positional Encoding : Devil's Staircase multi-scale position embeddings
• Geometric Simplex Features : k-simplex vertex computations from Cantor measure
• SimplexFactory Initialization : Pre-initialized simplices with geometrically meaningful shapes (regular/random/uniform)
• Adaptive Augmentation : Progressive augmentation escalation to prevent overfitting
• Beatrix Formula Suite : Flow alignment, hierarchical coherence, and multi-scale consistency losses

Simplex Initialization

Instead of random initialization, the model uses SimplexFactory to create geometrically sound starting configurations:

• Regular (default): All edges equal length, perfectly balanced symmetric structure
• Random : QR decomposition ensuring affine independence
• Uniform : Hypercube sampling with perturbations

Regular simplices provide the most stable and mathematically meaningful initialization, giving the model a better starting point for learning geometric features.

Adaptive Augmentation System

The trainer includes an intelligent augmentation system that monitors train/validation accuracy gap and progressively enables more augmentation:

1. Baseline : RandomCrop + RandomHorizontalFlip
2. Stage 1 : + ColorJitter
3. Stage 2 : + RandomRotation
4. Stage 3 : + RandomAffine
5. Stage 4 : + RandomErasing
6. Stage 5 : + AutoAugment (CIFAR policy)
7. Stage 6 : Enable Mixup (α=0.2)
8. Stage 7 : Enable CutMix (α=1.0) - Final stage

When train accuracy exceeds validation accuracy by 2% or more, the system automatically escalates to the next augmentation stage.

Available Models (Best Checkpoints Only)

Latest Updated Model: beatrix-simplex4-patch4-512d-flow (Session: 20251008_115206)

Model Details

• Architecture : Vision Transformer with fractal positional encoding
• Dataset : CIFAR-100 (100 classes)
• Embedding Dimension : 512
• Depth : 8 layers
• Patch Size : 4x4
• PE Levels : 12
• Simplex Dimension : 4-simplex
• Simplex Initialization : regular (scale=1.0)

Training Details

• Training Session : 20251008_115206
• Best Accuracy : 0.5674
• Epochs Trained : 87
• Batch Size : 512
• Learning Rate : 0.0001
• Adaptive Augmentation : Enabled

Loss Configuration

• Task Loss Weight: 0.5
• Flow Alignment Weight: 1.0
• Coherence Weight: 0.3
• Multi-Scale Weight: 0.2

TensorBoard Logs

Training logs are available in the repository at:

logs/beatrix-simplex4-patch4-512d-flow/20251008_115206

To view them locally:

# Clone the repo
git clone https://huggingface.co/AbstractPhil/vit-beatrix

# View logs in TensorBoard
tensorboard --logdir vit-beatrix/logs/beatrix-simplex4-patch4-512d-flow/20251008_115206

Usage

Installation

For Google Colab:

# Install for Colab
try:
  !pip uninstall -qy geometricvocab
except:
  pass

!pip install -q git+https://github.com/AbstractEyes/lattice_vocabulary.git

For local environments:

# install the repo into your environment
pip install -q git+https://github.com/AbstractEyes/lattice_vocabulary.git

Loading Models

from geovocab2.train.model.vit_beatrix import SimplifiedGeometricClassifier
from safetensors.torch import load_file
from huggingface_hub import hf_hub_download
import json

# Download and view manifest to see all available models
manifest_path = hf_hub_download(
    repo_id="AbstractPhil/vit-beatrix",
    filename="manifest.json"
)

with open(manifest_path, 'r') as f:
    manifest = json.load(f)
    
# List all available models sorted by accuracy
for key, info in sorted(manifest.items(), key=lambda x: x[1]['accuracy'], reverse=True):
    print(f"{info['model_name']} ({info['timestamp']}): {info['accuracy']:.4f}")

# Download weights for the latest training session of beatrix-simplex4-patch4-512d-flow
weights_path = hf_hub_download(
    repo_id="AbstractPhil/vit-beatrix",
    filename="weights/beatrix-simplex4-patch4-512d-flow/20251008_115206/model.safetensors"
)

# Load model
model = SimplifiedGeometricClassifier(
    num_classes=100,
    img_size=32,
    embed_dim=512,
    depth=8
)

# Load weights
state_dict = load_file(weights_path)
model.load_state_dict(state_dict)
model.eval()

# Inference
output = model(images)

Citation

@misc{vit-beatrix,
  author = {AbstractPhil},
  title = {ViT-Beatrix: Fractal Positional Encoding with Geometric Simplices},
  year = {2025},
  url = {https://github.com/AbstractEyes/lattice_vocabulary}
}

License

MIT License