# google/ml-compiler-opt architecture

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

- Interactive diagram: https://gitdiagram.com/google/ml-compiler-opt
- Repository: https://github.com/google/ml-compiler-opt

## Overview

##### Project type and purpose
- MLGO is an open-source Python framework for training machine-learning-driven compiler optimizations (in LLVM). It provides CLI scripts, libraries, and distributed/local trainers (Policy Gradient today, ES planned) to replace hard-coded inlining and register-allocation heuristics with learned models.

##### High-level architecture overview
At its core, MLGO is a pipeline with these major phases:
a. Configuration & orchestration (CLI entrypoints + gin config system)
b. Data generation & collection (feature extraction from LLVM IR corpora, traces)
c. Training loop (RL trainer or ES trainer, local or distributed)
d. Model serialization (TensorFlow SavedModel)
e. Benchmarking & evaluation (scripts to measure performance against LLVM baselines)
f. Integration & deployment (buildbot scripts, LLVM CMake flags to load models)

##### Main components & how they interact
- CLI Entrypoints (train_locally.py, train_bc.py, inlining_runner.py, regalloc_runner.py)
– Invoke pipeline based on gin configs.
– Pass control to the orchestration layer.
- Orchestration Layer (compiler_opt.rl.compilation_runner and equivalent ES trainer)
– Reads gin configs, spawns data collectors and workers.
– For distributed mode: interacts with ppo_reverb_server, ppo_collect, ppo_train, ppo_eval.
– For local mode: uses LocalDataCollector and local WorkerManager.
- Data Collection & Environment
– compiler_opt.rl.data_collector / local_data_collector: compile code with LLVM “development-mode,” extract IR features, traces.
– compiler_opt.es.blackbox_evaluator / inlining_worker / regalloc_trace_worker for ES pipelines.
- Policy & Learner
– RL: constant_value_network, policy_saver, ppo_*.py (distributed)
– ES: blackbox_learner, blackbox_evaluators
– Both rely on TensorFlow and gin-configurable networks.
- Storage & Serialization
– Models serialized as TensorFlow SavedModel (saved_model.pb + variables/).
– Pipelines write checkpoints & logs.
- Benchmarking & Reporting
– compiler_opt.benchmark: list_gtests, gtest_executable_utils, benchmark_report_converter.
– Produce performance regressions or wins vs. LLVM defaults.
- Buildbot & Deployment
– buildbot scripts to compile LLVM, point -DLLVM_INLINER_MODEL_PATH to “download” or local model.
– check-license, CI workflows, Dockerfile for reproducible environments.

##### Architectural patterns & principles
- Separation of concerns: CLI/orchestrator vs. data collection vs. training vs. evaluation
- Modular design: “compiler_opt” Python package divided into subpackages (rl, es, benchmark, tools, distributed)
- Pluggable configuration: gin-config files in each subpackage to swap agents/algorithms without code changes
- Support for horizontal scaling: distributed learners & collectors coordinate via Reverb (actor-learner pattern)

