# cuhk-eda/xplace architecture

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

- Interactive diagram: https://gitdiagram.com/cuhk-eda/xplace
- Repository: https://github.com/cuhk-eda/xplace

## Overview

Xplace is a GPU-accelerated chip global-placement framework. Users provide a benchmark or custom design and placement options; the Python entry point hands execution to the placement workflow, which loads a design, initializes placement, optimizes positions, and can proceed through legalization, detailed placement, and evaluation. Documented optional branches add timing-driven optimization, routability-aware placement, and GPU global routing; a standalone GPU timer is another product capability. The graph follows documented workflow stages; several orchestration and optional-feature links rely on README descriptions because their implementation was not sampled.

Main entry points: [`src/run_placement.py`](https://github.com/cuhk-eda/xplace/blob/main/src/run_placement.py) (Placement workflow), [`src/nesterov_optimizer.py`](https://github.com/cuhk-eda/xplace/blob/main/src/nesterov_optimizer.py) (Global placement optimizer), [`src/database.py`](https://github.com/cuhk-eda/xplace/blob/main/src/database.py) (Design loader), [`main.py`](https://github.com/cuhk-eda/xplace/blob/main/main.py) (Python CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Design input"]
  node_cli["Python CLI<br/>[main.py]"]
  node_loader["Design loader<br/>[database.py]"]
  node_nativeparse["Native design parser"]
  node_placedb[("Placement database<br/>[database.py]")]
end

subgraph group_placement["Placement optimization"]
  node_workflow["Placement workflow<br/>[run_placement.py]"]
  node_initializer["Placement initialization<br/>[initializer.py]"]
  node_optimizer["Global placement optimizer"]
  node_objectives["Placement objectives"]
  node_scheduler["Parameter scheduling<br/>[param_scheduler.py]"]
end

subgraph group_refinement["Refinement and evaluation"]
  node_legalizer["Legalization"]
  node_detail["Detailed placement"]
  node_evaluator["Placement evaluation<br/>[evaluator.py]"]
end

subgraph group_extensions["Timing and routing"]
  node_timingopt["Timing optimization<br/>[timing_opt.py]"]
  node_timer["GPU timing engine"]
  node_router["GPU global router"]
  node_routeforce["Routing force<br/>[route_force.py]"]
end

node_user(("Placement user"))
node_placementresult["Placement result"]

node_user -->|"sets options"| node_cli
node_cli -->|"starts workflow"| node_workflow
node_workflow -->|"loads design"| node_loader
node_loader -->|"parses input"| node_nativeparse
node_loader -->|"builds model"| node_placedb
node_workflow -->|"initializes placement"| node_initializer
node_initializer -->|"reads design"| node_placedb
node_workflow -->|"runs optimization"| node_optimizer
node_optimizer -->|"updates positions"| node_placedb
node_optimizer -->|"evaluates costs"| node_objectives
node_optimizer -->|"gets parameters"| node_scheduler
node_workflow -->|"legalizes placement"| node_legalizer
node_workflow -->|"refines placement"| node_detail
node_workflow -->|"evaluates result"| node_evaluator
node_workflow -->|"writes outputs"| node_placementresult
node_workflow -.->|"enables timing mode"| node_timingopt
node_timingopt -.->|"computes timing"| node_timer
node_workflow -.->|"enables routability mode"| node_routeforce
node_routeforce -.->|"uses routing estimates"| node_router
node_workflow -.->|"runs route evaluation"| node_router
node_timer -.->|"reports timing"| node_user

click node_cli "https://github.com/cuhk-eda/xplace/blob/main/main.py"
click node_loader "https://github.com/cuhk-eda/xplace/blob/main/src/database.py"
click node_nativeparse "https://github.com/cuhk-eda/xplace/tree/main/cpp_to_py/io_parser"
click node_placedb "https://github.com/cuhk-eda/xplace/blob/main/src/database.py"
click node_workflow "https://github.com/cuhk-eda/xplace/blob/main/src/run_placement.py"
click node_initializer "https://github.com/cuhk-eda/xplace/blob/main/src/initializer.py"
click node_optimizer "https://github.com/cuhk-eda/xplace/blob/main/src/nesterov_optimizer.py"
click node_objectives "https://github.com/cuhk-eda/xplace/tree/main/src/core"
click node_scheduler "https://github.com/cuhk-eda/xplace/blob/main/src/param_scheduler.py"
click node_legalizer "https://github.com/cuhk-eda/xplace/blob/main/src/core/macro_legalization.py"
click node_detail "https://github.com/cuhk-eda/xplace/blob/main/src/detail_placement.py"
click node_evaluator "https://github.com/cuhk-eda/xplace/blob/main/src/evaluator.py"
click node_timingopt "https://github.com/cuhk-eda/xplace/blob/main/src/core/timing_opt.py"
click node_timer "https://github.com/cuhk-eda/xplace/tree/main/cpp_to_py/gputimer"
click node_router "https://github.com/cuhk-eda/xplace/tree/main/cpp_to_py/gpugr"
click node_routeforce "https://github.com/cuhk-eda/xplace/blob/main/src/core/route_force.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_cli,node_loader,node_nativeparse,node_placedb,node_user toneBlue
class node_workflow,node_initializer,node_optimizer,node_objectives,node_scheduler toneAmber
class node_legalizer,node_detail,node_evaluator toneMint
class node_timingopt,node_timer,node_router,node_routeforce toneRose
class node_placementresult toneIndigo
```

## Components

### Design input

- [Python CLI](https://github.com/cuhk-eda/xplace/blob/main/main.py): `main.py`
- [Design loader](https://github.com/cuhk-eda/xplace/blob/main/src/database.py): `src/database.py`
- [Native design parser](https://github.com/cuhk-eda/xplace/tree/main/cpp_to_py/io_parser): `cpp_to_py/io_parser`
- [Placement database](https://github.com/cuhk-eda/xplace/blob/main/src/database.py): `src/database.py`

### Placement optimization

- [Placement workflow](https://github.com/cuhk-eda/xplace/blob/main/src/run_placement.py): `src/run_placement.py`
- [Placement initialization](https://github.com/cuhk-eda/xplace/blob/main/src/initializer.py): `src/initializer.py`
- [Global placement optimizer](https://github.com/cuhk-eda/xplace/blob/main/src/nesterov_optimizer.py): `src/nesterov_optimizer.py`
- [Placement objectives](https://github.com/cuhk-eda/xplace/tree/main/src/core): `src/core`
- [Parameter scheduling](https://github.com/cuhk-eda/xplace/blob/main/src/param_scheduler.py): `src/param_scheduler.py`

### Refinement and evaluation

- [Legalization](https://github.com/cuhk-eda/xplace/blob/main/src/core/macro_legalization.py): `src/core/macro_legalization.py`
- [Detailed placement](https://github.com/cuhk-eda/xplace/blob/main/src/detail_placement.py): `src/detail_placement.py`
- [Placement evaluation](https://github.com/cuhk-eda/xplace/blob/main/src/evaluator.py): `src/evaluator.py`

### Timing and routing

- [Timing optimization](https://github.com/cuhk-eda/xplace/blob/main/src/core/timing_opt.py): `src/core/timing_opt.py`
- [GPU timing engine](https://github.com/cuhk-eda/xplace/tree/main/cpp_to_py/gputimer): `cpp_to_py/gputimer`
- [GPU global router](https://github.com/cuhk-eda/xplace/tree/main/cpp_to_py/gpugr): `cpp_to_py/gpugr`
- [Routing force](https://github.com/cuhk-eda/xplace/blob/main/src/core/route_force.py): `src/core/route_force.py`

### Other components

- **Placement user**
- **Placement result**

## Connections

- Placement user → Python CLI: sets options
- Python CLI → Placement workflow: starts workflow
- Placement workflow → Design loader: loads design
- Design loader → Native design parser: parses input
- Design loader → Placement database: builds model
- Placement workflow → Placement initialization: initializes placement
- Placement initialization → Placement database: reads design
- Placement workflow → Global placement optimizer: runs optimization
- Global placement optimizer → Placement database: updates positions
- Global placement optimizer → Placement objectives: evaluates costs
- Global placement optimizer → Parameter scheduling: gets parameters
- Placement workflow → Legalization: legalizes placement
- Placement workflow → Detailed placement: refines placement
- Placement workflow → Placement evaluation: evaluates result
- Placement workflow → Placement result: writes outputs
- Placement workflow → Timing optimization: enables timing mode
- Timing optimization → GPU timing engine: computes timing
- Placement workflow → Routing force: enables routability mode
- Routing force → GPU global router: uses routing estimates
- Placement workflow → GPU global router: runs route evaluation
- GPU timing engine → Placement user: reports timing