Merge pull request 'change readme to uv' (#2) from lingke-changereadmetouv into main

Reviewed-on: http://192.168.31.243:3012/Jiao77/Geo-Layout-Transformer/pulls/2
2025-09-19 16:25:53 +00:00
parent d110130008 d8186d9d13
commit 7cc845b71a
2 changed files with 160 additions and 66 deletions
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
  <a href="https://github.com/your-username/Geo-Layout-Transformer/network/members"><img src="https://img.shields.io/github/forks/your-username/Geo-Layout-Transformer.svg" /></a>
  <a href="https://github.com/your-username/Geo-Layout-Transformer/issues"><img src="https://img.shields.io/github/issues-raw/your-username/Geo-Layout-Transformer" /></a>
  <a href="https://github.com/your-username/Geo-Layout-Transformer/issues?q=is%3Aissue+is%3Aclosed"><img src="https://img.shields.io/github/issues-closed-raw/your-username/Geo-Layout-Transformer" /></a>
-  <a><img src="https://img.shields.io/badge/python-3.9%2B-blue" /></a>
+  <a><img src="https://img.shields.io/badge/python-3.12%2B-blue" /></a>
  <a><img src="https://img.shields.io/badge/PyTorch-2.x-orange" /></a>
 </p>

@@ -35,7 +35,7 @@

 ## 🖥️ Supported Systems

- **Python**: 3.9+
+- **Python**: 3.12+
 - **OS**: macOS 13+/Apple Silicon, Linux (Ubuntu 20.04/22.04). Windows via **WSL2** recommended
 - **Frameworks**: PyTorch, PyTorch Geometric (with CUDA optional)
 - **EDA I/O**: GDSII/OASIS (via `klayout` Python API)
@@ -98,37 +98,75 @@ Geo-Layout-Transformer/

 ### 3.1. Prerequisites 🧰

-*   Python 3.9+
-*   A Conda environment is highly recommended.
+*   Python 3.12+
+*   Dependency management: using uv is recommended for fast, reproducible installs (uv.lock provided). Conda/Python is supported as an alternative.
 *   Access to EDA tools for generating labeled data (e.g., a DRC engine for hotspot labels).

 ### 3.2. Installation 🚧

-1.  **Clone the repository:**
+#### A) Using uv (recommended)
+
+1) Install uv (one-time):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+2) Clone the repository:
+
 ```bash
 git clone https://github.com/your-username/Geo-Layout-Transformer.git
 cd Geo-Layout-Transformer
 ```

-2.  **Create and activate the Conda environment:**
+3) Ensure Python 3.12 is available (uv can manage it):
+
 ```bash
-    conda create -n geo_trans python=3.9
+uv python install 3.12
+```
+
+4) Create the environment and install dependencies from uv.lock/pyproject:
+
+```bash
+uv sync
+```
+
+Notes:
+- For CUDA builds of PyTorch/PyG, follow the official installers first, then install the rest via uv:
+  - PyTorch: https://pytorch.org/get-started/locally/
+  - PyG: https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html
+  After installing the correct Torch/PyG wheels, you may run `uv sync --frozen` to install the remaining packages.
+- You may need to install `klayout` separately (package manager or from source) to enable its Python API.
+
+#### B) Using Python/Conda (alternative)
+
+1) Clone the repository:
+
+```bash
+git clone https://github.com/your-username/Geo-Layout-Transformer.git
+cd Geo-Layout-Transformer
+```
+
+2) Create and activate an environment (Conda example):
+
+```bash
+conda create -n geo_trans python=3.12
 conda activate geo_trans
 ```

-3.  **Install dependencies:**
-    This project requires PyTorch and PyTorch Geometric (PyG). Please follow the official installation instructions for your specific CUDA version.
+3) Install PyTorch and PyTorch Geometric per your CUDA setup:

-    *   **PyTorch:** [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)
-    *   **PyG:** [https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html](https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html)
+- PyTorch: https://pytorch.org/get-started/locally/
+- PyG: https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html
+
+4) Install the remaining dependencies:

-    After installing PyTorch and PyG, install the remaining dependencies:
 ```bash
 pip install -r requirements.txt
 ```
-    *(Note: You may need to install `klayout` separately via its own package manager or build from source to enable its Python API).*

 > Tip: GPU is optional. For CPU-only environments, install the CPU variants of PyTorch/PyG.
+> Note: You may need to install `klayout` separately to enable its Python API.

 ## 4. Project Usage 🛠️

@@ -141,6 +179,11 @@ The first step is to convert your GDSII/OASIS files into a graph dataset that th
 1.  Place your layout files in the `data/gds/` directory.
 2.  Configure the preprocessing parameters in `configs/default.yaml`. You will need to define patch size, stride, layer mappings, and how to construct graph edges.
 3.  Run the preprocessing script:
