Target generator

Target-generation plugin interface for PhysicalPlacementStrategy.

PhysicalPlacementStrategy asks a :class:TargetGeneratorABC for an ordered list of candidate target placements before each CZ stage. The strategy always appends :class:DefaultTargetGenerator's output as a guaranteed last-resort fallback, so plugins may return [] to defer entirely to the default.

AODClusterTargetGenerator `dataclass`

AODClusterTargetGenerator()

Bases: TargetGeneratorABC


              flowchart TD
              bloqade.lanes.heuristics.physical.target_generator.AODClusterTargetGenerator[AODClusterTargetGenerator]
              bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC[TargetGeneratorABC]

                              bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC --> bloqade.lanes.heuristics.physical.target_generator.AODClusterTargetGenerator
                


              click bloqade.lanes.heuristics.physical.target_generator.AODClusterTargetGenerator href "" "bloqade.lanes.heuristics.physical.target_generator.AODClusterTargetGenerator"
              click bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC href "" "bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC"

Choose CZ directions to maximise AOD-shot packing.

For each CZ pair, enumerate both direction candidates (control-moves or target-moves) and classify each by the (move_type, zone_id, bus_id, direction) signature of its first path hop — the same signature the downstream move scheduler uses to batch lanes into one AOD shot. Directions are then assigned greedily: the signature appearing in the most candidate first-hops is filled first, then the next largest, and so on. When no further clustering gain is possible (largest remaining bucket has a single unresolved pair), remaining pairs default to control-direction for parity with :class:DefaultTargetGenerator.

Rationale: CongAware rewards same-direction lane reuse per edge via a Dijkstra weight. That is a local proxy for shot-sharing; the scheduler actually batches by the 4-tuple above, not by individual lane reuse. Choosing CZ directions that align first-hops on shared signatures produces targets the scheduler can pack more tightly.

CongestionAwareTargetGenerator `dataclass`

CongestionAwareTargetGenerator(
    direction_factor: float = 0.5,
    shared_site_factor: float = 1.1,
)

Bases: TargetGeneratorABC


              flowchart TD
              bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator[CongestionAwareTargetGenerator]
              bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC[TargetGeneratorABC]

                              bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC --> bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator
                


              click bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator href "" "bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator"
              click bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC href "" "bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC"

Joint, longest-first, congestion-aware target generator.

For each CZ pair, picks whether to move the control or the target based on schedule-time cost computed against a working placement that reflects all prior pairs' committed moves and a running directional congestion record.

Per-lane weighting composes two orthogonal multiplicative factors (see :func:_make_weight_fn):

direction_factor ** (N - M) — signed net of same-direction (N) minus opposite-direction (M) prior commits on the lane. With direction_factor < 1, net-positive traffic rewards AOD-parallel reuse and net-negative traffic penalises contention; balanced traffic (N == M) is neutral.
shared_site_factor — applied whenever an endpoint of the candidate lane is a site a prior committed path already traversed. Applies independently of direction_factor; the two signals compose multiplicatively.

Dijkstra requires non-negative edge weights. direction_factor must be strictly positive (the negative exponent is otherwise undefined); shared_site_factor must be >= 0. Defaults reflect the canonical tuning; empirical retuning is a follow-up.

DefaultTargetGenerator `dataclass`

DefaultTargetGenerator()

Bases: TargetGeneratorABC


              flowchart TD
              bloqade.lanes.heuristics.physical.target_generator.DefaultTargetGenerator[DefaultTargetGenerator]
              bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC[TargetGeneratorABC]

                              bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC --> bloqade.lanes.heuristics.physical.target_generator.DefaultTargetGenerator
                


              click bloqade.lanes.heuristics.physical.target_generator.DefaultTargetGenerator href "" "bloqade.lanes.heuristics.physical.target_generator.DefaultTargetGenerator"
              click bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC href "" "bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC"

Default rule: control qubit moves to the CZ partner of the target's location.

LookaheadCongestionAwareTargetGenerator `dataclass`

