{"id":23167511,"url":"https://github.com/tscircuit/autorouting","last_synced_at":"2025-08-18T06:32:29.435Z","repository":{"id":249316222,"uuid":"831171674","full_name":"tscircuit/autorouting","owner":"tscircuit","description":"Algorithms and dataset of autorouting problems for developing and benchmarking autorouters","archived":true,"fork":false,"pushed_at":"2025-08-15T20:57:57.000Z","size":1946,"stargazers_count":38,"open_issues_count":34,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-15T22:46:56.874Z","etag":null,"topics":["autorouting","dsn","kicad","pcb-design","router","routing","routing-algorithm","specctra"],"latest_commit_sha":null,"homepage":"https://dataset.autorouting.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tscircuit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-19T20:47:42.000Z","updated_at":"2025-08-15T20:58:09.000Z","dependencies_parsed_at":"2024-08-29T22:21:27.102Z","dependency_job_id":"ec9c6e72-5d9a-4b34-90f7-54d8dc65b007","html_url":"https://github.com/tscircuit/autorouting","commit_stats":null,"previous_names":["tscircuit/autorouting-dataset","tscircuit/autorouting"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tscircuit/autorouting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tscircuit%2Fautorouting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tscircuit%2Fautorouting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tscircuit%2Fautorouting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tscircuit%2Fautorouting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tscircuit","download_url":"https://codeload.github.com/tscircuit/autorouting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tscircuit%2Fautorouting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270954734,"owners_count":24674757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autorouting","dsn","kicad","pcb-design","router","routing","routing-algorithm","specctra"],"created_at":"2024-12-18T02:29:01.591Z","updated_at":"2025-08-18T06:32:29.425Z","avatar_url":"https://github.com/tscircuit.png","language":"TypeScript","readme":"# tscircuit autorouting\n\n[view online](https://dataset.autorouting.com) \u0026middot; [blog](https://blog.autorouting.com) \u0026middot; [discord](https://tscircuit.com/community/join-redirect) \u0026middot; [tscircuit](https://github.com/tscircuit/tscircuit) \u0026middot; [benchmarks](./BENCHMARKS.md)\n\n\u003e [!WARNING]\n\u003e This repository has been largely replaced by the [tscircuit-autorouter](https://github.com/tscircuit/tscircuit-autorouter)\n\nA dataset of autorouting problems for benchmarking 🥇, plus a ton of utilities 🔨 including a viewer and testing server\nfor developing new autorouting algorithms.\n\nAutorouting is the process of drawing traces (wires) to connect chips on a PCB. It is a decades-old largely unsolved\nproblem.\n\n\u003e [!TIP]\n\u003e Check out the getting started guide and videos section!\n\n![image](https://github.com/user-attachments/assets/bad8e749-1c84-4b6f-bbdf-12bf7e9c3e7b)\n\n- [tscircuit autorouting](#tscircuit-autorouting)\n  - [What is autorouting?](#what-is-autorouting)\n  - [Getting Started Guide](#getting-started-guide)\n    - [Part 1: Creating a new Autorouter](#part-1-creating-a-new-autorouter)\n    - [Part 2: Creating new synthetic datasets](#part-2-creating-new-synthetic-datasets)\n    - [Part 3: Running benchmarks and understanding autorouters](#part-3-running-benchmarks-and-understanding-autorouters)\n  - [Problems](#problems)\n    - [Example Problems](#example-problems)\n      - [`simple-multi-point-trace`](#simple-multi-point-trace)\n  - [Benchmarks](#benchmarks)\n  - [Usage](#usage)\n  - [Writing a Solver](#writing-a-solver)\n    - [Typescript Solvers](#typescript-solvers)\n    - [Non-Typescript Solvers](#non-typescript-solvers)\n  - [Visualizing Problems/Solutions](#visualizing-problemssolutions)\n    - [Running a Dev Server with Typescript](#running-a-dev-server-with-typescript)\n  - [Running a Benchmark](#running-a-benchmark)\n    - [Running Benchmarks with Typescript](#running-benchmarks-with-typescript)\n    - [Running Benchmarks without Typescript](#running-benchmarks-without-typescript)\n  - [CLI Usage](#cli-usage)\n    - [Installation](#installation)\n    - [Starting Dev Servers](#starting-dev-servers)\n    - [Running Benchmarks](#running-benchmarks)\n      - [Customizing Benchmarks](#customizing-benchmarks)\n    - [Generating Datasets](#generating-datasets)\n    - [Generating Single Problems](#generating-single-problems)\n  - [Community Solvers](#community-solvers)\n  - [References](#references)\n\n## What is autorouting?\n\nAutorouting\nis the drawing of traces (wires) across a 2d surface to connect\ncopper pads together. Traces can go underneath pads using a\ncopper-plated hole called a \"via\". Traces must also avoid \"obstacles\"\nwhich are other pads or blocked areas where a trace cannot pass\nsuch as a hole or region designated for an antenna.\n\n## Getting Started Guide\n\n### Part 1: Creating a new Autorouter\n\nYou can create a new autorouter in minutes! Here are some tips:\n\n- Run the project with `bun run start` and go to [localhost:3080](http://localhost:3080). This will use all the existing algorithms!\n- The [./algos](./algos/) has all the algorithms we have created so far\n- Copy the [./algos/algorithm-template-ts](./algos/algorithm-template-ts/) directory into a new directory to get started\n- Run `bun run --hot ./algos/my-new-algorithm/server.ts` to start _your_ algorithm development server\n- You can feed the `AI_GUIDE.md` file into an LLM to help you\n  write or debug your algorithm\n- You can also copy or import other algorithm directories and extend them!\n- Snapshot tests [(like this)](https://github.com/tscircuit/autorouting/blob/main/algos/infinite-grid-ijump-astar/tests/__snapshots__/intersection-with-margin.snap.svg) are INCREDIBLY USEFUL and easy to generate for developing your autorouter- use them!\n\n[![2024-10-10_11-46](https://github.com/user-attachments/assets/b7110e0d-bff0-4f22-a9fe-e3284d38310b)](https://www.youtube.com/watch?v=f72SQGu0kws)\n\n\n## Problems\n\nThere are different classifications of problems, each problem\napplies to a different autorouting scenario. A perfect autorouter\ncan solve all of these problems, but partial autorouting is\nvery useful for human-assisted routing.\n\n| Problem                | Ready Status                                                              | Description                                                                                  | Difficulty |\n| ---------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- |\n| `single-trace`         | [🟢 view](https://dataset.autorouting.com/problem/single-trace/1)         | Route a single trace through obstacles                                                       | Easy       |\n| `traces`               | [🟢 view](https://dataset.autorouting.com/problem/traces/1)               | Route multiple traces to pairs of points, without crossing traces                            | Medium     |\n| `distant-single-trace` | [🟢 view](https://dataset.autorouting.com/problem/distant-single-trace/1) | Long (200mm+) single trace                                                                   | Easy       |\n| `single-trace-group`   | 🔴 [TBA](https://blog.autorouting.com)                                    | Route a single trace through multiple points                                                 | Easy       |\n| `layers-traces`        | 🔴 [TBA](https://blog.autorouting.com)                                    | Route a trace through multiple layers to connect two points                                  | Easy       |\n| `traces-groups`        | 🔴 [TBA](https://blog.autorouting.com)                                    | Route multiple traces to groups of points, without crossing traces                           | Medium     |\n| `layers-traces`        | 🔴 [TBA](https://blog.autorouting.com)                                    | Route multiple traces to pairs of points, without crossing traces across layers              | Hard       |\n| `layers-traces-groups` | 🔴 [TBA](https://blog.autorouting.com)                                    | Route multiple traces, through multiple places, to groups of points, without crossing traces | Hard       |\n| `width-constraints-*`  | 🔴 [TBA](https://blog.autorouting.com)                                    | Maintain the optimal trace widths, given target ranges for each trace                        | Hard       |\n| `hyperdense-*`         | 🔴 [TBA](https://blog.autorouting.com)                                    | Super dense BGA routing                                                                      | Hard+      |\n| `incremental-*`        | 🔴 [TBA](https://blog.autorouting.com)                                    | The same dataset but a component is moved or a trace is changed. Tests cache efficiency      | Hard+      |\n\n### Example Problems\n\n#### `simple-multi-point-trace`\n\n![image](https://github.com/user-attachments/assets/6f21ae45-191a-4f3a-aeb2-8b56576a1ece)\n\n## Benchmarks\n\nThere are several criteria we use for running benchmarks:\n\n- Speed (machine specs TBD)\n- Percent of Boards fully routed inside category\n- Quality (as compared to \"ideal routing\")\n  - How much longer are the traces? Shorter traces are usually better\n  - How good is the trace width relative to the ideal routing\n- Problem Type\n- Incremental Speed (speed if a single component is moved or a trace is changed)\n- Memory Usage\n\nOver time, we'd like to have a simple 2d chart showing Speed and Quality.\n\n## Usage\n\nThis dataset is composed of thousands of files in the [tscircuit soup format](https://docs.tscircuit.com/api-reference/advanced/soup). You\ncan find a dataset for each problem tscircuit in the [datasets](./datasets) directory. You can download a [`zip` file](#) containing the datasets\nfrom the [releases page](#). If your solver is in typescript, you can generate the datasets on the fly by importing `autorouting-dataset`\n\nsoup can be easily visualized and contains a lot of metadata that can be used for constraints. However, you may want to use the `getSimpleRouteJson`\nutility function from `autorouting-dataset` to convert it into a simple object with the following interface:\n\n```tsx\ninterface SimpleRouteJson {\n  layerCount: number\n  obstacles: Array\u003c{\n    type: \"rect\"\n    center: { x: number; y: number }\n    width: number\n    height: number\n  }\u003e\n  connections: Array\u003c{\n    name: string\n    pointsToConnect: Array\u003c{ x: number; y: number }\u003e\n  }\u003e\n  bounds: { minX: number; maxX: number; minY: number; maxY: number }\n}\n```\n\nEach directory in the `datasets` directory contains a dataset for each problem. The `code` directory contains the code to generate datasets.\n\n## Writing a Solver\n\nYou can write a solver in any language you want, but currently most of the examples are in Typescript. You can read about building a \"hello world\" autorouter in [this blog post.](https://blog.autorouting.com/p/building-a-grid-based-pcb-autorouter)\n\n\u003e Hate Javascript? Skip to [building a non-typescript solver](#non-typescript-solvers)\n\n\u003e [!NOTE]\n\u003e There are tons of examples of solvers inside the [algos directory!](./algos/)\n\n### Typescript Solvers\n\nTypescript solvers can accept either [tscircuit soup](https://docs.tscircuit.com/api-reference/advanced/soup) or [`SimpleRouteJson`](#usage). To develop\nyour Typescript solver, just create a file like this:\n\n```tsx\nimport { startAutoroutingDevServer, getSimpleRouteJson } from \"autorouting-dataset\"\n\nconst mySolver = (soup: AnySoupElement[]) =\u003e {\n  const routeJson = getSimpleRouteJson(soup)\n\n  // ...\n\n  // ...return one or more pcb_trace objects with our solution!\n  return [\n    {\n      \"type\": \"pcb_trace\",\n      \"route\": [\n        {\n          \"route_type\": \"wire\",\n          \"x\": 3,\n          \"y\": 1,\n          \"width\": 5,\n          \"layer\": \"top\"\n        },\n        {\n          \"route_type\": \"via\",\n          \"x\": 3,\n          \"y\": 1,\n          \"from_layer\": \"top\",\n          \"to_layer\": \"bottom\"\n        }\n      ]\n    }\n  ]\n\nstartAutoroutingDevServer({\n  solver: mySolver,\n  port: 3080\n})\n```\n\nYou can then run this file with `bun --hot ./solver-server.ts`\n\n\u003e [!TIP]\n\u003e Try it out with `bun ./algos/simple-grid/server.ts`\n\n\u003e [!NOTE]\n\u003e We recommend putting the solver in a separate file then importing it inside your server file, this way\n\u003e you can easily export your solver as a library!\n\n### Non-Typescript Solvers\n\n\u003e [!TIP]\n\u003e Check out a [simple python autorouter](./algos/python-simple-grid)\n\n- Host a server with your algorithm (see the simple flask server below)\n- Run `npx autorouting-dataset server start --solver-url http://localhost:1234` (replace `localhost:1234` with your solver server url\n- To benchmark your solver, run `npx autorouting-dataset benchmark --solver-url http://localhost:1234` [see running benchmarks without typescript](#running-benchmarks-without-typescript)\n\n```python\nfrom flask import Flask, request, jsonify\nfrom autoroute import autoroute\n\napp = Flask(__name__)\n\n@app.route('/solve', methods=['POST'])\ndef solve():\n    simple_route_json = request.json['simple_route_json']\n\n    solution = autoroute(simple_route_json)\n\n    return jsonify({\n        \"solution_soup\": solution\n    })\n\nif __name__ == '__main__':\n    app.run(host='0.0.0.0', port=1234)\n```\n\nThe autorouting-dataset dev server will send a `POST` request to the provided\nurl with the a JSON payload containing the following fields:\n\n```ts\ninterface Payload {\n  problem_soup: Array\u003cAnySoupElement\u003e\n  simple_route_json: SimpleRouteJson\n}\n```\n\nYou must return a JSON array containing `pcb_trace` elements in the following\nformat:\n\n```ts\ninterface Response {\n  solution_soup: Array\u003c{\n    type: \"pcb_trace\"\n    route: Array\u003c{\n      route_type: \"wire\" | \"via\"\n      x: number\n      y: number\n      width: number\n      layer: string\n    }\u003e\n  }\u003e\n}\n```\n\n## Visualizing Problems/Solutions\n\nYou can visualization your algorithm against a sample using the dev server. To\nstart the dev server, just run `npx autorouting-dataset server start --solver-url \u003csolver-url\u003e`\nand run your solver server.\n\nWhen you're debugging your solver, you may want to insert additional elements\ninto your solution_soup to help debug visually. To do this, just return elements\nin addition to or instead of the `pcb_trace` element. A full list of elements\ncan be found in the [tscircuit json format (soup)](https://docs.tscircuit.com/api-reference/advanced/soup).\n\nOne easy element you can add is a [`fabrication_note_path`](https://docs.tscircuit.com/api-reference/advanced/soup#pcb-fabrication-note-path), which is shown in gray on the PCB viewer. Here's an example:\n\n```json\n{\n  \"type\": \"pcb_fabrication_note_path\",\n  \"layer\": \"top\",\n  \"route\": [\n    {\n      \"x\": \"3mm\",\n      \"y\": \"1mm\"\n    },\n    {\n      \"x\": \"3mm\",\n      \"y\": \"1mm\"\n    }\n  ],\n  \"stroke_width\": \"0.1mm\"\n}\n```\n\nYou could also add a [`pcb_fabrication_note_text`](https://docs.tscircuit.com/api-reference/advanced/soup#pcb-fabrication-note-text) to add helpful text annotations:\n\n```json\n{\n  \"type\": \"pcb_fabrication_note_text\",\n  \"font\": \"tscircuit2024\",\n  \"font_size\": \"1mm\",\n  \"text\": \"Hello, World!\",\n  \"layer\": \"top\",\n  \"anchor_position\": {\n    \"x\": \"3mm\",\n    \"y\": \"1mm\"\n  },\n  \"anchor_alignment\": \"top_left\"\n}\n```\n\n### Running a Dev Server with Typescript\n\nIf you're using Typescript, you can run a dev server\nwith the code below:\n\n```ts\nimport { startDevServer } from \"autorouting-dataset\"\nimport { autoroute } from \"./my-autorouter\"\n\nawait startDevServer({\n  solver: autoroute,\n  solverName: \"my-autorouter\",\n  port: 3080,\n})\n```\n\n\u003e [!TIP] \u003e `export DEBUG=autorouting-dataset*` will give you all the debug output\n\u003e including additional dropdown debug information\n\n\u003e [!TIP]\n\u003e Check out [this directory](./algos/simple-grid/) for a typical Typescript autorouter configuration\n\n## Running a Benchmark\n\n### Running Benchmarks with Typescript\n\nIf you have a Typescript solver, you can run a benchmark programmatically using:\n\n```tsx\nimport { runBenchmark } from \"benchmark\"\nimport mySolver from \"./my-solver\"\n\nconst result = await runBenchmark({\n  solver: mySolver,\n  verbose: true,\n})\n```\n\nYou can then just run your file with `bun ./benchmark.ts`\n\n\u003e [!TIP]\n\u003e Try it out with `bun ./algos/simple-grid/benchmark.ts`\n\n### Running Benchmarks without Typescript\n\n```bash\nautorouting-dataset benchmark --solver-url http://localhost:1234\n```\n\nSee the section on [customizing benchmarks](#customizing-benchmarks) for more details\non how to change the sample count, customize the problem type etc.\n\n## CLI Usage\n\nYou can use the CLI to generate datasets, run benchmarks, and start a dev server.\n\n### Installation\n\n```bash\nnpm install -g autorouting-dataset\n```\n\n### Starting Dev Servers\n\nThe dev server helps you visualize a dataset and will automatically send data\nto your solver to test it.\n\nThe dev server will start on port 3080 by default, after you start the dev server\nyou can visit `http://localhost:3080` to view the dev server.\n\n```bash\n# Start the dev server with the default grid-based solver\nautorouting-dataset server start\n\n# Start the dev server with a custom solver url\nautorouting-dataset server start --solver-url http://localhost:1234\n\n# You can send specify\nautorouting-dataset server start --port 3080\n```\n\n### Running Benchmarks\n\nRuns a benchmark against a solver server. See [running benchmarks without typescript](#running-benchmarks-without-typescript) for more details.\n\n```bash\nautorouting-dataset benchmark --solver-url http://localhost:1234\n```\n\n#### Customizing Benchmarks\n\n| Option        | Flag             | Description                                       |\n| ------------- | ---------------- | ------------------------------------------------- |\n| `sampleCount` | `--sample-count` | Number of samples to run for each problem type    |\n| `problemType` | `--problem-type` | Problem type to run benchmarks for (default: all) |\n| `verbose`     | `--verbose`      | Prints out more information                       |\n| `solverUrl`   | `--solver-url`   | URL of the solver to benchmark                    |\n| `sampleSeed`  | `--sample-seed`  | Seed to randomize sampling (default: 0)           |\n| `noSkipping`  | `--no-skipping`  | Disables skipping of problem types                |\n\nBy default, running a benchmark will run for 100 samples against all problem types.\n\n\u003e If no `problemType` is provided and the solver fails on the first 10 samples, it will\n\u003e not run the remaining samples of the problem type. You can disable this behavior\n\u003e by setting `noSkipping` to `true`\n\nThe sample count can be changed with the `--sample-count` flag. For public evaluations\nthe sample count should be set to at least 1,000.\n\n### Generating Datasets\n\n```bash\nautorouting-dataset generate-dataset --problem-type single-trace --output ./single-trace-problem-XXX.json\n```\n\nThis command will generate a dataset of 100 problems (by default) for the specified problem type, saving each problem as a separate JSON file.\n\n### Generating Single Problems\n\nTo generate a single problem:\n\n```bash\nautorouting-dataset generate-problem --problem-type single-trace --seed 0 --output ./single-trace-problem-0.json\n```\n\nThis command generates a single problem of the specified type with the given seed and saves it to the specified output file.\n\n## Community Solvers\n\nComing soon! Please create an issue to add your solver to this repo, we will be listing benchmarks etc.!\n\nWe are working on a dedicated test machine for measuring performance.\n\n## References\n\n- [Pathfinding Architecture Optimizations](https://www.gameaipro.com/GameAIPro/GameAIPro_Chapter17_Pathfinding_Architecture_Optimizations.pdf)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftscircuit%2Fautorouting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftscircuit%2Fautorouting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftscircuit%2Fautorouting/lists"}