# google-research/circuit_training architecture

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

- Interactive diagram: https://gitdiagram.com/google-research/circuit_training
- Repository: https://github.com/google-research/circuit_training

## Overview

AlphaChip generates chip floorplans through clustered netlist preprocessing, reinforcement-learning macro placement, placement-cost evaluation, and optional DREAMPlace standard-cell refinement. Users provide a netlist; grouping produces clustered data, the environment exposes placement observations and rewards, PPO actors learn placement policies, and the resulting floorplan can be refined and exported. The graph preserves documented congestion, density, spacing, alignment, fixed-macro, orientation, and distributed-training capabilities. Some orchestration paths are inferred from module roles because only selected source excerpts were available.

Main entry points: [`circuit_training/environment/environment.py`](https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/environment.py) (Placement Environment), [`circuit_training/grouping/grouper.py`](https://github.com/google-research/circuit_training/blob/main/circuit_training/grouping/grouper.py) (Netlist Grouper), [`circuit_training/environment/plc_client.py`](https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/plc_client.py) (Placement Cost Client), [`circuit_training/learning/train_ppo_lib.py`](https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/train_ppo_lib.py) (PPO Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_input["Netlist Preparation"]
  node_netlist["Input Netlist"]
  node_grouping["Netlist Grouper<br/>[grouper.py]"]
  node_group_logic["Grouping Logic<br/>[grouping.py]"]
  node_clustered_netlist["Clustered Netlist"]
end

subgraph group_g_env["Placement Environment"]
  node_environment["Placement Environment<br/>[environment.py]"]
  node_observations["Observation Extractor"]
  node_plc_client["Placement Cost Client<br/>[plc_client.py]"]
end

subgraph group_g_learning["Distributed Learning"]
  node_ppo_collect["PPO Data Collection<br/>[ppo_collect_lib.py]"]
  node_reverb["Replay Service"]
  node_model_wrapper["Policy Value Models<br/>[model.py]"]
  node_neural_model["Graph Neural Model<br/>[model_lib.py]"]
  node_ppo_agent["PPO Agent<br/>[agent.py]"]
  node_ppo_training["PPO Training<br/>[train_ppo_lib.py]"]
end

subgraph group_g_backend["Placement Backends"]
  node_dreamplace_core["DREAMPlace Refinement<br/>[dreamplace_core.py]"]
  node_plc_converter["DREAMPlace Converter<br/>[plc_converter.py]"]
  node_coordinate_descent["Coordinate Descent"]
end

subgraph group_g_result["Floorplan Results"]
  node_floorplan["Final Floorplan"]
end

node_user(("Chip Designer"))
node_placement_cost["Placement Cost Service"]

node_user -->|"provides"| node_netlist
node_netlist -->|"reads"| node_grouping
node_grouping -->|"partitions"| node_group_logic
node_grouping -->|"writes"| node_clustered_netlist
node_grouping -->|"evaluates"| node_plc_client
node_plc_client -->|"calls"| node_placement_cost
node_clustered_netlist -->|"initializes"| node_environment
node_environment -->|"extracts"| node_observations
node_environment -->|"queries"| node_plc_client
node_environment -->|"feeds episodes"| node_ppo_collect
node_ppo_collect -->|"publishes trajectories"| node_reverb
node_ppo_training -->|"reads trajectories"| node_reverb
node_ppo_training -->|"trains"| node_ppo_agent
node_ppo_agent -->|"runs networks"| node_model_wrapper
node_model_wrapper -->|"constructs"| node_neural_model
node_ppo_training -->|"saves policy"| node_model_wrapper
node_environment -.->|"optimizes coordinates"| node_coordinate_descent
node_dreamplace_core -->|"converts data"| node_plc_converter
node_plc_converter -->|"reads placement"| node_plc_client
node_dreamplace_core -->|"outputs refinement"| node_floorplan
node_coordinate_descent -.->|"outputs placement"| node_floorplan
node_user -->|"receives"| node_floorplan

click node_grouping "https://github.com/google-research/circuit_training/blob/main/circuit_training/grouping/grouper.py"
click node_group_logic "https://github.com/google-research/circuit_training/blob/main/circuit_training/grouping/grouping.py"
click node_environment "https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/environment.py"
click node_observations "https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/observation_extractor.py"
click node_plc_client "https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/plc_client.py"
click node_ppo_collect "https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/ppo_collect_lib.py"
click node_reverb "https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/ppo_reverb_server_lib.py"
click node_model_wrapper "https://github.com/google-research/circuit_training/blob/main/circuit_training/model/model.py"
click node_neural_model "https://github.com/google-research/circuit_training/blob/main/circuit_training/model/model_lib.py"
click node_ppo_agent "https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/agent.py"
click node_ppo_training "https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/train_ppo_lib.py"
click node_dreamplace_core "https://github.com/google-research/circuit_training/blob/main/circuit_training/dreamplace/dreamplace_core.py"
click node_plc_converter "https://github.com/google-research/circuit_training/blob/main/circuit_training/dreamplace/plc_converter.py"
click node_coordinate_descent "https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/coordinate_descent_placer.py"

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_netlist,node_grouping,node_group_logic,node_clustered_netlist toneBlue
class node_environment,node_observations,node_plc_client toneAmber
class node_ppo_collect,node_reverb,node_model_wrapper,node_neural_model,node_ppo_agent,node_ppo_training toneMint
class node_dreamplace_core,node_plc_converter,node_coordinate_descent toneRose
class node_floorplan,node_user,node_placement_cost toneIndigo
```

## Components

### Netlist Preparation

- **Input Netlist**
- [Netlist Grouper](https://github.com/google-research/circuit_training/blob/main/circuit_training/grouping/grouper.py): `circuit_training/grouping/grouper.py`
- [Grouping Logic](https://github.com/google-research/circuit_training/blob/main/circuit_training/grouping/grouping.py): `circuit_training/grouping/grouping.py`
- **Clustered Netlist**

### Placement Environment

- [Placement Environment](https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/environment.py): `circuit_training/environment/environment.py`
- [Observation Extractor](https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/observation_extractor.py): `circuit_training/environment/observation_extractor.py`
- [Placement Cost Client](https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/plc_client.py): `circuit_training/environment/plc_client.py`

### Distributed Learning

- [PPO Data Collection](https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/ppo_collect_lib.py): `circuit_training/learning/ppo_collect_lib.py`
- [Replay Service](https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/ppo_reverb_server_lib.py): `circuit_training/learning/ppo_reverb_server_lib.py`
- [Policy Value Models](https://github.com/google-research/circuit_training/blob/main/circuit_training/model/model.py): `circuit_training/model/model.py`
- [Graph Neural Model](https://github.com/google-research/circuit_training/blob/main/circuit_training/model/model_lib.py): `circuit_training/model/model_lib.py`
- [PPO Agent](https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/agent.py): `circuit_training/learning/agent.py`
- [PPO Training](https://github.com/google-research/circuit_training/blob/main/circuit_training/learning/train_ppo_lib.py): `circuit_training/learning/train_ppo_lib.py`

### Placement Backends

- [DREAMPlace Refinement](https://github.com/google-research/circuit_training/blob/main/circuit_training/dreamplace/dreamplace_core.py): `circuit_training/dreamplace/dreamplace_core.py`
- [DREAMPlace Converter](https://github.com/google-research/circuit_training/blob/main/circuit_training/dreamplace/plc_converter.py): `circuit_training/dreamplace/plc_converter.py`
- [Coordinate Descent](https://github.com/google-research/circuit_training/blob/main/circuit_training/environment/coordinate_descent_placer.py): `circuit_training/environment/coordinate_descent_placer.py`

### Floorplan Results

- **Final Floorplan**

### Other components

- **Chip Designer**
- **Placement Cost Service**

## Connections

- Chip Designer → Input Netlist: provides
- Input Netlist → Netlist Grouper: reads
- Netlist Grouper → Grouping Logic: partitions
- Netlist Grouper → Clustered Netlist: writes
- Netlist Grouper → Placement Cost Client: evaluates
- Placement Cost Client → Placement Cost Service: calls
- Clustered Netlist → Placement Environment: initializes
- Placement Environment → Observation Extractor: extracts
- Placement Environment → Placement Cost Client: queries
- Placement Environment → PPO Data Collection: feeds episodes
- PPO Data Collection → Replay Service: publishes trajectories
- PPO Training → Replay Service: reads trajectories
- PPO Training → PPO Agent: trains
- PPO Agent → Policy Value Models: runs networks
- Policy Value Models → Graph Neural Model: constructs
- PPO Training → Policy Value Models: saves policy
- Placement Environment → Coordinate Descent: optimizes coordinates
- DREAMPlace Refinement → DREAMPlace Converter: converts data
- DREAMPlace Converter → Placement Cost Client: reads placement
- DREAMPlace Refinement → Final Floorplan: outputs refinement
- Coordinate Descent → Final Floorplan: outputs placement
- Chip Designer → Final Floorplan: receives