##### Final recommendations
- External dependencies (TensorFlow, LLVM, Docker, GitHub releases) at the periphery

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User/API Layer
    subgraph "User/API Layer"
        direction TB
        train_locally["train_locally.py"]:::api
        train_bc["train_bc.py"]:::api
        inlining_runner["inlining_runner.py"]:::api
        regalloc_runner["regalloc_runner.py"]:::api
    end

    %% Config Layer
    subgraph "Config Layer"
        direction TB
        rl_inlining_gin["RL Inlining Gin Configs"]:::config
        rl_regalloc_gin["RL Regalloc Gin Configs"]:::config
        rl_dist_gin["RL Distributed Gin Configs"]:::config
        es_inlining_gin["ES Inlining Gin Configs"]:::config
        es_regalloc_gin["ES RegallocTrace Gin Configs"]:::config
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        rl_data_collector["data_collector.py"]:::data
        rl_env["env.py"]:::data
        es_inlining_worker["inlining_worker.py"]:::data
        es_regalloc_worker["regalloc_trace_worker.py"]:::data
    end

    %% Training Layer
    subgraph "Training Layer"
        direction TB
        %% Orchestration
        rl_comp_runner["compilation_runner.py"]:::training
        es_trainer_lib["es_trainer_lib.py"]:::training
        es_trainer["es_trainer.py"]:::training
        %% Local Mode
        local_collector["local_data_collector.py"]:::training
        local_worker_mgr["local_worker_manager.py"]:::training
        %% Distributed Mode
        ppo_reverb_svr_lib["ppo_reverb_server_lib.py"]:::training
        ppo_reverb_svr["ppo_reverb_server.py"]:::training
        ppo_collect_lib["ppo_collect_lib.py"]:::training
        ppo_collect["ppo_collect.py"]:::training
        ppo_train_lib["ppo_train_lib.py"]:::training
        ppo_train["ppo_train.py"]:::training
        ppo_eval_lib["ppo_eval_lib.py"]:::training
        ppo_eval["ppo_eval.py"]:::training
        %% Policy & Learner
        const_value_net["constant_value_network.py"]:::training
        policy_saver["policy_saver.py"]:::training
        es_blackbox_learner["blackbox_learner.py"]:::training
        es_blackbox_evaluator["blackbox_evaluator.py"]:::training
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        savedmodel["TensorFlow SavedModel"]:::model
        checkpoints["Checkpoints & Logs"]:::model
    end

    %% Benchmark & Integration Layer
    subgraph "Benchmark & Integration Layer"
        direction TB
        list_gtests["list_gtests.py"]:::integ
        gtest_utils["gtest_executable_utils.py"]:::integ
        report_converter["benchmark_report_converter.py"]:::integ
        benchmark_chromium["benchmark_chromium.py"]:::integ
        benchmark_llvm["benchmark_llvm_test_suite.py"]:::integ
        buildbot_init["buildbot_init.sh"]:::integ
        build_tflite["build_tflite.sh"]:::integ
        license_check["check-license.sh"]:::integ
        dockerfile["Dockerfile"]:::integ
        dev_docker["development.Dockerfile"]:::integ
        LLVM["LLVM Compiler"]:::external
        TensorFlow["TensorFlow"]:::external
        Docker["Docker"]:::external
        GitHub["GitHub Releases"]:::external
    end

    %% Flows
    train_locally -->|"reads"| rl_inlining_gin
    train_locally -->|"reads"| rl_regalloc_gin
    train_bc -->|"reads"| rl_inlining_gin
    inlining_runner -->|"reads"| rl_inlining_gin
    regalloc_runner -->|"reads"| rl_regalloc_gin

    rl_inlining_gin --> rl_comp_runner
    rl_regalloc_gin --> rl_comp_runner
    rl_comp_runner --> rl_data_collector
    rl_data_collector --> rl_env
    rl_env --> const_value_net
    rl_env --> es_blackbox_evaluator

    local_collector --> local_worker_mgr
    local_worker_mgr --> const_value_net
    rl_comp_runner --> ppo_collect
    ppo_collect --> ppo_reverb_svr
    ppo_reverb_svr --> ppo_train
    ppo_train --> ppo_eval
    ppo_eval --> policy_saver

    es_trainer_lib --> es_trainer
    es_trainer --> es_inlining_worker
    es_trainer --> es_regalloc_worker
    es_inlining_worker --> es_blackbox_learner
    es_regalloc_worker --> es_blackbox_learner

    policy_saver --> savedmodel
    es_blackbox_learner --> checkpoints

    savedmodel --> buildbot_init
    buildbot_init --> LLVM
    savedmodel --> build_tflite
    build_tflite --> Docker
    checkpoints --> benchmark_chromium
    checkpoints --> benchmark_llvm
    benchmark_chromium --> report_converter
    benchmark_llvm --> report_converter
    report_converter --> GitHub

    %% Click Events
    click train_locally "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/train_locally.py"
    click train_bc "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/train_bc.py"
    click inlining_runner "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/inlining/inlining_runner.py"
    click regalloc_runner "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/regalloc/regalloc_runner.py"
    click rl_comp_runner "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/compilation_runner.py"
    click es_trainer "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/es/es_trainer.py"
    click es_trainer_lib "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/es/es_trainer_lib.py"
    click ppo_reverb_svr "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_reverb_server.py"
    click ppo_reverb_svr_lib "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_reverb_server_lib.py"
    click ppo_collect "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_collect.py"
    click ppo_collect_lib "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_collect_lib.py"
    click ppo_train "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_train.py"
    click ppo_train_lib "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_train_lib.py"
    click ppo_eval "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_eval.py"
    click ppo_eval_lib "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/distributed/ppo_eval_lib.py"
    click local_collector "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/local_data_collector.py"
    click local_worker_mgr "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/distributed/local/local_worker_manager.py"
    click rl_data_collector "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/data_collector.py"
    click rl_env "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/env.py"
    click es_inlining_worker "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/es/inlining/inlining_worker.py"
    click es_regalloc_worker "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/es/regalloc_trace/regalloc_trace_worker.py"
    click const_value_net "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/constant_value_network.py"
    click policy_saver "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/rl/policy_saver.py"
    click es_blackbox_learner "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/es/blackbox_learner.py"
    click es_blackbox_evaluator "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/es/blackbox_evaluator.py"
    click rl_inlining_gin "https://github.com/google/ml-compiler-opt/tree/main/compiler_opt/rl/inlining/gin_configs/"
    click rl_regalloc_gin "https://github.com/google/ml-compiler-opt/tree/main/compiler_opt/rl/regalloc/gin_configs/"
    click rl_dist_gin "https://github.com/google/ml-compiler-opt/tree/main/compiler_opt/rl/distributed/gin_configs/"
    click es_inlining_gin "https://github.com/google/ml-compiler-opt/tree/main/compiler_opt/es/inlining/gin_configs/"
    click es_regalloc_gin "https://github.com/google/ml-compiler-opt/tree/main/compiler_opt/es/regalloc_trace/gin_configs/"
    click list_gtests "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/benchmark/list_gtests.py"
    click gtest_utils "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/benchmark/gtest_executable_utils.py"
    click report_converter "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/benchmark/benchmark_report_converter.py"
    click benchmark_chromium "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/benchmark/benchmark_chromium.py"
    click benchmark_llvm "https://github.com/google/ml-compiler-opt/blob/main/compiler_opt/benchmark/benchmark_llvm_test_suite.py"
    click buildbot_init "https://github.com/google/ml-compiler-opt/blob/main/buildbot/buildbot_init.sh"
    click build_tflite "https://github.com/google/ml-compiler-opt/blob/main/buildbot/build_tflite.sh"
    click license_check "https://github.com/google/ml-compiler-opt/blob/main/check-license.sh"
    click dockerfile "https://github.com/google/ml-compiler-opt/tree/main/Dockerfile"
    click dev_docker "https://github.com/google/ml-compiler-opt/blob/main/experimental/docker/development.Dockerfile"

    %% Styles
    classDef api fill:#f9f,stroke:#333,stroke-width:1px;
    classDef config fill:#bbf,stroke:#333,stroke-width:1px;
    classDef data fill:#acf,stroke:#333,stroke-width:1px;
    classDef training fill:#cfc,stroke:#333,stroke-width:1px;
    classDef model fill:#fcf,stroke:#333,stroke-width:1px;
    classDef integ fill:#fbb,stroke:#333,stroke-width:1px;
    classDef external fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5;
```
