# lightning-ai/torchmetrics architecture

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

- Interactive diagram: https://gitdiagram.com/lightning-ai/torchmetrics
- Repository: https://github.com/lightning-ai/torchmetrics

## Overview

##### Project type and purpose
TorchMetrics is an open-source Python library (packaged via PyPI/Conda) providing standardized, distributed, GPU-accelerated metrics for PyTorch. It is not a full-stack app, but a layered library with:
- Module-based API (stateful `Metric` classes)
- Functional API (stateless functions)
- Domain-specific implementations (audio, image, text, etc.)
- Utilities for distributed synchronization, plotting, and packaging
- Continuous integration, documentation, and sample code

##### Directory-level architecture insights
- src/torchmetrics – core code, grouped by API type (module vs functional) and domain
- utilities & wrappers – shared helpers, distributed reductions, plotting
- docs/ & _samples/ & examples/ – documentation sources, Sphinx config, usage scripts
- dockers/, .devcontainer/ – development containers for local testing and GPU CI
- .github/, .azure/ – CI/CD workflows, caching, unit & integration pipelines
- tests/ – unit tests and Lightning integration tests
- packaging files – setup.py, pyproject.toml, requirements, Makefile

##### Key components
A. API Layer
– Module-based API (`torchmetrics.Metric` subclasses)
– Functional API (`torchmetrics.functional.*` functions)
Relationship: both sit at top, called by user code.
B. Domain Implementations
Organization: each domain folder contains module & functional code; share base classes.
C. Core Library & Utilities
– Base classes (`Metric`, `BaseMetric`), `state` management, `dist_reduce_fx`
– Distributed synchronization (`torch.distributed` wrappers), device placement
– Plotting utilities and wrappers for batched accumulation
D. External Dependencies
– PyTorch backend (tensor operations, autograd, dists)
– Optional: SciPy, matplotlib (for certain metrics or plotting), pretrained weights for LPIPS, DISTS
E. Packaging & CI/CD
– PyPI / Conda packaging (setup.py, pyproject.toml)
– GitHub Actions & Azure pipelines (linting, tests, docs build, Docker builds)
– Devcontainer & Dockerfiles for reproducible development/CI

- User Application → API Layer (calls)
- API Layer → Domain Implementations → Core Utilities → PyTorch
- API Layer ←– Dataset & Model (inputs/outputs)
- Utilities → Distributed Backend (all-reduce across GPUs/nodes)
- Packaging → Registry (PyPI/Conda)
- CI/CD Workflows → GitHub/Azure

##### Architectural patterns & principles
- Layered architecture: API → Domain modules → Core → External
- Plugin-like domains: new metrics drop into domain folder, auto-discovered in docs
- Separation of concerns: functional vs module APIs, metric code vs utilities
- Distributed-first design: states annotated with reduction functions, automatic sync

