Spherical-CNN 🌐

Welcome to the Spherical-CNN repository! This project allows you to explore equivariant neural networks on homogeneous spaces, specifically focusing on the sphere ( S^2 ) as ( SO(3)/SO(2) ). This exploration stems from Lecture 8 of the Lie Groups course with Quantum Formalism.

Table of Contents

• Introduction
• Features
• Installation
• Usage
• Examples
• Contributing
• License
• Acknowledgments

Introduction

Equivariant neural networks offer a powerful way to handle data that exhibits symmetry. This repository provides tools and examples for working with such networks, specifically on spherical domains. The focus on the sphere ( S^2 ) allows for applications in various fields, including computer vision, robotics, and physics.

Features

• Interactive tools for exploring equivariant neural networks.
• Focus on the mathematical foundations of homogeneous spaces.
• Integration with PyTorch for deep learning applications.
• Examples demonstrating the use of spherical CNNs.
• Comprehensive documentation to guide users.

Installation

To get started, clone the repository and install the required dependencies.

git clone https://github.com/seydoux02/Spherical-CNN.git
cd Spherical-CNN
pip install -r requirements.txt

Make sure you have Python 3.6 or higher installed.

Usage

Once installed, you can start exploring the functionalities of Spherical-CNN. Here’s a basic example of how to use the library:

import torch
from spherical_cnn import SphericalCNN

# Create a spherical CNN instance
model = SphericalCNN()

# Example input
input_data = torch.randn(1, 3, 64, 64)  # Batch size of 1, 3 channels, 64x64 resolution

# Forward pass
output = model(input_data)
print(output.shape)

For more detailed usage, check the examples section below.

Examples

Example 1: Basic Spherical CNN

Here’s a simple example demonstrating how to create and use a spherical CNN.

import torch
from spherical_cnn import SphericalCNN

# Initialize the model
model = SphericalCNN()

# Generate random input
input_data = torch.randn(1, 3, 128, 128)

# Perform a forward pass
output = model(input_data)

# Print output shape
print("Output shape:", output.shape)

Example 2: Training a Model

To train a model on your dataset, follow these steps:

1. Prepare your dataset.
2. Create a data loader.
3. Define a loss function and optimizer.
4. Train the model.

Here’s a simplified code snippet:

from torch.utils.data import DataLoader
from spherical_cnn import SphericalCNN

# Load your dataset
train_loader = DataLoader(your_dataset, batch_size=32, shuffle=True)

# Initialize the model, loss, and optimizer
model = SphericalCNN()
criterion = torch.nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)

# Training loop
for epoch in range(num_epochs):
    for data, labels in train_loader:
        optimizer.zero_grad()
        outputs = model(data)
        loss = criterion(outputs, labels)
        loss.backward()
        optimizer.step()
    print(f'Epoch [{epoch+1}/{num_epochs}], Loss: {loss.item():.4f}')

Contributing

We welcome contributions! If you want to contribute, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them.
4. Push your changes to your forked repository.
5. Submit a pull request.

Please ensure that your code follows the project's coding style and includes appropriate tests.

License

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

Acknowledgments

We thank the contributors and the community for their support. Special thanks to the instructors of the Lie Groups course for their insights and guidance.

For the latest releases, please visit this link. You can download the files and execute them to explore the features of Spherical-CNN.

Conclusion

The Spherical-CNN repository provides a platform for exploring equivariant neural networks in a mathematically rich environment. We encourage users to dive into the examples, contribute to the project, and apply these concepts to their work. Your exploration of spherical domains and equivariant networks can lead to exciting advancements in various fields.

Feel free to reach out if you have questions or need assistance. Happy coding!