# ecmwf-lab/ai-models-gencast architecture

> Architecture diagram of the GitHub repository ecmwf-lab/ai-models-gencast, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ecmwf-lab/ai-models-gencast
- Repository: https://github.com/ecmwf-lab/ai-models-gencast

## Overview

##### Project Type and Purpose
- This is a Python library plugin (“ai-models-gencast”) that extends the ai-models framework to integrate Google DeepMind’s GenCast diffusion-based weather forecasting model.
- It exposes a Python API (and CLI flags) for users to load inputs, invoke the GenCast model (via JAX on CPU/GPU), convert data formats, and write outputs (e.g., GRIB files).

##### File-Structure Analysis
- Top‐level:
- pyproject.toml / requirements*.txt / .github/workflows/python-publish.yml: packaging, CI/CD, dependency management
- src/ai_models_gencast/: core plugin code
- tests/: unit tests
- Inside src/ai_models_gencast:
- input.py – reading and validating input data
- convert.py – transforming data to/from the formats expected by GenCast
- model.py – wrapping the GenCast model, handling ensemble configuration, JAX initialization
- output.py – formatting and writing forecasts (e.g., GRIB)
- No frontend or database layers—this is purely a computational library.

##### README Insights
- Describes plugin’s purpose, installation steps (CPU vs. GPU), integration with ai-models & JAX, and ensemble controls via CLI args.

a. Main Components
1. User/API Entrypoint (CLI flags or Python import)
2. Input Module (input.py)
3. Conversion Module (convert.py)
4. Model Module (model.py)
– JAX runtime (CPU/GPU)
– DeepMind GraphCast weights
– Ensemble configuration
5. Output Module (output.py)
6. External Frameworks/Services
– ai-models core plugin interface
– JAX (with optional CUDA back end)
– GenCast model repository/weights
b. Relationships & Data Flow
- Entry → Input Module: validate and load raw data
- Input → Conversion: transform into model tensor formats
- Conversion → Model: run forward pass with JAX & GenCast
- Model → Conversion (reverse): convert raw model outputs back to meteorological grids
- Conversion → Output: write final GRIB or other formats
- Throughout: errors/exceptions feed back to user entrypoint
c. Architectural Patterns / Principles
– Modular separation of concerns (I/O, conversion, computation, output)
– Plugin pattern: registering with ai-models framework
– Dependency inversion: high-level code depends on interfaces (not implementations)
– GPU‐aware computing via JAX
d. Key Technologies / Libraries
– Python packaging (pyproject.toml, pip)
– ai-models plugin API
– JAX (CPU/GPU back ends)
– DeepMind GraphCast code & weights
– Testing: pytest (tests/test_code.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    Entry["User/API Entrypoint\n(CLI flags / Python import)"]:::internal

    %% Core Modules
    subgraph "Core Modules"
        Input["Input Module"]:::internal
        Convert["Conversion Module"]:::internal
        Model["Model Module"]:::internal
        Output["Output Module"]:::internal
    end

    %% External Dependencies
    AI["ai-models Core Plugin Interface"]:::external
    JAXCPU["JAX CPU Back-end"]:::external
    JAXGPU["JAX GPU Back-end"]:::external
    Weights["GenCast Model Weights"]:::external

    %% Persistence
    GRIB["GRIB Files"]:::persistent

    %% Packaging & CI/CD
    subgraph "Packaging & CI/CD"
        PyProj["pyproject.toml"]:::internal
        Req1["requirements.txt"]:::internal
        ReqGPU["requirements-gpu.txt"]:::internal
        CI[".github/workflows/python-publish.yml"]:::internal
    end

    %% Tests
    Tests["pytest Tests"]:::test

    %% Data Flow
    Entry -->|"validate & load raw data"| Input
    Input -->|"raw netCDF → tensor"| Convert
    Convert -->|"tensor input"| Model
    Model -->|"raw tensor output"| Convert
    Convert -->|"meteorological grid"| Output
    Output -->|"write GRIB"| GRIB

    %% Integration Points
    Entry -->|"plugin registration"| AI
    Model -->|"invoke JAX"| JAXCPU
    Model -->|"invoke JAX"| JAXGPU
    Model -->|"load weights"| Weights

    %% Testing Coverage
    Tests -.-> Input
    Tests -.-> Convert
    Tests -.-> Model
    Tests -.-> Output

    %% Click Events
    click Entry "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/src/ai_models_gencast/__init__.py"
    click Input "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/src/ai_models_gencast/input.py"
    click Convert "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/src/ai_models_gencast/convert.py"
    click Model "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/src/ai_models_gencast/model.py"
    click Output "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/src/ai_models_gencast/output.py"
    click PyProj "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/pyproject.toml"
    click Req1 "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/requirements.txt"
    click ReqGPU "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/requirements-gpu.txt"
    click CI "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/.github/workflows/python-publish.yml"
    click Tests "https://github.com/ecmwf-lab/ai-models-gencast/blob/develop/tests/test_code.py"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#2196F3,color:#000
    classDef external fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef persistent fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef test fill:#FFCDD2,stroke:#E53935,color:#000
```
