TorchSOM Documentation¶
GPU-accelerated Self-Organizing Maps in PyTorch with a scikit-learn API, advanced visualization, and clustering.
TorchSOM is the PyTorch-native reference implementation of the Self-Organizing Map (SOM). It pairs a familiar scikit-learn-style API with GPU-accelerated batch training, a built-in clustering interface, just-in-time-learning support, and a visualization suite for both rectangular and hexagonal topologies. It accompanies the paper torchsom: The Reference PyTorch Library for Self-Organizing Maps (Berthier et al., 2025).
Install TorchSOM and train your first Self-Organizing Map in a few minutes.
End-to-end worked examples on real datasets: classification, regression, and clustering.
Architecture, topologies, training, clustering, JITL, visualization, and benchmarks.
Full API documentation for torchsom.core, torchsom.utils, and torchsom.visualization.
Key Features¶
Performance
GPU-accelerated batch training with PyTorch
77–99% faster training than MiniSom (see Benchmarks)
Quantization-error parity with lower topographic error
Optional FAISS backend for BMU search on large maps
Flexibility
Rectangular and hexagonal topologies, optionally toroidal via periodic boundary conditions
Four distance metrics and four neighborhood kernels
Configurable learning-rate and neighborhood-width decay schedules
Configurable BMU search backend (PyTorch or FAISS)
Visualization
Seven visualization types for both rectangular and hexagonal topologies
Distance, hit, component-plane, classification, and metric maps
Score and rank maps for per-neuron reliability in regression
Clustering diagnostics: elbow, silhouette, and algorithm comparison
Developer-Friendly
scikit-learn-style API (
fit,build_map,cluster)Pydantic-based configuration with validation
Full type hints throughout
90% test coverage, Apache 2.0 licensed
Quick Start¶
Install TorchSOM:
uv add torchsom
Train and visualize a SOM:
import torch
from torchsom import SOM, 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)
viz = SOMVisualizer(som=som)
viz.plot_training_errors(
quantization_errors=q_errors, topographic_errors=t_errors
)
viz.plot_distance_map()
viz.plot_hit_map(data=X)
Citation¶
If you use TorchSOM in your work, please cite:
@misc{berthier2025torchsom,
title={torchsom: The Reference PyTorch Library for Self-Organizing Maps},
author={Berthier, Louis and Shokry, Ahmed and Moreaud, Maxime
and Ramelet, Guillaume and Moulines, Eric},
year={2025},
eprint={2510.11147},
archivePrefix={arXiv},
primaryClass={stat.ML},
url={https://arxiv.org/abs/2510.11147}
}
Support¶
Documentation: You’re reading it!
Bug Reports: GitHub Issues
Source Code: GitHub
License¶
TorchSOM is released under the Apache License 2.0.