README.md

metadata

tags:
  - hyperbolic
  - attention
  - dynamic
  - field
  - module
  - Poincaré

HDF-Transformer: Hyperbolic Dynamic Field Transformer

A reconceptualized transformer architecture where all core components evolve through physical PDE (Partial Differential Equation) dynamics instead of static operations.

🌊 What Makes This Different?

Standard transformers use static operations:

• Attention: Fixed dot-product → softmax
• MLP: Static linear → activation
• LayerNorm: Per-token statistics

HDF-Transformer uses dynamic field evolution:

• HDFAttention: Attention patterns propagate as waves with damping and bistable forcing
• HDFMLP: Features evolve via reaction-diffusion dynamics
• HDFLayerNorm: Context-aware normalization with diffusive smoothing
• HDFPositionalEncoding: Wave-based position signals

🎯 Key Innovation: The Bistable Term

The attention field ψ evolves according to:

***********************

Visual analogy: Attention is a field of grass with three magnets pulling it toward states {-1, 0, +1}, creating sharper, more decisive attention patterns.

📦 Installation

Prerequisites

• Python 3.8+
• PyTorch 2.0+
• CUDA (optional, for GPU acceleration)

Setup

# Clone/navigate to the repository
cd C:\coding_projectsusers\hdf-transformer
# Install dependencies
pip install -r requirements.txt

# Verify installation
python -c "from hdf_modules import HDFTransformer; print('✓ Installation successful!')"

🚀 Quick Start

Option 1: Interactive Testing (Recommended First)

Open the Jupyter notebook for interactive experimentation:

jupyter notebook test_hdf.ipynb

This notebook will guide you through:

• Creating a model
• Testing forward pass
• Inspecting PDE parameters
• Generating text
• Benchmarking performance

Option 2: Command-Line Training

Tiny Model (Fast Testing)

python train_hdf.py --model_size tiny --epochs 3 --batch_size 8

Small Model (Research)

python train_hdf.py --model_size small --epochs 10 --batch_size 4 --gradient_accumulation_steps 4

Full Training Options

python train_hdf.py \
    --model_size small \
    --internal_steps 5 \
    --epochs 10 \
    --batch_size 4 \
    --gradient_accumulation_steps 4 \
    --seq_length 128 \
    --learning_rate 1e-4 \
    --dataset wikitext \
    --output_dir ./checkpoints \
    --device cuda \
    --mixed_precision

Option 3: Use in Your Own Code

import torch
from hdf_modules.transformer import hdf_gpt2_small, HDFTransformer
from transformers import GPT2Tokenizer

# Create model
model = hdf_gpt2_small(vocab_size=50257, internal_steps=5)
model.eval()

# Load tokenizer
tokenizer = GPT2Tokenizer.from_pretrained('gpt2')

# Generate text
prompt = "Once upon a time"
input_ids = tokenizer.encode(prompt, return_tensors='pt')

with torch.no_grad():
    outputs = model(input_ids=input_ids)
    logits = outputs['logits']
    
# Sample next token
probs = torch.softmax(logits[0, -1], dim=-1)
next_token = torch.multinomial(probs, num_samples=1)

📁 Project Structure

hdf-transformer/
├── hdf_modules/              # Core HDF components
│   ├── __init__.py           # Package initialization
│   ├── attention.py          # HDFAttention (wave equation)
│   ├── mlp.py                # HDFMLP (reaction-diffusion)
│   ├── norm.py               # HDFLayerNorm (diffusive smoothing)
│   ├── pos_encoding.py       # HDFPositionalEncoding (wave-based)
│   └── transformer.py        # Complete model integration
├── train_hdf.py              # Training script
├── test_hdf.ipynb            # Interactive testing notebook
├── requirements.txt          # Dependencies
└── README.md                 # This file

🔧 Configuration

Model Sizes

Size	Layers	Embed Dim	Heads	Parameters	Use Case
Tiny	4	128	4	~500K	Testing, debugging
Small	12	768	12	~124M	Research, experiments
Medium	24	1024	16	~355M	Production (requires GPU)

Key Hyperparameters

• internal_steps: Number of PDE solver iterations (3-5 for speed, 5-10 for richer dynamics)
• dt: Time step for finite difference solver (default: 0.1, reduce if unstable)
• noise_std: Stochastic forcing strength during training (default: 0.01)

PDE Parameters (Automatically Learned)

All PDE coefficients are trainable parameters:

Parameter	Description	Initial Value
log_c	Wave speed	ln(0.5)
log_kappa	Damping coefficient	ln(0.1)
beta	Bistable forcing strength	0.05
log_diffusion	MLP diffusion rate	ln(0.1)
log_reaction	MLP reaction rate	ln(0.2)
log_saturation	MLP saturation	ln(0.15)

