Geometry

AbstractGeometry

Abstract base type for all geometry specifications — the "where" of a gate application (apply!(state, gate, geometry)).

Geometries fall into two families, reported by the is_broadcast(geo) trait:

• Broadcast ("distribution") geometries expand to K ≥ 1 independent elements, each receiving its own gate application (and, inside apply_with_prob!, its own coin): AllSites, Bricklayer, EachSite.
• Set ("region") geometries denote ONE region of sites, a single element: SingleSite, AdjacentPair, Sites, StaircaseLeft/ StaircaseRight, Pointer.

The canonical enumeration for either family is elements(geo, L, bc) -> Vector{Vector{Int}} (physical site indices). Dynamic geometries (staircases, Pointer) are MUTABLE — staircases advance after each application, Pointer moves only via move!.

Geometries always speak PHYSICAL site indices; backends translate to their internal (RAM) indexing via state.phy_ram.

SingleSite(site::Int)

Geometry specifying a single physical site. Used for single-qubit gates like PauliX, Projection.

AdjacentPair(first::Int)

Geometry specifying an adjacent pair of physical sites: (first, first+1). For PBC, wraps: (L, 1) when first=L.

Sites(sites)

Set geometry: ONE region made of the given sites (a range or collection of Ints, kept in the given order). A gate applied to Sites(c) must have support(gate) == length(c) (see validate_support).

Expands to a single element [collect(sites)]. For applying a gate independently at each site, use EachSite instead.

AllSites

Geometry for applying single-site gates to all sites. apply! loops internally over all L sites.

EachSite(sites)

Broadcast geometry: apply a single-site gate independently at each site in sites (a range or collection of Ints, kept in the given order).

Expands to [[i] for i in sites] — one element per site. Example: SRN bulk eligibility is EachSite(2:L-1).

See also AllSites (all L sites) and Sites (one multi-site region, NOT a broadcast).

Bricklayer(parity::Symbol)

Geometry for bricklayer gate application pattern.

Nearest-neighbor (NN) modes:

• :odd parity → pairs (1,2), (3,4), (5,6), ...
• :even parity → pairs (2,3), (4,5), ... plus (L,1) for PBC
• :nn parity → ALL NN pairs (combines :odd + :even)

Next-nearest-neighbor (NNN) modes (4 sublayers covering all 12 NNN pairs for L=12):

• :nnn_odd_1 parity → pairs (1,3), (5,7), (9,11), ... (stride 4, offset 1)
• :nnn_odd_2 parity → pairs (3,5), (7,9), (11,1), ... (stride 4, offset 3, PBC wrap)
• :nnn_even_1 parity → pairs (2,4), (6,8), (10,12), ... (stride 4, offset 2)
• :nnn_even_2 parity → pairs (4,6), (8,10), (12,2), ... (stride 4, offset 4, PBC wrap)
• :nnn parity → ALL NNN pairs (combines all 4 sublayers)

apply! loops internally over all pairs.

StaircaseLeft(start_position::Int; range::Int=1)

Staircase that moves left: applies at (pos, pos+range), then decrements pos.

Arguments

• start_position: Initial position
• range: Distance between sites (default 1 for nearest neighbors)

Examples

StaircaseLeft(1)           # NN: (1,2), (2,3), ...
StaircaseLeft(1; range=2)  # NNN: (1,3), (2,4), ...

StaircaseRight(start_position::Int; range::Int=1)

Staircase that moves right: applies at (pos, pos+range), then advances pos.

Arguments

• start_position: Initial position
• range: Distance between sites (default 1 for nearest neighbors)

Examples

StaircaseRight(1)           # NN: (1,2), (2,3), ...
StaircaseRight(1; range=2)  # NNN: (1,3), (2,4), ...

Pointer(start_position::Int)

A bidirectional pointer that can move left or right. Unlike StaircaseLeft/StaircaseRight which are unidirectional, Pointer supports explicit direction control via move!().

For two-qubit gates, the pair is (position, position+1) with PBC wrap.

move!(p::Pointer, direction::Symbol, L::Int, bc::Symbol=:periodic)

Move the pointer in the specified direction.

• direction = :left → position decreases (wraps L → 1 for PBC)
• direction = :right → position increases (wraps 1 → L for PBC)

This is the PUBLIC API for pointer movement, unlike advance!() which is internal.

elements(geo::AbstractGeometry, L::Int, bc::Symbol) -> Vector{Vector{Int}}

Canonical element enumeration for a geometry: each inner vector is the sites for one gate application. This is the SINGLE source of truth consolidating the former get_pairs / get_compound_elements duplicates.

Broadcast geometries return K ≥ 1 elements in their documented canonical order (API contract — RNG coin consumption follows this order):

• AllSites() → [[1], [2], ..., [L]]
• EachSite(c) → [[i] for i in c] (collection order)
• Bricklayer(parity) → pairs exactly as documented in the README parity table (e.g. :odd → [[1,2],[3,4],...]; :even → [[2,3],...,[L,1]] for PBC at even L; :nn = :odd then :even plus the (L,1) wrap bond; :nnn = sublayers 1,2,3,4). At odd L, single layers (:odd, :even) leave one site unpaired rather than double-touching a site — see the parity branches below. Using :odd/:even at odd L under PBC emits a one-time warning at circuit-build / apply! time (helper _warn_bricklayer_odd_pbc in Geometry/static.jl — deliberately NOT called here: elements sits in performance-critical loops).

Set geometries return a single element [[sites...]]:

• SingleSite(i) → [[i]]
• AdjacentPair(i) → [[i, i+1]] (PBC wrap at L)
• Sites(c) → [collect(c)]
• StaircaseLeft/Right → [[pos, pos+range]] at the CURRENT position (PBC wrap via mod1; OBC out-of-bounds throws ArgumentError)
• Pointer → [[pos, pos+1]] at the current position (PBC wrap at L)

element_count(geo::AbstractGeometry, L::Int, bc::Symbol) -> Int

Number of elements (K) that geo expands to via elements. Broadcast geometries give K ≥ 1; set geometries always give 1. Used by builder validation (equal-K rule across stochastic outcomes).

is_broadcast(geo::AbstractGeometry) -> Bool

Trait: true for broadcast ("distribution") geometries that expand to multiple independent elements (AllSites, Bricklayer, EachSite); false for set ("region") geometries that denote a single region (SingleSite, AdjacentPair, Sites, StaircaseLeft/StaircaseRight, Pointer).