Goal

Goal predicates, type aliases, and shared infrastructure for traversals.

CostFunction module-attribute

CostFunction = Callable[[ConfigurationNode], float]

Computes the accumulated cost of reaching a node. Lower is better.

GoalPredicate module-attribute

GoalPredicate = Callable[[ConfigurationNode], bool]

Returns True if the node satisfies the search goal.

HeuristicFunction module-attribute

HeuristicFunction = Callable[[ConfigurationNode], float]

Estimates the cost from a node to the goal. Lower is better.

PriorityEntry dataclass

PriorityEntry(priority: float, node: ConfigurationNode)

Heap entry for priority-based search.

SearchResult dataclass

SearchResult(
    *,
    nodes_expanded: int,
    max_depth_reached: int,
    goal_nodes: tuple[ConfigurationNode, ...] = (),
    goal_node: ConfigurationNode | None = None
)

Result of a search strategy.

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

def __init__(
    self,
    *,
    nodes_expanded: int,
    max_depth_reached: int,
    goal_nodes: tuple[ConfigurationNode, ...] = (),
    goal_node: ConfigurationNode | None = None,
) -> None:
    # Canonicalize all results into goal_nodes so single/multi-solution
    # handling uses one representation everywhere.
    if goal_node is not None:
        if goal_nodes and goal_nodes[0] is not goal_node:
            raise ValueError(
                "goal_node must match first item in goal_nodes when both are set"
            )
        goal_nodes = (goal_node, *goal_nodes[1:]) if goal_nodes else (goal_node,)

    self.nodes_expanded = nodes_expanded
    self.max_depth_reached = max_depth_reached
    self.goal_nodes = goal_nodes

goal_node property

goal_node: ConfigurationNode | None

Best goal node, or None if no goal was found.

goal_nodes instance-attribute

goal_nodes: tuple[ConfigurationNode, ...] = goal_nodes

Goal nodes found during search, ordered best to worst.

max_depth_reached instance-attribute

max_depth_reached: int = max_depth_reached

Maximum depth reached during search.

nodes_expanded instance-attribute

nodes_expanded: int = nodes_expanded

Total number of nodes expanded during search.

partial_placement_goal

partial_placement_goal(
    target: dict[int, LocationAddress],
    min_placed: int | None = None,
) -> GoalPredicate

Goal: at least some qubits are at their target locations.

If min_placed is None, all qubits in target must be placed (same as placement_goal). Otherwise, at least min_placed qubits must be at their target.

Parameters:

Name	Type	Description	Default
target	dict[int, LocationAddress]	Mapping of qubit ID to desired location.	required
min_placed	int | None	Minimum number of qubits that must be at their target. None means all.	None

Returns:

Type	Description
GoalPredicate	A GoalPredicate.

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

def partial_placement_goal(
    target: dict[int, LocationAddress],
    min_placed: int | None = None,
) -> GoalPredicate:
    """Goal: at least some qubits are at their target locations.

    If `min_placed` is None, all qubits in `target` must be placed
    (same as `placement_goal`). Otherwise, at least `min_placed`
    qubits must be at their target.

    Args:
        target: Mapping of qubit ID to desired location.
        min_placed: Minimum number of qubits that must be at their
            target. None means all.

    Returns:
        A GoalPredicate.
    """
    required = min_placed if min_placed is not None else len(target)

    def goal(node: ConfigurationNode) -> bool:
        placed = sum(
            1 for qid, loc in target.items() if node.configuration.get(qid) == loc
        )
        return placed >= required

    return goal

placement_goal

placement_goal(
    target: dict[int, LocationAddress],
) -> GoalPredicate

Goal: all specified qubits are at their target locations.

Every qubit in target must be at the exact location. Qubits not in target are ignored.

Parameters:

Name	Type	Description	Default
target	dict[int, LocationAddress]	Mapping of qubit ID to desired location.	required

Returns:

Type	Description
GoalPredicate	A GoalPredicate that returns True when all targets are met.

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

def placement_goal(target: dict[int, LocationAddress]) -> GoalPredicate:
    """Goal: all specified qubits are at their target locations.

    Every qubit in `target` must be at the exact location. Qubits not
    in `target` are ignored.

    Args:
        target: Mapping of qubit ID to desired location.

    Returns:
        A GoalPredicate that returns True when all targets are met.
    """

    def goal(node: ConfigurationNode) -> bool:
        return all(node.configuration.get(qid) == loc for qid, loc in target.items())

    return goal

zone_goal

zone_goal(
    zone_id: int, arch_spec: ArchSpec
) -> GoalPredicate

Goal: all qubits are located in the specified zone.

A qubit is "in the zone" if its location's word_id is in the zone's word list.

Parameters:

Name	Type	Description	Default
zone_id	int	The zone to target.	required
arch_spec	ArchSpec	Architecture specification (for zone → word mapping).	required

Returns:

Type	Description
GoalPredicate	A GoalPredicate that returns True when all qubits are in the zone.

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

def zone_goal(zone_id: int, arch_spec: ArchSpec) -> GoalPredicate:
    """Goal: all qubits are located in the specified zone.

    A qubit is "in the zone" if its location's word_id is in the
    zone's word list.

    Args:
        zone_id: The zone to target.
        arch_spec: Architecture specification (for zone → word mapping).

    Returns:
        A GoalPredicate that returns True when all qubits are in the zone.
    """
    zone_words = set(arch_spec.zones[zone_id])

    def goal(node: ConfigurationNode) -> bool:
        return all(loc.word_id in zone_words for loc in node.configuration.values())

    return goal