# qlayout-rust

**Repository Path**: redfalsh/qlayout-rust

## Basic Information

- **Project Name**: qlayout-rust
- **Description**: No description available
- **Primary Language**: Rust
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# qlayout-rust

超导量子芯片 EDA 工具 — Rust 工作空间，基于 KLayout `db` 模块风格的版图引擎。

## 项目结构

```
qlayout-rust/
├── Cargo.toml                  # [workspace] 虚拟清单，5 个成员
├── rust-toolchain.toml         # stable Rust (edition 2021)
├── proto-undo/                 # 独立的 undo 所有权转移原型（非正式依赖）
├── crates/
│   ├── ql-layout/              # ★ 核心版图引擎（KLayout db 风格）
│   ├── ql-project/             # 项目 .ql_pro JSON 读写、库表、文件树
│   ├── ql-pm/                  # 项目管理器：项目创建/打开/库管理
│   └── ql-le/                  # ★ 版图编辑器：布局查看/编辑/DRC
├── docs/
│   ├── decisions/              # 架构决策记录 (ADR)
│   └── ql-layout-architecture.md
└── .sisyphus/                  # 工作计划与证据
```

**关键约束**：crate 之间独立 — `ql-layout` 与 `ql-project` **零跨 crate 依赖**。`ql-pm` 仅依赖 ql-project，`ql-le` 仅依赖 ql-layout，不再有同时依赖两者的 crate。

## 快速开始

**环境要求**：Rust stable (edition 2021)，由 `rust-toolchain.toml` 固定版本。

```bash
# 编译全部 crate
cargo build --workspace

# 运行全部测试（282+）
cargo test --workspace

# 零容忍 lint 检查
cargo clippy --workspace -- -D warnings

# 启动项目管理器
cargo run -p ql-pm

# 启动版图编辑器
cargo run -p ql-le
```

**单 crate 测试**：

```bash
cargo test -p ql-layout          # 版图引擎（127 test）
cargo test -p ql-project         # 项目读写（13 test）
cargo test -p proto-undo         # undo 原型（11 test, 含 Miri）
cargo test -p ql-pm              # 项目管理器
cargo test -p ql-le              # 版图编辑器
```

## ql-layout — 核心版图引擎

