# tarunnagarajan/compiler-opt architecture

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

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

## Overview

This is a research framework for hierarchical reinforcement learning of LLVM optimization policies. The main workflow selects an IR benchmark, extracts state, chooses a strategic macro-action and tactical pass refinement, applies compiler passes, then measures the result for the next decision and reward. Training and evaluation scripts support the research loop, including world-model prediction and baseline comparisons. Relationships among components are limited to those stated in the README or visible in indexed imports; several model and measurement internals were not sampled.

Main entry points: [`src/env/compiler_env.py`](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/env/compiler_env.py) (RL compiler environment), [`src/models/hrl_agent.py`](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/hrl_agent.py) (Hierarchical policy), [`src/models/world_model.py`](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/world_model.py) (World model), [`scripts`](https://github.com/tarunnagarajan/compiler-opt/tree/main/scripts) (Policy and model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_environment["Compiler environment"]
  node_environment["RL compiler environment<br/>[compiler_env.py]"]
  node_config["LLVM and action config<br/>[config.py]"]
  node_profiler["Hardware profiler"]
end

subgraph group_features["IR representation"]
  node_parser["IR parser and CFG<br/>[ir_parser.py]"]
  node_scalar_features["Scalar features<br/>[feature_vector.py]"]
  node_graph_extract["IR graph extraction"]
  node_graph_extract_v5["Loop-aware extraction"]
  node_feature_graph_encoder["Graph encoder<br/>[graph_encoder.py]"]
end

subgraph group_models["Learning models"]
  node_world_model["World model<br/>[world_model.py]"]
  node_world_model_v7["Scale-aware world model<br/>[world_model_v7.py]"]
  node_graph_encoder["Model graph encoder<br/>[graph_encoder.py]"]
  node_graph_encoder_v6["Graph encoder V6"]
  node_policy["Hierarchical policy<br/>[hrl_agent.py]"]
  node_worker["Tactical worker<br/>[hrl_worker.py]"]
  node_history["Pass history encoder<br/>[history_encoder.py]"]
  node_calibrator["Meta calibrator<br/>[meta_calibrator.py]"]
end

subgraph group_execution["Passes and metrics"]
  node_macro_actions["Macro actions<br/>[macro_actions.py]"]
  node_micro_actions["Micro actions<br/>[micro_actions.py]"]
  node_pass_executor["Pass executor<br/>[pass_executor.py]"]
  node_metrics["Metrics and runtime<br/>[metrics.py]"]
end

subgraph group_research["Research workflows"]
  node_training["Policy and model training"]
  node_evaluation["Evaluation and audits"]
end

node_researcher(("Researcher"))
node_benchmarks["Benchmark inputs"]
node_llvm["LLVM toolchain"]

node_researcher -->|"starts episode"| node_environment
node_benchmarks -->|"supplies IR"| node_environment
node_environment -->|"uses configuration"| node_config
node_environment -->|"parses IR"| node_parser
node_environment -->|"applies passes"| node_pass_executor
node_environment -->|"measures outcomes"| node_metrics
node_environment -->|"invokes compiler"| node_llvm
node_environment -.->|"profiles hardware"| node_profiler
node_parser -->|"provides IR stats"| node_scalar_features
node_environment -->|"uses graph encoder"| node_graph_encoder_v6
node_world_model -->|"uses V7 model"| node_world_model_v7
node_world_model_v7 -->|"uses encoder"| node_graph_encoder_v6
node_policy -->|"selects refinements"| node_worker
node_policy -->|"encodes pass history"| node_history
node_policy -.->|"predicts action effects"| node_world_model
node_policy -->|"chooses objectives"| node_macro_actions
node_worker -->|"selects pass refinements"| node_micro_actions
node_environment -->|"accepts macro actions"| node_macro_actions
node_environment -->|"accepts refined passes"| node_micro_actions
node_metrics -->|"compiles benchmarks"| node_llvm
node_calibrator -.->|"calibrates predictions"| node_world_model
node_training -->|"trains against"| node_environment
node_training -->|"trains policy"| node_policy
node_training -->|"trains model"| node_world_model
node_evaluation -->|"evaluates behavior"| node_policy
node_evaluation -->|"compares baselines"| node_llvm

click node_environment "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/env/compiler_env.py"
click node_config "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/config.py"
click node_profiler "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/env/hardware_profiler.py"
click node_parser "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/ir_parser.py"
click node_scalar_features "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/feature_vector.py"
click node_graph_extract "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/ir_graph_extractor.py"
click node_graph_extract_v5 "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/ir_graph_extractor_v5.py"
click node_feature_graph_encoder "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/graph_encoder.py"
click node_world_model "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/world_model.py"
click node_world_model_v7 "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/world_model_v7.py"
click node_graph_encoder "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/graph_encoder.py"
click node_graph_encoder_v6 "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/graph_encoder_v6.py"
click node_policy "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/hrl_agent.py"
click node_worker "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/hrl_worker.py"
click node_history "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/history_encoder.py"
click node_calibrator "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/meta_calibrator.py"
click node_macro_actions "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/actions/macro_actions.py"
click node_micro_actions "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/actions/micro_actions.py"
click node_pass_executor "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/passes/pass_executor.py"
click node_metrics "https://github.com/tarunnagarajan/compiler-opt/blob/main/src/passes/metrics.py"
click node_training "https://github.com/tarunnagarajan/compiler-opt/tree/main/scripts"
click node_evaluation "https://github.com/tarunnagarajan/compiler-opt/tree/main/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_environment,node_config,node_profiler toneBlue
class node_parser,node_scalar_features,node_graph_extract,node_graph_extract_v5,node_feature_graph_encoder toneAmber
class node_world_model,node_world_model_v7,node_graph_encoder,node_graph_encoder_v6,node_policy,node_worker,node_history,node_calibrator toneMint
class node_macro_actions,node_micro_actions,node_pass_executor,node_metrics toneRose
class node_training,node_evaluation,node_researcher,node_benchmarks,node_llvm toneIndigo
```

## Components

### Compiler environment

- [RL compiler environment](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/env/compiler_env.py): `src/env/compiler_env.py`
- [LLVM and action config](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/config.py): `src/config.py`
- [Hardware profiler](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/env/hardware_profiler.py): `src/env/hardware_profiler.py`

### IR representation

- [IR parser and CFG](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/ir_parser.py): `src/features/ir_parser.py`
- [Scalar features](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/feature_vector.py): `src/features/feature_vector.py`
- [IR graph extraction](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/ir_graph_extractor.py): `src/features/ir_graph_extractor.py`
- [Loop-aware extraction](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/ir_graph_extractor_v5.py): `src/features/ir_graph_extractor_v5.py`
- [Graph encoder](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/features/graph_encoder.py): `src/features/graph_encoder.py`

### Learning models

- [World model](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/world_model.py): `src/models/world_model.py`
- [Scale-aware world model](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/world_model_v7.py): `src/models/world_model_v7.py`
- [Model graph encoder](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/graph_encoder.py): `src/models/graph_encoder.py`
- [Graph encoder V6](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/graph_encoder_v6.py): `src/models/graph_encoder_v6.py`
- [Hierarchical policy](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/hrl_agent.py): `src/models/hrl_agent.py`
- [Tactical worker](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/hrl_worker.py): `src/models/hrl_worker.py`
- [Pass history encoder](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/history_encoder.py): `src/models/history_encoder.py`
- [Meta calibrator](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/models/meta_calibrator.py): `src/models/meta_calibrator.py`

### Passes and metrics

- [Macro actions](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/actions/macro_actions.py): `src/actions/macro_actions.py`
- [Micro actions](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/actions/micro_actions.py): `src/actions/micro_actions.py`
- [Pass executor](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/passes/pass_executor.py): `src/passes/pass_executor.py`
- [Metrics and runtime](https://github.com/tarunnagarajan/compiler-opt/blob/main/src/passes/metrics.py): `src/passes/metrics.py`

### Research workflows

- [Policy and model training](https://github.com/tarunnagarajan/compiler-opt/tree/main/scripts): `scripts`
- [Evaluation and audits](https://github.com/tarunnagarajan/compiler-opt/tree/main/scripts): `scripts`

### Other components

- **Researcher**
- **Benchmark inputs**
- **LLVM toolchain**

## Connections

- Researcher → RL compiler environment: starts episode (evidence: `README.md`)
- Benchmark inputs → RL compiler environment: supplies IR (evidence: `README.md`)
- RL compiler environment → LLVM and action config: uses configuration (evidence: `src/env/compiler_env.py`)
- RL compiler environment → IR parser and CFG: parses IR (evidence: `src/env/compiler_env.py`)
- RL compiler environment → Pass executor: applies passes (evidence: `src/env/compiler_env.py`)
- RL compiler environment → Metrics and runtime: measures outcomes (evidence: `README.md`)
- RL compiler environment → LLVM toolchain: invokes compiler (evidence: `README.md`)
- RL compiler environment → Hardware profiler: profiles hardware
- IR parser and CFG → Scalar features: provides IR stats (evidence: `src/features/feature_vector.py`)
- RL compiler environment → Graph encoder V6: uses graph encoder (evidence: `src/env/compiler_env.py`)
- World model → Scale-aware world model: uses V7 model (evidence: `src/models/world_model.py`)
- Scale-aware world model → Graph encoder V6: uses encoder (evidence: `src/models/world_model_v7.py`)
- Hierarchical policy → Tactical worker: selects refinements (evidence: `README.md`)
- Hierarchical policy → Pass history encoder: encodes pass history (evidence: `README.md`)
- Hierarchical policy → World model: predicts action effects
- Hierarchical policy → Macro actions: chooses objectives (evidence: `README.md`)
- Tactical worker → Micro actions: selects pass refinements (evidence: `src/models/hrl_worker.py`)
- RL compiler environment → Macro actions: accepts macro actions (evidence: `src/env/compiler_env.py`)
- RL compiler environment → Micro actions: accepts refined passes (evidence: `src/env/compiler_env.py`)
- Metrics and runtime → LLVM toolchain: compiles benchmarks (evidence: `src/passes/metrics.py`)
- Meta calibrator → World model: calibrates predictions
- Policy and model training → RL compiler environment: trains against (evidence: `README.md`)
- Policy and model training → Hierarchical policy: trains policy (evidence: `README.md`)
- Policy and model training → World model: trains model (evidence: `README.md`)
- Evaluation and audits → Hierarchical policy: evaluates behavior (evidence: `README.md`)
- Evaluation and audits → LLVM toolchain: compares baselines (evidence: `README.md`)