{"id":30762556,"url":"https://github.com/michelin/torchsom","last_synced_at":"2025-09-04T15:07:19.698Z","repository":{"id":287037187,"uuid":"939998887","full_name":"michelin/TorchSOM","owner":"michelin","description":"TorchSOM is a PyTorch-based library for training Self-Organizing Maps (SOMs), a type of unsupervised learning algorithm used for clustering and dimensionality reduction. Designed for scalability and ease of use, this implementation is optimized for large-scale data.","archived":false,"fork":false,"pushed_at":"2025-09-01T14:37:18.000Z","size":140907,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-01T15:28:43.835Z","etag":null,"topics":["clustering","clustering-algorithm","data-visualisation","dimensionality-reduction-algorithms","dimensionality-reduction-technique","just-in-time","just-in-time-learning","pytorch","pytorch-implementation","self-organizing-maps","unsupervised-machine-learning"],"latest_commit_sha":null,"homepage":"https://opensource.michelin.io/TorchSOM/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/michelin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-27T13:01:52.000Z","updated_at":"2025-09-01T14:37:22.000Z","dependencies_parsed_at":"2025-08-14T18:07:29.466Z","dependency_job_id":"0d193b88-140a-48ac-b166-93d5d04d1d9f","html_url":"https://github.com/michelin/TorchSOM","commit_stats":null,"previous_names":["louistier/torchsom","michelin/torchsom"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/michelin/TorchSOM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michelin%2FTorchSOM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michelin%2FTorchSOM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michelin%2FTorchSOM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michelin%2FTorchSOM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michelin","download_url":"https://codeload.github.com/michelin/TorchSOM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michelin%2FTorchSOM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273626380,"owners_count":25139463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clustering","clustering-algorithm","data-visualisation","dimensionality-reduction-algorithms","dimensionality-reduction-technique","just-in-time","just-in-time-learning","pytorch","pytorch-implementation","self-organizing-maps","unsupervised-machine-learning"],"created_at":"2025-09-04T15:07:15.232Z","updated_at":"2025-09-04T15:07:19.665Z","avatar_url":"https://github.com/michelin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `torchsom`: The Reference PyTorch Library for Self-Organizing Maps\n\n\u003cdiv align=\"center\"\u003e\n\n\u003c!-- Global Package information --\u003e\n[![PyPI version](https://img.shields.io/pypi/v/torchsom.svg?color=blue)](https://pypi.org/project/torchsom/)\n[![Python versions](https://img.shields.io/pypi/pyversions/torchsom.svg?color=blue)](https://pypi.org/project/torchsom/)\n[![PyTorch versions](https://img.shields.io/badge/PyTorch-2.7-EE4C2C.svg)](https://pytorch.org/)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/license/apache-2-0)\n\n\u003c!-- Sonar Qube badges --\u003e\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=michelin_TorchSOM\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=michelin_TorchSOM\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=michelin_TorchSOM\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=michelin_TorchSOM\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=michelin_TorchSOM\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM)\n\n\u003c!-- [![SonarQube Cloud](https://sonarcloud.io/images/project_badges/sonarcloud-light.svg)](https://sonarcloud.io/summary/new_code?id=michelin_TorchSOM) --\u003e\n\n\u003c!-- GitHub Workflows --\u003e\n[![Tests](https://github.com/michelin/TorchSOM/workflows/Tests/badge.svg)](https://github.com/michelin/TorchSOM/actions/workflows/test.yml)\n[![Code Quality](https://github.com/michelin/TorchSOM/workflows/Code%20Quality/badge.svg)](https://github.com/michelin/TorchSOM/actions/workflows/code-quality.yml)\n[![Downloads](https://static.pepy.tech/badge/torchsom)](https://pepy.tech/project/torchsom)\n[![GitHub stars](https://img.shields.io/github/stars/michelin/TorchSOM.svg?style=social\u0026label=Star)](https://github.com/michelin/TorchSOM)\n\u003c!-- [![Security](https://github.com/michelin/TorchSOM/workflows/Security%20Scanning/badge.svg)](https://github.com/michelin/TorchSOM/actions/workflows/security.yml) --\u003e\n\n\u003c!-- Code Style and Tools --\u003e\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/imports-isort-6c757d.svg?color=blue)](https://pycqa.github.io/isort/)\n[![Ruff](https://img.shields.io/badge/linter-ruff-6c757d.svg?color=blue)](https://github.com/astral-sh/ruff)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/logo.png\" alt=\"TorchSOM_logo\" width=\"400\"/\u003e\n\u003c/p\u003e\n\n**A modern, comprehensive and GPU-accelerated PyTorch implementation of Self-Organizing Maps for scalable ML workflows**\n\n[📚 Documentation](https://opensource.michelin.io/TorchSOM/)\n| [🚀 Quick Start](#-quick-start)\n| [📊 Examples](notebooks/)\n| [🤝 Contributing](CONTRIBUTING.md)\n\u003c!-- | [📄 Paper (PDF)](assets/torchsom_jmlr.pdf) --\u003e\n\n**⭐ If you find [`torchsom`](https://github.com/michelin/TorchSOM) valuable, please consider starring this repository ⭐**\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Overview\n\nSelf-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.\n\nDespite 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.\n\n**`torchsom`** addresses these gaps as a **reference PyTorch library** for SOMs. It provides:\n\n- **GPU-accelerated training**\n- **Advanced clustering capabilities**\n- A **scikit-learn-style API** for ease of use\n- **Rich visualization tools**\n- **Robust software engineering practices**\n\n`torchsom` enables researchers and practitioners to integrate SOMs seamlessly into workflows, from exploratory data analysis to advanced model architectures.\n\nThis library accompanies 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 both the paper and the software (see [`CITATION`](CITATION.cff)).\n\n\u003e **Note**: See the comparison table below to understand how `torchsom` differs from other SOM libraries, and explore our [Visualization Gallery](#-visualization-gallery) for example outputs.\n\n## ⚡ Why `torchsom`?\n\nUnlike legacy implementations, `torchsom` is engineered from the ground up for modern ML workflows:\n\n|  | [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| **Architecture Section** |  |  |  |  |  |  |\n| Framework | PyTorch | NumPy | NumPy | NumPy | C++/CUDA | NumPy |\n| GPU Acceleration |  ✅ CUDA | ❌ | ✅ CuPy/CUML | ❌ | ✅ CUDA | ❌ |\n| API Design | scikit-learn | Custom | Custom | MATLAB | Custom | custom |\n| **Development Quality Section** |  |  |  |  |  |  |\n| Maintenance | ✅ Active | ✅ Active | ⚠️ Minimal | ⚠️ Minimal | ⚠️ Minimal | ❌ |\n| Documentation | ✅ Rich | ❌ | ⚠️ Basic | ❌ | ⚠️ Basic | ⚠️ Basic |\n| Test Coverage | ✅ ~86% | ❌ | 🟠 ~53% | ❌ | ⚠️ Minimal | ❌ |\n| PyPI Distribution | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |\n| **Functionality Section** |  |  |  |  |  |  |\n| Visualization | ✅ Advanced | ❌ | 🟠 Moderate | 🟠 Moderate | ⚠️ Basic | ⚠️ Basic |\n| Clustering | ✅ Advanced | ❌ | ❌ | ❌ | ❌ | ❌ |\n| JITL support | ✅ Built-in | ❌ | ❌ | ❌ | ❌ | ❌ |\n| SOM Variants | 🚧 In development | ❌ | 🟠 PBC | ❌ | 🟠 PBC | 🟠 PBC |\n| Extensibility | ✅ High | 🟠 Moderate | ⚠️ Low | ⚠️ Low | ⚠️ Low | ⚠️ Low |\n\n\u003e **Note**: `torchsom` supports **Just-In-Time Learning (JITL)**.\n\u003e Given an online query, JITL collects relevant datapoints to form a local buffer (selected first by topology, then by distance). A lightweight local model is then trained on this buffer, enabling efficient supervised learning (regression or classification).\n\n---\n\n## 📑 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- [Related Work and References](#-related-work-and-references)\n\u003c!-- - [Reproducibility](#-reproducibility) --\u003e\n\u003c!-- - [Performance Benchmarks](#-performance-benchmarks) --\u003e\n\n---\n\n## 🚀 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_hit_map(data=X, batch_size=256, save_path=None)\nvisualizer.plot_distance_map(\n  save_path=None,\n  distance_metric=som.distance_fn_name,\n  neighborhood_order=som.neighborhood_order,\n  scaling=\"sum\"\n)\n```\n\n## 📓 Tutorials\n\nExplore our comprehensive collection of Jupyter notebooks:\n\n- 📊 [`iris.ipynb`](notebooks/iris.ipynb): Multiclass classification\n- 🍷 [`wine.ipynb`](notebooks/wine.ipynb): Multiclass classification\n- 🏠 [`boston_housing.ipynb`](notebooks/boston_housing.ipynb): Regression\n- ⚡ [`energy_efficiency.ipynb`](notebooks/energy_efficiency.ipynb): Multi-output regression\n- 🎯 [`clustering.ipynb`](notebooks/clustering.ipynb): SOM-based clustering analysis\n\n### 🎨 Visualization Gallery\n\n\u003cp align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cb\u003e🗺️ D-Matrix Visualization\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eMichelin production line (regression)\u003c/p\u003e\n        \u003cimg src=\"assets/michelin_dmatrix.png\" alt=\"U-Matrix\" width=\"220\"/\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cb\u003e📍 Hit Map Visualization\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eMichelin production line (regression)\u003c/p\u003e\n        \u003cimg src=\"assets/michelin_hitmap.png\" alt=\"Hit Map\" width=\"220\"/\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cb\u003e📊 Mean Map Visualization\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eMichelin production line (regression)\u003c/p\u003e\n        \u003cimg src=\"assets/michelin_meanmap.png\" alt=\"Mean Map\" width=\"220\"/\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" colspan=\"2\"\u003e\n        \u003cb\u003e🗺️ Component Planes Visualization\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eAnother Michelin line (regression)\u003c/p\u003e\n        \u003ctable\u003e\n          \u003ctr\u003e\n            \u003ctd align=\"center\"\u003e\n              \u003cimg src=\"assets/michelin_cp12.png\" alt=\"Component Plane 1\" width=\"220\"/\u003e\n            \u003c/td\u003e\n            \u003ctd align=\"center\"\u003e\n              \u003cimg src=\"assets/michelin_cp21.png\" alt=\"Component Plane 2\" width=\"220\"/\u003e\n            \u003c/td\u003e\n          \u003c/tr\u003e\n        \u003c/table\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cb\u003e🏷️ Classification Map\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eWine dataset (multi-classification)\u003c/p\u003e\n        \u003cimg src=\"assets/wine_classificationmap.png\" alt=\"Classification Map\" width=\"220\"/\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cb\u003e📊 Cluster Metrics\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eClustering analysis\u003c/p\u003e\n        \u003cimg src=\"assets/cluster_metrics.png\" alt=\"Cluster Metrics\" width=\"220\"/\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cb\u003e📈 K-Means Elbow\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eOptimal cluster selection\u003c/p\u003e\n        \u003cimg src=\"assets/kmeans_elbow.png\" alt=\"K-Means Elbow\" width=\"220\"/\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cb\u003e🎯 HDBSCAN Cluster Map\u003c/b\u003e\u003cbr\u003e\n        \u003cp\u003eCluster visualization\u003c/p\u003e\n        \u003cimg src=\"assets/hdbscan_cluster_map.png\" alt=\"HDBSCAN Cluster Map\" width=\"220\"/\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/p\u003e\n\n---\n\n## 💾 Installation\n\n### 📦 PyPI\n\n```bash\npip install torchsom\n```\n\n### 🔧 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 \".[all]\"\n```\n\n---\n\n## 📚 Documentation\n\nComprehensive documentation is available at [opensource.michelin.io/TorchSOM](https://opensource.michelin.io/TorchSOM/)\n\n---\n\n## 📝 Citation\n\nIf you use `torchsom` in your academic, research or industrial work, 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## 🤝 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\u003c!-- - **GitHub Discussions**: [Ask questions and share ideas](https://github.com/michelin/TorchSOM/discussions) --\u003e\n\n---\n\n## 🙏 Acknowledgments\n\n- [Centre de Mathématiques Appliquées (CMAP)](https://cmap.ip-paris.fr/) at École Polytechnique\n- [Manufacture Française 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## 📄 License\n\n`torchsom` is licensed under the [Apache License 2.0](LICENSE). See the [LICENSE](LICENSE) file for details.\n\n---\n\n## 📚 Related Work and References\n\n### 📖 Foundational Literature Papers\n\n- Kohonen, T. (2001). [Self-Organizing Maps](https://link.springer.com/book/10.1007/978-3-642-56927-2). Springer.\n\n### 🔗 Related Softwares\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichelin%2Ftorchsom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichelin%2Ftorchsom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichelin%2Ftorchsom/lists"}