AGENT SKILL

cypress-tuning

Systematically diagnoses, tunes, and executes Cypress GPU-accelerated PCB placement optimization runs. Trigger when running DREAMPlace/Cypress component placement, diagnosing placement divergence or clumping, or tuning wirelength, density, rotation, and net crossing parameters.

License 许可
GPL-2.0
最近更新
2026-08-23
Stars
★ 0
Forks
0

01 前言 Front Matter

name
cypress-tuning
description
Systematically diagnoses, tunes, and executes Cypress GPU-accelerated PCB placement optimization runs. Trigger when running DREAMPlace/Cypress component placement, diagnosing placement divergence or clumping, or tuning wirelength, density, rotation, and net crossing parameters.

02 资源文件 5

03 SKILL.md 正文

Cypress Placement Diagnostic & Hyperparameter Tuning Skill

This skill provides a systematic, cause-and-effect methodology to analyze log telemetry, diagnose optimization regimes, execute parameter adjustments, and run component placement optimization using the Cypress PCB Placement Framework.


1. Operational Knowledge

Tool Execution Wrappers

Cypress executes GPU non-linear placement optimization within its designated container workspace. Use the bundled wrapper scripts under tools/:

  • Run Placement Optimization:

    tools/run_placer.sh <path_to_config_json>
    

    Example: tools/run_placer.sh configs/test_small1.json

  • Run Hyperparameter Exploration (MOTPE Search):

    tools/run_placer_tuner.sh <config_space_json> <aux_file_path> <ppa_json> <results_dir>
    
  • Monitor Telemetry Logs:

    tail -f DREAMPlace.log
    

Progressive Disclosure Context & Environment

For detailed guidance on Docker execution, PyTorch ABI checks, and C++/CUDA build operator troubleshooting, consult:

  • references/environment_and_troubleshooting.md (Relative path: references/environment_and_troubleshooting.md)
  • External tool context in Cypress repository: ../../../../open-source-repos/Cypress/AGENTS.md (or repo root AGENTS.md)

2. Reasoning Guidance

Diagnostic Decision Matrix

When evaluating real-time placement runs, inspect DREAMPlace.log telemetry to identify the optimization regime and apply targeted parameter adjustments in your JSON configuration:

                  Observe Optimization Telemetry
                               │
       ┌───────────────────────┼───────────────────────┐
       ▼                       ▼                       ▼
 Regime A: Divergence     Regime B: Clumping    Regime C: Wire Crossings
(Gradient Explosion)    (Overflow Stalled)     (Poor Routability)
       │                       │                       │
       ▼                       ▼                       ▼
• γ ↑ (4.0 → 10.0)      • λ_D ↑ (1e-6 → 8e-5)   • enable_rotation: 1
• lr ↓ (0.01 → 0.002)   • opt: nesterov         • net_crossing_flag: 1
• static weights        • enable_fillers: 0*    • Early orient trigger

Regime A: Gradient Explosion & Divergence

  • Observable Symptoms: Log reports Obj INF, NaN gradients, HPWL exploding ($> 10^7$), or components pushed far outside board boundaries.
  • Prescribed Adjustments:
    1. Increase Base Wirelength Scale ($\gamma$): Raise base "gamma" from 4.0 to 10.0 or 20.0 in the JSON config.
    2. Disable Net Crossing During Initial Spreading: Set "net_crossing_flag": 0 during early global placement.
    3. Reduce Learning Rate: Lower "learning_rate" in global_place_stages from 0.01 to 0.002 or 0.005.

Regime B: Component Overlap & Stalled Overflow

  • Observable Symptoms: Global placement terminates prematurely or stalls with high overflow ($\text{Overflow} > 0.1$), leaving cell clusters overlapping.
  • Prescribed Adjustments:
    1. Increase Initial Density Multiplier: Boost "density_weight" from 1e-6 to 8e-5 or 1e-3.
    2. Switch Optimizer to Nesterov: Set "optimizer": "nesterov" with "learning_rate": 0.01.
    3. Disable Fillers for Macro-Only PCB Layouts: Set "enable_fillers": 0 if all components are movable macros on sparse PCB boards.

