# mllam/weather-model-graphs architecture

> Architecture diagram of the GitHub repository mllam/weather-model-graphs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mllam/weather-model-graphs
- Repository: https://github.com/mllam/weather-model-graphs

## Overview

Key design intent from the README:
- The **primary in-memory representation is `networkx.DiGraph`** for as long as possible.
- Graph creation is **modular/pipeline-oriented**: “every step outputs a `networkx.DiGraph`”.
- Output formats are pluggable; one called out explicitly is **PyTorch Geometric** (optional extra).

##### File tree analysis (what the components likely are)
Top-level signals:
- `src/weather_model_graphs/…` → the core library
- `docs/` + Jupyter Book config (`docs/_config.yml`, `_toc.yml`, many `.ipynb`) → documentation is a first-class artifact
- `tests/` → strong expected behavior contracts (useful to infer module responsibilities)

- `weather_model_graphs/create/`
- `archetype.py` → “reference architectures” / canned graph recipes (e.g., Keisler)
- `base.py` → shared creation primitives / interfaces
- `grid/grid.py` → grid node generation + grid-related edges/attributes
- `mesh/mesh.py` → mesh node generation + mesh connectivity
- `mesh/kinds/flat.py`, `mesh/kinds/hierarchical.py` → strategy implementations for mesh construction
- `weather_model_graphs/networkx_utils.py` → graph manipulation utilities (README references `split_graph_by_edge_attribute`)
- `weather_model_graphs/save.py` → persistence / exporters (incl. `to_pyg`)

##### Create
- `create.archetype.create_keisler_graph(...)`
- internally:
- `grid` creation
- `mesh` creation (flat/hierarchical strategy)
- edge creation (grid↔mesh / component-labeled edges)
##### Utilities
- `split_graph_by_edge_attribute(attr="component")` → multiple component graphs
##### Persist/export
- `save.to_pyg(graph, name, output_directory)` → artifacts on filesystem
- (optionally show other potential exporters as extension points)

- Node attrs: coordinates, masks, types (grid/mesh), etc. (keep generic if not explicitly known)
- Edge attrs: `component` (explicitly in README)

##### Main components to include (checklist)
When drawing, explicitly include and label:

**Core functional components**
- Graph creation API: `weather_model_graphs.create.*`
- Grid builder: `create.grid.grid`
- Mesh builder: `create.mesh.mesh`
- Mesh “kinds” strategies: `create.mesh.kinds.flat`, `create.mesh.kinds.hierarchical`
- Graph utilities: `networkx_utils` (splitting, decoding masks, etc.)
- Persistence/export: `save` (`to_pyg` called out)

**Primary data structures**
- `networkx.DiGraph` as the canonical in-memory graph
- Exported formats:
- PyTorch Geometric `Data` (optional dependency group)
- Files on disk (directory of saved graph components)

**Secondary (but valuable) SDLC components (optional lane)**
- Docs: Jupyter Book (`docs/` notebooks → static site)
- CI: tests, linting, PyPI deploy, docs deploy (`.github/workflows/*`)

- “constructs”, “transforms”, “splits”, “renders”, “serializes/exports”

Concrete interactions based on README example:
- `User` → `create.archetype.create_keisler_graph` → `DiGraph`
- `DiGraph` → `networkx_utils.split_graph_by_edge_attribute` → `{component: DiGraph}`
- Each `DiGraph` → `save.to_pyg` → `Filesystem (PyG artifacts)`

Optional feedback loop:

##### Architectural patterns/design principles to highlight
- **Intermediate Representation (IR) pattern**: `networkx.DiGraph` is the IR.
- **Pipeline/modular stages**: each stage outputs a DiGraph → easy debugging and substitution.
- **Strategy pattern** for mesh creation: `mesh.kinds.flat` vs `mesh.kinds.hierarchical`.
- **Separation of concerns**:
- `create` builds structure
- `save` exports
- `networkx_utils` transforms/queries

##### Technologies/frameworks to label
- Python package (src-layout, `pyproject.toml`, `pdm`)
- `networkx` (core)
- `numpy` (inputs/coords)
- Optional: `torch`, `torch-geometric` (export target)
- Jupyter Book for docs
- GitHub Actions for CI/CD (if diagramming delivery pipeline)

