# google-deepmind/optax architecture

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

- Interactive diagram: https://gitdiagram.com/google-deepmind/optax
- Repository: https://github.com/google-deepmind/optax

## Overview

##### Project type and purpose
- Project type: A pure-Python library (Optax) for gradient processing and optimization built on JAX.
- Purpose: Provide small, composable building blocks (optimizers, gradient transforms, losses, schedules, utilities) that can be recombined into custom optimization pipelines in research and production.

##### File structure
- Top-level files: configuration (.github workflows, pre-commit, pyproject.toml), packaging, tests (test.sh), documentation (docs/), examples/.
- Source tree: optax/ contains a _src folder and subpackages:
- alias, base, clipping, combine, constrain, factorized, linesearch, lookahead, numerics, schedule, transform, update, utils, wrappers
- assignment (Hungarian), contrib (advanced/experimental optimizers), losses, monte_carlo, perturbations, projections, schedules, second_order, transforms, tree, tree_utils.
- Tests: co-located with modules (_test.py files).
- Examples: Jupyter notebooks showing usage scenarios.
- Docs: reStructuredText API docs, Sphinx configuration.

##### README for additional insights
- Confirms core functionality: optimizers, losses, scheduling, gradient processing.
- Mentions quickstart: “optimizer.init”, “optimizer.update”, “optax.apply_updates”.
- Tech stack: Python, JAX, Sphinx, GitHub Actions, ReadTheDocs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef runtime fill:#D0E6FF,stroke:#000,stroke-width:1px
    classDef tooling fill:#E1FFD6,stroke:#000,stroke-width:1px
    classDef packaging fill:#FFF3C4,stroke:#000,stroke-width:1px

    %% Runtime Components
    subgraph "Runtime Components"
        direction TB
        UserCode["User Code Examples"]:::runtime
        JAX["JAX (autodiff, JIT)"]:::runtime

        subgraph "Optax Core API"
            direction TB
            OptaxInit["optax/__init__.py"]:::runtime
            Base["base.py<br/>(Params, OptState, Updates)"]:::runtime
            UpdateCore["update.py<br/>(update logic)"]:::runtime
            ApplyUpdates["apply_updates"]:::runtime

            subgraph "Primitive Transforms<br/>(optax/_src)"
                direction TB
                Alias["alias.py"]:::runtime
                ClippingCore["clipping.py"]:::runtime
                CombineCore["combine.py"]:::runtime
                ConstrainCore["constrain.py"]:::runtime
                Factorized["factorized.py"]:::runtime
                LinAlg["linear_algebra.py"]:::runtime
                LineSearch["linesearch.py"]:::runtime
                Lookahead["lookahead.py"]:::runtime
                Numerics["numerics.py"]:::runtime
                ScheduleCore["schedule.py"]:::runtime
                TransformCore["transform.py"]:::runtime
                UtilsCore["utils.py"]:::runtime
                WrappersCore["wrappers.py"]:::runtime
            end

            subgraph "User-Facing API"
                direction TB
                OptaxTest["optax_test.py"]:::runtime
            end
        end

        subgraph "Transforms Subpackage"
            direction TB
            Accumulation["_accumulation.py"]:::runtime
            ClippingTrans["_clipping.py"]:::runtime
            CombiningTrans["_combining.py"]:::runtime
            Conditionality["_conditionality.py"]:::runtime
            Constraining["_constraining.py"]:::runtime
            Freezing["_freezing.py"]:::runtime
            Layouts["_layouts.py"]:::runtime
            Masking["_masking.py"]:::runtime
            Adding["_adding.py"]:::runtime
        end

        subgraph "Category Modules"
            direction TB
            Losses["optax/losses"]:::runtime
            Schedules["optax/schedules"]:::runtime
            Projections["optax/projections"]:::runtime
            Perturbations["optax/perturbations"]:::runtime
            MonteCarlo["optax/monte_carlo"]:::runtime
            SecondOrder["optax/second_order"]:::runtime
        end

        subgraph "Contrib Extensions"
            direction TB
            Contrib["optax/contrib"]:::runtime
        end

        subgraph "Data Structures & Tree Utils"
            direction TB
            TreeUtils["optax/tree_utils"]:::runtime
            PyTree["optax/tree"]:::runtime
        end
    end

    %% Tooling Components
    subgraph "Development Tooling"
        direction TB
        Tests["test.sh & pytest"]:::tooling
        Docs["docs/ (Sphinx)"]:::tooling
        CI[".github/workflows"]:::tooling
    end

    %% Packaging
    subgraph "Packaging & Config"
        direction TB
        PyProject["pyproject.toml"]:::packaging
        PreCommit[".pre-commit-config.yaml"]:::packaging
    end

    %% Data Flow
    UserCode -->|"init(params)"| OptaxInit
    OptaxInit --> Base
    Base -->|"OptState"| UserCode
    UserCode -->|"compute grads"| JAX
    JAX -->|"grads"| UpdateCore
    UpdateCore --> PrimitiveTransforms
    PrimitiveTransforms --> CombineCore
    CombineCore --> UpdateCore
    UpdateCore -->|"Updates & OptState"| ApplyUpdates
    ApplyUpdates --> UserCode

    %% Testing & Documentation & CI
    Tests --> OptaxCore.APIUndefined
    Docs --> OptaxCore.APIUndefined
    CI --> Tests
    CI --> Docs

    %% Packaging flow
    CI --> PyProject
    CI --> PreCommit

    %% Click events
    click UserCode "https://github.com/google-deepmind/optax/tree/main/examples/"
    click OptaxInit "https://github.com/google-deepmind/optax/blob/main/optax/__init__.py"
    click Base "https://github.com/google-deepmind/optax/blob/main/optax/_src/base.py"
    click UpdateCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/update.py"
    click ApplyUpdates "https://github.com/google-deepmind/optax/blob/main/optax/_src/utils.py"
    click Alias "https://github.com/google-deepmind/optax/blob/main/optax/_src/alias.py"
    click ClippingCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/clipping.py"
    click CombineCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/combine.py"
    click ConstrainCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/constrain.py"
    click Factorized "https://github.com/google-deepmind/optax/blob/main/optax/_src/factorized.py"
    click LinAlg "https://github.com/google-deepmind/optax/blob/main/optax/_src/linear_algebra.py"
    click LineSearch "https://github.com/google-deepmind/optax/blob/main/optax/_src/linesearch.py"
    click Lookahead "https://github.com/google-deepmind/optax/blob/main/optax/_src/lookahead.py"
    click Numerics "https://github.com/google-deepmind/optax/blob/main/optax/_src/numerics.py"
    click ScheduleCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/schedule.py"
    click TransformCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/transform.py"
    click UtilsCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/utils.py"
    click WrappersCore "https://github.com/google-deepmind/optax/blob/main/optax/_src/wrappers.py"
    click Accumulation "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_accumulation.py"
    click ClippingTrans "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_clipping.py"
    click CombiningTrans "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_combining.py"
    click Conditionality "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_conditionality.py"
    click Constraining "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_constraining.py"
    click Freezing "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_freezing.py"
    click Layouts "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_layouts.py"
    click Masking "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_masking.py"
    click Adding "https://github.com/google-deepmind/optax/blob/main/optax/transforms/_adding.py"
    click Losses "https://github.com/google-deepmind/optax/tree/main/optax/losses/"
    click Schedules "https://github.com/google-deepmind/optax/tree/main/optax/schedules/"
    click Projections "https://github.com/google-deepmind/optax/blob/main/optax/projections/_projections.py"
    click Perturbations "https://github.com/google-deepmind/optax/blob/main/optax/perturbations/_make_pert.py"
    click MonteCarlo "https://github.com/google-deepmind/optax/tree/main/optax/monte_carlo/"
    click SecondOrder "https://github.com/google-deepmind/optax/tree/main/optax/second_order/"
    click Contrib "https://github.com/google-deepmind/optax/tree/main/optax/contrib/"
    click TreeUtils "https://github.com/google-deepmind/optax/tree/main/optax/tree_utils/"
    click PyTree "https://github.com/google-deepmind/optax/tree/main/optax/tree/"
    click OptaxTest "https://github.com/google-deepmind/optax/blob/main/optax/optax_test.py"
    click Tests "https://github.com/google-deepmind/optax/blob/main/test.sh"
    click Docs "https://github.com/google-deepmind/optax/tree/main/docs/"
    click CI "https://github.com/google-deepmind/optax/tree/main/.github/workflows/"
    click PyProject "https://github.com/google-deepmind/optax/blob/main/pyproject.toml"
    click PreCommit "https://github.com/google-deepmind/optax/blob/main/.pre-commit-config.yaml"
```
