Circuit.surround
- Circuit.surround(point, num_qudits, bounding_region=None, fail_quickly=None, filter=None, scoring_fn=None)[source]
Retrieve the maximal connected region in this circuit with point.
- Parameters:
point (
tuple[int,int] |CircuitPoint|Mapping[int,tuple[int,int] |CycleInterval] |CircuitRegion) – Find a surrounding region for this point (or region). This point (or region) will be in the final CircuitRegion.num_qudits (
int) – The maximum number of qudits to include in the surrounding region.bounding_region (
Mapping[int,tuple[int,int] |CycleInterval] |CircuitRegion|None) – An optional region that bounds the resulting region.fail_quickly (
bool|None) – If set to true, will not branch on an invalid region. This will lead to a much faster result in some cases at the cost of only approximating the maximal region. (Deprecated, does nothing now besides print a warning if a bool.)filter (
Callable[[CircuitRegion],bool] |None) – The filter function determines if a candidate region is valid in the caller’s context. This is used to prune the search space of the surround function. If None, then no filtering is done. It takes a CircuitRegion and returns a boolean. Only regions that pass the filter are considered.scoring_fn (
Callable[[CircuitRegion],float] |None) – The scoring function determines the “best” surrounding region. If left as None, then this will default to the region with the most number of gates with larger gates worth more. It takes a CircuitRegion and returns a float. Larger scores are better.
- Raises:
IndexError – If point is not a valid index.
ValueError – If num_qudits is nonpositive.
ValueError – If the operation at point is too large for num_qudits.
ValueError – If bounding_region is invalid.
ValueError – If the initial node does not pass the filter.
- Return type:
Notes
This algorithm explores outward horizontally as much as possible. When a gate is encountered that involves another qudit not currently in the region, a decision needs to be made on whether that gate will be included or not. These decisions form a tree; an exhaustive search is employed to find the maximal region from this decision tree.