# pytorch/xla architecture

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

- Interactive diagram: https://gitdiagram.com/pytorch/xla
- Repository: https://github.com/pytorch/xla

## Overview

##### Project type and purpose
- PyTorch/XLA is an open-source library and toolchain that connects PyTorch to the XLA compiler stack (TPU, GPU, CPU).
- It provides a Python API, C++ bindings, and backend plugins (PJRT) to compile and execute PyTorch workloads on accelerators.

##### File structure
- Top-level modules/directories:
- torch_xla/         – Python package (API, internal modules, bindings)
- torch_xla/csrc/    – C++ implementation of tensor ops, runtime, PJRT clients
- plugins/           – PJRT plugin implementations (CPU plugin, CUDA plugin)
- codegen/           – Code-generation scripts for lazy tensor definitions
- examples/, docs/, benchmarks/ – consumer-facing examples, user guides, performance tests
- test/              – unit/integration tests (Python and C++)
- infra/, docker/    – CI/CD infrastructure (Ansible, Terraform), Dockerfiles
- bazel/, BUILD, WORKSPACE – Bazel build definitions
- Architectural patterns:
- Layered architecture (Python API → core Python modules → C++ bindings → runtime → XLA compiler → device)
- Plugin pattern (PJRT plugins loaded at runtime)
- Separation of concerns (core, experimental, distributed, debugging, profiling)

##### README for insights
- Confirms support for TPU, GPU, CPU via XLA and PJRT.
- Describes Python usage modes (single-process, multi-process, SPMD).
- Mentions key components: torch_xla.step(), XLA device assignment, xm.optimizer_step(), torch_xla.launch().