LookaheadCongestionAwareTargetGenerator(
    direction_factor: float = 0.5,
    shared_site_factor: float = 1.1,
    K: int = 4,
    gamma: float = 0.7,
)

Bases: CongestionAwareTargetGenerator


              flowchart TD
              bloqade.lanes.heuristics.physical.target_generator.LookaheadCongestionAwareTargetGenerator[LookaheadCongestionAwareTargetGenerator]
              bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator[CongestionAwareTargetGenerator]
              bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC[TargetGeneratorABC]

                              bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator --> bloqade.lanes.heuristics.physical.target_generator.LookaheadCongestionAwareTargetGenerator
                                bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC --> bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator
                



              click bloqade.lanes.heuristics.physical.target_generator.LookaheadCongestionAwareTargetGenerator href "" "bloqade.lanes.heuristics.physical.target_generator.LookaheadCongestionAwareTargetGenerator"
              click bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator href "" "bloqade.lanes.heuristics.physical.target_generator.CongestionAwareTargetGenerator"
              click bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC href "" "bloqade.lanes.heuristics.physical.target_generator.TargetGeneratorABC"

Congestion-aware target picker with K-stage participation lookahead.

Extends :class:CongestionAwareTargetGenerator by augmenting each pair's cost with a discounted simulation of future-stage path costs. For each candidate direction (move ctrl or move tgt), the score is

cost = path_cost_now + sum_{k=1..K} gamma^k * stage_cost_k

where stage_cost_k simulates stage k ahead under the chosen commit and computes the per-pair cheapest-direction cost. The lower-total direction wins; path-length tiebreak is preserved from :func:_choose_control.

With K=0 this reduces to :class:CongestionAwareTargetGenerator.

The lookahead favours keeping qubits stable when they are reused in the next K stages — useful for hub-and-spoke patterns (single repeated control), GHZ ladders (chain neighbours), and magic-state factory cycles.

Attributes:

Name	Type	Description
`K`	`int`	Lookahead horizon in stages. Must be `>= 0`. Default 4.
`gamma`	`float`	Per-stage discount factor for simulated future cost. Must be in `(0, 1]`. Default 0.7.
`direction_factor`	`/ shared_site_factor`	Inherited; same semantics as :class:`CongestionAwareTargetGenerator`.

generate

generate(
    ctx: TargetContext,
) -> list[dict[int, LocationAddress]]

Same as parent's generate(), but threads ctx.lookahead_cz_layers through state so :meth:_simulate_future_cost can read it.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/heuristics/physical/target_generator.py

def generate(self, ctx: TargetContext) -> list[dict[int, LocationAddress]]:
    """Same as parent's generate(), but threads ``ctx.lookahead_cz_layers``
    through ``state`` so :meth:`_simulate_future_cost` can read it.
    """
    placement = ctx.placement
    if not ctx.controls:
        return [dict(placement)]

    pf = PathFinder(ctx.arch_spec)
    state = _GenerateState(
        arch_spec=ctx.arch_spec,
        pf=pf,
        working=dict(placement),
        committed_lanes={},
        committed_sites=set(),
        lookahead_cz_layers=ctx.lookahead_cz_layers,
    )

    pairs = self._sort_pairs_longest_first(ctx, pf)
    for ctrl, tgt in pairs:
        result = self._commit_pair(state, ctrl, tgt)
        if result is None:
            return []
        mover, new_loc, chosen = result
        state.working[mover] = new_loc
        for lane in chosen[0]:
            counts = state.committed_lanes.setdefault(_lane_key(lane), Counter())
            counts[lane.direction] += 1
        state.committed_sites.update(chosen[1])

    return [state.working]

TargetContext `dataclass`

TargetContext(
    arch_spec: ArchSpec,
    state: ConcreteState,
    controls: tuple[int, ...],
    targets: tuple[int, ...],
    lookahead_cz_layers: tuple[
        tuple[tuple[int, ...], tuple[int, ...]], ...
    ],
    cz_stage_index: int,
)

Signals passed to a TargetGenerator.

Composes ConcreteState to avoid duplicating lattice state fields.