- **User Code**
→ **Public API (`weather_model_graphs.__init__`)**
→ **Archetypes (`create/archetype.py`)**
→ **Grid Builder (`create/grid/grid.py`)**
→ **Mesh Builder (`create/mesh/mesh.py`)**
→ **Mesh Strategy (`create/mesh/kinds/{flat,hierarchical}.py`)**
→ **DiGraph (NetworkX)**
→ **Utils (`networkx_utils.py`)** (split/transform)
→ **Save/Export (`save.py`)**
→ **Filesystem / PyTorch Geometric artifacts**

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Context: Users & Ecosystem
    %% =========================
    subgraph "Library Context (Ecosystem)"
        direction TB

        U["User code / downstream training pipeline\n(coords+config → graph)"]:::external

        subgraph "weather-model-graphs (Python package)"
            direction TB
            API["Public API\nweather_model_graphs.__init__\n(re-exports)"]:::api
        end

        NX[("networkx.DiGraph\nCanonical in-memory IR")]:::coredata
        NP["numpy\n(coords & generation helpers)"]:::external
        MPL["matplotlib / plotting stack\n(debug rendering)"]:::external
        TORCH["torch (optional)"]:::external
        PYG["torch-geometric (optional)\nPyG Data"]:::external
        FS[("Filesystem / artifact store\n(saved graph components)")]:::storage
    end

    U -->|"calls API"| API
    API -->|"constructs/transforms"| NX
    API -->|"uses"| NP
    API -->|"renders via"| MPL
    API -->|"exports via"| PYG
    PYG -->|"may require"| TORCH
    API -->|"persists to"| FS

    %% =========================
    %% Internal Architecture
    %% =========================
    subgraph "Internal Module Architecture (Inside package)"
        direction TB

        subgraph "Graph creation (pipeline; each step outputs DiGraph)"
            direction TB
            CREATE_DIR["create/\nPipeline-oriented builders"]:::pkg

            ARCH["create.archetype\nCanned graph recipes\n(e.g., create_keisler_graph)"]:::api
            BASE["create.base\nShared primitives / interfaces"]:::core

            GRID["create.grid.grid\nGrid nodes+edges+attrs"]:::core
            MESH["create.mesh.mesh\nMesh nodes+connectivity"]:::core

            subgraph "Mesh strategy (Strategy pattern)"
                direction TB
                KINDS_DIR["create.mesh.kinds/\nStrategy implementations"]:::pkg
                FLAT["kinds.flat\nFlat mesh construction"]:::strategy
                HIER["kinds.hierarchical\nHierarchical mesh construction"]:::strategy
            end
        end

        UTILS["networkx_utils\nGraph transform/query utilities\n(e.g., split by edge attr)"]:::core
        VIS["visualise.plot_2d\n2D inspection plotter"]:::tool
        SAVE["save\nPersistence / exporters\n(incl. to_pyg)"]:::io
    end

    %% Dependencies (directional)
    ARCH -->|"uses"| BASE
    ARCH -->|"builds grid via"| GRID
    ARCH -->|"builds mesh via"| MESH
    MESH -->|"selects strategy"| KINDS_DIR
    KINDS_DIR -->|"implements"| FLAT
    KINDS_DIR -->|"implements"| HIER

    ARCH -->|"outputs"| NX
    GRID -->|"outputs"| NX
    MESH -->|"outputs"| NX

    ARCH -->|"post-process via"| UTILS
    GRID -->|"helpers via"| UTILS
    MESH -->|"helpers via"| UTILS

    VIS -->|"reads (no mutation)"| NX
    SAVE -->|"reads"| NX

    %% =========================
    %% End-to-end Dataflow Pipeline (most important)
    %% =========================
    subgraph "End-to-end Dataflow / Pipeline"
        direction TB

        INP["Inputs\ncoords (Nx2), params (e.g., mesh_node_distance)"]:::external

        STEP_API["Public API entry\nweather_model_graphs.__init__"]:::api
        STEP_ARCH["Archetype orchestration\ncreate_keisler_graph(...)"]:::api

        STEP_GRID["Grid stage\n(grid nodes/edges/attrs)"]:::core
        STEP_MESH["Mesh stage\n(mesh nodes/edges)"]:::core
        STEP_STRAT["Mesh kind strategy\n(flat | hierarchical)"]:::strategy

        IR["Intermediate Representation (IR)\nnetworkx.DiGraph\n(node attrs: coords/type/masks...;\nedge attrs: component=... )"]:::coredata

        SPLIT["Utils stage\nsplit_graph_by_edge_attribute(attr='component')\n→ {component: DiGraph}"]:::coredata

        DBG["Optional inspection\nvisualise.plot_2d(graph)"]:::tool

        EXP["Export stage\nsave.to_pyg(graph,name,output_dir)\n(or other exporters)"]:::io
        OUT["Outputs\nPyG Data objects and/or\nsaved artifacts on filesystem"]:::storage

        NOTE["Design principles\n• DiGraph is stable IR\n• Modular pipeline: each stage outputs DiGraph\n• Strategy pattern for mesh kinds\n• Separation: create vs utils vs visualise vs save"]:::note
    end

    INP -->|"provides coords+config"| STEP_API
    STEP_API -->|"calls"| STEP_ARCH
    STEP_ARCH -->|"creates"| STEP_GRID
    STEP_ARCH -->|"creates"| STEP_MESH
    STEP_MESH -->|"chooses"| STEP_STRAT
    STEP_GRID -->|"outputs DiGraph"| IR
    STEP_MESH -->|"outputs DiGraph"| IR
    STEP_ARCH -->|"combines components → DiGraph"| IR

    IR -->|"transforms/splits"| SPLIT
    IR -.->|"debug render"| DBG
    SPLIT -.->|"debug render"| DBG
    SPLIT -->|"each component DiGraph"| EXP
    EXP -->|"serializes/exports"| OUT

    %% Connect pipeline nodes to actual modules
    STEP_API -->|"implemented by"| API
    STEP_ARCH -->|"implemented by"| ARCH
    STEP_GRID -->|"implemented by"| GRID
    STEP_MESH -->|"implemented by"| MESH
    STEP_STRAT -->|"implemented by"| FLAT
    STEP_STRAT -->|"implemented by"| HIER
    SPLIT -->|"implemented by"| UTILS
    DBG -->|"implemented by"| VIS
    EXP -->|"implemented by"| SAVE

    %% =========================
    %% SDLC (Docs/CI/Tests)
    %% =========================
    subgraph "SDLC (Docs, CI, Tests)"
        direction TB
        DOCS["docs/\nJupyter Book + notebooks\n(static site)"]:::tool
        DOCS_CFG["docs/_config.yml\nJupyter Book config"]:::tool
        DOCS_TOC["docs/_toc.yml\nSite TOC"]:::tool
        CI[".github/workflows/\nGitHub Actions (tests/docs/release)"]:::tool

        TESTS["tests/\nBehavior contracts"]:::tool
        T_CREATE["tests/test_graph_creation.py"]:::tool
        T_UTILS["tests/test_graph_utils.py"]:::tool
        T_SAVE["tests/test_save.py"]:::tool
        T_PLOTS["tests/test_graph_plots.py"]:::tool
        T_README["tests/test_readme.py"]:::tool
        T_MASK["tests/test_graph_decode_gridpoints_mask.py"]:::tool
    end

    CI -->|"runs"| TESTS
    TESTS -->|"covers"| T_CREATE
    TESTS -->|"covers"| T_UTILS
    TESTS -->|"covers"| T_SAVE
    TESTS -->|"covers"| T_PLOTS
    TESTS -->|"covers"| T_README
    TESTS -->|"covers"| T_MASK

    DOCS_CFG -->|"configures"| DOCS
    DOCS_TOC -->|"structures"| DOCS
    CI -->|"builds/deploys"| DOCS

    %% =========================
    %% Click Events (paths only)
    %% =========================
    click API "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/__init__.py"
    click CREATE_DIR "https://github.com/mllam/weather-model-graphs/tree/main/src/weather_model_graphs/create/"
    click ARCH "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/create/archetype.py"
    click BASE "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/create/base.py"
    click GRID "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/create/grid/grid.py"
    click MESH "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/create/mesh/mesh.py"
    click KINDS_DIR "https://github.com/mllam/weather-model-graphs/tree/main/src/weather_model_graphs/create/mesh/kinds/"
    click FLAT "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/create/mesh/kinds/flat.py"
    click HIER "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/create/mesh/kinds/hierarchical.py"
    click UTILS "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/networkx_utils.py"
    click VIS "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/visualise/plot_2d.py"
    click SAVE "https://github.com/mllam/weather-model-graphs/blob/main/src/weather_model_graphs/save.py"
    click DOCS "https://github.com/mllam/weather-model-graphs/tree/main/docs/"
    click DOCS_CFG "https://github.com/mllam/weather-model-graphs/blob/main/docs/_config.yml"
    click DOCS_TOC "https://github.com/mllam/weather-model-graphs/blob/main/docs/_toc.yml"
    click CI "https://github.com/mllam/weather-model-graphs/tree/main/.github/workflows/"
    click TESTS "https://github.com/mllam/weather-model-graphs/tree/main/tests/"
    click T_CREATE "https://github.com/mllam/weather-model-graphs/blob/main/tests/test_graph_creation.py"
    click T_UTILS "https://github.com/mllam/weather-model-graphs/blob/main/tests/test_graph_utils.py"
    click T_SAVE "https://github.com/mllam/weather-model-graphs/blob/main/tests/test_save.py"
    click T_PLOTS "https://github.com/mllam/weather-model-graphs/blob/main/tests/test_graph_plots.py"
    click T_README "https://github.com/mllam/weather-model-graphs/blob/main/tests/test_readme.py"
    click T_MASK "https://github.com/mllam/weather-model-graphs/blob/main/tests/test_graph_decode_gridpoints_mask.py"

    %% =========================
    %% Styles (color is critical)
    %% =========================
    classDef external fill:#0b3d91,stroke:#05224f,color:#ffffff,stroke-width:1px
    classDef api fill:#146c94,stroke:#0a3b52,color:#ffffff,stroke-width:1px
    classDef pkg fill:#1f3a5f,stroke:#0f1e33,color:#ffffff,stroke-width:1px
    classDef core fill:#2a9d8f,stroke:#1b6f65,color:#ffffff,stroke-width:1px
    classDef strategy fill:#6d597a,stroke:#46394d,color:#ffffff,stroke-width:1px
    classDef coredata fill:#264653,stroke:#12242a,color:#ffffff,stroke-width:1px
    classDef io fill:#e76f51,stroke:#9d3f2b,color:#ffffff,stroke-width:1px
    classDef storage fill:#8d6e63,stroke:#4e3c35,color:#ffffff,stroke-width:1px
    classDef tool fill:#f4a261,stroke:#a7642f,color:#1b1b1b,stroke-width:1px
    classDef note fill:#fff3b0,stroke:#c9b458,color:#1b1b1b,stroke-width:1px
```