+    - Using uv (recommended):
+      ```bash
+      uv run python scripts/preprocess_gds.py --config-file configs/default.yaml --gds-file data/gds/my_design.gds --output-dir data/processed/my_design/
+      ```
+    - Using Python/Conda:
      ```bash
      python scripts/preprocess_gds.py --config-file configs/default.yaml --gds-file data/gds/my_design.gds --output-dir data/processed/my_design/
      ```
@@ -171,6 +214,10 @@ Once the dataset is ready, you can train the Geo-Layout Transformer.
 To build a powerful foundation model, we first pre-train it on unlabeled data using a "Masked Layout Modeling" task.

 ```bash
+# Using uv (recommended)
+uv run python main.py --config-file configs/default.yaml --mode pretrain --data-dir data/processed/my_design/
+
+# Using Python/Conda
 python main.py --config-file configs/default.yaml --mode pretrain --data-dir data/processed/my_design/
 ```
 This will train the model to understand the fundamental "grammar" of physical layouts without requiring any expensive labels.
@@ -183,6 +230,10 @@ After pre-training, you can fine-tune the model on a smaller, labeled dataset fo
 2.  Use a task-specific config file (e.g., `hotspot_detection.yaml`) that defines the model head and loss function.
 3.  Run the main script in `train` mode:
  ```bash
+  # Using uv (recommended)
+  uv run python main.py --config-file configs/hotspot_detection.yaml --mode train --data-dir data/processed/labeled_hotspots/ --checkpoint-path /path/to/pretrained_model.pth
+
+  # Using Python/Conda
  python main.py --config-file configs/hotspot_detection.yaml --mode train --data-dir data/processed/labeled_hotspots/ --checkpoint-path /path/to/pretrained_model.pth
  ```

@@ -207,7 +258,3 @@ We stand on the shoulders of open-source communities. This project draws inspira
 - Research works such as LayoutGMN (graph matching for structural similarity) that informed our polygon/graph handling design

 If your work is used and not listed here, please open an issue or PR so we can properly credit you.
-
---
-
-Made with ❤️ for EDA research and open-source collaboration.
--- a/README_zh.md
+++ b/README_zh.md
@@ -10,7 +10,7 @@
  <a href="https://github.com/your-username/Geo-Layout-Transformer/network/members"><img src="https://img.shields.io/github/forks/your-username/Geo-Layout-Transformer.svg" /></a>
  <a href="https://github.com/your-username/Geo-Layout-Transformer/issues"><img src="https://img.shields.io/github/issues-raw/your-username/Geo-Layout-Transformer" /></a>
  <a href="https://github.com/your-username/Geo-Layout-Transformer/issues?q=is%3Aissue+is%3Aclosed"><img src="https://img.shields.io/github/issues-closed-raw/your-username/Geo-Layout-Transformer" /></a>
-  <a><img src="https://img.shields.io/badge/python-3.9%2B-blue" /></a>
+  <a><img src="https://img.shields.io/badge/python-3.12%2B-blue" /></a>
  <a><img src="https://img.shields.io/badge/PyTorch-2.x-orange" /></a>
 </p>

@@ -35,7 +35,7 @@

 ## 🖥️ 支持系统 💻

- **Python**：3.9+
+- **Python**：3.12+
 - **操作系统**：macOS 13+/Apple Silicon、Linux（Ubuntu 20.04/22.04）。Windows 建议使用 **WSL2**
 - **深度学习框架**：PyTorch、PyTorch Geometric（CUDA 可选）
 - **EDA I/O**：GDSII/OASIS（通过 `klayout` Python API）
@@ -98,37 +98,75 @@ Geo-Layout-Transformer/

 ### 3.1. 环境要求 🧰

-*   Python 3.9+
-*   强烈建议使用 Conda 进行环境管理。
+*   Python 3.12+
+*   依赖管理：推荐使用 uv（已提供 uv.lock）来进行快速、可复现的安装；也支持使用 Conda/Python 作为替代方案。
 *   能够访问 EDA 工具以生成带标签的数据（例如，使用 DRC 工具生成热点标签）。

 ### 3.2. 安装步骤 🚧

-1.  **克隆代码仓库：**
+#### A) 使用 uv（推荐）
+
+1）安装 uv（一次性）：
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+2）克隆代码仓库：
+
 ```bash
 git clone https://github.com/your-username/Geo-Layout-Transformer.git
 cd Geo-Layout-Transformer
 ```

