> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.conductorquantum.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.conductorquantum.com/_mcp/server.

# stanza.routines.builtins.dqd_search.grid_search

Grid-based search utilities for DQD discovery.

## Module Contents

### Classes

| Name | Description |
|------|-------------|
| [`SearchSquare`](#stanzaroutinesbuiltinsdqd_searchgrid_searchsearchsquare) | Results from measuring a single grid square. |

### Functions

| Name | Description |
|------|-------------|
| [`generate_grid_corners`](#stanzaroutinesbuiltinsdqd_searchgrid_searchgenerate_grid_corners) | Generate grid of square corners covering the voltage space. |
| [`generate_diagonal_sweep`](#stanzaroutinesbuiltinsdqd_searchgrid_searchgenerate_diagonal_sweep) | Generate diagonal line through a square. |
| [`generate_2d_sweep`](#stanzaroutinesbuiltinsdqd_searchgrid_searchgenerate_2d_sweep) | Generate 2D grid sweep over a square. |
| [`get_neighboring_squares`](#stanzaroutinesbuiltinsdqd_searchgrid_searchget_neighboring_squares) | Get neighboring grid square indices. |
| [`get_grid_distance`](#stanzaroutinesbuiltinsdqd_searchgrid_searchget_grid_distance) | Calculate Manhattan distance between two grid squares. |
| [`select_weighted_by_score`](#stanzaroutinesbuiltinsdqd_searchgrid_searchselect_weighted_by_score) | Select candidate weighted by proximity and score of successful squares. |
| [`select_next_square`](#stanzaroutinesbuiltinsdqd_searchgrid_searchselect_next_square) | Select next grid square using hierarchical priority strategy. |

### Data

`HIGH_SCORE_THRESHOLD`
`GRID_SQUARE_MULTIPLIER`
`DISTANCE_DECAY_FACTOR`

### API

```python
stanza.routines.builtins.dqd_search.grid_search.HIGH_SCORE_THRESHOLD: float
```

**Value**: `1.5`


```python
stanza.routines.builtins.dqd_search.grid_search.GRID_SQUARE_MULTIPLIER: float
```

**Value**: `None`


```python
stanza.routines.builtins.dqd_search.grid_search.DISTANCE_DECAY_FACTOR: float
```

**Value**: `1.0`


```python
class stanza.routines.builtins.dqd_search.grid_search.SearchSquare
```

Results from measuring a single grid square.

```python
grid_idx: int
```

**Value**: `None`


```python
current_trace_currents: numpy.typing.NDArray[numpy.float64]
```

**Value**: `None`


```python
current_trace_voltages: numpy.typing.NDArray[numpy.float64]
```

**Value**: `None`


```python
current_trace_score: float
```

**Value**: `None`


```python
current_trace_classification: bool
```

**Value**: `None`


```python
low_res_csd_currents: numpy.typing.NDArray[numpy.float64] | None
```

**Value**: `None`


```python
low_res_csd_voltages: numpy.typing.NDArray[numpy.float64] | None
```

**Value**: `None`


```python
low_res_csd_score: float
```

**Value**: `None`


```python
low_res_csd_classification: bool
```

**Value**: `None`


```python
high_res_csd_currents: numpy.typing.NDArray[numpy.float64] | None
```

**Value**: `None`


```python
high_res_csd_voltages: numpy.typing.NDArray[numpy.float64] | None
```

**Value**: `None`


```python
high_res_csd_score: float
```

**Value**: `None`


```python
high_res_csd_classification: bool
```

**Value**: `None`


```python
total_score: float
```


```python
is_dqd: bool
```


```python
to_list(arr: numpy.typing.NDArray[numpy.float64] | None) -> list[float] | None
```


```python
to_dict() -> dict[str, typing.Any]
```

Convert to JSON-serializable dictionary.


```python
stanza.routines.builtins.dqd_search.grid_search.generate_grid_corners(
    plunger_x_bounds: tuple[float, float],
    plunger_y_bounds: tuple[float, float],
    square_size: float
) -> tuple[numpy.typing.NDArray[numpy.float64], int, int]
```

Generate grid of square corners covering the voltage space.

**Parameters:**

<ParamField path="plunger_x_bounds" type="tuple[float, float]">
  (min, max) voltage bounds for X plunger
</ParamField>

<ParamField path="plunger_y_bounds" type="tuple[float, float]">
  (min, max) voltage bounds for Y plunger
</ParamField>

<ParamField path="square_size" type="float">
  Side length of each grid square
</ParamField>

**Returns:**

Tuple of (grid_corners, n_x, n_y) where:
- grid_corners: (n_x*n_y, 2) array of bottom-left corners
- n_x: Number of squares in X direction
- n_y: Number of squares in Y direction


```python
stanza.routines.builtins.dqd_search.grid_search.generate_diagonal_sweep(
    corner: numpy.typing.NDArray[numpy.float64],
    size: float,
    num_points: int
) -> numpy.typing.NDArray[numpy.float64]
```

Generate diagonal line through a square.

**Parameters:**

<ParamField path="corner" type="numpy.typing.NDArray[numpy.float64]">
  (2,) bottom-left corner coordinates
</ParamField>

<ParamField path="size" type="float">
  Square side length
</ParamField>

<ParamField path="num_points" type="int">
  Number of points along diagonal
</ParamField>

**Returns:**

(num_points, 2) array of voltage coordinates


```python
stanza.routines.builtins.dqd_search.grid_search.generate_2d_sweep(
    corner: numpy.typing.NDArray[numpy.float64],
    size: float,
    num_points: int
) -> numpy.typing.NDArray[numpy.float64]
```

Generate 2D grid sweep over a square.

**Parameters:**

<ParamField path="corner" type="numpy.typing.NDArray[numpy.float64]">
  (2,) bottom-left corner coordinates
</ParamField>

<ParamField path="size" type="float">
  Square side length
</ParamField>

<ParamField path="num_points" type="int">
  Number of points per axis
</ParamField>

**Returns:**

(num_points, num_points, 2) array of voltage coordinates


```python
stanza.routines.builtins.dqd_search.grid_search.get_neighboring_squares(
    grid_idx: int,
    n_x: int,
    n_y: int,
    include_diagonals: bool = False
) -> list[int]
```

Get neighboring grid square indices.

**Parameters:**

<ParamField path="grid_idx" type="int">
  Linear index of current grid square
</ParamField>

<ParamField path="n_x" type="int">
  Number of grid squares in X direction
</ParamField>

<ParamField path="n_y" type="int">
  Number of grid squares in Y direction
</ParamField>

<ParamField path="include_diagonals" type="bool" default="False">
  Use 8-connected (True) vs 4-connected (False)
</ParamField>

**Returns:**

List of neighboring grid square indices


```python
stanza.routines.builtins.dqd_search.grid_search.get_grid_distance(
    idx1: int,
    idx2: int,
    n_x: int,
    n_y: int
) -> int
```

Calculate Manhattan distance between two grid squares.

Manhattan distance is the sum of horizontal and vertical distances,
appropriate for grid topology where moves are limited to cardinal directions.

**Parameters:**

<ParamField path="idx1" type="int">
  Linear index of first square
</ParamField>

<ParamField path="idx2" type="int">
  Linear index of second square
</ParamField>

<ParamField path="n_x" type="int">
  Number of squares in X direction
</ParamField>

<ParamField path="n_y" type="int">
  Number of squares in Y direction
</ParamField>

**Returns:**

Manhattan distance (sum of horizontal and vertical distance)


```python
stanza.routines.builtins.dqd_search.grid_search.select_weighted_by_score(
    candidates: list[int],
    successful_squares: list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare],
    n_x: int,
    n_y: int,
    distance_decay: float = DISTANCE_DECAY_FACTOR
) -> int
```

Select candidate weighted by proximity and score of successful squares.

DQDs cluster in voltage space, so weight candidates by nearby high scores.

**Parameters:**

<ParamField path="candidates" type="list[int]">
  Candidate square indices
</ParamField>

<ParamField path="successful_squares" type="list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare]">
  High-scoring squares
</ParamField>

<ParamField path="n_x" type="int">
  Number of squares in X direction
</ParamField>

<ParamField path="n_y" type="int">
  Number of squares in Y direction
</ParamField>

<ParamField path="distance_decay" type="float" default="DISTANCE_DECAY_FACTOR">
  Weight decay per unit distance
</ParamField>

**Returns:**

Selected square index


```python
stanza.routines.builtins.dqd_search.grid_search.select_next_square(
    visited: list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare],
    dqd_squares: list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare],
    n_x: int,
    n_y: int,
    include_diagonals: bool,
    score_threshold: float = HIGH_SCORE_THRESHOLD
) -> int | None
```

Select next grid square using hierarchical priority strategy.

Priority: DQD neighbors > high-score neighbors > random unvisited.

**Parameters:**

<ParamField path="visited" type="list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare]">
  Already-visited squares
</ParamField>

<ParamField path="dqd_squares" type="list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare]">
  Confirmed DQD squares
</ParamField>

<ParamField path="n_x" type="int">
  Number of squares in X direction
</ParamField>

<ParamField path="n_y" type="int">
  Number of squares in Y direction
</ParamField>

<ParamField path="include_diagonals" type="bool">
  Use 8-connected vs 4-connected neighborhoods
</ParamField>

<ParamField path="score_threshold" type="float" default="HIGH_SCORE_THRESHOLD">
  Minimum score for high-scoring squares
</ParamField>

**Returns:**

Grid index to sample next, or None if all visited