# michelin/torchsom architecture

> Architecture diagram of the GitHub repository michelin/torchsom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michelin/torchsom
- Repository: https://github.com/michelin/torchsom

## Overview

##### Project type and purpose
- Open-source Python library (“tool”) for building and visualizing Self-Organizing Maps (SOMs).
- Leverages PyTorch for GPU acceleration and seamless integration into ML pipelines.

##### File structure
- Top-level modules:
- torchsom/configs – model and visualization configuration
- torchsom/core – core SOM implementations (batch, growing, hierarchical)
- torchsom/utils – helper functions (distances, decay, initialization, metrics, grid, topology)
- torchsom/visualization – plotting and map-drawing utilities
- docs, notebooks, data, tests, CI/CD scripts
- External points: PyTorch, Jupyter notebooks, PyPI packaging.

##### README for insights
- Emphasis on GPU support, scalability, modular design.

##### Main components and their interactions
a. User Code (scripts or notebooks)
b. TorchSOM API
- Config Loader (torchsom/configs)
- SOM Engine (torchsom/core)
- Utilities (torchsom/utils)
- Visualizer (torchsom/visualization)
c. External Dependencies
- PyTorch (CPU/GPU computation)
- Jupyter (interactive demos)
- CI/CD (GitHub Actions)
- PyPI (distribution)
d. Data
- Input datasets (e.g., iris.csv)
- Output artifacts (plots, logs, model weights)

##### Architectural patterns and design principles
- Modular layering (Configs → Core → Utils → Visualization)
- Clear API boundary between user code and low-level SOM operations
- Separation of concerns: computation vs. configuration vs. plotting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and external systems
    User["User Code"]:::external
    DataAssets["Input Datasets"]:::external
    PyTorch["PyTorch"]:::external
    Jupyter["Jupyter Notebooks"]:::external
    CICD["CI/CD Workflow"]:::external
    PyPI["PyPI Distribution"]:::external

    %% TorchSOM API
    subgraph "TorchSOM API"
        subgraph "Configs"
            ConfigLoader["Config Loader"]:::config
        end
        subgraph "Core SOM Engine"
            BaseSOM["Base SOM"]:::core
            SOM["Standard SOM"]:::core
            GrowingSOM["Growing SOM"]:::core
            GrowingComp["Growing SOM Components"]:::core
            HierSOM["Hierarchical SOM"]:::core
            HierComp["Hierarchical SOM Components"]:::core
        end
        subgraph "Utilities"
            Distances["Distance Metrics"]:::utils
            Decay["Learning Rate Decay"]:::utils
            Neighborhood["Neighborhood Functions"]:::utils
            Grid["Grid Functions"]:::utils
            Topology["Topology Functions"]:::utils
            Initialization["Initialization Routines"]:::utils
            Metrics["Evaluation Metrics"]:::utils
        end
        subgraph "Visualization"
            BasePlot["Base Plotting Classes"]:::viz
            PlotConfig["Plot Configuration"]:::viz
        end
        Version["Versioning"]:::external
    end

    %% Data and Flow
    User -->|"loads data"| DataAssets
    DataAssets -->|"provides to"| ConfigLoader
    User -->|"invokes API"| ConfigLoader
    ConfigLoader -->|"initializes"| BaseSOM
    BaseSOM -->|"implements"| SOM
    SOM -->|"uses components"| BaseSOM
    SOM -->|"variant"| GrowingSOM
    GrowingSOM -->|"uses"| GrowingComp
    SOM -->|"variant"| HierSOM
    HierSOM -->|"uses"| HierComp
    BaseSOM -->|"calls"| Distances
    BaseSOM -->|"calls"| Decay
    BaseSOM -->|"calls"| Neighborhood
    BaseSOM -->|"calls"| Grid
    BaseSOM -->|"calls"| Topology
    BaseSOM -->|"calls"| Initialization
    BaseSOM -->|"calls"| Metrics
    BaseSOM -->|"outputs metrics"| BasePlot
    BasePlot -->|"configured by"| PlotConfig
    BasePlot -->|"renders to"| User

    %% External integrations
    subgraph "Integrations"
        TorchSOM["TorchSOM API"]
    end
    TorchSOM <-->|"compute calls"| PyTorch
    User <-->|"interactive"| Jupyter
    TorchSOM -->|"tested by"| CICD
    TorchSOM -->|"packaged to"| PyPI

    %% Click Events
    click ConfigLoader "https://github.com/michelin/torchsom/blob/main/torchsom/configs/som_config.py"
    click BaseSOM "https://github.com/michelin/torchsom/blob/main/torchsom/core/base_som.py"
    click SOM "https://github.com/michelin/torchsom/blob/main/torchsom/core/som.py"
    click GrowingSOM "https://github.com/michelin/torchsom/blob/main/torchsom/core/growing/growing_som.py"
    click GrowingComp "https://github.com/michelin/torchsom/blob/main/torchsom/core/growing/components.py"
    click HierSOM "https://github.com/michelin/torchsom/blob/main/torchsom/core/hierarchical/hierarchical_som.py"
    click HierComp "https://github.com/michelin/torchsom/blob/main/torchsom/core/hierarchical/components.py"
    click Distances "https://github.com/michelin/torchsom/blob/main/torchsom/utils/distances.py"
    click Decay "https://github.com/michelin/torchsom/blob/main/torchsom/utils/decay.py"
    click Neighborhood "https://github.com/michelin/torchsom/blob/main/torchsom/utils/neighborhood.py"
    click Grid "https://github.com/michelin/torchsom/blob/main/torchsom/utils/grid.py"
    click Topology "https://github.com/michelin/torchsom/blob/main/torchsom/utils/topology.py"
    click Initialization "https://github.com/michelin/torchsom/blob/main/torchsom/utils/initialization.py"
    click Metrics "https://github.com/michelin/torchsom/blob/main/torchsom/utils/metrics.py"
    click BasePlot "https://github.com/michelin/torchsom/blob/main/torchsom/visualization/base.py"
    click PlotConfig "https://github.com/michelin/torchsom/blob/main/torchsom/visualization/config.py"
    click Version "https://github.com/michelin/torchsom/blob/main/torchsom/version.py"
    click DocsConfigs "https://github.com/michelin/torchsom/blob/main/docs/source/api/configs.rst"
    click DocsCore "https://github.com/michelin/torchsom/blob/main/docs/source/api/core.rst"
    click DocsUtils "https://github.com/michelin/torchsom/blob/main/docs/source/api/utils.rst"
    click DocsViz "https://github.com/michelin/torchsom/blob/main/docs/source/api/visualization.rst"
    click CICD "https://github.com/michelin/torchsom/blob/main/.github/workflows/docs.yml"

    %% Styling
    classDef core fill:#ADD8E6,stroke:#000;
    classDef utils fill:#90EE90,stroke:#000;
    classDef config fill:#FFD700,stroke:#000;
    classDef viz fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
    class ConfigLoader config
    class BaseSOM,SOM,GrowingSOM,GrowingComp,HierSOM,HierComp core
    class Distances,Decay,Neighborhood,Grid,Topology,Initialization,Metrics utils
    class BasePlot,PlotConfig viz
    class User,DataAssets,PyTorch,Jupyter,CICD,PyPI,Version external
```
