Scoring

Candidate scoring for entropy-guided search.

Two-level scoring: 1. Per-qubit-bus: s(q, b, d; E) — entropy-weighted distance/mobility heuristic 2. Per-moveset: score[M] — alphadistance + betaarrived + gamma*mobility

CandidateScorer dataclass

CandidateScorer(
    params: SearchParams, target: dict[int, LocationAddress]
)

Scores qubit-bus pairs and movesets for entropy-guided search.

score_all_qubit_bus_pairs

score_all_qubit_bus_pairs(
    node: ConfigurationNode,
    entropy: int,
    tree: ConfigurationTree,
) -> dict[tuple[int, MoveType, int, Direction], float]

Score all legal (qubit, move_type, bus_id, direction) tuples.

Returns mapping of (qubit_id, move_type, bus_id, direction) -> score. Only includes legal tuples where the qubit is on the bus source and the destination is unoccupied.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/search/scoring.py

def score_all_qubit_bus_pairs(
    self,
    node: ConfigurationNode,
    entropy: int,
    tree: ConfigurationTree,
) -> dict[tuple[int, MoveType, int, Direction], float]:
    """Score all legal (qubit, move_type, bus_id, direction) tuples.

    Returns mapping of (qubit_id, move_type, bus_id, direction) -> score.
    Only includes legal tuples where the qubit is on the bus source and
    the destination is unoccupied.
    """
    occupied = node.occupied_locations | tree.blocked_locations
    e_eff = min(entropy, self.params.e_max)

    # Identify unresolved qubits
    unresolved = {
        qid: loc
        for qid, loc in node.configuration.items()
        if qid in self.target and loc != self.target[qid]
    }
    if not unresolved:
        return {}

    # Cache d_now and m_now per qubit (same across all buses)
    d_now: dict[int, float] = {}
    m_now: dict[int, int] = {}
    for qid, loc in unresolved.items():
        d_now[qid] = self._distance_to_target(loc, self.target[qid], tree)
        m_now[qid] = self._mobility_at(loc, occupied, tree)

    # Compute raw deltas for all legal (qubit, move_type, bus_id, direction)
    d_after_cache: dict[tuple[int, LocationAddress], float] = {}
    m_after_cache: dict[LocationAddress, int] = {}
    raw_scores: dict[tuple[int, MoveType, int, Direction], tuple[float, float]] = {}
    for mt in (MoveType.SITE, MoveType.WORD):
        buses = (
            tree.arch_spec.site_buses
            if mt == MoveType.SITE
            else tree.arch_spec.word_buses
        )
        for bus_id in range(len(buses)):
            for direction in (Direction.FORWARD, Direction.BACKWARD):
                for qid, loc in unresolved.items():
                    lane = tree.lane_for_source(mt, bus_id, direction, loc)
                    if lane is None:
                        continue
                    _, dst = tree.arch_spec.get_endpoints(lane)
                    if dst in occupied:
                        continue
                    d_key = (qid, dst)
                    d_after = d_after_cache.get(d_key)
                    if d_after is None:
                        d_after = self._distance_to_target(
                            dst, self.target[qid], tree
                        )
                        d_after_cache[d_key] = d_after
                    m_after = m_after_cache.get(dst)
                    if m_after is None:
                        m_after = self._mobility_at(dst, occupied, tree)
                        m_after_cache[dst] = m_after
                    delta_d = d_now[qid] - d_after
                    delta_m = m_after - m_now[qid]
                    raw_scores[(qid, mt, bus_id, direction)] = (delta_d, delta_m)

    if not raw_scores:
        return {}

    # Normalize
    d_ref = max(1.0, max(abs(dd) for dd, _ in raw_scores.values()))
    m_ref = max(1.0, max(abs(dm) for _, dm in raw_scores.values()))

    # Apply entropy-weighted formula
    result: dict[tuple[int, MoveType, int, Direction], float] = {}
    for key, (delta_d, delta_m) in raw_scores.items():
        d_hat = delta_d / d_ref
        m_hat = delta_m / m_ref
        score = (self.params.w_d / e_eff) * d_hat + self.params.w_m * e_eff * m_hat
        result[key] = score

    return result

score_moveset

score_moveset(
    moveset: frozenset[LaneAddress],
    node: ConfigurationNode,
    tree: ConfigurationTree,
) -> float

Score a candidate moveset.

Returns alphadistance_moved + betaarrived_gain + gamma*mobility_gain.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/search/scoring.py

def score_moveset(
    self,
    moveset: frozenset[LaneAddress],
    node: ConfigurationNode,
    tree: ConfigurationTree,
) -> float:
    """Score a candidate moveset.

    Returns alpha*distance_moved + beta*arrived_gain + gamma*mobility_gain.
    """
    occupied = node.occupied_locations | tree.blocked_locations
    distance_moved = 0.0
    arrived_gain = 0
    mobility_before = 0
    mobility_after = 0

    # Identify moved qubits and build post-move config
    new_config: dict[int, LocationAddress] = dict(node.configuration)
    moved_qubits: list[tuple[int, LocationAddress, LocationAddress]] = []

    for lane in moveset:
        src, dst = tree.arch_spec.get_endpoints(lane)
        qid = node.get_qubit_at(src)
        if qid is None:
            continue
        moved_qubits.append((qid, src, dst))
        new_config[qid] = dst

    new_occupied = frozenset(new_config.values()) | tree.blocked_locations

    for qid, src, dst in moved_qubits:
        if qid not in self.target:
            continue
        d_before = self._distance_to_target(src, self.target[qid], tree)
        d_after = self._distance_to_target(dst, self.target[qid], tree)
        distance_moved += max(0.0, d_before - d_after)
        if dst == self.target[qid]:
            arrived_gain += 1
        mobility_before += self._mobility_at(src, occupied, tree)
        mobility_after += self._mobility_at(dst, new_occupied, tree)

    mobility_gain = mobility_after - mobility_before

    return (
        self.params.alpha * distance_moved
        + self.params.beta * arrived_gain
        + self.params.gamma * mobility_gain
    )