# google-deepmind/graph_nets architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Python library (“Graph Nets”) for building and training graph neural networks in TensorFlow + Sonnet.
- It provides core abstractions (graphs, graph-network modules), utilities (NumPy/TF batching & conversion), demos (Jupyter notebooks), docs, and tests.

##### File structure
- Top level
– setup.py, README.md, LICENSE, CONTRIBUTING.md, images/ (assets), docs/ (static documentation)
- Core package: graph_nets/
– _base.py: common helpers & abstract base classes
– graphs.py: graph data structures (GraphTuple) & I/O
– blocks.py: message-passing building blocks
– modules.py: high-level GraphNetwork and GraphIndependent modules
– utils_np.py / utils_tf.py: batching / unbatching / conversion utilities for NumPy and TF
– demos/ & demos_tf2/: example notebooks + minimal model definitions
– tests/ & tests_tf2/: unit tests for all submodules

##### README for additional insights
- Core concepts:
– Input: GraphTuple with node, edge, global features
– GraphNetwork: runs edge→node→global update functions via user-supplied MLPs
– Designed for TensorFlow 1.x + Sonnet 1 and TF2 + Sonnet 2
- External dependencies: TensorFlow, dm-sonnet, tensorflow_probability
- Demo use-cases: shortest path, sorting, physical simulation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        GT["GraphTuple"]:::util
        UN["utils_np.py"]:::util
        UT["utils_tf.py"]:::util
    end

    %% Core Engine
    subgraph "Core Engine"
        Base["_base.py"]:::core
        Blocks["blocks.py"]:::core
        Modules["GraphNetwork / GraphIndependent"]:::core
    end

    %% Infrastructure & Tooling
    subgraph "Infrastructure & Tooling"
        Setup["setup.py"]:::infra
        Docs["docs/"]:::demo
        Images["images/"]:::demo
        subgraph "Demos"
            D1["graph_nets_basics.ipynb"]:::demo
            D2["models.py"]:::demo
            D3["physics.ipynb"]:::demo
            D4["shortest_path.ipynb"]:::demo
            D5["sort.ipynb"]:::demo
            D6["graph_nets_basics.ipynb (TF2)"]:::demo
            D7["models.py (TF2)"]:::demo
            D8["sort.ipynb (TF2)"]:::demo
        end
        subgraph "Tests"
            T1["blocks_test.py"]:::infra
            T2["graphs_test.py"]:::infra
            T3["modules_test.py"]:::infra
            T4["test_utils.py"]:::infra
            T5["utils_np_test.py"]:::infra
            T6["utils_tf_test.py"]:::infra
            T7["blocks_test.py (TF2)"]:::infra
            T8["modules_test.py (TF2)"]:::infra
            T9["test_utils.py (TF2)"]:::infra
            T10["utils_tf_test.py (TF2)"]:::infra
        end
        DocTop["README.md / CONTRIBUTING.md / LICENSE"]:::infra
    end

    %% External Dependencies
    subgraph "External Dependencies"
        TF["TensorFlow"]:::external
        Sonnet["Sonnet"]:::external
        TFP["TensorFlow Probability"]:::external
        Python["Python runtime"]:::external
    end

    %% User Code
    User["User Code"]:::external

    %% Connections
    User -->|imports| GT
    GT -->|constructs| Modules
    Modules -->|invokes| Blocks
    Modules -->|relies on| Base
    Modules -->|uses| UN
    Modules -->|uses| UT
    D1 -->|imports| GT
    D1 -->|calls| Modules
    D1 -->|depends on| TF
    D1 -->|depends on| Sonnet
    Setup -->|packages| GT
    Setup -->|distributes| Docs
    Setup -->|includes| Images
    Setup -->|installs into| Python
    TF -->|backend for| Modules
    Sonnet -->|backend for| Modules

    %% Click Events
    click GT "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/graphs.py"
    click UN "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/utils_np.py"
    click UT "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/utils_tf.py"
    click Base "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/_base.py"
    click Blocks "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/blocks.py"
    click Modules "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/modules.py"
    click D1 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos/graph_nets_basics.ipynb"
    click D2 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos/models.py"
    click D3 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos/physics.ipynb"
    click D4 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos/shortest_path.ipynb"
    click D5 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos/sort.ipynb"
    click D6 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos_tf2/graph_nets_basics.ipynb"
    click D7 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos_tf2/models.py"
    click D8 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/demos_tf2/sort.ipynb"
    click Docs "https://github.com/google-deepmind/graph_nets/tree/master/docs/"
    click Setup "https://github.com/google-deepmind/graph_nets/blob/master/setup.py"
    click Images "https://github.com/google-deepmind/graph_nets/tree/master/images/"
    click T1 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests/blocks_test.py"
    click T2 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests/graphs_test.py"
    click T3 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests/modules_test.py"
    click T4 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests/test_utils.py"
    click T5 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests/utils_np_test.py"
    click T6 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests/utils_tf_test.py"
    click T7 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests_tf2/blocks_test.py"
    click T8 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests_tf2/modules_test.py"
    click T9 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests_tf2/test_utils.py"
    click T10 "https://github.com/google-deepmind/graph_nets/blob/master/graph_nets/tests_tf2/utils_tf_test.py"

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C
    classDef util fill:#A9DFBF,stroke:#196F3D
    classDef infra fill:#FAD7A0,stroke:#B9770E
    classDef demo fill:#F5CBA7,stroke:#A04000
    classDef external fill:#D5D8DC,stroke:#5D6D7E
```
