Contributing Autorouting Datasets

Autorouting datasets help tscircuit contributors compare routers, reproduce failures, and improve routing behavior over time. A good dataset is small enough to inspect, named consistently, easy to install from GitHub, and includes a visualization of the routing problem.

Dataset naming

When creating a new dataset, increase the number from the last known dataset in that prefix. Always use two digits for dataset numbers, such as 01, 02, or 05.

Use these prefixes:

Prefix	Dataset type
Z	Zero-obstacle dataset
SRJ	Simple Route JSON dataset
HG	HyperGraph dataset
HD	High-density node dataset, solved
TS	tscircuit code dataset

For example, if the latest Simple Route JSON dataset is dataset-srj05, the next one should be dataset-srj06.

Dataset library structure

Dataset repositories should be installable directly from GitHub:

bun add https://github.com/tscircuit/dataset-srj05

Use this structure:

dataset-srj05/
├── index.js
├── index.d.ts
├── package.json
└── samples/
    ├── sample001.json
    ├── sample002.json
    └── sample003.json

The package.json should point to index.js:

{
  "name": "@tscircuit/dataset-srj05",
  "main": "index.js",
  "types": "index.d.ts"
}

Export samples from index.js:

export { default as sample001 } from "./samples/sample001.json"
export { default as sample002 } from "./samples/sample002.json"
export { default as sample003 } from "./samples/sample003.json"

Keep index.d.ts lightweight:

import type { SimpleRouteJson } from "@tscircuit/core"

export const sample001: SimpleRouteJson
export const sample002: SimpleRouteJson
export const sample003: SimpleRouteJson

Follow these rules:

• Do not transpile the dataset package. Transpiled dataset packages do not work reliably with GitHub installation.
• Do not publish the dataset package to npm.
• Do not create an index.ts file. It can break type resolution for dataset packages.

Creating Simple Route JSON

To create a Simple Route JSON dataset from Circuit JSON, use getSimpleRouteJsonFromCircuitJson from @tscircuit/core:

import { getSimpleRouteJsonFromCircuitJson } from "@tscircuit/core"

const simpleRouteJson = getSimpleRouteJsonFromCircuitJson(circuitJson)

Save the generated Simple Route JSON objects as files in samples/.

Add a visualization

Every useful autorouting dataset should include a visualization so contributors can quickly understand the routing problem before running a router.

Use one of these approaches:

• A Cosmos server or similar local sample viewer that loads the dataset samples and renders them with graphics-debug from tscircuit. Contributors should be able to browse samples, inspect obstacles and connections, and understand the expected route behavior without writing a custom script.
• An SVG generated with circuit-to-svg when the dataset starts from Circuit JSON.

The visualization should live with the dataset and make it clear why each sample is interesting, such as a hard obstacle pattern, dense node layout, known failure case, solved high-density route, or minimal regression fixture.

Add snapshot tests

Datasets should include a small test suite that renders representative samples and checks them against snapshots. Snapshot tests make it easier to catch unexpected changes in generated Simple Route JSON, Graphic Debug output, or SVG rendering.

Prefer snapshots that are easy to inspect when they fail:

• Use Graphic Debug snapshots for datasets focused on routing obstacles, connections, or solver behavior.
• Use circuit-to-svg snapshots for datasets that start from Circuit JSON and need a PCB or schematic rendering.
• Include at least one snapshot for each important sample category in the dataset, not only the smallest sample.