# google/jax-cfd architecture

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

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

## Overview

##### Project Type and Purpose
- JAX-CFD is an open-source scientific library for computational fluid dynamics (CFD) built on JAX.
- It provides core numerical methods (finite-volume/difference and pseudospectral), ML-augmented CFD models, and data processing/visualization utilities.
- Users interact via Python APIs and demonstration notebooks.

##### File-Structure Analysis
- Top-level directories:
- jax_cfd/base     → core finite-volume and difference methods
- jax_cfd/collocated → experimental FVM on collocated grids
- jax_cfd/spectral → pseudospectral solvers
- jax_cfd/ml       → machine-learning models and training/inference utilities
- jax_cfd/data     → data preparation, evaluation, visualization
- notebooks        → example workflows and demos
- Supporting files: setup.py, CI workflows, tests alongside modules.
- External configs: .gin files under ml/models_configs and ml/physics_configs.

##### README Insights
- Confirms four main submodules (base, spectral, ml, data).
- Lists core dependencies: JAX (+jaxlib), NumPy, SciPy, Haiku (for ml), Xarray & Pillow (for data).
- Highlights use cases: simulations, model training/inference, data analysis.

##### Main Components
a. Core CFD Numerics Module
- jax_cfd/base (MAC-FVM & finite differences)
- jax_cfd/collocated (collocated-grid experiments)
- jax_cfd/spectral (pseudospectral pipeline)
b. ML Augmentation Layer
- jax_cfd/ml: encoders/decoders, custom Haiku layers, model builder, training utilities, physics-informed modules
c. Data Processing & Visualization
- jax_cfd/data: Xarray-based I/O, evaluation metrics, plotting routines
d. User Interface / Demos
- notebooks: Jupyter workflows that glue together numerics, ML models, and data visualization
e. External Dependencies
- JAX & jaxlib, NumPy, SciPy, Haiku, Xarray, Pillow

##### Relationships and Interactions
- Numerics modules expose solver APIs consumed by notebooks and ML code.
- ML layer wraps numerics (e.g., for learned advection/diffusion closures) via JAX transforms.
- Data module ingests simulation outputs (arrays) for analysis/plotting.
- Notebooks import all modules to demonstrate end-to-end workflows.
- CI pipeline runs tests across all submodules; setup.py orchestrates packaging and dependency resolution.

##### Architectural Patterns and Principles
- Modular layering: core numerics → ML augmentation → data utilities → presentation (notebooks).
- Separation of concerns: each submodule has clearly defined responsibilities.
- Dependency inversion: higher-level layers (ml, notebooks) depend on abstract solver interfaces in base/spectral.
- Configuration management via Gin files for physics and model hyperparameters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core CFD Numerics
    subgraph "Core CFD Numerics"
        Base["jax_cfd/base"]:::core
        Collocated["jax_cfd/collocated"]:::core
        Spectral["jax_cfd/spectral"]:::core
    end

    %% ML Augmentation Layer
    subgraph "ML Augmentation Layer"
        ML["jax_cfd/ml"]:::ml
        ImplicitConfig["implicit_diffusion_dns_config.gin"]:::ml_sub
        SmagoConfig["smagorinsky_config.gin"]:::ml_sub
        PhysicsConfig["physics_configs"]:::ml_sub
    end

    %% Data Processing & Visualization
    subgraph "Data Processing & Visualization"
        Data["jax_cfd/data"]:::data
        XarrayUtils["xarray_utils.py"]:::data_sub
    end

    %% User Interface / Demos
    Notebooks["notebooks/"]:::notebook

    %% Packaging & CI
    Setup["setup.py"]:::misc
    CI["CI & Testing\n.github/workflows/ci-build.yml"]:::misc

    %% External Dependencies
    subgraph "External Dependencies"
        JAX["JAX & jaxlib"]:::ext
        NumPy["NumPy"]:::ext
        SciPy["SciPy"]:::ext
        Haiku["Haiku"]:::ext
        XarrayExt["Xarray"]:::ext
        Pillow["Pillow"]:::ext
    end

    %% Data & Control Flows
    Base -->|"provides solver APIs"| ML
    Collocated -->|"provides solver APIs"| ML
    Spectral -->|"provides solver APIs"| ML

    Base -->|"outputs arrays"| Data
    Collocated -->|"outputs arrays"| Data
    Spectral -->|"outputs arrays"| Data

    ML -->|"uses solver interfaces"| Base
    ML -->|"uses solver interfaces"| Spectral

    Data -->|"used by"| Notebooks
    ML -->|"used by"| Notebooks
    Base -->|"used by"| Notebooks

    Notebooks -->|"runs simulations"| Base
    Notebooks -->|"trains/models"| ML
    Notebooks -->|"post-processes"| Data

    Setup -->|"packages & resolves deps"| Base
    Setup -->|"packages & resolves deps"| ML
    Setup -->|"packages & resolves deps"| Data
    Setup -->|"packages & resolves deps"| Notebooks

    CI -->|"tests modules"| Base
    CI -->|"tests modules"| ML
    CI -->|"tests modules"| Data
    CI -->|"tests modules"| Notebooks

    %% Dependency Arrows from External Libraries
    JAX --> Base
    JAX --> Collocated
    JAX --> Spectral
    JAX --> ML

    NumPy --> Base
    SciPy --> Spectral
    Haiku --> ML
    XarrayExt --> Data
    Pillow --> Data

    %% Click Events
    click Base "https://github.com/google/jax-cfd/tree/main/jax_cfd/base/"
    click Collocated "https://github.com/google/jax-cfd/tree/main/jax_cfd/collocated/"
    click Spectral "https://github.com/google/jax-cfd/tree/main/jax_cfd/spectral/"
    click ML "https://github.com/google/jax-cfd/tree/main/jax_cfd/ml/"
    click ImplicitConfig "https://github.com/google/jax-cfd/blob/main/jax_cfd/ml/models_configs/implicit_diffusion_dns_config.gin"
    click SmagoConfig "https://github.com/google/jax-cfd/blob/main/jax_cfd/ml/models_configs/smagorinsky_config.gin"
    click PhysicsConfig "https://github.com/google/jax-cfd/tree/main/jax_cfd/ml/physics_configs/"
    click Data "https://github.com/google/jax-cfd/tree/main/jax_cfd/data/"
    click XarrayUtils "https://github.com/google/jax-cfd/blob/main/jax_cfd/data/xarray_utils.py"
    click Notebooks "https://github.com/google/jax-cfd/tree/main/notebooks/"
    click Setup "https://github.com/google/jax-cfd/blob/main/setup.py"
    click CI "https://github.com/google/jax-cfd/blob/main/.github/workflows/ci-build.yml"

    %% Styles
    classDef core fill:#D0E4F2,stroke:#339,stroke-width:1px;
    classDef ml fill:#DFF2D8,stroke:#3A7,stroke-width:1px;
    classDef ml_sub fill:#E8F5E9,stroke:#3A7,stroke-width:1px;
    classDef data fill:#FFE5B4,stroke:#E68A00,stroke-width:1px;
    classDef data_sub fill:#FFF2E0,stroke:#E68A00,stroke-width:1px;
    classDef notebook fill:#E5DAF1,stroke:#6A3,stroke-width:1px;
    classDef ext fill:#EEEEEE,stroke:#888,stroke-width:1px,stroke-dasharray: 2 2;
    classDef misc fill:#F5F5F5,stroke:#AAA,stroke-width:1px,stroke-dasharray: 2 2;
```
