Draft: Schematic graph export

[gpeairs]

This is a draft for YAML export of graph topology, complementing ParameterSet export, which I'm opening for visibility/discussion. This version is scoped for read-only consumption by external tooling. Graph generation from YAML is out of scope (maybe could be convenient for part of authoring, but actual designs will have arbitrary Julia code in graph construction, requiring a full Julia project and manifest for reproducibility anyway).

The design produces a three-file bundle alongside any DL design project:

my_design/
  parameters.yml        # existing ParameterSet YAML, populated for every node
  topology.yml          # NEW: SchematicGraph as data (pre-plan!)
  floorplan.yml         # NEW (optional): post-plan! resolved geometry

Implementation is a new SchematicGraphYAMLExt package extension paired with
save_parameter_set from ParameterSetYAMLExt.

Example topology.yml:

schema_version: "1"
parameters: parameters.yml
floorplan: floorplan.yml          # optional pointer
name: my_design

nodes:
  - id: cpw_1
    component:
      type: RouteComponent
      module: DeviceLayout
      params: components.cpw_1    # address in corresponding parameters.yml
      name: cpw_1
    additional_hooks:             # only when :additional_hooks vertex prop set
      attach_label_1:
        kind: HandedPointHook
        point: ["1mm", "1mm"]
        direction: "90°"
        handedness: left
    properties:                   # other vertex props; absent if none
      some_user_prop: 42

  - id: qubit_1
    component:
      type: ExampleStarTransmon
      module: DeviceLayout.SchematicDrivenLayout.ExamplePDK.Transmons
      params: components.qubit_1
      name: qubit_1
    subgraph:                     # present iff component is AbstractCompositeComponent
      name: qubit_1
      nodes: [...]                # recursive: same node schema
      edges: [...]                # recursive: same edge schema

edges:
  - nodes: [qubit_1, cpw_1]
    hooks: [readout, p0]
    properties:
      plan_skips_edge: true

There is no geometry or parameter information here. The one potential exception is if a node has additional_hooks, they need to be present here, with their type and geometry. This arguably could be a graph-native format but right now it's YAML for consistency with ParameterSet.

Example floorplan.yml:

schema_version: "1"
topology: topology.yml
name: my_design
coordinate_type: nm                # type parameter S of Schematic{S}, as unit string

nodes:
  - id: qubit_1
    transformation:                # decomposed ScaledIsometry
      origin: ["1.5mm", "0.8mm"]
      rotation: "90°"
      xrefl: false
      mag: 1.0
    hooks:                         # resolved global pos+dir for every hook (named + additional)
      readout:
        kind: HandedPointHook
        point: ["1.6mm", "0.85mm"]
        direction: "180°"
        handedness: right
      drive:
        kind: PointHook
        point: ["1.4mm", "0.85mm"]
        direction: "0°"
    bounds:                        # global Rectangle from bounds(sch, node)
      ll: ["1.4mm", "0.7mm"]
      ur: ["1.6mm", "0.9mm"]

routes:                            # one entry per RouteComponent node, post-resolution
  - id: cpw_1
    p0: ["1.6mm", "0.85mm"]
    p1: ["3.2mm", "0.85mm"]
    α0: "0°"
    α1: "180°"
    waypoints: [["2.0mm", "0.85mm"], ["2.5mm", "1.0mm"]]
    waydirs: ["0°", "45°"]
    rule_type: BSplineRouting
    # Rule parameters could live here, current draft assumes they're in parameters.yml if needed.

nested_nodes:                      # composite-internal nodes, flattened
  - path: [unit_cell_1, qubit_2]   # tuple addressing matches find_components
    transformation: { ... }
    hooks: { ... }
    bounds: { ... }

This is flat while topology.yml is nested on the assumption that most floorplan consumers are interested in a global view of the design.

Also adds a "bundle" entry to each of the three files:

bundle:
  source_fingerprint: "sha256:7446ae74…b1d950"
  design_id: "demo"
  generator: "DeviceLayout v1.18.0"
  generated_at: "2026-08-25T11:57:54Z"

---

If we ever go through a major redesign, it's worth considering different models of reproducibility/authoring, e.g. with component parameterized geometry as data along with as many manual-code finishing touches as possible (e.g. autofill). The additional_hooks in the SchematicGraph are also a bit impure if we really want to separate connectivity and placement. But I think we value the flexibility too much.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[gpeairs]

• Timestamp and fingerprint seem like overkill, maybe just be careful to write and remove (for replacement) bundles atomically
• Route handling -- routes can be inside composite components; floorplan gets route rule type but parameters are nowhere & not extractable to parameter set (true of paths also)
• Really would like to handle structured parameters better, collections with unsupported elements don't get repr-ed, just dropped
• Vector-valued hooks not supported
• a pre-existing bundle namespace can get overwritten
• Actually document the schema specification, don't just describe