GASM - Generalized Geometric Inference System

A universal geometry inference system that is group-invariant, topology-agnostic, and domain-independent. GASM implements a novel Universal Invariant Attention (UIA) mechanism that generalizes Invariant Point Attention (IPA) to work with arbitrary Lie group spaces.

🎯 Key Features

• Universal Invariant Attention: Generalizes IPA to arbitrary Lie groups (SE(3), SO(n), GL(n), etc.)
• Group Invariance: Maintains geometric consistency across transformations
• Topology Agnostic: Works with any graph structure or connectivity pattern
• Domain Independent: No protein-specific or domain-specific assumptions
• Emergent Structure Physics: Learns geometric constraints through curvature optimization
• Comprehensive Testing: >90% test coverage with SE(3) invariance verification

🧠 Architecture Overview

Core Components

1. Universal Invariant Attention (UIA)

   • Learnable attention mechanism in Lie group manifolds
   • Geodesic distance computation for geometric consistency
   • Multi-head attention with group action transformations

2. Iterative Geometry Unfolding

   • Progressive refinement of geometric structure
   • Curvature-based optimization with learnable targets
   • Early stopping for convergence

3. Emergent Structure Physics (Omega Projection)

   • Final geometric configuration synthesis
   • Consistency verification (invariance, information preservation, constraints)
   • Automated quality assessment

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/your-repo/gasm.git
cd gasm

# Install dependencies
pip install -r requirements.txt

# Install GASM
pip install -e .

Basic Usage

import torch
from gasm import GASM

# Initialize GASM
model = GASM(
    feature_dim=64,
    hidden_dim=128,
    output_dim=3,
    max_iterations=30,
    lie_group_type="se3"
)

# Prepare input data
n_entities = 100
E = torch.arange(n_entities)                    # Entities (indices)
F = torch.randn(n_entities, 64)                 # Features (n, d)
R = torch.randn(n_entities, n_entities, 8)      # Relations (n, n, p)
C = torch.randn(12)                              # Constraints (optional)

# Forward pass
output = model(E, F, R, C)
print(f"Output shape: {output.shape}")  # (100, 3)

Command Line Interface

# Basic usage
python -m gasm.cli --entities 100 --features 64 --relations 8 --max_iter 30

# With SE(3) invariance testing
python -m gasm.cli --entities 50 --test_invariance --num_invariance_tests 10

# Training with custom parameters
python -m gasm.cli --entities 200 --features 128 --epochs 100 --lr 0.001 --verbose

# Save and load models
python -m gasm.cli --save_model model.pth --load_model pretrained.pth

📊 Input/Output Interface

Parameter	Type	Shape	Description
E	List/Tensor	(n,)	Discrete entities (nodes, points, objects)
F	FloatTensor	(n, d)	Feature vectors per entity
R	FloatTensor	(n, n, p)	Relational map (edge features)
C	FloatTensor	(q,)	Optional constraints (symmetry, topology)
Output	FloatTensor	(n, m)	Final geometric configuration

🧪 Mathematical Foundation

Universal Invariant Attention

The core attention mechanism operates in Lie group manifolds:

a_ij = softmax(-d²(exp(θ) · x_i, exp(θ) · x_j) / √d)

Where:

• θ ∈ Lie-Algebra (learnable parameters)
• exp(θ) is the group action
• d is the geodesic distance in the target space

Iterative Geometry Unfolding

for t in range(max_iterations):
    F[t+1] = UIA(F[t], R, C)
    curvature = compute_local_curvature(F[t+1])
    loss = ||curvature - target_curvature||²

Geometric Consistency Tests

Test	Description	Criteria
Invariance	S' = group_action(g, S)	`
Information Loss	MI(S_raw, S) ≥ τ	Mutual information threshold
Constraint Matching	C @ S ≈ 0	Linear constraint satisfaction

📈 Performance & Benchmarks

SE(3) Invariance Testing

from gasm.utils import check_se3_invariance

# Test invariance with random transformations
is_invariant = check_se3_invariance(
    model=gasm,
    points=point_cloud,
    features=features,
    relations=relations,
    num_tests=100,
    tolerance=1e-4
)

Geometric Consistency Verification

# Built-in consistency checking
results = gasm.verify_geometric_consistency(
    S=output,
    S_raw=input_features,
    C=constraints,
    tolerance=1e-3
)

print(f"Invariance test: {results['invariance_test']}")
print(f"Information loss: {results['information_loss']}")
print(f"Constraint matching: {results['constraint_matching']}")

🔧 Advanced Configuration

Custom Lie Groups

# SE(3) for 3D transformations
gasm_se3 = GASM(lie_group_type="se3")

