# rocm/jax architecture

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

- Interactive diagram: https://gitdiagram.com/rocm/jax
- Repository: https://github.com/rocm/jax

## Overview

This project is the source code for JAX – a high‐performance, accelerator‐oriented Python library that transforms numerical programs using techniques such as automatic differentiation (grad), just-in-time compilation (jit), automatic vectorization (vmap), and SPMD parallelism (pmap). The purpose is to provide a composable system for numerical computations at scale via transformations and integration with XLA; the file structure and README show that it’s a large-scale, full-featured library with extensive test suites, benchmarks, documentation, and CI/CD workflows.

##### Main Components
- Core API Layer ("jax" package): Represent the core Python API that users interact with. This layer includes the transformation functions (grad, jit, vmap, pmap) and the “pure functions” paradigm.
- Plugins and Backend Extensions (“jax_plugins”): This includes CUDA and ROCM plugins that extend functionality to specific hardware. Mark these as modular components providing enhanced support for different platforms.
- Experimental and Additional Modules: Include “jax.experimental” components such as experimental transformations, array serialization, pallas (for fusion and mosaic kernels), and other features in development.
- Documentation and Examples: Include components such as “docs” (with Sphinx templates, tutorials, and notebooks in docs/notebooks) and “examples” that highlight how users can deploy and experiment with JAX.
- Benchmarks and Performance: Represent the “benchmarks” folder used for performance assessment; these will illustrate how performance testing of the core libraries is integrated.

##### Relationships and Interactions
- “experimental” modules to the main core, signaling these are advanced or in-the-lab features that augment the primary API.

##### Architectural Patterns and Design Principles
- Cross-layer transformations: the transformation pipeline where a function goes from a user-written Python function, is transformed (via grad, jit), and then compiled by XLA through jaxlib; you might illustrate this as a flowchart inside the core API.
- Use a layered architecture model: top layer (user APIs and examples/documentation), middle layer (transformation and compilation logic), and bottom layer (hardware-specific drivers and backends).
- Role of design principles like immutability/pure functions – a key constraint that allows the transformations without unintended side effects.

##### Relevant Technologies and Frameworks
- JAX itself (Python, NumPy-like API) and integration with XLA.
- Bazel: shown by BUILD files and WORKSPACE for managing builds and dependencies.
- CI systems (GitHub Actions, Docker containers from build/rocm/docker etc.) for automating testing and deployment.
- C++ code integration in jaxlib for performance-critical computation.

##### Instructing the Principal Software Engineer
- Use clear labels for each component: “User API (jax)”, “Compilation Layer (jaxlib + XLA)”, “Hardware Plugins (jax_plugins)”, “Experimental Features”, “CI/Build & Tests”, “Documentation & Examples.”
– API components (perhaps rounded rectangles),

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Facing Layer
    subgraph "User Facing"
        F["Documentation"]:::docs
        G["Examples"]:::examples
    end

    %% User Layer
    subgraph "User Layer"
        A["User API (jax package)"]:::api
        D["Experimental Features (jax/experimental)"]:::experimental
    end

    %% Core Computation Layer
    subgraph "Core Computation"
        B["Compilation Layer (jaxlib + XLA)"]:::compilation
        C["Hardware Plugins (jax_plugins)"]:::plugins
        E["Accelerator Hardware"]:::hardware
    end

    %% Supporting Infrastructure Layer
    subgraph "Supporting Infrastructure"
        H["Build Scripts"]:::build
        H2["Bazel Build"]:::build
        I["CI Workflows"]:::ci
        I2["CI Scripts"]:::ci
        J["Test Suites"]:::tests
        K["Benchmarks"]:::benchmarks
    end

    %% Connections from User Facing to User Layer
    F -->|"educates"| A
    G -->|"provides_examples"| A

    %% Core transformation and augmentation connections
    A -->|"transformation"| B
    D -->|"augments"| A
    C -->|"extension"| B
    B -->|"compiles_to"| E

    %% Infrastructure interactions with Core Components
    H -->|"validate"| A
    H -->|"validate"| B
    H2 -->|"validate"| A
    H2 -->|"validate"| B
    I -->|"validate"| A
    I -->|"validate"| B
    I2 -->|"validate"| A
    I2 -->|"validate"| B
    J -->|"testing"| A
    J -->|"testing"| B
    K -->|"performance"| B

    %% Click Events
    click A "https://github.com/rocm/jax/tree/rocm-main/jax/"
    click B "https://github.com/rocm/jax/tree/rocm-main/jaxlib/"
    click C "https://github.com/rocm/jax/tree/rocm-main/jax_plugins/"
    click D "https://github.com/rocm/jax/tree/rocm-main/jax/experimental/"
    click F "https://github.com/rocm/jax/tree/rocm-main/docs/"
    click G "https://github.com/rocm/jax/tree/rocm-main/examples/"
    click H "https://github.com/rocm/jax/tree/rocm-main/build/"
    click H2 "https://github.com/rocm/jax/blob/rocm-main/BUILD.bazel"
    click I "https://github.com/rocm/jax/tree/rocm-main/.github/workflows/"
    click I2 "https://github.com/rocm/jax/tree/rocm-main/ci/"
    click J "https://github.com/rocm/jax/tree/rocm-main/tests/"
    click K "https://github.com/rocm/jax/tree/rocm-main/benchmarks/"

    %% Styles
    classDef docs fill:#ccf,stroke:#333,stroke-width:2px;
    classDef examples fill:#ccf,stroke:#333,stroke-width:2px;
    classDef api fill:#afa,stroke:#333,stroke-width:2px;
    classDef experimental fill:#ffa,stroke:#333,stroke-width:2px,stroke-dasharray: 5,5;
    classDef compilation fill:#aaf,stroke:#333,stroke-width:2px;
    classDef plugins fill:#cfc,stroke:#333,stroke-width:2px;
    classDef hardware fill:#fc9,stroke:#333,stroke-width:2px;
    classDef build fill:#fdd,stroke:#333,stroke-width:2px;
    classDef ci fill:#dfd,stroke:#333,stroke-width:2px;
    classDef tests fill:#ffd,stroke:#333,stroke-width:2px;
    classDef benchmarks fill:#ddf,stroke:#333,stroke-width:2px;
```