##### Final advice
- Both build/deployment (Bazel, Docker, infra) and runtime flows (API → runtime → device)
- Special flows (distributed training, SPMD, lazy tracing) to show where control splits

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Flow
    User["User Code (examples/)"]:::external
    subgraph "Python API Layer"
        direction TB
        API["torch_xla/"]:::onpath
        AMP["torch_xla/amp/"]:::onpath
        Dynamo["torch_xla/_dynamo/"]:::onpath
        CorePy["torch_xla/core/"]:::onpath
        Dist["torch_xla/distributed/"]:::onpath
        Exp["torch_xla/experimental/"]:::experimental
    end

    Binding["pybind11 Bindings"]:::binding
    subgraph "C++ Core & Runtime"
        direction TB
        IR["IR Builder\n(torch_xla/csrc/ir.cpp,\ntorch_xla/csrc/ir_builder.h)"]:::core
        Lower["Lowering Context\n(torch_xla/csrc/lowering_context.cpp)"]:::core
        Exec["Graph Executor\n(torch_xla/csrc/xla_graph_executor.cpp)"]:::core
        Client["PJRT Client & Registry\n(torch_xla/csrc/runtime/pjrt_computation_client.cpp,\n torch_xla/csrc/runtime/pjrt_registry.cpp)"]:::core
        Prof["Metrics & Profiler\n(torch_xla/csrc/runtime/metrics.cpp,\n torch_xla/csrc/runtime/profiler.cpp)"]:::core
        Tensor["Tensor & Ops Impl\n(torch_xla/csrc/tensor.cpp,\n torch_xla/csrc/ops/)"]:::core
    end

    subgraph "Plugin Layer"
        direction TB
        CPU["CPU Plugin\n(plugins/cpu/torch_xla_cpu_plugin/)"]:::plugin
        CUDA["CUDA Plugin\n(plugins/cuda/torch_xla_cuda_plugin/)"]:::plugin
    end

    Compiler["XLA Compiler (HLO/MLIR)"]:::core
    subgraph "Target Devices"
        direction TB
        TPU["Cloud TPU VM"]:::external
        GPU["GPU (CUDA)"]:::external
        CPUDev["CPU Fallback"]:::external
    end

    subgraph "External Systems"
        direction TB
        Docker["Docker Images\n(docker/)"]:::external
        CICD["CI/CD\n(.circleci/, .github/workflows/)"]:::external
        Infra["Infra as Code\n(infra/)"]:::external
        BazelSys["Bazel Build\n(bazel/, BUILD, WORKSPACE)"]:::external
        Docs["Documentation Site\n(docs/)"]:::external
        Tests["Tests\n(test/)"]:::external
        Bench["Benchmarks\n(benchmarks/)"]:::external
    end

    %% Connections
    User -->|imports| API
    API --> AMP
    API --> Dynamo
    API --> CorePy
    API --> Dist
    API --> Exp
    CorePy --> Binding
    Binding --> IR
    IR --> Lower
    Lower --> Exec
    Exec --> Client
    Exec --> Prof
    Exec --> Tensor
    Client --> Compiler
    Tensor --> Compiler
    Compiler --> CPU
    Compiler --> GPU
    Compiler --> TPU

    %% External systems interactions
    BazelSys -.->|builds| Binding
    Docker -.->|containerizes| Binding
    CICD -.->|runs| Tests
    Infra -.->|provisions| TPU

    %% Click events
    click API "https://github.com/pytorch/xla/tree/master/torch_xla/"
    click AMP "https://github.com/pytorch/xla/tree/master/torch_xla/amp/"
    click Dynamo "https://github.com/pytorch/xla/tree/master/torch_xla/_dynamo/"
    click CorePy "https://github.com/pytorch/xla/tree/master/torch_xla/core/"
    click Dist "https://github.com/pytorch/xla/tree/master/torch_xla/distributed/"
    click Exp "https://github.com/pytorch/xla/tree/master/torch_xla/experimental/"
    click Binding "https://github.com/pytorch/xla/blob/master/torch_xla/csrc/init_python_bindings.cpp"
    click IR "https://github.com/pytorch/xla/blob/master/torch_xla/csrc/ir.cpp"
    click Lower "https://github.com/pytorch/xla/blob/master/torch_xla/csrc/lowering_context.cpp"
    click Exec "https://github.com/pytorch/xla/blob/master/torch_xla/csrc/xla_graph_executor.cpp"
    click Client "https://github.com/pytorch/xla/blob/master/torch_xla/csrc/runtime/pjrt_computation_client.cpp"
    click Prof "https://github.com/pytorch/xla/blob/master/torch_xla/csrc/runtime/metrics.cpp"
    click Tensor "https://github.com/pytorch/xla/blob/master/torch_xla/csrc/tensor.cpp"
    click CPU "https://github.com/pytorch/xla/tree/master/plugins/cpu/torch_xla_cpu_plugin/"
    click CUDA "https://github.com/pytorch/xla/tree/master/plugins/cuda/torch_xla_cuda_plugin/"
    click Docs "https://github.com/pytorch/xla/tree/master/docs/"
    click Tests "https://github.com/pytorch/xla/tree/master/test/"
    click Bench "https://github.com/pytorch/xla/tree/master/benchmarks/"
    click Docker "https://github.com/pytorch/xla/tree/master/docker/"
    click CICD "https://github.com/pytorch/xla/tree/master/.github/workflows/"
    click Infra "https://github.com/pytorch/xla/tree/master/infra/"
    click BazelSys "https://github.com/pytorch/xla/tree/master/bazel/"

    %% Styles
    classDef onpath fill:#a8d0f0,stroke:#000,stroke-width:1px
    classDef plugin fill:#b8f1a2,stroke:#000,stroke-width:1px
    classDef external fill:#d0d0d0,stroke:#000,stroke-width:1px
    classDef experimental fill:#f0e68c,stroke-dasharray: 5 5,stroke:#000
    classDef binding fill:#f4c2c2,stroke:#000,stroke-width:1px
    classDef core fill:#add8e6,stroke:#000,stroke-width:1px
```