Regime C: Excessive Net Crossings & Poor Routability

  • Observable Symptoms: High net crossing penalties or trace congestion despite low density overflow.
  • Prescribed Adjustments:
    1. Enable Rotation Optimization: Set "enable_rotation": 1 to execute continuous orientation relaxation ($\theta \in {0^\circ, 90^\circ, 180^\circ, 270^\circ}$).
    2. Two-Phase Net Crossing Strategy: Phase 1 run with "net_crossing_flag": 0; Phase 2 enable "net_crossing_flag": 1 once overflow drops below 0.10.

Regime D: Local Minima Trapping

  • Observable Symptoms: Rapid convergence yielding high HPWL and asymmetric macro distribution.
  • Prescribed Adjustments:
    1. Enable "random_center_init_flag": 1 and increase "gp_noise_ratio" to 0.05.

Deep Technical References

  • Telemetry Metric Definitions: Consult references/telemetry_metrics.md for field breakdowns of DREAMPlace.log.
  • Mathematical Foundations: Consult references/mathematical_foundations.md for smooth LSE/WA wirelength formulations and Gumbel-Softmax orientation models.

3. Workflow Instructions

Follow this standard procedure when running or tuning Cypress placement:

  1. Step 1: Environment Readiness Check
    Verify Docker container status and GPU accessibility (references/environment_and_troubleshooting.md).
  2. Step 2: Configuration Setup
    Confirm "aux_input" points to target Bookshelf .aux file and setup initial hyperparameters in configuration JSON.
  3. Step 3: Execute Optimization Run
    Run tools/run_placer.sh <config_json_path> and stream telemetry log.
  4. Step 4: Iterative Regime Diagnosis & Parameter Adjustment
    Monitor DREAMPlace.log. If overflow stalls or loss explodes, apply parameter adjustments according to the Diagnostic Decision Matrix.
  5. Step 5: Output Artifact Extraction
    Extract legal component placement coordinates from the generated <design_name>.gp.pl file.

4. Verification

A placement run is verified and considered successful when all of the following criteria are met:

  1. Clean Optimization Convergence: Optimization completes without NaN loss or floating-point exceptions in DREAMPlace.log.
  2. Target Density Overflow Reached: Final normalized density overflow drops below the termination threshold ($\text{Overflow} \le 0.07$).
  3. Valid Bounding Box Constraints: Final component coordinates lie strictly within the physical board outline $[0, W_{\text{board}}] \times [0, H_{\text{board}}]$.
  4. Discrete Legal Angles: Final exported component rotations are locked to valid discrete orientation angles $\theta \in {0^\circ, 90^\circ, 180^\circ, 270^\circ}$.

04 同仓库更多 Skills

vivekvjnk
vivekvjnk/three-wise-monkeys

circuitjson-bookshelf-converter

Converts Circuit JSON PCB and schematic designs into Bookshelf physical design format (.nodes, .nets, .pl, .scl, .aux) with courtyard keep-out boundary modeling, and back-annotates Cypress placement optimization results back into Circuit JSON. Trigger this skill whenever converting circuit.json files to Bookshelf format or back-annotating .pl / .gp.pl placement outputs into Circuit JSON.

Skill与智能体开发
★ 0
vivekvjnk
vivekvjnk/three-wise-monkeys

circuit-json-analysis

Analyzes Circuit JSON files for structural component relationships, domain mappings (source, schematic, pcb, cad), and geometric layout DRC violations (courtyard overlaps, solder paste misalignments, pad clearances). Trigger this skill whenever analyzing a circuit.json file, inspecting PCB placement, or performing design rule checks on Circuit JSON data.

Skill与智能体开发
★ 0
vivekvjnk
vivekvjnk/three-wise-monkeys

vhl-concepts

Architectural foundation for Virtual Hardware Laboratory (VHL). Explains the four fundamental VHL concepts (Module vs Assembly, Interface Boundary, Git Worktree Workspace Isolation, and Shared Circuit Understanding Document), why VHL uses them, their core invariants, and when an agent must reason about them. Trigger this skill whenever reasoning about VHL architecture, defining boundaries, identifying module/assembly scope, or referencing SCUD artifacts.

文档处理Skill与智能体开发
★ 0
vivekvjnk
vivekvjnk/three-wise-monkeys

SCUD

暂无简介

★ 0
vivekvjnk
vivekvjnk/three-wise-monkeys

Module_Synthesis

暂无简介

★ 0
vivekvjnk
vivekvjnk/three-wise-monkeys

Boundary_Reconciliation

暂无简介

★ 0