##### Important details not to miss
- The dual API (module vs functional) at the top layer
- Domain folder structure illustrating clear separation
- Automatic state reduction and device placement via utilities
- Continuous integration and publishing as integral “components” of the system

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User layer
    User["User Application"]:::external

    %% API Layer
    subgraph "API Layer"
        ModuleAPI["Module-based API"]:::api
        FunctionalAPI["Functional API"]:::api
    end

    %% Domain Implementations
    subgraph "Domain Implementations"
        Classification["Classification"]:::domain
        Regression["Regression"]:::domain
        Clustering["Clustering"]:::domain
        Audio["Audio"]:::domain
        Image["Image"]:::domain
        Text["Text"]:::domain
        Detection["Detection"]:::domain
        Retrieval["Retrieval"]:::domain
        Segmentation["Segmentation"]:::domain
        Multimodal["Multimodal"]:::domain
        Nominal["Nominal"]:::domain
        Pairwise["Pairwise"]:::domain
        Shape["Shape"]:::domain
    end

    %% Core Utilities
    subgraph "Core & Utilities"
        BaseClasses["Base Classes & State"]:::core
        Utilities["Utilities & Distributed Sync"]:::core
        Wrappers["Wrappers & Batched Accumulation"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PyTorch[(PyTorch)]:::external
        SciPy[(SciPy)]:::external
        Matplotlib[(Matplotlib)]:::external
    end

    %% Packaging & CI/CD
    subgraph "Packaging & CI/CD"
        Packaging["Packaging Config"]:::infra
        PyPI[(PyPI / Conda Registry)]:::infra
        GitHub[(GitHub Actions)]:::infra
        Azure[(Azure Pipelines)]:::infra
        DockerDev["Devcontainers & Docker"]:::infra
    end

    %% Legend
    subgraph "Legend"
        L1["Blue: API Layer"]:::api
        L2["Green: Domain Implementations"]:::domain
        L3["Yellow: Core & Utilities"]:::core
        L4["Gray: External Dependencies"]:::external
        L5["Orange: Packaging & CI/CD"]:::infra
    end

    %% Connections
    User -->|"calls"| ModuleAPI
    User -->|"calls"| FunctionalAPI

    ModuleAPI -->|"uses"| Classification
    FunctionalAPI -->|"uses"| Classification

    Classification -->|"implemented via"| BaseClasses
    Regression -->|"implemented via"| BaseClasses
    Clustering -->|"implemented via"| BaseClasses
    Audio -->|"implemented via"| BaseClasses
    Image -->|"implemented via"| BaseClasses
    Text -->|"implemented via"| BaseClasses
    Detection -->|"implemented via"| BaseClasses
    Retrieval -->|"implemented via"| BaseClasses
    Segmentation -->|"implemented via"| BaseClasses
    Multimodal -->|"implemented via"| BaseClasses
    Nominal -->|"implemented via"| BaseClasses
    Pairwise -->|"implemented via"| BaseClasses
    Shape -->|"implemented via"| BaseClasses

    BaseClasses -->|"relies on"| Utilities
    Utilities -->|"syncs with"| PyTorch
    Wrappers -->|"wraps over"| Utilities

    Packaging -->|"publishes to"| PyPI
    GitHub -->|"triggers build/test"| Packaging
    Azure -->|"triggers build/test"| Packaging
    DockerDev -->|"used in"| GitHub
    DockerDev -->|"used in"| Azure

    %% Click Events
    click ModuleAPI "https://github.com/lightning-ai/torchmetrics/blob/master/src/torchmetrics/metric.py"
    click FunctionalAPI "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/functional/"
    click Classification "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/classification"
    click Regression "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/regression"
    click Clustering "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/clustering"
    click Audio "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/audio"
    click Image "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/image"
    click Text "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/text"
    click Detection "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/detection"
    click Retrieval "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/retrieval"
    click Segmentation "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/segmentation"
    click Multimodal "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/multimodal"
    click Nominal "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/nominal"
    click Pairwise "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/pairwise"
    click Shape "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/shape"
    click BaseClasses "https://github.com/lightning-ai/torchmetrics/blob/master/src/torchmetrics/collections.py"
    click Utilities "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/utilities/"
    click Wrappers "https://github.com/lightning-ai/torchmetrics/tree/master/src/torchmetrics/wrappers/"
    click Packaging "https://github.com/lightning-ai/torchmetrics/blob/master/setup.py"
    click PyPI "https://github.com/lightning-ai/torchmetrics/tree/master/PyPI"
    click GitHub "https://github.com/lightning-ai/torchmetrics/tree/master/.github/workflows/"
    click Azure "https://github.com/lightning-ai/torchmetrics/tree/master/.azure/"
    click DockerDev "https://github.com/lightning-ai/torchmetrics/tree/master/.devcontainer/Dockerfile"

    %% Styles
    classDef api fill:#cce5ff,stroke:#2b6cb0,color:#2b6cb0;
    classDef domain fill:#d4edda,stroke:#276749,color:#276749;
    classDef core fill:#fff3cd,stroke:#92400e,color:#92400e;
    classDef external fill:#e2e8f0,stroke:#4a5568,color:#4a5568;
    classDef infra fill:#ffe5b4,stroke:#dd6b20,color:#dd6b20;
```
