# ensta-u2is-ai/torch-uncertainty architecture

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

- Interactive diagram: https://gitdiagram.com/ensta-u2is-ai/torch-uncertainty
- Repository: https://github.com/ensta-u2is-ai/torch-uncertainty

## Overview

##### Project Type and Purpose
- This is an open-source Python package (“torch_uncertainty”) providing a modular framework for uncertainty quantification in deep neural networks.
- It delivers building blocks (layers, models, losses, metrics), data handling (datasets, datamodules, transforms), training/evaluation routines, CLI scripts, tutorials, and an experiments harness.

##### File Structure Overview
- Top-level folders:
- torch_uncertainty/   ← core library modules
- auto_tutorial_source/← Jupyter-style tutorial source code
- experiments/         ← runnable experiment scripts + YAML configs
- docs/                ← Sphinx documentation source
- scripts/             ← auxiliary scripts (e.g., to_hub_format.py)
- tests/               ← pytest-based unit and integration tests
- CI/deployment:
- .github/workflows/   ← build-docs, test runner, PyPI publishing
- Dockerfile + docker/ ← containerization for contributors
- Config files: pyproject.toml, codecov.yml, pre-commit, .gitignore

##### Key Components (to represent as separate blocks)
A. Data Layer
- torch_uncertainty/datasets/       ← raw dataset classes & utilities
- torch_uncertainty/datamodules/    ← PyTorch Lightning–style DataModules
- torch_uncertainty/transforms/     ← data augmentations & corruptions
B. Model Layer
- torch_uncertainty/layers/         ← custom layers (Bayesian, ensembling)
- torch_uncertainty/models/         ← backbone architectures + wrappers
- torch_uncertainty/losses/         ← task-specific loss functions
C. Metric & Post-processing Layer
- torch_uncertainty/metrics/        ← performance & uncertainty metrics
- torch_uncertainty/post_processing/← calibration, conformal, Laplace, etc.
D. Orchestration & Utilities
- torch_uncertainty/routines/       ← high-level train/eval loops for tasks
- torch_uncertainty/utils/          ← CLI helpers, checkpointing, plotting, evaluation loops
- torch_uncertainty/callbacks/      ← custom PyTorch Lightning callbacks
- torch_uncertainty/optim/          ← specialized optimizers & recipes
E. User-Facing Interfaces
- CLI entrypoint (utils/cli.py → console_scripts)
- scripts/to_hub_format.py
- auto_tutorial_source/              ← self-contained tutorials exposing the API
F. Experiments Harness
- experiments/*/                     ← domain-specific scripts + YAML configs (classification, regression, segmentation, depth)

##### Relationships & Data Flow
1. User invokes CLI or Python API → selects a `routines` function (e.g., classification.train).
2. Routines instantiate a DataModule (datasets + transforms) → PyTorch Dataloaders.
3. Routines instantiate a model:
- Base architecture (models/) wraps layers (layers/)
- Optionally wrapped by ensembling or Bayesian wrappers (models/wrappers/)
4. Routines define loss (losses/) and metrics (metrics/) and attach callbacks (callbacks/).
5. Routines / Lightning Trainer run training:
- Data → Model → Loss → backprop → checkpoint via callbacks
6. After training: post-processing modules (post_processing/) calibrate or conformal predict.
7. Results plotted via utils/plotting or exported via scripts.
8. Experiments harness reads YAML configs → calls same routines with config parameters.

##### Architectural Patterns & Principles
- Modular plugin architecture: each capability (dataset, layer, model, loss, metric, post-processor) lives in its own namespace.
- Separation of concerns: data handling ↔ model definition ↔ training orchestration ↔ post-processing.
- Extensibility points:
- New layer under layers/
- New model or wrapper under models/
- New metric under metrics/
- New post-processor under post_processing/
- CI/CD pipeline automates testing, docs build, PyPI publishing.
- Docker container for reproducible contributor environment.

##### CI/CD & Documentation
- Sphinx docs generation: docs/source → ReadTheDocs/GitHub Pages.
- Dockerfile → Docker Hub (optional).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        direction TB
        CLIEntrypoint["CLI Entrypoint"]:::external
        API["Python API"]:::external
        HubScript["Hub Format Script"]:::external
        Tutorials["Tutorials Source"]:::external
    end

    %% Core Library Modules
    subgraph "torch_uncertainty"
        direction TB

        subgraph "Data Layer"
            direction TB
            Datasets["Datasets"]:::data
            DataModules["DataModules"]:::data
            Transforms["Transforms"]:::data
        end

        subgraph "Model Layer"
            direction TB
            Layers["Layers"]:::core
            Models["Models & Wrappers"]:::core
            Losses["Loss Functions"]:::core
        end

        subgraph "Metric & Post-processing"
            direction TB
            Metrics["Metrics"]:::post
            PostProcessing["Post-processing"]:::post
        end

        subgraph "Orchestration & Utilities"
            direction TB
            Routines["Routines"]:::orch
            Utils["Utilities"]:::orch
            Callbacks["Callbacks"]:::orch
            Optimizers["Optimizers & Recipes"]:::orch
        end
    end

    %% Experiments Harness
    Experiments["Experiments Harness"]:::external

    %% External Processes
    subgraph "External Processes"
        direction TB
        CI["GitHub Actions CI/CD"]:::external
        Docs["Docs Generation"]:::external
        Docker["Docker Build"]:::external
        PyPI["PyPI Publish"]:::external
    end

    %% Data/Control Flow
    CLIEntrypoint -->|"invokes"| Routines
    API -->|"invokes"| Routines
    Tutorials -->|"demonstrates"| Routines

    Routines -->|"instantiates"| DataModules
    DataModules -->|"loads"| Datasets
    DataModules -->|"applies"| Transforms

    Routines -->|"builds"| Models
    Models -->|"wraps"| Layers

    Routines -->|"defines"| Losses
    Routines -->|"computes"| Metrics
    Routines -->|"attaches"| Callbacks
    Routines -->|"uses"| Optimizers

    Routines -->|"runs training"| Utils
    Utils -->|"trains model"| Models

    Routines -->|"post-process"| PostProcessing
    PostProcessing -->|"outputs results"| Utils

    Utils -->|"exports"| HubScript

    Experiments -->|"reads configs & calls"| Routines

    CI -->|"triggers docs build"| Docs
    CI -->|"builds image"| Docker
    CI -->|"publishes package"| PyPI

    %% Click Events
    click Datasets "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/datasets/"
    click DataModules "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/datamodules/"
    click Transforms "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/transforms/"
    click Layers "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/layers/"
    click Models "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/models/"
    click Losses "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/losses/"
    click Metrics "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/metrics/"
    click PostProcessing "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/post_processing/"
    click Routines "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/routines/"
    click Utils "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/utils/"
    click Callbacks "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/callbacks/"
    click Optimizers "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/torch_uncertainty/optim/"
    click CLIEntrypoint "https://github.com/ensta-u2is-ai/torch-uncertainty/blob/main/torch_uncertainty/utils/cli.py"
    click HubScript "https://github.com/ensta-u2is-ai/torch-uncertainty/blob/main/scripts/to_hub_format.py"
    click Tutorials "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/auto_tutorial_source/"
    click Experiments "https://github.com/ensta-u2is-ai/torch-uncertainty/tree/main/experiments/"

    %% Styles
    classDef data fill:#b3e6b3,stroke:#2d7a2d,color:#1a3d1a
    classDef core fill:#cce0ff,stroke:#0047b3,color:#002b80
    classDef post fill:#ffd9b3,stroke:#b36b00,color:#663d00
    classDef orch fill:#fff2b3,stroke:#b38f00,color:#806300
    classDef external fill:#e6e6e6,stroke:#999999,color:#333333
```