📊 Monitoring Training

Watch PDE Parameters Evolve

The training script automatically logs PDE parameters every 500 steps:

--- PDE Parameters at Step 500 ---
h.0.attn.log_c: -0.6931 → exp = 0.5000
h.0.attn.log_kappa: -2.3026 → exp = 0.1000
h.0.attn.beta: 0.0500

TensorBoard (Optional)

# Log to TensorBoard (requires modification to train_hdf.py)
tensorboard --logdir ./runs

🎓 How It Works: Visual Explanation

1. Standard Attention (Static)

Q·K^T → Softmax → Weights

Attention is computed once and never changes.

2. HDF Attention (Dynamic)

Q·K^T → Initialize ψ → Evolve via PDE (5 steps) → Softmax → Weights

What happens during evolution:

• Wave propagation: Focus spreads to neighbors
• Damping: Wild patterns settle down
• Random gusts: Training noise for robustness
• Bistable magnets: Pull attention toward decisive states (-1, 0, +1)

Result: Sharper, more context-aware attention patterns.

🧪 Transfer Learning from GPT-2

You can initialize HDF-Transformer with pretrained GPT-2 weights:

from transformers import GPT2LMHeadModel
from hdf_modules.transformer import HDFTransformer
from transformers import GPT2Config

# Load standard GPT-2
standard_model = GPT2LMHeadModel.from_pretrained('gpt2')

# Create HDF model with same config
config = GPT2Config.from_pretrained('gpt2')
hdf_model = HDFTransformer(config)

# Copy compatible weights
hdf_model.wte.load_state_dict(standard_model.transformer.wte.state_dict())
hdf_model.lm_head.load_state_dict(standard_model.lm_head.state_dict())

# Initialize PDE parameters based on standard attention
for i, block in enumerate(hdf_model.h):
    # Copy QKV projection weights
    standard_qkv = torch.cat([
        standard_model.transformer.h[i].attn.c_attn.weight[:, :768],
        standard_model.transformer.h[i].attn.c_attn.weight[:, 768:1536],
        standard_model.transformer.h[i].attn.c_attn.weight[:, 1536:]
    ], dim=0)
    block.attn.qkv_proj.weight.data = standard_qkv.T
    
    # Keep PDE params at defaults (will be learned)

# Fine-tune on your data (10% of original training time)

🚨 Troubleshooting

Out of Memory (CUDA OOM)

# Reduce batch size or sequence length
python train_hdf.py --batch_size 2 --seq_length 64

# Or reduce internal_steps (faster, less dynamic)
python train_hdf.py --internal_steps 3

NaN Loss / Training Divergence

# Reduce time step
# Modify hdf_modules/attention.py: dt=0.05 instead of 0.1

# Clip gradients (add to train_hdf.py)
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)

Slow Training

# Use mixed precision
python train_hdf.py --mixed_precision

# Reduce internal_steps
python train_hdf.py --internal_steps 3

# Use smaller model
python train_hdf.py --model_size tiny

📈 Expected Performance

Untrained Model

• Perplexity: ~50,000 (random)
• Loss: ~10.8
• Generation: Incoherent

After Training (Small Model, WikiText-2)

• Perplexity: ~30-40 (research baseline)
• Loss: ~3.4-3.7
• Generation: Coherent short sentences

Compared to Standard GPT-2

• Perplexity: Similar or slightly better (hypothesis: bistable term helps)
• Training time: 1.15-1.3x slower (due to PDE overhead)
• Memory: 1.5-2x peak usage (intermediate tensors)

🤝 Contributing

This is a research implementation. Contributions welcome:

• Efficiency: Optimize PDE solver (CUDA kernels, sparse ops)
• Analysis: Visualize attention dynamics, phase diagrams
• Extensions: 3D diffusion, multi-scale time steps
• Benchmarks: Compare with standard transformers on standard tasks

📚 Citation

If you use this code in research:

@software{hdf_transformer_2025,
  title={HDF-Transformer: Hyperbolic Dynamic Field Attention for Transformers},
  author={[Matthew Connelly theaiwillwin@gmail.com]},
  year={Nov 21 2025},
  url={https://github.com/theaiwillwin/hdf-transformer}
  url={https://github.com/theaiwillwin/hdf-transformer}
  url={https://github.com/theaiwillwin/hdf-transformer}
}

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• Built on HuggingFace Transformers
• Inspired by physics-informed neural networks (PINNs)
• Wave equation formulation inspired by hyperbolic PDEs in physics

🔗 Resources

• Transformers Documentation
• PyTorch Documentation
• Original GPT-2 Paper

---

Questions? Open an issue or discussion!

Status: Research implementation - suitable for experimentation and small-scale training.