torchsom 0.0.1

torchsom: The Reference PyTorch Library for Self-Organizing Maps

TorchSOM: The Reference PyTorch Library for Self-Organizing Maps

The most comprehensive, scalable, and PyTorch-native implementation of Self-Organizing Maps

📚 Documentation | 🚀 Quick Start | 📊 Examples | 🤝 Contributing

---

🎯 Why TorchSOM?

TorchSOM is the reference PyTorch library for Self-Organizing Maps (SOMs), purpose-built for seamless integration with modern deep learning and scientific workflows. Unlike legacy SOM packages, TorchSOM is engineered from the ground up to fully leverage PyTorch’s ecosystem—offering native GPU acceleration, scalable performance, and compatibility with neural network pipelines. Whether you are a researcher or practitioner, TorchSOM empowers you to efficiently incorporate SOMs into your machine learning projects, from exploratory data analysis to advanced model architectures.

TorchSOM is the official implementation accompanying the paper: TorchSOM: A Scalable PyTorch-Compatible Library for Self-Organizing Maps, presented at @CONFERENCE, @DATE.

⭐ If you find TorchSOM valuable, please consider starring this repository ⭐

⚡ Key Advantages

Feature	TorchSOM	MiniSom	SOMPY	SOMToolbox
🖥️ Code Compatibility	Python	Python	Python	MATLAB
🚀 GPU Acceleration	✅	❌	❌	❌
🔥 PyTorch Integration	✅	❌	❌	❌
📈 Scalability	✅	⚠️ Limited	⚠️ Limited	Unknown
🧩 Deep Learning Compatible	✅	❌	❌	❌
🌱 Growing SOM	🚧 Building	❌	❌	✅
🏗️ Hierarchical SOM	🚧 Building	❌	❌	✅
📊 Rich Visualizations	✅	❌	✅	✅
🔬 Active Development	✅	⚠️ (small updates)	❌	❌

---

📑 Table of Contents

• Quick Start
• Examples
• Installation
• Documentation
• Citation
• Contributing
• Acknowledgments
• License
• References

---

🚀 Quick Start

Get started with TorchSOM in just a few lines of code:

import torch
from torchsom.core import SOM
from torchsom.visualization import SOMVisualizer,

# Create a 10x10 map for 3D input
som = SOM(x=10, y=10, num_features=3, epochs=50)

# Train SOM for 50 epochs on 1000 samples
X = torch.randn(1000, 3)
som.initialize_weights(data=X, mode="pca")
QE, TE = som.fit(data=X)

# Visualize results
visualizer = SOMVisualizer(som=som, config=None)
visualizer.plot_training_errors(quantization_errors=QE, topographic_errors=TE, save_path=None)
visualizer.plot_distance_map(save_path=None)
visualizer.plot_hit_map(data=X, save_path=None)

📓 Examples

Explore our comprehensive collection of Jupyter notebooks:

• 📊 iris.ipynb: Multiclass classification
• 🍷 wine.ipynb: Multiclass classification
• 🏠 boston_housing.ipynb: Regression
• ⚡ energy_efficiency.ipynb: Multi-output regression

🎨 Some visualizations

🗺️ D-Matrix Visualization Michelin production line (regression)	📍 Hit Map Visualization Michelin production line (regression)	📊 Mean Map Visualization Michelin production line (regression)
🎯 Component Planes Visualization Another Michelin line (regression)		🏷️ Classification Map Wine dataset (multi-classification)

---

💾 Installation

📦 PyPI (not yet available)

pip install torchsom

🔧 Development Version

git clone https://github.com/michelin/TorchSOM.git
cd TorchSOM
python3.9 -m venv .torchsom_env
source .torchsom_env/bin/activate
pip install -e ".[dev]"

---

📚 Documentation

Comprehensive documentation is available at michelin.github.io/TorchSOM

---

📝 Citation

If you use TorchSOM in your research, please cite both the paper and software:

@inproceedings{Berthier2025TorchSOM,
    title={TorchSOM: A Scalable PyTorch-Compatible Library for Self-Organizing Maps},
    author={Berthier, Louis},
    booktitle={Conference Name},
    year={2025}
}

@software{Berthier_TorchSOM_The_Reference_2025,
    author={Berthier, Louis},
    title={TorchSOM: The Reference PyTorch Library for Self-Organizing Maps},
    url={https://github.com/michelin/TorchSOM},
    version={1.0.0},
    year={2025}
}

For more details, please refer to the CITATION.cff file.

---

🤝 Contributing

We welcome contributions from the community! See our Contributing Guide and Code of Conduct for details.

• GitHub Issues: Report bugs or request features

---

🙏 Acknowledgments

• Centre de Mathématiques Appliquées (CMAP) at École Polytechnique
• Manufacture Française des Pneumatiques Michelin for collaboration
• Giuseppe Vettigli for MiniSom inspiration
• The PyTorch team for the amazing framework
• Logo created using DALL-E

---

📄 License

TorchSOM is licensed under the Apache License 2.0. See the LICENSE file for details.

---

📚 References

📖 Core Papers

• Kohonen, T. (2001). Self-Organizing Maps. Springer.

🔗 Related Projects

• MiniSom: Minimalistic Python SOM
• SOMPY: Python SOM library
• SOM Toolbox: MATLAB implementation

---

If you find TorchSOM useful, please ⭐ star this repository!