# `torchsom`: The Reference PyTorch Library for Self-Organizing Maps
<div align="center">
<!-- Global Package information -->
[](https://pypi.org/project/torchsom/)
[](https://pypi.org/project/torchsom/)
[](https://pytorch.org/)
[](https://opensource.org/license/apache-2-0)
<!-- Sonar Qube badges -->
[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)
[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)
[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)
[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)
[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)
<!-- [](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM) -->
<!-- GitHub Workflows -->
[](https://github.com/michelin/TorchSOM/actions/workflows/test.yml)
[](https://github.com/michelin/TorchSOM/actions/workflows/code-quality.yml)
[](https://pepy.tech/project/torchsom)
[](https://github.com/michelin/TorchSOM)
<!-- [](https://github.com/michelin/TorchSOM/actions/workflows/security.yml) -->
<!-- Code Style and Tools -->
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
[](https://github.com/astral-sh/ruff)
<p align="center">
<img src="assets/logo.jpg" alt="TorchSOM_logo" width="400"/>
</p>
**The most comprehensive, scalable, and PyTorch-native implementation of Self-Organizing Maps**
[📚 Documentation](https://opensource.michelin.io/TorchSOM/)
| [🚀 Quick Start](#-quick-start)
| [📊 Examples](notebooks/)
| [🤝 Contributing](CONTRIBUTING.md)
<!-- | [📄 Paper (PDF)](assets/torchsom_jmlr.pdf) -->
**⭐ If you find [`torchsom`](https://github.com/michelin/TorchSOM) valuable, please consider starring this repository ⭐**
</div>
---
## 🎯 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`: The Reference PyTorch Library for Self-Organizing Maps](assets/torchsom_jmlr.pdf).
If you use `torchsom` in academic or industrial work, please cite the paper and the software (see [`CITATION`](CITATION.cff)).
> **Note**: Check the table below for a comprehensive comparison of how `torchsom` differs from existing SOM libraries, and explore our [Visualization Gallery](#-visualization-gallery) for examples of the rich visual outputs available.
### ⚡ Key Advantages
| Aspect | [torchsom](https://github.com/michelin/TorchSOM) | [MiniSom](https://github.com/JustGlowing/minisom) | [SimpSOM](https://github.com/fcomitani/simpsom) | [SOMPY](https://github.com/sevamoo/SOMPY) | [somoclu](https://github.com/peterwittek/somoclu) | [som-pbc](https://github.com/alexarnimueller/som) |
|---|---|---|---|---|---|---|
| Framework | PyTorch | NumPy | NumPy | NumPy | C++/CUDA | NumPy |
| GPU Acceleration | CUDA | ❌ | CuPy/CUML | ❌ | CUDA | ❌ |
| API Design | scikit-learn | Custom | Custom | MATLAB | Custom | custom |
| Maintenance | Active | Active | Minimal | Minimal | Minimal | ❌ |
| Documentation | Rich | ❌ | Basic | ❌ | Basic | Basic |
| Test Coverage | ~86% | ❌ | ~53% | ❌ | Minimal | ❌ |
| PyPI Distribution | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
| SOM Variants | Multiple | ❌ | PBC | ❌ | PBC | PBC (only) |
| Visualization | Advanced | ❌ | Moderate | Moderate | Basic | Basic |
| Extensibility | High | Moderate | Low | Low | Low | Low |
---
## 📑 Table of Contents
- [Quick Start](#-quick-start)
- [Tutorials](#-tutorials)
- [Installation](#-installation)
- [Documentation](#-documentation)
- [Citation](#-citation)
- [Contributing](#-contributing)
- [Acknowledgments](#-acknowledgments)
- [License](#-license)
- [References](#-references)
<!-- - [Reproducibility](#-reproducibility) -->
<!-- - [Performance Benchmarks](#-performance-benchmarks) -->
---
## 🚀 Quick Start
Get started with `torchsom` in just a few lines of code:
```python
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)
```
## 📓 Tutorials
Explore our comprehensive collection of Jupyter notebooks:
- 📊 [`iris.ipynb`](notebooks/iris.ipynb): Multiclass classification
- 🍷 [`wine.ipynb`](notebooks/wine.ipynb): Multiclass classification
- 🏠 [`boston_housing.ipynb`](notebooks/boston_housing.ipynb): Regression
- ⚡ [`energy_efficiency.ipynb`](notebooks/energy_efficiency.ipynb): Multi-output regression
- 🎯 [`clustering.ipynb`](notebooks/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"/>
</td>
<td align="center">
<b>🎯 HDBSCAN Cluster Map</b><br>
<p>Cluster visualization</p>
<img src="assets/hdbscan_cluster_map.png" alt="HDBSCAN Cluster Map" width="220"/>
</td>
</tr>
</table>
</p>
---
## 💾 Installation
### 📦 PyPI
```bash
pip install torchsom
```
### 🔧 Development Version
```bash
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 [opensource.michelin.io/TorchSOM](https://opensource.michelin.io/TorchSOM/)
---
## 📝 Citation
If you use `torchsom` in your research, please cite both the paper and software:
```bibtex
@inproceedings{Berthier2025TorchSOM,
title={torchsom: The Reference PyTorch 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](CITATION.cff) file.
---
## 🤝 Contributing
We welcome contributions from the community! See our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) for details.
- **GitHub Issues**: [Report bugs or request features](https://github.com/michelin/TorchSOM/issues)
<!-- - **GitHub Discussions**: [Ask questions and share ideas](https://github.com/michelin/TorchSOM/discussions) -->
---
## 🙏 Acknowledgments
- [Centre de Mathématiques Appliquées (CMAP)](https://cmap.ip-paris.fr/) at École Polytechnique
- [Manufacture Française des Pneumatiques Michelin](https://www.michelin.com/) for collaboration
- [Giuseppe Vettigli](https://github.com/JustGlowing) for [MiniSom](https://github.com/JustGlowing/minisom) inspiration
- The [PyTorch](https://pytorch.org/) team for the amazing framework
- Logo created using [DALL-E](https://openai.com/index/dall-e-3/)
---
## 📄 License
`torchsom` is licensed under the [Apache License 2.0](LICENSE). See the [LICENSE](LICENSE) file for details.
---
## 📚 References
### 📖 Core Papers
- Kohonen, T. (2001). [Self-Organizing Maps](https://link.springer.com/book/10.1007/978-3-642-56927-2). Springer.
### 🔗 Related Projects
- [MiniSom](https://github.com/JustGlowing/minisom): Minimalistic Python SOM
- [SimpSOM](https://github.com/fcomitani/simpsom):Simple Self-Organizing Maps
- [SOMPY](https://github.com/sevamoo/SOMPY): Python SOM library
- [somoclu](https://github.com/peterwittek/somoclu): Massively Parallel Self-Organizing Maps
- [som-pbc](https://github.com/alexarnimueller/som): A simple self-organizing map implementation in Python with periodic boundary conditions
- [SOM Toolbox](http://www.cis.hut.fi/projects/somtoolbox/): MATLAB implementation
---
<!-- ### 🎨 Core Capabilities
- **🏗️ Multiple SOM Variants**: Batch SOM, Growing SOM, Hierarchical SOM, and other variants
- **⚡ GPU Acceleration**: Full CUDA support with automatic device management
- **🔄 PyTorch Native**: Seamless integration with existing PyTorch workflows
- **📊 Rich Visualizations**: 10+ visualization types including U-Matrix, Component Planes, Hit Maps
- **🎯 Flexible Training**: Online and batch learning modes with customizable schedules
### 🧪 Advanced Features
- **🌐 Deep Learning Integration**: Use SOMs as layers, with autograd support
- **📈 Scalable Architecture**: Handle millions of samples efficiently
- **🔧 Customizable Components**: Plug-in architecture for neighborhoods, learning rates, distances
- **📱 Multi-GPU Support**: Distributed training for large-scale applications
- **🎮 Interactive Visualizations**: Real-time training monitoring and exploration
### 🛠️ Technical Specifications
- **✅ Type Safety**: Full type hints and runtime validation with Pydantic
- **📝 Comprehensive Docs**: Detailed API documentation with examples
- **🧪 Thoroughly Tested**: 95%+ test coverage with CI/CD
- **🔍 Reproducible**: Deterministic training with seed management -->
<!-- ---
## ⚡ Performance Benchmarks
### Training & Memory Performance
| Case | Samples | Features | Map Size | TorchSOM<br>CPU Time (s) | TorchSOM<br>CPU RAM (GB) | TorchSOM<br>GPU Time (s) | TorchSOM<br>GPU RAM (GB) | MiniSom<br>CPU Time (s) | MiniSom<br>CPU RAM (GB) |
|------|---------|----------|----------|--------------------------|--------------------------|--------------------------|--------------------------|-------------------------|-------------------------|
| 1 | 1,000 | 30 | 15×15 | 0.7 ± 0.1 | 0.6 ± 0.1 | 0.09 ± 0.01 | 0.09 ± 0.01 | 2.1 ± 0.2 | 0.7 ± 0.1 |
| 2 | 2,500 | 40 | 20×20 | 1.5 ± 0.2 | 0.8 ± 0.1 | 0.15 ± 0.01 | 0.12 ± 0.01 | 4.8 ± 0.3 | 1.0 ± 0.1 |
| 3 | 5,000 | 50 | 25×25 | 3.2 ± 0.3 | 1.2 ± 0.1 | 0.28 ± 0.02 | 0.18 ± 0.01 | 10.2 ± 0.5 | 1.6 ± 0.2 |
| 4 | 10,000 | 60 | 30×30 | 6.8 ± 0.5 | 1.8 ± 0.2 | 0.55 ± 0.03 | 0.25 ± 0.02 | 22.5 ± 1.0 | 2.5 ± 0.2 |
| 5 | 20,000 | 80 | 40×40 | 14.7 ± 0.8 | 2.9 ± 0.2 | 1.1 ± 0.05 | 0.42 ± 0.03 | 48.9 ± 2.0 | 4.2 ± 0.3 |
| 6 | 35,000 | 100 | 50×50 | 28.3 ± 1.2 | 4.5 ± 0.3 | 2.0 ± 0.08 | 0.65 ± 0.04 | 98.7 ± 3.5 | 7.0 ± 0.5 |
| 7 | 50,000 | 120 | 60×60 | 44.2 ± 1.8 | 6.2 ± 0.4 | 3.1 ± 0.10 | 0.92 ± 0.05 | 152.3 ± 5.0 | 9.8 ± 0.7 |
| 8 | 65,000 | 150 | 75×75 | 62.8 ± 2.5 | 8.7 ± 0.6 | 4.5 ± 0.15 | 1.3 ± 0.07 | 210.5 ± 7.0 | 13.5 ± 1.0 |
| 9 | 80,000 | 200 | 100×100 | 85.6 ± 3.0 | 12.1 ± 0.8 | 6.2 ± 0.20 | 1.8 ± 0.09 | 295.0 ± 10.0 | 18.7 ± 1.2 |
| 10 | 100,000 | 300 | 125×125 | 120.3 ± 4.0 | 18.5 ± 1.2 | 8.9 ± 0.25 | 2.7 ± 0.12 | 410.2 ± 15.0 | 27.5 ± 2.0 |
*RAM values are in GB. Times are in seconds. "OOM" = (out of memory).
Benchmarks performed on NVIDIA RTX 3090 (GPU), AMD Ryzen 9 5900X (CPU).*
### Training & Memory Speedup
| Case | TorchSOM CPU Speedup | TorchSOM GPU Speedup | TorchSOM CPU RAM Saving | TorchSOM GPU RAM Saving |
|------|------------------------|-------------------------|----------------------------|----------------------------|
| 1 | 3.0× | 23.3× | 1.2× | 7.8× |
| 2 | 3.2× | 32.0× | 1.3× | 8.3× |
| 3 | 3.2× | 36.4× | 1.3× | 8.9× |
| 4 | 3.3× | 40.9× | 1.4× | 10.0× |
| 5 | 3.3× | 44.5× | 1.4× | 10.0× |
| 6 | 3.5× | 49.4× | 1.6× | 10.8× |
| 7 | 3.4× | 49.2× | 1.6× | 10.7× |
| 8 | 3.4× | 46.8× | 1.6× | 10.4× |
| 9 | 3.4× | 47.6× | 1.5× | 10.4× |
| 10 | 3.4× | 46.1× | 1.5× | 10.2× |
*Speedup = (MiniSom CPU Time / TorchSOM Time) for each mode.*
**Summary:**
- TorchSOM (GPU) achieves up to ~Z× speedup and ~Z× lower memory usage compared to MiniSom (CPU) on large datasets.
- TorchSOM (CPU) is consistently Y–Z× faster and more memory efficient than MiniSom (CPU).
- All benchmarks use identical data and map initialization for fair comparison. -->
Raw data
{
"_id": null,
"home_page": null,
"name": "torchsom",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Louis Berthier <louis-desire-romeo.berthier@michelin.com>",
"keywords": "Self-Organizing-Maps, SOM, PyTorch, Machine-Learning, Unsupervised-Learning, Dimensionality-Reduction, Clustering, Data-Visualization, Just-In-Time-Learning",
"author": null,
"author_email": "Louis Berthier <louis-desire-romeo.berthier@michelin.com>",
"download_url": "https://files.pythonhosted.org/packages/65/53/ef427b792014afe35f467b129dd50b83145e3622f3446889dd536d041928/torchsom-1.0.0.tar.gz",
"platform": null,
"description": "# `torchsom`: The Reference PyTorch Library for Self-Organizing Maps\n\n<div align=\"center\">\n\n<!-- Global Package information -->\n[](https://pypi.org/project/torchsom/)\n[](https://pypi.org/project/torchsom/)\n[](https://pytorch.org/)\n[](https://opensource.org/license/apache-2-0)\n\n<!-- Sonar Qube badges -->\n[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n\n<!-- [](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM) -->\n\n<!-- GitHub Workflows -->\n[](https://github.com/michelin/TorchSOM/actions/workflows/test.yml)\n[](https://github.com/michelin/TorchSOM/actions/workflows/code-quality.yml)\n[](https://pepy.tech/project/torchsom)\n[](https://github.com/michelin/TorchSOM)\n<!-- [](https://github.com/michelin/TorchSOM/actions/workflows/security.yml) -->\n\n<!-- Code Style and Tools -->\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n[](https://github.com/astral-sh/ruff)\n\n<p align=\"center\">\n <img src=\"assets/logo.jpg\" alt=\"TorchSOM_logo\" width=\"400\"/>\n</p>\n\n**The most comprehensive, scalable, and PyTorch-native implementation of Self-Organizing Maps**\n\n[\ud83d\udcda Documentation](https://opensource.michelin.io/TorchSOM/)\n| [\ud83d\ude80 Quick Start](#-quick-start)\n| [\ud83d\udcca Examples](notebooks/)\n| [\ud83e\udd1d Contributing](CONTRIBUTING.md)\n<!-- | [\ud83d\udcc4 Paper (PDF)](assets/torchsom_jmlr.pdf) -->\n\n**\u2b50 If you find [`torchsom`](https://github.com/michelin/TorchSOM) valuable, please consider starring this repository \u2b50**\n\n</div>\n\n---\n\n## \ud83c\udfaf Why `torchsom`?\n\n**`torchsom`** is the reference PyTorch library for Self-Organizing Maps (SOMs), purpose-built for seamless integration with modern deep learning and scientific workflows.\nUnlike legacy SOM packages, `torchsom` is engineered from the ground up to fully leverage PyTorch\u2019s ecosystem\u2014offering native GPU acceleration, scalable performance, and compatibility with neural network pipelines.\nWhether 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.\n\n`torchsom` is the official implementation accompanying the paper: [`torchsom`: The Reference PyTorch Library for Self-Organizing Maps](assets/torchsom_jmlr.pdf).\nIf you use `torchsom` in academic or industrial work, please cite the paper and the software (see [`CITATION`](CITATION.cff)).\n\n> **Note**: Check the table below for a comprehensive comparison of how `torchsom` differs from existing SOM libraries, and explore our [Visualization Gallery](#-visualization-gallery) for examples of the rich visual outputs available.\n\n### \u26a1 Key Advantages\n\n| Aspect | [torchsom](https://github.com/michelin/TorchSOM) | [MiniSom](https://github.com/JustGlowing/minisom) | [SimpSOM](https://github.com/fcomitani/simpsom) | [SOMPY](https://github.com/sevamoo/SOMPY) | [somoclu](https://github.com/peterwittek/somoclu) | [som-pbc](https://github.com/alexarnimueller/som) |\n|---|---|---|---|---|---|---|\n| Framework | PyTorch | NumPy | NumPy | NumPy | C++/CUDA | NumPy |\n| GPU Acceleration | CUDA | \u274c | CuPy/CUML | \u274c | CUDA | \u274c |\n| API Design | scikit-learn | Custom | Custom | MATLAB | Custom | custom |\n| Maintenance | Active | Active | Minimal | Minimal | Minimal | \u274c |\n| Documentation | Rich | \u274c | Basic | \u274c | Basic | Basic |\n| Test Coverage | ~86% | \u274c | ~53% | \u274c | Minimal | \u274c |\n| PyPI Distribution | \u2705 | \u2705 | \u2705 | \u274c | \u2705 | \u274c |\n| SOM Variants | Multiple | \u274c | PBC | \u274c | PBC | PBC (only) |\n| Visualization | Advanced | \u274c | Moderate | Moderate | Basic | Basic |\n| Extensibility | High | Moderate | Low | Low | Low | Low |\n\n---\n\n## \ud83d\udcd1 Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Tutorials](#-tutorials)\n- [Installation](#-installation)\n- [Documentation](#-documentation)\n- [Citation](#-citation)\n- [Contributing](#-contributing)\n- [Acknowledgments](#-acknowledgments)\n- [License](#-license)\n- [References](#-references)\n<!-- - [Reproducibility](#-reproducibility) -->\n<!-- - [Performance Benchmarks](#-performance-benchmarks) -->\n\n---\n\n## \ud83d\ude80 Quick Start\n\nGet started with `torchsom` in just a few lines of code:\n\n```python\nimport torch\nfrom torchsom.core import SOM\nfrom torchsom.visualization import SOMVisualizer\n\n# Create a 10x10 map for 3D input\nsom = SOM(x=10, y=10, num_features=3, epochs=50)\n\n# Train SOM for 50 epochs on 1000 samples\nX = torch.randn(1000, 3)\nsom.initialize_weights(data=X, mode=\"pca\")\nQE, TE = som.fit(data=X)\n\n# Visualize results\nvisualizer = SOMVisualizer(som=som, config=None)\nvisualizer.plot_training_errors(quantization_errors=QE, topographic_errors=TE, save_path=None)\nvisualizer.plot_distance_map(save_path=None)\nvisualizer.plot_hit_map(data=X, save_path=None)\n```\n\n## \ud83d\udcd3 Tutorials\n\nExplore our comprehensive collection of Jupyter notebooks:\n\n- \ud83d\udcca [`iris.ipynb`](notebooks/iris.ipynb): Multiclass classification\n- \ud83c\udf77 [`wine.ipynb`](notebooks/wine.ipynb): Multiclass classification\n- \ud83c\udfe0 [`boston_housing.ipynb`](notebooks/boston_housing.ipynb): Regression\n- \u26a1 [`energy_efficiency.ipynb`](notebooks/energy_efficiency.ipynb): Multi-output regression\n- \ud83c\udfaf [`clustering.ipynb`](notebooks/clustering.ipynb): SOM-based clustering analysis\n\n### \ud83c\udfa8 Visualization Gallery\n\n<p align=\"center\">\n <table>\n <tr>\n <td align=\"center\">\n <b>\ud83d\uddfa\ufe0f D-Matrix Visualization</b><br>\n <p>Michelin production line (regression)</p>\n <img src=\"assets/michelin_dmatrix.png\" alt=\"U-Matrix\" width=\"220\"/>\n </td>\n <td align=\"center\">\n <b>\ud83d\udccd Hit Map Visualization</b><br>\n <p>Michelin production line (regression)</p>\n <img src=\"assets/michelin_hitmap.png\" alt=\"Hit Map\" width=\"220\"/>\n </td>\n <td align=\"center\">\n <b>\ud83d\udcca Mean Map Visualization</b><br>\n <p>Michelin production line (regression)</p>\n <img src=\"assets/michelin_meanmap.png\" alt=\"Mean Map\" width=\"220\"/>\n </td>\n </tr>\n <tr>\n <td align=\"center\" colspan=\"2\">\n <b>\ud83d\uddfa\ufe0f Component Planes Visualization</b><br>\n <p>Another Michelin line (regression)</p>\n <table>\n <tr>\n <td align=\"center\">\n <img src=\"assets/michelin_cp12.png\" alt=\"Component Plane 1\" width=\"220\"/>\n </td>\n <td align=\"center\">\n <img src=\"assets/michelin_cp21.png\" alt=\"Component Plane 2\" width=\"220\"/>\n </td>\n </tr>\n </table>\n </td>\n <td align=\"center\">\n <b>\ud83c\udff7\ufe0f Classification Map</b><br>\n <p>Wine dataset (multi-classification)</p>\n <img src=\"assets/wine_classificationmap.png\" alt=\"Classification Map\" width=\"220\"/>\n </td>\n </tr>\n <tr>\n <td align=\"center\">\n <b>\ud83d\udcca Cluster Metrics</b><br>\n <p>Clustering analysis</p>\n <img src=\"assets/cluster_metrics.png\" alt=\"Cluster Metrics\" width=\"220\"/>\n </td>\n <td align=\"center\">\n <b>\ud83d\udcc8 K-Means Elbow</b><br>\n <p>Optimal cluster selection</p>\n <img src=\"assets/kmeans_elbow.png\" alt=\"K-Means Elbow\" width=\"220\"/>\n </td>\n <td align=\"center\">\n <b>\ud83c\udfaf HDBSCAN Cluster Map</b><br>\n <p>Cluster visualization</p>\n <img src=\"assets/hdbscan_cluster_map.png\" alt=\"HDBSCAN Cluster Map\" width=\"220\"/>\n </td>\n </tr>\n </table>\n</p>\n\n---\n\n## \ud83d\udcbe Installation\n\n### \ud83d\udce6 PyPI\n\n```bash\npip install torchsom\n```\n\n### \ud83d\udd27 Development Version\n\n```bash\ngit clone https://github.com/michelin/TorchSOM.git\ncd TorchSOM\npython3.9 -m venv .torchsom_env\nsource .torchsom_env/bin/activate\npip install -e \".[dev]\"\n```\n\n---\n\n## \ud83d\udcda Documentation\n\nComprehensive documentation is available at [opensource.michelin.io/TorchSOM](https://opensource.michelin.io/TorchSOM/)\n\n---\n\n## \ud83d\udcdd Citation\n\nIf you use `torchsom` in your research, please cite both the paper and software:\n\n```bibtex\n@inproceedings{Berthier2025TorchSOM,\n title={torchsom: The Reference PyTorch Library for Self-Organizing Maps},\n author={Berthier, Louis},\n booktitle={Conference Name},\n year={2025}\n}\n\n@software{Berthier_TorchSOM_The_Reference_2025,\n author={Berthier, Louis},\n title={torchsom: The Reference PyTorch Library for Self-Organizing Maps},\n url={https://github.com/michelin/TorchSOM},\n version={1.0.0},\n year={2025}\n}\n```\n\nFor more details, please refer to the [CITATION](CITATION.cff) file.\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions from the community! See our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) for details.\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/michelin/TorchSOM/issues)\n<!-- - **GitHub Discussions**: [Ask questions and share ideas](https://github.com/michelin/TorchSOM/discussions) -->\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\n- [Centre de Math\u00e9matiques Appliqu\u00e9es (CMAP)](https://cmap.ip-paris.fr/) at \u00c9cole Polytechnique\n- [Manufacture Fran\u00e7aise des Pneumatiques Michelin](https://www.michelin.com/) for collaboration\n- [Giuseppe Vettigli](https://github.com/JustGlowing) for [MiniSom](https://github.com/JustGlowing/minisom) inspiration\n- The [PyTorch](https://pytorch.org/) team for the amazing framework\n- Logo created using [DALL-E](https://openai.com/index/dall-e-3/)\n\n---\n\n## \ud83d\udcc4 License\n\n`torchsom` is licensed under the [Apache License 2.0](LICENSE). See the [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83d\udcda References\n\n### \ud83d\udcd6 Core Papers\n\n- Kohonen, T. (2001). [Self-Organizing Maps](https://link.springer.com/book/10.1007/978-3-642-56927-2). Springer.\n\n### \ud83d\udd17 Related Projects\n\n- [MiniSom](https://github.com/JustGlowing/minisom): Minimalistic Python SOM\n- [SimpSOM](https://github.com/fcomitani/simpsom):Simple Self-Organizing Maps\n- [SOMPY](https://github.com/sevamoo/SOMPY): Python SOM library\n- [somoclu](https://github.com/peterwittek/somoclu): Massively Parallel Self-Organizing Maps\n- [som-pbc](https://github.com/alexarnimueller/som): A simple self-organizing map implementation in Python with periodic boundary conditions\n- [SOM Toolbox](http://www.cis.hut.fi/projects/somtoolbox/): MATLAB implementation\n\n---\n\n<!-- ### \ud83c\udfa8 Core Capabilities\n\n- **\ud83c\udfd7\ufe0f Multiple SOM Variants**: Batch SOM, Growing SOM, Hierarchical SOM, and other variants\n- **\u26a1 GPU Acceleration**: Full CUDA support with automatic device management\n- **\ud83d\udd04 PyTorch Native**: Seamless integration with existing PyTorch workflows\n- **\ud83d\udcca Rich Visualizations**: 10+ visualization types including U-Matrix, Component Planes, Hit Maps\n- **\ud83c\udfaf Flexible Training**: Online and batch learning modes with customizable schedules\n\n### \ud83e\uddea Advanced Features\n\n- **\ud83c\udf10 Deep Learning Integration**: Use SOMs as layers, with autograd support\n- **\ud83d\udcc8 Scalable Architecture**: Handle millions of samples efficiently\n- **\ud83d\udd27 Customizable Components**: Plug-in architecture for neighborhoods, learning rates, distances\n- **\ud83d\udcf1 Multi-GPU Support**: Distributed training for large-scale applications\n- **\ud83c\udfae Interactive Visualizations**: Real-time training monitoring and exploration\n\n### \ud83d\udee0\ufe0f Technical Specifications\n\n- **\u2705 Type Safety**: Full type hints and runtime validation with Pydantic\n- **\ud83d\udcdd Comprehensive Docs**: Detailed API documentation with examples\n- **\ud83e\uddea Thoroughly Tested**: 95%+ test coverage with CI/CD\n- **\ud83d\udd0d Reproducible**: Deterministic training with seed management -->\n\n<!-- ---\n\n## \u26a1 Performance Benchmarks\n\n### Training & Memory Performance\n\n| Case | Samples | Features | Map Size | TorchSOM<br>CPU Time (s) | TorchSOM<br>CPU RAM (GB) | TorchSOM<br>GPU Time (s) | TorchSOM<br>GPU RAM (GB) | MiniSom<br>CPU Time (s) | MiniSom<br>CPU RAM (GB) |\n|------|---------|----------|----------|--------------------------|--------------------------|--------------------------|--------------------------|-------------------------|-------------------------|\n| 1 | 1,000 | 30 | 15\u00d715 | 0.7 \u00b1 0.1 | 0.6 \u00b1 0.1 | 0.09 \u00b1 0.01 | 0.09 \u00b1 0.01 | 2.1 \u00b1 0.2 | 0.7 \u00b1 0.1 |\n| 2 | 2,500 | 40 | 20\u00d720 | 1.5 \u00b1 0.2 | 0.8 \u00b1 0.1 | 0.15 \u00b1 0.01 | 0.12 \u00b1 0.01 | 4.8 \u00b1 0.3 | 1.0 \u00b1 0.1 |\n| 3 | 5,000 | 50 | 25\u00d725 | 3.2 \u00b1 0.3 | 1.2 \u00b1 0.1 | 0.28 \u00b1 0.02 | 0.18 \u00b1 0.01 | 10.2 \u00b1 0.5 | 1.6 \u00b1 0.2 |\n| 4 | 10,000 | 60 | 30\u00d730 | 6.8 \u00b1 0.5 | 1.8 \u00b1 0.2 | 0.55 \u00b1 0.03 | 0.25 \u00b1 0.02 | 22.5 \u00b1 1.0 | 2.5 \u00b1 0.2 |\n| 5 | 20,000 | 80 | 40\u00d740 | 14.7 \u00b1 0.8 | 2.9 \u00b1 0.2 | 1.1 \u00b1 0.05 | 0.42 \u00b1 0.03 | 48.9 \u00b1 2.0 | 4.2 \u00b1 0.3 |\n| 6 | 35,000 | 100 | 50\u00d750 | 28.3 \u00b1 1.2 | 4.5 \u00b1 0.3 | 2.0 \u00b1 0.08 | 0.65 \u00b1 0.04 | 98.7 \u00b1 3.5 | 7.0 \u00b1 0.5 |\n| 7 | 50,000 | 120 | 60\u00d760 | 44.2 \u00b1 1.8 | 6.2 \u00b1 0.4 | 3.1 \u00b1 0.10 | 0.92 \u00b1 0.05 | 152.3 \u00b1 5.0 | 9.8 \u00b1 0.7 |\n| 8 | 65,000 | 150 | 75\u00d775 | 62.8 \u00b1 2.5 | 8.7 \u00b1 0.6 | 4.5 \u00b1 0.15 | 1.3 \u00b1 0.07 | 210.5 \u00b1 7.0 | 13.5 \u00b1 1.0 |\n| 9 | 80,000 | 200 | 100\u00d7100 | 85.6 \u00b1 3.0 | 12.1 \u00b1 0.8 | 6.2 \u00b1 0.20 | 1.8 \u00b1 0.09 | 295.0 \u00b1 10.0 | 18.7 \u00b1 1.2 |\n| 10 | 100,000 | 300 | 125\u00d7125 | 120.3 \u00b1 4.0 | 18.5 \u00b1 1.2 | 8.9 \u00b1 0.25 | 2.7 \u00b1 0.12 | 410.2 \u00b1 15.0 | 27.5 \u00b1 2.0 |\n\n*RAM values are in GB. Times are in seconds. \"OOM\" = (out of memory).\nBenchmarks performed on NVIDIA RTX 3090 (GPU), AMD Ryzen 9 5900X (CPU).*\n\n### Training & Memory Speedup\n\n| Case | TorchSOM CPU Speedup | TorchSOM GPU Speedup | TorchSOM CPU RAM Saving | TorchSOM GPU RAM Saving |\n|------|------------------------|-------------------------|----------------------------|----------------------------|\n| 1 | 3.0\u00d7 | 23.3\u00d7 | 1.2\u00d7 | 7.8\u00d7 |\n| 2 | 3.2\u00d7 | 32.0\u00d7 | 1.3\u00d7 | 8.3\u00d7 |\n| 3 | 3.2\u00d7 | 36.4\u00d7 | 1.3\u00d7 | 8.9\u00d7 |\n| 4 | 3.3\u00d7 | 40.9\u00d7 | 1.4\u00d7 | 10.0\u00d7 |\n| 5 | 3.3\u00d7 | 44.5\u00d7 | 1.4\u00d7 | 10.0\u00d7 |\n| 6 | 3.5\u00d7 | 49.4\u00d7 | 1.6\u00d7 | 10.8\u00d7 |\n| 7 | 3.4\u00d7 | 49.2\u00d7 | 1.6\u00d7 | 10.7\u00d7 |\n| 8 | 3.4\u00d7 | 46.8\u00d7 | 1.6\u00d7 | 10.4\u00d7 |\n| 9 | 3.4\u00d7 | 47.6\u00d7 | 1.5\u00d7 | 10.4\u00d7 |\n| 10 | 3.4\u00d7 | 46.1\u00d7 | 1.5\u00d7 | 10.2\u00d7 |\n\n*Speedup = (MiniSom CPU Time / TorchSOM Time) for each mode.*\n\n**Summary:**\n\n- TorchSOM (GPU) achieves up to ~Z\u00d7 speedup and ~Z\u00d7 lower memory usage compared to MiniSom (CPU) on large datasets.\n- TorchSOM (CPU) is consistently Y\u2013Z\u00d7 faster and more memory efficient than MiniSom (CPU).\n- All benchmarks use identical data and map initialization for fair comparison. -->\n",
"bugtrack_url": null,
"license": null,
"summary": "torchsom: The Reference PyTorch Library for Self-Organizing Maps",
"version": "1.0.0",
"project_urls": {
"Citation": "https://github.com/michelin/TorchSOM/blob/main/CITATION.cff",
"Code of Conduct": "https://github.com/michelin/TorchSOM/blob/main/CODE_OF_CONDUCT.md",
"Contributing": "https://github.com/michelin/TorchSOM/blob/main/CONTRIBUTING.md",
"Documentation": "https://opensource.michelin.io/TorchSOM/",
"License": "https://github.com/michelin/TorchSOM/blob/main/LICENSE",
"Source": "https://github.com/michelin/torchsom",
"Tracker": "https://github.com/michelin/TorchSOM/issues"
},
"split_keywords": [
"self-organizing-maps",
" som",
" pytorch",
" machine-learning",
" unsupervised-learning",
" dimensionality-reduction",
" clustering",
" data-visualization",
" just-in-time-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62f139272b50df2ef0c50947f8143fab22c68fbad88182dc6e803d041a3f2906",
"md5": "3057b0dd6c72de289a1f821c9eccbbc4",
"sha256": "2bce0ac11c3cb42f14fe11547ae1d65a008c11cbff4952a964f509ca724685b7"
},
"downloads": -1,
"filename": "torchsom-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3057b0dd6c72de289a1f821c9eccbbc4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 60154,
"upload_time": "2025-08-20T13:35:51",
"upload_time_iso_8601": "2025-08-20T13:35:51.267105Z",
"url": "https://files.pythonhosted.org/packages/62/f1/39272b50df2ef0c50947f8143fab22c68fbad88182dc6e803d041a3f2906/torchsom-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6553ef427b792014afe35f467b129dd50b83145e3622f3446889dd536d041928",
"md5": "9e56e72f58ed8d76cd471193ddd8c3c1",
"sha256": "74ee60581494a347f10393c536384f0237e88e6bf6feecfd94fbce9db130db6b"
},
"downloads": -1,
"filename": "torchsom-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9e56e72f58ed8d76cd471193ddd8c3c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 58788,
"upload_time": "2025-08-20T13:35:52",
"upload_time_iso_8601": "2025-08-20T13:35:52.303460Z",
"url": "https://files.pythonhosted.org/packages/65/53/ef427b792014afe35f467b129dd50b83145e3622f3446889dd536d041928/torchsom-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 13:35:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "michelin",
"github_project": "TorchSOM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "torchsom"
}
JSON
