# google-deepmind/alphatensor architecture

> Architecture diagram of the GitHub repository google-deepmind/alphatensor, 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/alphatensor
- Repository: https://github.com/google-deepmind/alphatensor

## Overview

##### Project type and purpose
- This is an open-source research codebase accompanying the “AlphaTensor” paper.
- It bundles four independent pipelines (no single monolithic service):
- algorithms – precomputed matrix multiplication factorizations + a Colab notebook for exploration
- benchmarking – scripts to measure GPU performance of those algorithms
- nonequivalence – dataset of 14 236 distinct factorizations + a Colab notebook to verify nonequivalence
- recombination – a Python module that recombines smaller factorizations to tackle larger problems

##### File-structure analysis
- Top level: README.md, LICENSE, CONTRIBUTING.md, plus four directories.
- algorithms/
- Data: factorizations_r.npz, factorizations_f2.npz
- Notebook: explore_factorizations.ipynb
- benchmarking/
- requirements.txt, benchmarking scripts (run_gpu_benchmark.py, test_correctness.py, utils.py)
- nonequivalence/
- Data: alphatensor_14236_factorizations.npz
- Notebook: inspect_factorizations_notebook.ipynb
- recombination/
- Python modules: recombination.py, sota.py, example.py, recombination_test.py
- requirements.txt

##### README insights
- Each subfolder has its own README or instructions.
- Usage styles:
- algorithms/nonequivalence via Google Colab (user uploads .npz)
- benchmarking via local command-line on an NVIDIA V100 GPU
- recombination via `python3 -m alphatensor.recombination.example`

a. Main components
- Data stores (NumPy .npz files)
- Jupyter notebooks (exploration & verification)
- Python scripts/modules (benchmarking & recombination)
- External environments: Google Colab, local GPU setup
- Dependencies: numpy, absl-py, CUDA runtime

b. Relationships & data flow
- .npz files → notebooks (for exploration or nonequivalence checks)
- .npz files → benchmarking scripts → GPU kernels → timing outputs
- .npz files → recombination module → new factorizations (in memory or written out)
- User ↔ Colab (notebooks); CLI → benchmarking/recombination

c. Architectural patterns
- Modular separation: each pipeline lives in its own folder with isolated deps
- Data-driven workflows: centralized factorizations exploited by all components
- Plugin-style: recombination can be imported into other codebases

d. Key technologies
- Python 3, NumPy, absl-py
- Jupyter/Colab for interactive analysis
- NVIDIA CUDA (via Python bindings)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Environments
    Colab("Google Colab"):::external
    CLI("Local CLI"):::external

    %% Shared Data Stores Section Title
    subgraph "Data Stores"
        direction TB
        AlgoDR["factorizations_r.npz"]:::datastore
        AlgoDF2["factorizations_f2.npz"]:::datastore
        NoneqData["alphatensor_14236_factorizations.npz"]:::datastore
    end

    %% Algorithms Pipeline
    subgraph "Algorithms Pipeline"
        direction TB
        AlgoDR
        AlgoDF2
        ExploreNotebook["explore_factorizations.ipynb"]:::notebook
    end

    AlgoDR -->|loads| ExploreNotebook
    AlgoDF2 -->|loads| ExploreNotebook
    Colab -->|interactive use| ExploreNotebook

    %% Benchmarking Pipeline
    subgraph "Benchmarking Pipeline"
        direction TB
        BenchmarkLoader["factorizations.py"]:::script
        BenchmarkRun["run_gpu_benchmark.py"]:::script
        BenchmarkTest["test_correctness.py"]:::script
        BenchmarkUtils["utils.py"]:::script
        RequirementsBM["requirements.txt"]:::script
    end

    AlgoDR -->|input data| BenchmarkLoader
    AlgoDF2 -->|input data| BenchmarkLoader
    BenchmarkLoader -->|provides data| BenchmarkRun
    BenchmarkLoader -->|provides data| BenchmarkTest
    BenchmarkRun -->|uses| BenchmarkUtils
    BenchmarkTest -->|uses| BenchmarkUtils
    CLI -->|execute scripts| BenchmarkRun
    CLI -->|execute scripts| BenchmarkTest

    %% Nonequivalence Pipeline
    subgraph "Nonequivalence Pipeline"
        direction TB
        NoneqData
        InspectNotebook["inspect_factorizations_notebook.ipynb"]:::notebook
    end

    NoneqData -->|loads| InspectNotebook
    Colab -->|interactive use| InspectNotebook

    %% Recombination Pipeline
    subgraph "Recombination Pipeline"
        direction TB
        RecombModule["recombination.py"]:::script
        SotaModule["sota.py"]:::script
        ExampleCLI["example.py"]:::script
        RecombTest["recombination_test.py"]:::script
        RequirementsRec["requirements.txt"]:::script
    end

    AlgoDR -->|base factorizations| RecombModule
    AlgoDF2 -->|base factorizations| RecombModule
    RecombModule -->|advanced algos| SotaModule
    RecombModule -->|provides API| ExampleCLI
    ExampleCLI -->|runs tests| RecombTest
    CLI -->|run example| ExampleCLI

    %% Click Events
    click AlgoDR "https://github.com/google-deepmind/alphatensor/blob/main/algorithms/factorizations_r.npz"
    click AlgoDF2 "https://github.com/google-deepmind/alphatensor/blob/main/algorithms/factorizations_f2.npz"
    click ExploreNotebook "https://github.com/google-deepmind/alphatensor/blob/main/algorithms/explore_factorizations.ipynb"
    click BenchmarkLoader "https://github.com/google-deepmind/alphatensor/blob/main/benchmarking/factorizations.py"
    click BenchmarkRun "https://github.com/google-deepmind/alphatensor/blob/main/benchmarking/run_gpu_benchmark.py"
    click BenchmarkTest "https://github.com/google-deepmind/alphatensor/blob/main/benchmarking/test_correctness.py"
    click BenchmarkUtils "https://github.com/google-deepmind/alphatensor/blob/main/benchmarking/utils.py"
    click InspectNotebook "https://github.com/google-deepmind/alphatensor/blob/main/nonequivalence/inspect_factorizations_notebook.ipynb"
    click NoneqData "https://github.com/google-deepmind/alphatensor/blob/main/nonequivalence/alphatensor_14236_factorizations.npz"
    click RecombModule "https://github.com/google-deepmind/alphatensor/blob/main/recombination/recombination.py"
    click SotaModule "https://github.com/google-deepmind/alphatensor/blob/main/recombination/sota.py"
    click ExampleCLI "https://github.com/google-deepmind/alphatensor/blob/main/recombination/example.py"
    click RecombTest "https://github.com/google-deepmind/alphatensor/blob/main/recombination/recombination_test.py"

    %% Styles
    classDef datastore fill:#f9f,stroke:#333,stroke-width:1px;
    classDef notebook fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef script fill:#9ff,stroke:#333,stroke-width:1px;
    classDef external fill:#fcf,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
```
