Explanation¶
The design documents: what TraceMaker is meant to do, how it does it, and why, with the papers each algorithm comes from cited where it is defined. They are the source of truth for the design: when the code has to differ, the document changes in the same pull request, with a decision record.
Read them in this order the first time:
| Document | What it explains |
|---|---|
| Requirements | What the product must do, its scope, success criteria and glossary |
| Architecture | Processes, the pipeline, threading, determinism, the repository layout |
| Data structures and DRC | Geometry, spatial indices, search structures, the exact design-rule check |
| Placement | Optimality levels; analytic placement, legalisation, annealing, exact windows, ECO moves |
| Routing | The routing stages, the escalation ladder, the cost model, and every routing feature since |
| Failure memory | Learning from failed attempts: records, nogoods, history, bandits, the knowledge base |
| GPU acceleration | What runs on the GPU, the kernels, and how CPU and GPU give identical results |
| KiCad integration | File I/O, kicad-cli, the plugin, the DRC judge |
| Live viewer | Streaming, replay and the visual design of the browser viewer |
| Benchmarking | Datasets, metrics, baselines, the harness and the gates |
Studies and features with a document of their own:
| Document | Status |
|---|---|
| Placement test plan | How placement is tested: levels, datasets, metrics, gates |
| Component-aware rules | Partly built (M13 P0–P3): detect parts such as USB, crystals and regulators, and apply their layout rules |
| BGA breakout | Partly built (M14, M15): matching tscircuit on its BGA breakout sets, with measured outcomes |
| Advice files and advisors | Partly built (M16, stages 0–3): hints for the router when it is stuck; the engine never talks to a model |
| Agent interface | Partly built (M18, stages A–B): a board session an agent drives over MCP or JSON lines |
Background, outside this site: the routing-stage design and the Freerouting evidence it rests on
(cpp_autorouter_clean_sheet.md), a survey of placement and routing
approaches (pcb-routing-optimization.md), and verified facts on KiCad,
its APIs, benchmark sets and GPU techniques (research/).