-2.  **创建并激活 Conda 环境：**
+3）确保系统可用 Python 3.12（uv 可管理）：
+
 ```bash
-    conda create -n geo_trans python=3.9
+uv python install 3.12
+```
+
+4）基于 uv.lock/pyproject 创建环境并安装依赖：
+
+```bash
+uv sync
+```
+
+说明：
+- 如需安装带 CUDA 的 PyTorch/PyG，请先根据官方说明安装对应版本，然后再用 uv 安装其余依赖：
+  - PyTorch: https://pytorch.org/get-started/locally/
+  - PyG: https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html
+  正确安装 Torch/PyG 轮子后，可执行 `uv sync --frozen` 安装剩余依赖。
+- 若需要 `klayout` 的 Python API，可能需要通过其包管理器或源码单独安装。
+
+#### B) 使用 Python/Conda（备选）
+
+1）克隆代码仓库：
+
+```bash
+git clone https://github.com/your-username/Geo-Layout-Transformer.git
+cd Geo-Layout-Transformer
+```
+
+2）创建并激活环境（以 Conda 为例）：
+
+```bash
+conda create -n geo_trans python=3.12
 conda activate geo_trans
 ```

-3.  **安装依赖：**
-    本项目需要 PyTorch 和 PyTorch Geometric (PyG)。请根据您的 CUDA 版本遵循官方指南进行安装。
+3）根据 CUDA 环境安装 PyTorch 和 PyTorch Geometric：

-    *   **PyTorch:** [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)
-    *   **PyG:** [https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html](https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html)
+- PyTorch: https://pytorch.org/get-started/locally/
+- PyG: https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html
+
+4）安装其余依赖：

-    安装完 PyTorch 和 PyG 后，安装其余的依赖项：
 ```bash
 pip install -r requirements.txt
 ```
-    *（注意：您可能需要通过 `klayout` 自身的包管理器或从源码编译来单独安装它，以启用其 Python API）。*

 > 提示：GPU 不是必须的。仅 CPU 环境可安装 PyTorch/PyG 的 CPU 版本。
+> 说明：如需 `klayout` 的 Python API，可能需要单独安装。

 ## 4. 项目使用 🛠️

@@ -141,6 +179,11 @@ Geo-Layout-Transformer/
 1.  将您的版图文件放入 `data/gds/` 目录。
 2.  在 `configs/default.yaml` 中配置预处理参数。您需要定义区块大小、步长、层映射以及图边的构建方式。
 3.  运行预处理脚本：
+    - 使用 uv（推荐）：
+      ```bash
+      uv run python scripts/preprocess_gds.py --config-file configs/default.yaml --gds-file data/gds/my_design.gds --output-dir data/processed/my_design/
+      ```
+    - 使用 Python/Conda：
      ```bash
      python scripts/preprocess_gds.py --config-file configs/default.yaml --gds-file data/gds/my_design.gds --output-dir data/processed/my_design/
      ```
@@ -171,6 +214,10 @@ Geo-Layout-Transformer/
 为了构建一个强大的基础模型，我们首先在无标签数据上使用“掩码版图建模”任务对其进行预训练。

 ```bash
+# 使用 uv（推荐）
+uv run python main.py --config-file configs/default.yaml --mode pretrain --data-dir data/processed/my_design/
+
+# 使用 Python/Conda
 python main.py --config-file configs/default.yaml --mode pretrain --data-dir data/processed/my_design/
 ```
 这将训练模型理解物理版图的基本“语法”，而无需任何昂贵的标签。
@@ -183,6 +230,10 @@ python main.py --config-file configs/default.yaml --mode pretrain --data-dir dat
 2.  使用一个特定于任务的配置文件（例如 `hotspot_detection.yaml`），其中定义了模型的任务头和损失函数。
 3.  在 `train` 模式下运行主脚本：
  ```bash
+  # 使用 uv（推荐）
+  uv run python main.py --config-file configs/hotspot_detection.yaml --mode train --data-dir data/processed/labeled_hotspots/ --checkpoint-path /path/to/pretrained_model.pth
+
+  # 使用 Python/Conda
  python main.py --config-file configs/hotspot_detection.yaml --mode train --data-dir data/processed/labeled_hotspots/ --checkpoint-path /path/to/pretrained_model.pth
  ```

@@ -207,7 +258,3 @@ python main.py --config-file configs/default.yaml --mode pretrain --data-dir dat
 - 研究工作 LayoutGMN（面向结构相似性的图匹配），启发了我们对多边形/图构建的设计

 若您的工作被本项目使用但尚未列出，欢迎提交 Issue 或 PR 以便完善致谢。
-
---
-
-Made with ❤️ 面向 EDA 研究与开源协作。