# nishi951/torch-named-linops architecture

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

- Interactive diagram: https://gitdiagram.com/nishi951/torch-named-linops
- Repository: https://github.com/nishi951/torch-named-linops

## Overview

##### Project Type and Purpose
- This is an open-source Python library (“torch-named-linops”) providing a flexible abstraction for linear operators in PyTorch.
- Key purpose: allow users to create, compose, and apply “linops” (linear operators) with named dimensions, support GPU execution, automatic differentiation, and optional Triton backends.

##### High-Level File Structure Analysis
- Top-level: CI/CD (`.github/workflows`), packaging (`pyproject.toml`, `LICENSE.txt`), docs (`docs/`), dev helpers (`dev/`), source code (`src/torchlinops/`), tests embedded under `src/torchlinops/tests`.
- Under `src/torchlinops/`:
- `linops/` – core operator classes (Dense, Diagonal, FFT, Chain, etc.).
- `functional/` – stateless functional implementations (indexing, interpolation, unfolding), some with Triton backends.
- `alg/` – higher-level algorithms built atop linops (PCG, power method, polynomial).
- `utils/` – shared helper functions (device management, batching, I/O, FFT wrappers).
- `tests/` – unit and benchmark tests for each submodule.

##### README Insights
- Core features: named dimensions, `.H`/.N` for adjoint/normal ops, composition wrappers (Add, Chain), batch wrappers (Batch, MPBatch), Triton acceleration.
- Dependencies: PyTorch, optional Triton.
- Developer docs in `docs/` using Sphinx.

##### Main Components
a. Source Code Modules
- Linops Module: object-oriented classes for fundamental ops
- Functional Module: pure functions (index, interp, unfold) + optional Triton kernels
- Algorithms Module: solvers that combine linops
- Utils Module: underpinning services (device, batching, logging, file I/O)
b. External Dependencies
- PyTorch core
- Triton (for accelerated kernels)
- Python packaging tools (pip, setuptools via `pyproject.toml`)
c. Supporting Systems
- CI/CD pipelines (`test-python.yml`, `release.yml`)
- Documentation system (Sphinx under `docs/`)
- Development tools (scripts under `dev/` for profiling and tools)

##### Relationships & Interactions
- Linops classes depend on Utils for device dispatch, batching, and logging.
- Functional layer offers building blocks for both linops implementations and direct user calls; some functions invoke Triton kernels if available.
- Algorithms module imports Linops to build iterative solvers.
- Tests validate each module in isolation.
- CI workflows run tests, build docs, and package releases.

##### Architectural Patterns & Principles
- Modular library design: clear separation of interfaces (linops), implementations (functional), and algorithms.
- Dependency inversion: core classes rely on abstracted utilities rather than raw PyTorch calls.
- Plugin-friendly: Triton backends can be swapped in for performance.
- Composition pattern: Chain/Add linops to build composite operators.
- Batch processing: wrappers (Batch, MPBatch) for scaling computations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Core Code Modules"
        direction TB
        Linops["Linops Module"]:::core
        Functional["Functional Module"]:::core
        Algorithms["Algorithms Module"]:::core
        Utils["Utils Module"]:::core
    end

    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch"]:::external
        Triton["Triton (optional Triton)"]:::externalOptional
        Packaging["Packaging System (pyproject.toml)"]:::external
    end

    subgraph "Supporting Systems"
        direction TB
        CI["CI/CD Pipelines"]:::support
        Docs["Documentation (Sphinx)"]:::support
        Dev["Development Tools"]:::support
    end

    subgraph "Testing"
        direction TB
        Tests["Test Suites"]:::support
    end

    %% Relationships
    Linops -->|"uses"| Utils
    Functional -->|"imports"| Utils
    Functional -->|"invokes"| Triton
    Algorithms -->|"builds on"| Linops
    PyTorch --> Linops
    PyTorch --> Functional
    PyTorch --> Algorithms
    PyTorch --> Utils
    Tests --> Linops
    Tests --> Functional
    Tests --> Algorithms
    Tests --> Utils
    CI -->|"runs"| Tests
    CI -->|"builds"| Docs
    CI -->|"packages via"| Packaging

    %% Click Events
    click Linops "https://github.com/nishi951/torch-named-linops/tree/main/src/torchlinops/linops/"
    click Functional "https://github.com/nishi951/torch-named-linops/tree/main/src/torchlinops/functional/"
    click Algorithms "https://github.com/nishi951/torch-named-linops/tree/main/src/torchlinops/alg/"
    click Utils "https://github.com/nishi951/torch-named-linops/tree/main/src/torchlinops/utils/"
    click Tests "https://github.com/nishi951/torch-named-linops/tree/main/src/torchlinops/tests/"
    click CI "https://github.com/nishi951/torch-named-linops/blob/main/.github/workflows/test-python.yml"
    click CI "https://github.com/nishi951/torch-named-linops/blob/main/.github/workflows/release.yml"
    click Docs "https://github.com/nishi951/torch-named-linops/tree/main/docs/"
    click Dev "https://github.com/nishi951/torch-named-linops/tree/main/dev/"
    click Packaging "https://github.com/nishi951/torch-named-linops/blob/main/pyproject.toml"
    click Packaging "https://github.com/nishi951/torch-named-linops/blob/main/LICENSE.txt"
    click Packaging "https://github.com/nishi951/torch-named-linops/blob/main/README.md"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef external fill:#DFFFE0,stroke:#22863a,stroke-width:1px;
    classDef externalOptional fill:#DFFFE0,stroke:#22863a,stroke-width:1px,stroke-dasharray: 5 5;
    classDef support fill:#FFF5B1,stroke:#b08800,stroke-width:1px;
```