仿照 [KLayout](https://www.klayout.de/) 的 `db` 模块设计，提供完整的版图数据管理能力。

### 数据模型

```
Layout                          # 顶层容器
├── cells: SlotMap<CellIndex, Cell>  # Cell 池（稳定句柄）
├── layers: LayerMap             # 层定义表（free-list 实现）
├── cell_map: CellMap            # 名称 → CellIndex 索引
├── dbu: f64                     # 数据库单位（默认 1nm）
└── undo_manager: UndoManager    # 命令模式撤销/重做

Cell                             # 单元
├── name: String
├── shapes: HashMap<LayerIndex, ShapeStore>  # 按层分组的形状
│    └── ShapeStore: 5 × ShapeBucket<T>     # ★ ECS 架构（hecs World）
│         ├── boxes: ShapeBucket<BoxI>
│         ├── polygons: ShapeBucket<Polygon<Coord>>
│         ├── paths: ShapeBucket<Path<Coord>>
│         ├── texts: ShapeBucket<TextI>
│         └── edges: ShapeBucket<EdgeI>
├── instances: Vec<CellInstArray>  # 子单元实例（层次引用）
└── bbox_cache: RefCell<Option<BoxI>>  # 惰性包围盒缓存
```

### Shape 管理 — ECS 架构

每个几何类型的形状通过独立的 `ShapeBucket<T>` 管理，底层使用 **hecs** ECS World 存储。支持：

- **分类存储**：Box、Polygon、Path、Text、Edge 各独立 Bucket，单 archetype 最优遍历
- **标记组件**：`Selected`、`Locked`、`Hidden`、`Highlighted`（ZST 零开销）
- **插入顺序确定性**：`OrderIndex` component 保证迭代顺序
- **Entity 代际安全**：hecs Entity 句柄天然防止 use-after-free

### 核心模块

| 模块 | 功能 |
|------|------|
| `types.rs` | `Coord = i64`, `DCoord = f64`, `CellIndex`, `LayerIndex`, `Error` |
| `dbu.rs` | 数据库单位转换（`to_microns` / `to_dbu`），默认 1nm |
| `geom/` | Point、Boxi、Edge、Polygon（带孔）、Path（等宽）、Text — 全部泛型于坐标类型 |
| `layout.rs` | `Layout`：Cell SlotMap、LayerMap、撤销管理、展平、包围盒 |
| `cell.rs` | `Cell`：按层形状存储、实例引用、惰性 bbox 缓存 |
| `shape.rs` | `ShapeBucket<T>`（ECS 容器）、`ShapeStore`（5 Bucket）、`OrderIndex` |
| `markers.rs` | ECS 标记组件：`Selected`、`Locked`、`Hidden`、`Highlighted` |
| `transform.rs` | `FixpointTrans` + `SimpleTrans` — 8 方向旋转/镜像，compose/invert |
| `region.rs` | `Region`：多边形集合，Sutherland-Hodgman AND 布尔运算 |
| `edges.rs` | `Edges`：DRC width/space 检查 |
| `undo/` | `UndoManager` + `UndoOp` trait + `OwnerPtr` — 命令模式，增量操作（非快照） |
| `io_oasis.rs` | OASIS 读写，委托 `laykit` crate（MIT） |
| `io_gds.rs` | GDSII 导出（手写二进制编码器） |

### 坐标体系

- **DBU 整数**：`Coord = i64`，内部所有几何以整数存储
- **用户空间浮点**：`DCoord = f64`，通过 `to_microns()` / `to_dbu()` 转换
- **D-prefix 约定**：`DPoint = Point<f64>`、`DBox = Box<f64>`，沿袭 KLayout 双表示模式
- **注意**：`Box` 是 Rust 关键字，模块路径为 `#[path = "box.rs"]`，类型别名 `BoxI`

### Undo/Redo 系统

命令模式（delta 型，非快照型），通过 `OwnerPtr<T>` 实现纯所有权转移：

```
begin_transaction()
  → queue(FullBoxLayerOp)       // op.execute() 立即应用
  → queue(FullPolygonLayerOp)   // op.execute() 立即应用
  → commit()                    // 事务入历史
// Drop TransactionGuard 时若未 commit → 自动 cancel（revert 所有已排队 op）
```

- **reverse-undo**：逆序迭代 ops，逐一 revert
- **forward-redo**：正序迭代 ops，逐一 execute
- **新事务截断 redo**：新 `begin_transaction()` 丢弃当前之后的历史
- **按类型拆分**：5 种几何类型各有独立的 `Full*LayerOp`

### IO 格式支持

| 格式 | 读取 | 写入 | 实现 |
|------|------|------|------|
| OASIS (.oas) | ✅ | ✅ | 委托 `laykit` crate（MIT），两遍读取 |
| GDSII (.gds) | ❌ | ✅ | 纯手写二进制编码器 |

## ql-project — 项目管理

处理 `.ql_pro` JSON 项目文件：

- `Project` 结构：name、uuid、path、sheets、boards、config、lib_table
- JSON 保存保留 `created` 时间戳，更新 `modified`
- `LibTable` 支持 `${KIPRJMOD}`、`${QLIB_HOME}` 变量解析
- `ProjectDir::create()` 生成完整项目目录树

## 共享依赖

```toml
serde = "1"         # features = ["derive"]
thiserror = "2"
slotmap = "1"
tracing = "0.1"
hecs = "0.11"       # ★ ECS 库，用于 Shape 分类存储
```

## 设计约束

- **无原理图模块** — 显式排除，不实现
- **核心 crate 无 GUI** — `ql-layout` 和 `ql-project` 不依赖任何 GUI 框架；应用层 crate（`ql-pm`、`ql-le`）使用 Bevy + egui
- **无量子硬编码** — transmon/qubit/coupler 等由用户库文件定义
- **无 OASIS 自实现解析** — 委托 laykit
- **无 `ql-types` / `ql-core` / `ql-common`** — 每个 crate 自包含
- **`Coord = i64`** — DBU 整数，非浮点

## 文档

- [ql-layout 版图数据管理架构](docs/ql-layout-architecture.md) — 完整架构文档
- [OASIS 策略决策](docs/decisions/oasis-strategy.md) — OASIS crate 选型评估

## License

MIT