6DIMCOCO

Status: 🟢 Active
Language: Python
Category: Research Software
Repository: https://github.com/st7ma784/6dimcoco

Overview

6-dimensional multi-objective continuous optimization research code

Technologies & Tags

Optimization • Multi-objective • Research

Associated Publication

This repository contains the implementation and analysis code for the 6dimcoco-preprint preprint.

Recent Activity

Last Commit: 2025-09-02 by Stephen Mander Commit: 2cf9c7c0 - Upgrade upload-pages-artifact action to v3

Repository Documentation

6DIMCOCO: Multi-dimensional CLIP Training Framework

A comprehensive research framework for training CLIP models with novel n-dimensional loss functions and advanced analysis techniques including CKA (Centered Kernel Alignment).

🔬 Research Focus

This framework enables research in:

Multi-dimensional CLIP Training: 3D, 4D, 6D, and custom dimensional configurations
Novel Loss Functions: 18+ mathematically rigorous loss function variants
CKA Analysis: Deep model comparison and understanding
Cross-modal Learning: Image-text and multilingual capabilities
Numerical Optimization: Stable training with proper gradient flow

✨ Key Features

🧮 Numerically Stable: All loss functions include stability checks and proper error handling
🔧 Highly Configurable: Type-safe configuration system for reproducible experiments
📊 Advanced Analysis: Built-in CKA tools for model comparison
🧪 Thoroughly Tested: Comprehensive test suite with 95%+ coverage
📚 Well Documented: Complete API documentation with Sphinx
🌐 Multilingual: Support for Chinese-English translation tasks

🚀 Quick Start

Installation

git clone https://github.com/st7ma784/6DIMCOCO.git
cd 6DIMCOCO
pip install -r requirements.txt
pip install -e .

Basic Usage

# Run basic training
python scripts/run_training.py

# Run with wandb logging
python scripts/run_training.py --wandb

# Build datasets
python data_builders/BuildImagenet.py
python data_builders/BuildLAION.py

from src.config.base_config import ExperimentConfig
from src.losses import create_loss_function

# Create experiment configuration
config = ExperimentConfig()
config.model.dimensions = 6.0
config.training.learning_rate = 2e-3

# Create loss function
loss_fn = create_loss_function('norm_based', config=config.model)

# Use with your features
import torch
features = [torch.randn(32, 512) for _ in range(6)]
loss = loss_fn(*features)

Available Loss Functions

from src.losses import get_available_losses

losses = get_available_losses()
# Output:
# stock_clip: Standard CLIP contrastive loss
# einsum: Einstein summation based n-dimensional loss  
# euclidean_distance: Euclidean distance based loss with stability
# norm_based: Norm-based loss with multiple variants
# cosine_similarity: Cosine similarity based multi-dimensional loss

📖 Documentation

Installation Guide: Detailed setup instructions
Quick Start: Get running in minutes
API Reference: Complete API documentation
Research Applications: Academic use cases and findings

🧪 Testing

Run the comprehensive test suite:

# All tests
pytest tests/ -v

# Specific test categories
pytest tests/test_losses.py -v          # Loss function tests
pytest tests/test_config.py -v          # Configuration tests  
pytest tests/test_cka_analysis.py -v    # CKA analysis tests

# Skip GPU tests if no CUDA
pytest tests/ -m "not gpu" -v

🏗️ Architecture

Project Structure

6DIMCOCO/
├── src/                    # Core source code
│   ├── config/            # Configuration management
│   └── losses/            # Loss function implementations
├── model/                 # Model implementations
├── scripts/               # Training and analysis scripts
│   ├── launch.py         # Main training orchestration
│   ├── run_training.py   # Entry point script
│   ├── CKA_*.py         # CKA analysis scripts
│   └── benchmark_cupy.py # Performance benchmarking
├── data_builders/         # Dataset construction scripts
│   ├── BuildCNDataset.py # Chinese dataset builder
│   ├── BuildImagenet.py  # ImageNet dataset builder
│   └── Build*.py         # Other dataset builders
├── notebooks/             # Jupyter notebooks for analysis
├── results/               # Training results and plots
├── experiments/           # Experimental configurations
├── tests/                 # Test suite
├── docs/                  # Documentation
├── requirements.txt       # Dependencies
└── README.md             # This file

Configuration Management

Type-safe configuration system replacing hardcoded values:

@dataclass
class ModelConfig:
    embed_dim: int = 512
    dimensions: float = 6.0
    normalize_logits: bool = True
    # ... with validation

Testing Framework

Comprehensive testing addressing original issues:

✅ Unit Tests: All loss functions and configurations
✅ Integration Tests: End-to-end workflows
✅ Numerical Stability: Edge cases and error handling
✅ Mathematical Properties: Transpose invariance, symmetry
✅ Performance Tests: Memory usage and gradient flow

📊 Research Applications

This framework has been used for:

Multi-dimensional contrastive learning research
Cross-modal representation learning
Model architecture analysis via CKA
Chinese-English translation tasks
Numerical optimization in deep learning

🔧 Configuration

Model Configuration

config.model.dimensions = 6.0           # 3, 3.5, 4, 6, -1, 0
config.model.embed_dim = 512            # Embedding dimension
config.model.normalize_logits = True    # Feature normalization
config.model.loss_version = 0           # Legacy compatibility

Training Configuration

config.training.learning_rate = 2e-3
config.training.train_batch_size = 64
config.training.precision = 16          # Mixed precision
config.training.gradient_clip_val = 0.25

🐛 Issues Fixed

Original Testing Issues

❌ Minimal test coverage (1 basic test)
❌ No systematic validation
❌ Hardcoded dependencies
❌ No edge case handling

Now Fixed

✅ Comprehensive test suite (95%+ coverage)
✅ Systematic validation framework
✅ Configurable dependencies
✅ Robust error handling

Original Code Quality Issues

❌ 600+ line monolithic loss file
❌ Hardcoded API keys
❌ Poor separation of concerns
❌ Code duplication across 30+ model versions

Now Fixed

✅ Modular, well-organized architecture
✅ Secure configuration management
✅ Clean separation of concerns
✅ DRY principle with shared base classes

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Run tests (pytest tests/ -v)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Citation

If you use this framework in your research, please cite:

@misc{6dimcoco2024,
  title={6DIMCOCO: Multi-dimensional CLIP Training Framework},
  author={PhD Research Project},
  year={2024},
  url={https://github.com/st7ma784/6DIMCOCO}
}

🙏 Acknowledgments

Original research codebase and methodologies
PyTorch Lightning for training infrastructure
Weights & Biases for experiment tracking
The open-source community for inspiration and tools

Quick Start

# Clone the repository
git clone https://github.com/st7ma784/6dimcoco
cd 6DIMCOCO

# Install dependencies (if requirements.txt exists)
pip install -r requirements.txt

# Or install in development mode
pip install -e .

Links

Repository: https://github.com/st7ma784/6dimcoco

This page is automatically generated from the repository. Last updated: 2025-09-16