torchsom: The Reference PyTorch Library for Self-Organizing Maps

<div align="center"> <!-- Global Package information -->

<!-- Sonar Qube badges -->

<!-- [](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM) --> <!-- GitHub Workflows -->

<!-- [](https://github.com/michelin/TorchSOM/actions/workflows/security.yml) --> <!-- Code Style and Tools -->

<p align="center"> <img src="assets/logo.png" alt="TorchSOM_logo" width="400"/> </p>

A modern, comprehensive and GPU-accelerated PyTorch implementation of Self-Organizing Maps for scalable ML workflows

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

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

</div>

---

🎯 Overview

Self-Organizing Maps (SOMs) remain highly relevant in modern machine learning (ML) due to their interpretability, topology preservation, and computational efficiency. They excel and are widely used in domains such as energy systems, biology, internet of things (IoT), environmental science, and industrial applications.

Despite their utility, the SOM ecosystem is fragmented. Existing implementations are often outdated, unmaintained, and lack GPU acceleration or modern deep learning (DL) framework integration, limiting adoption and scalability.

torchsom addresses these gaps as a reference PyTorch library for SOMs. It provides:

• GPU-accelerated training
• Advanced clustering capabilities
• A scikit-learn-style API for ease of use
• Rich visualization tools
• Robust software engineering practices

torchsom enables researchers and practitioners to integrate SOMs seamlessly into workflows, from exploratory data analysis to advanced model architectures.

This library accompanies the paper: torchsom: The Reference PyTorch Library for Self-Organizing Maps. If you use torchsom in academic or industrial work, please cite both the paper and the software (see CITATION).

Note: See the comparison table below to understand how torchsom differs from other SOM libraries, and explore our Visualization Gallery for example outputs.

⚡ Why torchsom?

Unlike legacy implementations, torchsom is engineered from the ground up for modern ML workflows:

| | torchsom | MiniSom | SimpSOM | SOMPY | somoclu | som-pbc | |---|---|---|---|---|---|---| | Architecture Section | | | | | | | | Framework | PyTorch | NumPy | NumPy | NumPy | C++/CUDA | NumPy | | GPU Acceleration | ✅ CUDA | ❌ | ✅ CuPy/CUML | ❌ | ✅ CUDA | ❌ | | API Design | scikit-learn | Custom | Custom | MATLAB | Custom | custom | | Development Quality Section | | | | | | | | Maintenance | ✅ Active | ✅ Active | ⚠️ Minimal | ⚠️ Minimal | ⚠️ Minimal | ❌ | | Documentation | ✅ Rich | ❌ | ⚠️ Basic | ❌ | ⚠️ Basic | ⚠️ Basic | | Test Coverage | ✅ 90% | ❌ | 🟠 ~53% | ❌ | ⚠️ Minimal | ❌ | | PyPI Distribution | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | | Functionality Section | | | | | | | | Visualization | ✅ Advanced | ❌ | 🟠 Moderate | 🟠 Moderate | ⚠️ Basic | ⚠️ Basic | | Clustering | ✅ Advanced | ❌ | ❌ | ❌ | ❌ | ❌ | | JITL support | ✅ Built-in | ❌ | ❌ | ❌ | ❌ | ❌ | | SOM Variants | 🚧 In development | ❌ | 🟠 PBC | ❌ | 🟠 PBC | 🟠 PBC | | Extensibility | ✅ High | 🟠 Moderate | ⚠️ Low | ⚠️ Low | ⚠️ Low | ⚠️ Low |

Note: torchsom supports Just-In-Time Learning (JITL). Given an online query, JITL collects relevant datapoints to form a local buffer (selected first by topology, then by distance). A lightweight local model can then be trained on this buffer, enabling efficient supervised learning (regression or classification).

---

📑 Table of Contents

• Quick Start
• Tutorials
• Installation
• Documentation
• Citation
• Contributing
• Acknowledgments
• License
• Related Work and 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_hit_map(data=X, batch_size=256, save_path=None)
visualizer.plot_distance_map(
  save_path=None,
  distance_metric=som.distance_fn_name,
  neighborhood_order=som.neighborhood_order,
  scaling="sum"
)

📓 Tutorials

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
• 🎯 clustering.ipynb: SOM-based clustering analysis

🎨 Visualization Gallery

<p align="center"> <table> <tr> <td align="center"> <b>🗺️ D-Matrix Visualization</b><br> <p>Michelin production line (regression)</p> <img src="assets/michelin_dmatrix.png" alt="U-Matrix" width="220"/> </td> <td align="center"> <b>📍 Hit Map Visualization</b><br> <p>Michelin production line (regression)</p> <img src="assets/michelin_hitmap.png" alt="Hit Map" width="220"/> </td> <td align="center"> <b>📊 Mean Map Visualization</b><br> <p>Michelin production line (regression)</p> <img src="assets/michelin_meanmap.png" alt="Mean Map" width="220"/> </td> </tr> <tr> <td align="center" colspan="2"> <b>🗺️ Component Planes Visualization</b><br> <p>Another Michelin line (regression)</p> <table> <tr> <td align="center"> <img src="assets/michelin_cp12.png" alt="Component Plane 1" width="220"/> </td> <td align="center"> <img src="assets/michelin_cp21.png" alt="Component Plane 2" width="220"/> </td> </tr> </table> </td> <td align="center"> <b>🏷️ Classification Map</b><br> <p>Wine dataset (multi-classification)</p> <img src="assets/wine_classificationmap.png" alt="Classification Map" width="220"/> </td> </tr> <tr> <td align="center"> <b>📊 Cluster Metrics</b><br> <p>Clustering analysis</p> <img src="assets/cluster_metrics.png" alt="Cluster Metrics" width="220"/> </td> <td align="center"> <b>📈 K-Means Elbow</b><br> <p>Optimal cluster selection</p> <img src="assets/kmeans_elbow.png" alt="K-Means Elbow" width="220"