# google-deepmind/dm-haiku architecture

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

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

## Overview

##### Project type and purpose
- This is a Python neural-network library for JAX, akin to “Sonnet for JAX.”
- It provides an object-oriented module abstraction (`hk.Module`), parameter/state management, RNG sequencing, and functional transforms (`hk.transform`, `hk.transform_with_state`) that integrate seamlessly with JAX’s `jit`, `grad`, `pmap`, etc.
- The repo is structured to support the core library (`haiku/_src`), examples, documentation, benchmarks, tests, CI/CD, and packaging.

##### File structure
- Top-level: configuration files (`.pylintrc`, `.style.yapf`), build scripts (`BUILD`, Bazel files), CI workflows, `setup.py`, `requirements*.txt`.
- `haiku/` package:
- `_src/`: the core implementation, divided into modules for layers, transforms, state/RNG management, integration tests, nets, utils.
- `benchmarks/`, `experimental/`, top-level convenience modules (`haiku/module.py`, `haiku/testing.py`, etc.)
- `examples/`: runnable demos (MNIST, ResNet, IMPALA RL), plus BUILD files for Bazel.
- `docs/`: Sphinx-based docs, notebooks, custom extensions.
- Tests sprinkled alongside source (`*_test.py`) and integration checkpoints (`.json` fixtures).

##### README for additional insights
- Core abstractions:
a. `hk.Module` for OO layering and parameter/state references
b. `hk.transform` / `hk.without_apply_rng` for converting impure OO functions into pure `(init, apply)` pairs
c. `hk.transform_with_state` for tracking mutable state (e.g. batch-norm moving averages)
- Emphasis on lifting a user-written function into pure init/apply, then lowering parameters and rng back into the forward pass.
- Examples of distributed training via `jax.pmap`.

##### Detailing the lifting/lowering between functional and OO
- Lifting (OO → Functional): annotate how `hk.transform` traverses the Python AST (or via decorators) to intercept calls to `hk.get_parameter`, `hk.get_state`, `hk.next_rng_key`. It builds up a graph of requested parameters and state, and returns two side-effect-free functions:
- apply: replay with the collected params & state, feeding RNG from a seeded sequence
- Lowering (Functional → OO execution): show how the `apply` function dispatches calls back into the module’s `__call__` methods with the parameter values injected. The RNG manager supplies fresh keys per module invocation, preserving reproducibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing OO Layer
    subgraph "User Code (OO Layer)"
        direction TB
        UserFn["Forward Function\nusing hk.Module"]:::oo
        ModuleBase["hk.Module (base)"]:::oo
        ModuleImpl["hk.Module (module)"]:::oo
    end

    %% Functional Transform Layer
    subgraph "Functional Transforms" 
        direction TB
        Transform["hk.transform\n & without_apply_rng"]:::core
        MultiTrans["hk.transform_with_state\n & multi-transform"]:::core
        Deferred["Deferred Execution Internals"]:::core
    end

    %% Core State Management
    subgraph "Haiku Core Internals"
        direction TB
        ParamStore["Parameter Store\n(get_parameter/init)"]:::core
        StateStore["State Store\n(get_state/set_state)"]:::core
        RNGMgr["RNG Manager\n(next_rng_key)"]:::core
        Config["Configuration & Runtime"]:::core
        Typing["Type Definitions & Annotations"]:::core
        Utils["Core Utilities"]:::core
    end

    %% JAX and Backend
    subgraph "JAX & XLA Backend"
        direction TB
        JAXTrans["jax.jit / grad / pmap"]:::jax
        XLABackend["XLA Device Execution"]:::jax
    end

    %% Auxiliary Systems
    subgraph "Auxiliary Systems"
        direction TB
        Docs["Sphinx Docs & Notebooks"]:::aux
        CI["CI/CD (Bazel & GitHub Actions)"]:::aux
        Packaging["PyPI Packaging"]:::aux
    end

    %% Lifting and Lowering Arrows
    UserFn -->|"OO code in"| Transform
    Transform -->|"lifts to pure init/apply"| InitApply["init(params)/apply(params)"]:::core
    InitApply -->|"init builds params"| ParamStore
    InitApply -->|"apply injects params & state"| ModuleImpl
    InitApply -->|"apply requests RNG"| RNGMgr
    ModuleImpl -->|"calls state ops"| StateStore
    Transform ---|"handles mutable state"| MultiTrans
    Transform ---|"deferred intercepts calls"| Deferred

    %% JAX integration
    InitApply -->|"fed to"| JAXTrans
    JAXTrans -->|"compiles for"| XLABackend

    %% Auxiliary connections
    Config --> ModuleImpl
    Typing --> ModuleImpl
    Utils --> ModuleImpl
    Docs -.-> ModuleBase
    CI -.-> UserFn
    Packaging -.-> UserFn

    %% Click Events
    click ModuleBase "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/base.py"
    click ModuleImpl "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/module.py"
    click ParamStore "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/lift.py"
    click StateStore "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/stateful.py"
    click RNGMgr "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/random.py"
    click Transform "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/transform.py"
    click MultiTrans "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/multi_transform.py"
    click Deferred "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/deferred.py"
    click Config "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/config.py"
    click Typing "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/typing.py"
    click Utils "https://github.com/google-deepmind/dm-haiku/blob/main/haiku/_src/utils.py"

    %% Styles
    classDef oo fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef core fill:#B8E6A3,stroke:#333,stroke-width:1px
    classDef jax fill:#F7C59F,stroke:#333,stroke-width:1px
    classDef aux fill:#D3D3D3,stroke:#333,stroke-width:1px
```
