ArchSpec — Architecture Specification

The ArchSpec defines the physical topology and transport capabilities of a Bloqade quantum device. It is the input that the bytecode compiler and validator use to determine which instructions are legal for a given hardware configuration.

The formal JSON Schema is available at archspec-schema.json.

Top-Level Structure

{
  "version": "1.0",
  "geometry": { ... },
  "buses": { ... },
  "words_with_site_buses": [...],
  "sites_with_word_buses": [...],
  "zones": [...],
  "entangling_zones": [...],
  "measurement_mode_zones": [...],
  "paths": [...],                 // optional
  "feed_forward": false,          // optional, default false
  "atom_reloading": false          // optional, default false
}

Geometry

The geometry describes the physical layout of the device: how many words exist, how many sites each word contains, and where those sites are in 2D space.

"geometry": {
  "sites_per_word": 10,
  "words": [
    {
      "positions": {
        "x_start": 1.0,
        "y_start": 2.5,
        "x_spacing": [2.0, 2.0, 2.0, 2.0],
        "y_spacing": [2.5]
      },
      "site_indices": [[0, 0], [1, 0], [2, 0], ...],
      "has_cz": [[0, 5], [0, 6], ...]       // optional
    }
  ]
}

Word

A word is an independent register of atom trapping sites arranged on a 2D grid. It is the fundamental unit of the device topology.

A word's ID is its index in the geometry.words array (e.g., the first word is word 0).

Grid

A grid defines the physical coordinate axes for a word using a start position and spacing values. Positions are typically in micrometers (µm).

The x-coordinates are computed as [x_start, x_start + x_spacing[0], x_start + x_spacing[0] + x_spacing[1], ...] (cumulative sum of spacings from the start). Same for y. Sites reference grid positions by index: site [2, 1] is located at the 3rd x-coordinate and 2nd y-coordinate.

All words must have the same grid shape — i.e., the same number of x and y grid points (same x_spacing and y_spacing lengths). The actual coordinate values may differ (words can be at different physical locations), but the grid dimensions must be consistent.

Buses

Buses are the physical transport channels that move atoms. There are two kinds:

Site Bus

A site bus moves atoms between sites within the same word. It defines a paired mapping where src[i] moves to dst[i].

{ "src": [0, 1, 2, 3, 4], "dst": [5, 6, 7, 8, 9] }

This means atom at site 0 moves to site 5, atom at site 1 moves to site 6, and so on — all in a single transport operation. The src and dst arrays must be the same length and must not overlap (no site can be both a source and a destination in the same bus). A site bus's ID is its index in the buses.site_buses array.

Word Bus

A word bus moves atoms between sites across different words. The src and dst arrays contain word IDs (not site indices). A word bus's ID is its index in the buses.word_buses array.

{ "src": [0], "dst": [1] }

The specific sites involved in inter-word transport are those listed in sites_with_word_buses — these are the "landing pad" positions within each word.

Supporting Fields

Zones

A zone groups words into logical regions for different execution phases (entangling, measurement, etc.).

"zones": [
  { "words": [0, 1, 2] }
]

A zone's ID is its index in the zones array (e.g., the first zone is zone 0).

Zone 0 is special — it must contain every word in the geometry. This ensures there is always a "global" zone that covers the entire device.

Entangling Zones

entangling_zones lists zone IDs where CZ (entangling) gates can be performed. Words in these zones must have has_cz defined to specify entanglement partners.

Measurement Mode Zones

measurement_mode_zones lists zone IDs that support measurement operations. If non-empty, the first entry must be zone 0.

Paths (Optional)

AOD (Acousto-Optic Deflector) transport paths. Each path identifies a transport lane and provides a sequence of [x, y] waypoints defining the physical trajectory atoms follow during transport.

The lane is identified by its encoded LaneAddr, serialized as a hex string. See Address Encoding for the LaneAddr bit layout.

"paths": [
  {
    "lane": "0xC000000000000000",                        // encoded LaneAddr (hex, 16-digit)
    "waypoints": [[1.0, 12.5], [1.0, 7.5], [1.0, 2.5]]  // physical trajectory
  }
]

Each TransportPath entry has:

To decode the lane hex string, parse it as a 64-bit unsigned integer. The low 32 bits (data0) contain [word_id:16][site_id:16] and the high 32 bits (data1) contain [dir:1][mt:1][pad:14][bus_id:16]. For example, "0xC000000000000000" decodes to direction=Backward, move_type=WordBus, word=0, site=0, bus=0. In the lane address convention, word_id always encodes the forward-direction source word for that lane; in this specific example the bus mapping is src=[0], dst=[1], so direction=Backward means the move goes from word 1 back to word 0.

This field is omitted from the JSON when not needed.

Capability Flags (Optional)

Two boolean flags describe device capabilities that affect bytecode validation:

Both fields are optional in the JSON — existing arch spec files that omit them default to false, which is the most restrictive setting.

{
  "feed_forward": true,
  "atom_reloading": false
}

Validation Rules

The ArchSpec::validate() method checks all structural rules in a single pass, collecting every error rather than failing fast. The following rules are enforced:

Zone Rules

Word / Site Rules

Site Bus Rules

Word Bus Rules

Cross-Reference Rules

Path Rules

Capability Rules (Bytecode Validation)

These rules are checked during bytecode validation when an ArchSpec is provided:

Address Encoding

At the bytecode level, locations and lanes are encoded as bit-packed integers with 16-bit address fields. Each address type is packed into instruction data words (u32):

These packed addresses are used in 16-byte bytecode instructions (opcode + 3 data words) and are validated against the arch spec during program validation. In JSON and Python, LaneAddr is represented as a 64-bit integer (16-digit hex string in JSON, u64 in Python).

Examples

Minimal spec with one word and one site bus:

{
  "version": "1.0",
  "geometry": {
    "sites_per_word": 5,
    "words": [
      {
        "positions": {
          "x_start": 1.0,
          "y_start": 2.0,
          "x_spacing": [2.0, 2.0, 2.0, 2.0],
          "y_spacing": []
        },
        "site_indices": [[0, 0], [1, 0], [2, 0], [3, 0], [4, 0]]
      }
    ]
  },
  "buses": {
    "site_buses": [
      { "src": [0, 1], "dst": [3, 4] }
    ],
    "word_buses": []
  },
  "words_with_site_buses": [0],
  "sites_with_word_buses": [],
  "zones": [
    { "words": [0] }
  ],
  "entangling_zones": [],
  "measurement_mode_zones": [0]
}

A fuller example with multiple words, CZ pairs, and word buses is available at examples/arch/full.json.