# SO(3) for pure rotations
gasm_so3 = GASM(lie_group_type="so3")

Curvature Computation Methods

from gasm.utils import compute_local_curvature

# Jacobian-based (default)
curvature = compute_local_curvature(features, projection_fn, "jacobian")

# Finite differences (fallback)
curvature = compute_local_curvature(features, projection_fn, "finite_diff")

Custom Graph Connectivity

from gasm.utils import create_edge_index

# Full connectivity
edge_index = create_edge_index(n_nodes, "full")

# Custom edge patterns (future)
# edge_index = create_edge_index(n_nodes, "knn", k=8)

🧪 Testing & Validation

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=gasm --cov-report=html

# Run specific test categories
pytest -m "not slow"  # Skip slow tests
pytest tests/test_core.py -v  # Core functionality only

Test Coverage

Our test suite includes:

• Unit Tests: Individual component testing
• Integration Tests: End-to-end system testing
• Invariance Tests: SE(3) and geometric consistency
• Edge Case Tests: Robustness and error handling
• Performance Tests: Memory and computational efficiency

Target: >90% test coverage ✅

Example Test Results

========================= test session starts ==========================
tests/test_core.py::TestGASM::test_forward_pass PASSED        [ 12%]
tests/test_core.py::TestGASM::test_se3_invariance PASSED      [ 25%]
tests/test_integration.py::TestGASMEndToEnd PASSED            [ 38%]
tests/test_utils.py::TestCurvatureComputation PASSED         [ 50%]
========================= 45 passed, 0 failed ===========================

---------- coverage: platform linux, python 3.8.10 -----------
Name                    Stmts   Miss  Cover
-------------------------------------------
gasm/__init__.py            5      0   100%
gasm/core.py              256     12    95%
gasm/utils.py             189      8    96%
gasm/cli.py               145      7    95%
-------------------------------------------
TOTAL                     595     27    95%

📚 API Reference

Core Classes

GASM(nn.Module)

Main GASM model implementation.

Parameters:

• feature_dim (int): Input feature dimension
• hidden_dim (int): Hidden layer dimension
• output_dim (int): Output geometric dimension (default: 3)
• num_heads (int): Number of attention heads (default: 8)
• max_iterations (int): Maximum unfolding iterations (default: 10)
• lie_group_type (str): Lie group type ("se3", "so3")
• dropout (float): Dropout probability (default: 0.1)

Methods:

• forward(E, F, R, C=None, return_intermediate=False): Main forward pass
• verify_geometric_consistency(S, S_raw, C=None): Consistency verification

UniversalInvariantAttention(MessagePassing)

Universal Invariant Attention mechanism.

Parameters:

• feature_dim (int): Feature dimension
• hidden_dim (int): Hidden dimension
• num_heads (int): Number of attention heads
• lie_group_type (str): Lie group type
• dropout (float): Dropout probability

Utility Functions

compute_local_curvature(features, projection_fn, method="jacobian")

Compute local curvature of geometric manifold.

check_se3_invariance(model, points, features, relations, num_tests=10, tolerance=1e-3)

Verify SE(3) invariance of model.

generate_random_pointcloud(n_points, dimension=3, distribution="uniform")

Generate random point clouds for testing.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/your-repo/gasm.git
cd gasm

# Install development dependencies
pip install -r requirements.txt
pip install -e ".[dev]"

# Run tests
pytest

# Code formatting
black gasm/
flake8 gasm/

# Type checking
mypy gasm/

Code Style

We follow:

• PEP 8 style guide
• Black code formatting
• mypy type checking
• SOLID principles for architecture

📄 License

This project is licensed under the CC-BY-NC 4.0, all rights reserved, Versino PsiOmega GmbH

📖 Citation

If you use GASM in your research, please cite:

@misc{gasm2024,
  title={GASM: Generalized Geometric Inference System},
  author={Michael Neuberger, Versino PsiOmega GmbH},
  year={2025, August},
  url={https://github.com/scheitelpunk/GASM}
}

🙏 Acknowledgments

• PyTorch team for the excellent deep learning framework
• PyTorch Geometric for graph neural network utilities
• geomstats for Lie group geometry computations
• The broader geometric deep learning community

📊 Project Status

• ✅ Core implementation complete
• ✅ Comprehensive testing suite
• ✅ CLI interface
• ✅ Documentation
• ✅ SE(3) invariance verification
• ✅ Geometric consistency testing
• 🔄 Performance optimization (ongoing)
• 🔄 Extended Lie group support (planned)
• 🔄 Advanced connectivity patterns (planned)

🔗 Links

• Documentation
• API Reference
• Examples
• Issue Tracker
• Discussions

---

Made with ❤️ by the Versino PsiOmega development team