michelin/TorchSOM
michelin/TorchSOM has 42 GitHub stars and 3 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-21 07:33 UTC. Last push 2026-10-18.
Gemessener Sternzuwachs
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- Verlauf wird gesammelt
- in 1 month
- Verlauf wird gesammelt
Nettoänderungen in überlappenden Zeiträumen, keine Tagessummen. Fehlende Messwerte bleiben leer. Sterne zeigen Interesse, nicht Qualität.
Über uns
torchsom: The Reference PyTorch Library for Self-Organizing Maps (JMLR 2026). GPU-accelerated SOMs with a scikit-learn API, clustering and visualization.
Maschinelles LernenREADME.md
Originaltorchsom: The Reference PyTorch Library for Self-Organizing Maps
GPU-accelerated Self-Organizing Maps in PyTorch with a scikit-learn API, rich visualization, and clustering: from dimensionality reduction to Just-In-Time Learning.
Paper | Documentation | Quick Start | Examples | Contributing
⭐ If you find torchsom valuable, please consider starring this repository ⭐
Overview
Self-Organizing Maps (SOMs) remain highly relevant in modern machine learning due to their interpretability, topology preservation, and computational efficiency. They are widely used in energy systems, biology, IoT, environmental science, and industrial applications.
Despite their utility, the Python SOM ecosystem is fragmented: existing implementations are often outdated, unmaintained, and lack GPU acceleration or integration with modern deep learning frameworks.
torchsom addresses these gaps as a reference PyTorch library for SOMs, providing:
- GPU-accelerated training via PyTorch CUDA backend
- Advanced clustering (K-Means, GMM, HDBSCAN) on the SOM latent space
- A scikit-learn-style API for ease of use and extensibility
- Rich visualization tools for both rectangular and hexagonal topologies
- Just-In-Time Learning (JITL) for supervised regression and classification
This library accompanies the paper torchsom: The Reference PyTorch Library for Self-Organizing Maps (Berthier et al., 2026), published in the Journal of Machine Learning Research. If you use torchsom in academic or industrial work, please cite the paper (see Citation).
Key Results
Benchmarked on synthetic datasets (240–16,000 samples, 4–300 features) with identical hyperparameters, comparing like with like on each device: on CPU against MiniSom (standard online + Numba-JIT), and on GPU against somoclu (CUDA C++), a massively parallel HPC library:
| Aspect | Result |
|---|---|
| Topology preservation | Lowest Topographic Error in every rectangular configuration and nearly all hexagonal ones, 62–100% below standard MiniSom, and below MiniSom-JIT and somoclu on rectangular maps. This is torchsom's most consistent edge. |
| CPU speed | 81–98% faster than standard MiniSom; and, with MiniSom-JIT's one-time compilation counted, matches or beats it in nearly all configurations (up to ~16×). |
| GPU speed | Up to ~12× faster than somoclu (CUDA) on high-dimensional data. |
| Scaling | Advantage grows with map size: on the larger 90×70 grid, up to ~200× faster than standard MiniSom (CPU) and ~66× faster than somoclu (GPU). |
| Quantization Error | Comparable across backends (torchsom marginally higher). |
torchsom is the only library combining this topology preservation and scaling with a scikit-learn API, GPU acceleration, clustering, JITL, and rich visualization. On small/low-dimensional workloads MiniSom-JIT (CPU) and somoclu (GPU) can be faster, reported transparently in the paper's Tables 2 (CPU) and 3 (GPU).
Hardware: Intel Xeon Gold 6134 (CPU), NVIDIA Tesla V100-32GB (GPU). See the paper for full benchmark tables.
Reproducing the JMLR benchmarks. All scripts and configurations are released under
benchmark/; seebenchmark/README.mdfor a step-by-step walkthrough, including the exact MiniSom pins and somoclu setup. Three annotated tags pin the versions of record:jmlr-submission-v1(original October 2025 submission),jmlr-revision-v1(first revision), andjmlr-revision-v2(the published version, which adds the somoclu and MiniSom-JIT baselines).git checkout <tag>reproduces the corresponding tables.
How It Works
A SOM is an unsupervised neural network that maps high-dimensional data onto a low-dimensional grid (typically 2D) while preserving topological relationships. At each training step, the Best Matching Unit (BMU) (the neuron closest to the input) is identified, and its weights along with its neighbors are updated:
$$\mathbf{w}{ij}(t+1) = \mathbf{w}{ij}(t) + \alpha(t) \cdot h_{ij}(t) \cdot \bigl(\mathbf{x} - \mathbf{w}_{ij}(t)\bigr)$$
where $\alpha(t)$ is the learning rate, $h_{ij}(t)$ is a neighborhood function (e.g., Gaussian) centered on the BMU, and $\mathbf{x} \in \mathbb{R}^k$ is the input vector. The BMU is found by:
$$\text{BMU} = \underset{i,j}{\arg\min}, \lVert \mathbf{x} - \mathbf{w}_{ij} \rVert_2$$
Training quality is assessed via Quantization Error (representation fidelity) and Topographic Error (topology preservation). See the documentation for the full mathematical background.
Why torchsom?
| torchsom | MiniSom | SimpSOM | SOMPY | somoclu | som-pbc | |
|---|---|---|---|---|---|---|
| Framework | PyTorch | NumPy | NumPy | NumPy | C++/CUDA | NumPy |
| GPU Acceleration | ✅ CUDA | ❌ | ✅ CuPy/CUML | ❌ | ✅ CUDA | ❌ |
| JIT Compilation | ✅ PyTorch | ✅ Numba (opt-in) | ❌ | ❌ | ❌ (AOT C++) | ❌ |
| API Design | scikit-learn | Custom | Custom | MATLAB | Custom | Custom |
| Maintenance | ✅ Active | ✅ Active | ⚠️ Minimal | ⚠️ Minimal | ⚠️ Minimal | ❌ |
| Documentation | ✅ Rich | ❌ | ⚠️ Basic | ❌ | ⚠️ Basic | ⚠️ Basic |
| Test Coverage | ✅ 90% | ✅ 98% | ~53% | ❌ | Minimal | ❌ |
| Visualization | ✅ Advanced | ❌ | Moderate | Moderate | Basic | Basic |
| Clustering | ✅ Advanced | ❌ | ❌ | ❌ | ❌ | ❌ |
| JITL Support | ✅ Built-in | ❌ | ❌ | ❌ | ❌ | ❌ |
| SOM Variants | PBC, Growing*, Hierarchical* | ❌ | PBC | ❌ | PBC | PBC |
* Work in progress
Just-In-Time Learning (JITL): Given an online query, JITL collects relevant samples by topology and distance to form a local buffer. A lightweight local model is then trained on this buffer, enabling efficient supervised learning (regression or classification).
Quick Start
import torch
from torchsom.core import SOM
from torchsom.visualization import SOMVisualizer
som = SOM(x=10, y=10, num_features=3, epochs=50)
X = torch.randn(1000, 3)
som.initialize_weights(data=X, mode="pca")
q_errors, t_errors = som.fit(data=X)
visualizer = SOMVisualizer(som=som)
visualizer.plot_training_errors(
quantization_errors=q_errors, topographic_errors=t_errors
)
visualizer.plot_hit_map(data=X, batch_size=256)
visualizer.plot_distance_map(
distance_metric=som.distance_fn_name,
neighborhood_order=som.neighborhood_order,
scaling="sum",
)
Tutorials
Explore our collection of Jupyter notebooks:
| Notebook | Task | Dataset |
|---|---|---|
iris.ipynb |
Multiclass classification | Iris |
wine.ipynb |
Multiclass classification | Wine |
boston_housing.ipynb |
Regression | Boston Housing |
energy_efficiency.ipynb |
Multi-output regression | Energy Efficiency |
clustering.ipynb |
Clustering analysis | Synthetic blobs |
Visualization Gallery
| D-Matrix (U-Matrix) Inter-neuron distances ![]() |
Hit Map BMU activation frequency ![]() |
Mean Map Target value distribution ![]() |
| Component Planes Feature-wise weight distribution ![]() |
Classification Map Dominant class per neuron ![]() |
HDBSCAN Cluster Map Cluster assignment ![]() |
| Component Planes Another feature dimension ![]() |
K-Means Elbow Optimal cluster selection ![]() |
Cluster Quality Metrics Algorithm comparison ![]() |
Installation
From PyPI
pip install torchsom
Or, in a uv project:
uv add torchsom
With optional FAISS acceleration for BMU search:
pip install "torchsom[faiss]"
Development Setup
Development uses uv for reproducible environments:
git clone https://github.com/michelin/TorchSOM.git
cd TorchSOM
uv sync --all-extras # creates .venv and installs everything
All Make targets use uv run so the correct environment is always activated:
make help # see all available commands
make cov # run tests with coverage
make check # lint / type-check
make fix # auto-format
make docs # build documentation
Documentation
Comprehensive documentation is available at opensource.michelin.io/TorchSOM, including:
- Getting Started: installation, quick start, SOM concepts
- User Guide: visualization, architecture, benchmarks
- API Reference: core, utils, visualization, configs
- Additional Resources: FAQ, troubleshooting, changelog
Citation
If you use torchsom in your academic, research, or industrial work, please cite the paper:
@article{berthierTorchsom2026,
author = {Louis Berthier and Ahmed Shokry and Maxime Moreaud and Guillaume Ramelet and Eric Moulines},
title = {torchsom: The Reference PyTorch Library for Self-Organizing Maps},
journal = {Journal of Machine Learning Research},
year = {2026},
volume = {27},
number = {190},
pages = {1--17},
url = {http://jmlr.org/papers/v27/25-2467.html}
}
An earlier preprint is available on arXiv (2510.11147). For more details, see the CITATION 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
License
torchsom is licensed under the Apache License 2.0. See the LICENSE file for details.
Related Work and References
Foundational Literature
- Kohonen, T. (1982). Self-organized formation of topologically correct feature maps. Biological Cybernetics, 43(1), 59–69.
- Kohonen, T. (1990). The self-organizing map. Proceedings of the IEEE, 78(9), 1464–1480.
- Kohonen, T. (2001). Self-Organizing Maps. Springer.
Related Software
- MiniSom: Minimalistic Python SOM
- SimpSOM: Simple Self-Organizing Maps
- SOMPY: Python SOM library
- somoclu: Massively Parallel Self-Organizing Maps
- som-pbc: SOM with periodic boundary conditions
- SOM Toolbox: MATLAB implementation








