# mscherbela/kfac-jax architecture

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

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

## Overview

##### Project Type and Purpose
- KFAC-JAX is an open-source Python library (not a standalone application) providing second-order optimization (K-FAC) and scalable curvature estimation for neural networks built on top of JAX.
- Its primary consumers are researchers and engineers who write model code in JAX (often with frameworks like Haiku) and want to plug in a drop-in optimizer.

##### File-Structure Analysis
Top-level directories and files:
- `.github/`, `CI` workflows: automation for testing and publishing.
- `README.md`, `LICENSE`, `CONTRIBUTING.md`, `setup.py`, `requirements*.txt`: packaging, installation, contribution guidelines.
- `docs/`: Sphinx source for user/documentation site.
- `examples/`: concrete end-to-end scripts illustrating how to use the library.
- `tests/`: unit tests for each core component.
- `kfac_jax/_src/`: library source code, broken into modules:
– `optimizer.py` – public `Optimizer` class and step logic
– `curvature_estimator.py` – driver for curvature approximation
– `curvature_blocks.py` – per-layer block implementations (dense, conv, etc.)
– `layers_and_loss_tags.py`, `loss_functions.py` – loss registration and tagging
– `tracer.py`, `tag_graph_matcher.py` – JAX graph introspection to match blocks to computation
– `patches_second_moment.py` – low-level moment computations
– `utils/` – submodules for math, accumulators, staging, parallel utilities, types

1. User Model & Training Script (examples or user code)
2. Public API Layer (`kfac_jax/__init__.py`)
3. Optimizer Module (`optimizer.py`)
4. Curvature Estimator (`curvature_estimator.py`)
5. Curvature Blocks (`curvature_blocks.py`)
6. Loss & Layer Registration (`layers_and_loss_tags.py`, `loss_functions.py`)
7. Tracer & Graph Matcher (`tracer.py`, `tag_graph_matcher.py`)
8. Patches & Low-Level Ops (`patches_second_moment.py`)
9. Utilities (`utils/…`)
10. External Dependencies:
– JAX (XLA backend, JIT, pmap)
– Haiku (or other NN frameworks)
– Python environment

1 → 2: User code imports `kfac_jax` API.
2 → 3: `Optimizer` is instantiated with user’s loss and gradient function.
3 ↔ 4: Optimizer calls `CurvatureEstimator` inside each step.
4 → 5: Estimator delegates per-layer curvature computation to the appropriate block.
4 ← 6: Before stepping, the registration subsystem has tagged parameters/losses so estimator knows what to do.
5 ← 7: Blocks are selected by matching the JAX computation graph via tracer + graph matcher.
5 ↔ 8: Blocks use low-level “second moment” patches for efficient moment updates.
3,4,5 → 9: All modules use common math, accumulators, parallel, staging utilities.
Everything relies on JAX primitives (jit, vmap, pmap, XLA) under the hood.

##### Architectural Patterns & Design Principles
- Modular layering: clear separation of public API, orchestration (optimizer), estimation, block implementations, and utilities.
- Strategy/factory pattern: different curvature blocks selected at runtime based on tags.
- Observer/tracer: introspects JAX computation graph to register and match layers.
- Registration system: declarative tagging of losses and parameters.
- Single responsibility for each module: easier to test (see `tests/`) and extend with new blocks or loss functions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    EXT["JAX / Haiku / Python Env"]:::external

    %% User Code
    USER["User Model & Training Script"]:::external

    %% Public API
    API["Public API Layer"]:::api

    %% Core Orchestration
    OPT["Optimizer Module"]:::core
    EST["Curvature Estimator"]:::core

    %% Implementations
    BLOCKS["Curvature Blocks"]:::impl
    REG["Loss & Layer Registration"]:::impl
    PATCHES["Patches & Low-Level Ops"]:::impl

    %% Utilities & Matchers
    TM["Tracer & Graph Matcher"]:::util
    UTILS["Utilities"]:::util

    %% Documentation & Tests
    DOCS["Documentation (docs/)"]:::doc
    TESTS["Tests (tests/)"]:::test

    %% Flow
    EXT --> USER
    USER --> API
    API --> OPT
    OPT <--> EST
    EST --> BLOCKS
    REG --> EST
    TM --> BLOCKS
    BLOCKS <--> PATCHES
    OPT --> UTILS
    EST --> UTILS
    BLOCKS --> UTILS

    %% Ancillary
    API --> DOCS
    API --> TESTS
    REG --> TESTS
    TM --> TESTS
    PATCHES --> TESTS

    %% Click Events
    click USER "https://github.com/mscherbela/kfac-jax/tree/main/examples/"
    click API "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/__init__.py"
    click OPT "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/optimizer.py"
    click EST "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/curvature_estimator.py"
    click BLOCKS "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/curvature_blocks.py"
    click REG "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/layers_and_loss_tags.py"
    click REG "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/loss_functions.py"
    click TM "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/tracer.py"
    click TM "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/tag_graph_matcher.py"
    click PATCHES "https://github.com/mscherbela/kfac-jax/blob/main/kfac_jax/_src/patches_second_moment.py"
    click UTILS "https://github.com/mscherbela/kfac-jax/tree/main/kfac_jax/_src/utils/"
    click DOCS "https://github.com/mscherbela/kfac-jax/tree/main/docs/"
    click TESTS "https://github.com/mscherbela/kfac-jax/tree/main/tests/"

    %% Styles
    classDef external fill:#B0BEC5,stroke:#455A64,color:#263238;
    classDef api fill:#BBDEFB,stroke:#1976D2,color:#0D47A1;
    classDef core fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef impl fill:#FFF9C4,stroke:#F9A825,color:#F57F17;
    classDef util fill:#FFE0B2,stroke:#F57C00,color:#E65100;
    classDef doc fill:#E1BEE7,stroke:#8E24AA,color:#4A148C;
    classDef test fill:#F8BBD0,stroke:#C2185B,color:#880E4F;
```
