# dotnet/torchsharp architecture

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

- Interactive diagram: https://gitdiagram.com/dotnet/torchsharp
- Repository: https://github.com/dotnet/torchsharp

## Overview

##### Project type and purpose
- This is not an end-user application but an open-source .NET wrapper library over PyTorch (LibTorch).  It provides managed bindings (TorchSharp) plus two “extension” libraries (TorchAudio and TorchVision), delivered as NuGet packages.  It also includes examples (C# and F#), native‐code glue, packaging projects, tests, and documentation.

##### File structure
- Top-level solution (TorchSharp.sln) with Directory.Build.props/targets for common MSBuild settings.
- build/ and azure-pipelines.yml: CI build orchestration and signing.
- src/Native: CMake‐based native glue layer (LibTorchSharp C++ code) that builds a small adaptor DLL for PInvoke.
- src/TorchSharp: managed code organized into sub-folders (PInvoke, JIT, NN, Tensor, Optimizers, Utils, etc.).  PInvoke layer directly maps to the native adaptor.
- src/TorchAudio and src/TorchVision: extension libraries built on top of TorchSharp core.
- src/Examples and src/FSharp.Examples: sample applications illustrating usage.
- src/Redist: rules for shipping native LibTorch binaries.
- pkg/: MSBuild nupkgproj files to generate NuGet packages (TorchSharp, TorchAudio, TorchVision, backends).
- test/: xUnit tests and notebooks validating managed + native behavior.
- docfx/: static site generator content for documentation.

##### README for additional insights
- Confirms it’s a “wrapper library” staying close to the PyTorch API, distributed via NuGet.
- Highlights supported backends (CPU/CUDA), packaging strategy, and developer notes.

##### Main components and their relationships
a. Native Layer
- External LibTorch binaries (downloaded via NuGet or installed locally)
- src/Native: builds LibTorchSharp adaptor library via CMake (Windows/Linux/macOS)
Relationship: Managed code calls into this adaptor via PInvoke.
b. PInvoke Layer
- src/TorchSharp/PInvoke: auto-generated and handwritten C# signatures for the native adaptor
Relationship: Exposes low-level LibTorch APIs to the managed world.
c. Managed Wrapper
- Core: src/TorchSharp (Tensor, NN modules, Autograd, JIT, Optimizers, Distributions, DataLoader, etc.)
- Extensions: src/TorchAudio, src/TorchVision
Relationship: All high-level APIs reference the PInvoke layer to operate on native tensors and modules.
d. Packaging
- pkg/: one .nupkgproj per library or backend
Relationship: Each packaging project references the corresponding src project(s) and Redist definitions.
e. Examples & Tests
- Examples (C# & F#): depend on TorchSharp core (+ optionally TorchAudio/Vision) to demonstrate usage.
- Tests: validate correctness of core and extensions on CPU and CUDA backends.
f. Build & CI
- build/ + azure-pipelines.yml: orchestrate native build, managed build, test, signing, and NuGet packaging.
g. Documentation
- docfx/: builds static docs (memory management, modules, saving/loading, torchscript)
Relationship: Pulls XML doc comments from managed code and articles from docfx/articles.

##### Architectural patterns & design principles
- Layered architecture: Native → PInvoke → Managed core → Extension libraries
- Single responsibility: each project focuses on one aspect (core wrapper, audio, vision, packaging)
- Convention over configuration: Directory.Build.* centralizes settings
- CI-as-code: Azure Pipelines and build templates under build/ci ensure reproducible builds

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        LibTorch["LibTorch Native Binaries"]:::native
    end

    %% Native Adaptor Layer
    subgraph "Native Adaptor" 
        AdaptorDLL["LibTorchSharp Adaptor (DLL)"]:::native
        CMakeLists["CMakeLists.txt"]:::config
        BuildProj["build.proj"]:::config
        BuildSh["build.sh"]:::config
        BuildCmd["build.cmd"]:::config
    end

    %% PInvoke Layer
    subgraph "PInvoke Layer"
        PInvoke["TorchSharp.PInvoke"]:::pinvoke
    end

    %% Managed Core
    subgraph "Managed Core"
        Core["TorchSharp (src/TorchSharp)"]:::managed
    end

    %% Extension Libraries
    subgraph "Extension Libraries"
        Audio["TorchAudio"]:::extension
        Vision["TorchVision"]:::extension
    end

    %% Samples & Tests
    subgraph "Samples & Tests"
        ExamplesCS["Examples (C#)"]:::samples
        ExamplesFS["Examples (F#)"]:::samples
        Tests["xUnit Tests"]:::samples
        TestsCuda["xUnit Tests with CUDA"]:::samples
        Notebooks["Notebooks"]:::samples
    end

    %% Packaging Projects
    subgraph "Packaging Projects"
        PackageCore["TorchSharp.nupkgproj"]:::packaging
        PackageCoreSym["TorchSharp.symbols.nupkgproj"]:::packaging
        PackageAudio["TorchAudio.nupkgproj"]:::packaging
        PackageVision["TorchVision.nupkgproj"]:::packaging
        PackageCPU["TorchSharp-cpu.nupkgproj"]:::packaging
        PackageCudaLinux["TorchSharp-cuda-linux.nupkgproj"]:::packaging
        PackageCudaWin["TorchSharp-cuda-windows.nupkgproj"]:::packaging
        Redist["Redist Rules (src/Redist)"]:::packaging
        CommonPkg["Common Packaging Targets (pkg/common)"]:::config
    end

    %% CI/CD Orchestration
    subgraph "CI/CD"
        CI["build/"]:::cicd
        JobTemplate["ci/job-template.yml"]:::config
        AzurePipelines["azure-pipelines.yml"]:::cicd
    end

    %% Documentation
    subgraph "Documentation"
        DocFX["docfx/"]:::docs
    end

    %% Configuration
    DirectoryPropsTop["Directory.Build.props"]:::config
    DirectoryTargetsTop["Directory.Build.targets"]:::config
    DirectoryPropsSrc["src/Directory.Build.props"]:::config
    DirectoryTargetsSrc["src/Directory.Build.targets"]:::config
    Solution["TorchSharp.sln"]:::config

    %% Relationships
    Core -->|"calls"| PInvoke
    PInvoke -->|"PInvoke to"| AdaptorDLL
    AdaptorDLL -->|"links to"| LibTorch

    Audio -->|"depends on"| Core
    Vision -->|"depends on"| Core

    ExamplesCS -->|"uses"| Core
    ExamplesCS -->|"opts add"| Audio
    ExamplesCS -->|"opts add"| Vision
    ExamplesFS -->|"uses"| Core

    Tests -->|"tests"| Core
    Tests -->|"uses Redist"| Redist
    TestsCuda -->|"tests CUDA"| Core
    Notebooks -->|"validates"| Core

    PackageCore -->|"packs"| Core
    PackageCoreSym -->|"packs symbols"| Core
    PackageAudio -->|"packs"| Audio
    PackageVision -->|"packs"| Vision
    PackageCPU -->|"packs CPU backend"| Redist
    PackageCudaLinux -->|"packs CUDA linux"| Redist
    PackageCudaWin -->|"packs CUDA windows"| Redist
    CommonPkg -->|"imported by"| PackageCore
    CommonPkg -->|"imported by"| PackageAudio

    CI -->|"orchestrates"| AdaptorDLL
    CI -->|"orchestrates"| Core
    CI -->|"orchestrates"| Tests
    CI -->|"orchestrates"| PackageCore
    CI -->|"runs"| AzurePipelines
    JobTemplate -->|"used in"| CI

    DocFX -->|"generates docs from"| Core
    DocFX -->|"uses articles in"| DocFX

    Solution -->|"includes all projects"| Core
    Solution --> Solution -->|"includes"| Audio
    Solution --> Solution -->|"includes"| Vision

    DirectoryPropsTop -->|"imported by"| Core
    DirectoryTargetsTop -->|"imported by"| Core
    DirectoryPropsSrc -->|"overrides"| Core
    DirectoryTargetsSrc -->|"overrides"| Core

    %% Click Events
    click AdaptorDLL "https://github.com/dotnet/torchsharp/tree/main/src/Native/LibTorchSharp"
    click CMakeLists "https://github.com/dotnet/torchsharp/blob/main/src/Native/CMakeLists.txt"
    click BuildProj "https://github.com/dotnet/torchsharp/blob/main/src/Native/build.proj"
    click BuildSh "https://github.com/dotnet/torchsharp/blob/main/src/Native/build.sh"
    click BuildCmd "https://github.com/dotnet/torchsharp/blob/main/src/Native/build.cmd"
    click PInvoke "https://github.com/dotnet/torchsharp/tree/main/src/TorchSharp/PInvoke"
    click Core "https://github.com/dotnet/torchsharp/tree/main/src/TorchSharp"
    click Audio "https://github.com/dotnet/torchsharp/tree/main/src/TorchAudio"
    click Vision "https://github.com/dotnet/torchsharp/tree/main/src/TorchVision"
    click ExamplesCS "https://github.com/dotnet/torchsharp/tree/main/src/Examples"
    click ExamplesFS "https://github.com/dotnet/torchsharp/blob/main/src/FSharp.Examples"
    click PackageCore "https://github.com/dotnet/torchsharp/blob/main/pkg/TorchSharp/TorchSharp.nupkgproj"
    click PackageCoreSym "https://github.com/dotnet/torchsharp/blob/main/pkg/TorchSharp/TorchSharp.symbols.nupkgproj"
    click PackageAudio "https://github.com/dotnet/torchsharp/blob/main/pkg/TorchAudio/TorchAudio.nupkgproj"
    click PackageVision "https://github.com/dotnet/torchsharp/blob/main/pkg/TorchVision/TorchVision.nupkgproj"
    click PackageCPU "https://github.com/dotnet/torchsharp/blob/main/pkg/TorchSharp-cpu/TorchSharp-cpu.nupkgproj"
    click PackageCudaLinux "https://github.com/dotnet/torchsharp/blob/main/pkg/TorchSharp-cuda-linux/TorchSharp-cuda-linux.nupkgproj"
    click PackageCudaWin "https://github.com/dotnet/torchsharp/blob/main/pkg/TorchSharp-cuda-windows/TorchSharp-cuda-windows.nupkgproj"
    click Redist "https://github.com/dotnet/torchsharp/tree/main/src/Redist"
    click Tests "https://github.com/dotnet/torchsharp/tree/main/test/TorchSharpTest"
    click TestsCuda "https://github.com/dotnet/torchsharp/blob/main/test/TorchSharpTest.WithCudaBinaries"
    click Notebooks "https://github.com/dotnet/torchsharp/tree/main/test/notebooks"
    click CI "https://github.com/dotnet/torchsharp/tree/main/build/"
    click JobTemplate "https://github.com/dotnet/torchsharp/blob/main/build/ci/job-template.yml"
    click AzurePipelines "https://github.com/dotnet/torchsharp/blob/main/azure-pipelines.yml"
    click DocFX "https://github.com/dotnet/torchsharp/tree/main/docfx/"
    click DirectoryPropsTop "https://github.com/dotnet/torchsharp/blob/main/Directory.Build.props"
    click DirectoryTargetsTop "https://github.com/dotnet/torchsharp/blob/main/Directory.Build.targets"
    click DirectoryPropsSrc "https://github.com/dotnet/torchsharp/blob/main/src/Directory.Build.props"
    click DirectoryTargetsSrc "https://github.com/dotnet/torchsharp/blob/main/src/Directory.Build.targets"
    click Solution "https://github.com/dotnet/torchsharp/blob/main/TorchSharp.sln"
    click CommonPkg "https://github.com/dotnet/torchsharp/tree/main/pkg/common"

    %% Styles
    classDef native fill:#ccffcc,stroke:#008000
    classDef pinvoke fill:#ccf2ff,stroke:#0066cc
    classDef managed fill:#cce0ff,stroke:#0033cc
    classDef extension fill:#ffe0b2,stroke:#ff8000
    classDef samples fill:#f0f0f0,stroke:#666666
    classDef packaging fill:#dddddd,stroke:#888888
    classDef cicd fill:#fff2cc,stroke:#cc9900
    classDef docs fill:#efefef,stroke:#999999
    classDef config fill:#f5f5f5,stroke:#aaaaaa
```
