stanza.routines.builtins.dqd_search.grid_search | Conductor Quantum

Grid-based search utilities for DQD discovery.

Module Contents

Classes

Name	Description
`SearchSquare`	Results from measuring a single grid square.

Functions

Name	Description
`generate_grid_corners`	Generate grid of square corners covering the voltage space.
`generate_diagonal_sweep`	Generate diagonal line through a square.
`generate_2d_sweep`	Generate 2D grid sweep over a square.
`get_neighboring_squares`	Get neighboring grid square indices.
`get_grid_distance`	Calculate Manhattan distance between two grid squares.
`select_weighted_by_score`	Select candidate weighted by proximity and score of successful squares.
`select_next_square`	Select next grid square using hierarchical priority strategy.

Data

HIGH_SCORE_THRESHOLD GRID_SQUARE_MULTIPLIER DISTANCE_DECAY_FACTOR

API

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

Value: 1.5

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

Value: None

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

Value: 1.0

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

Results from measuring a single grid square.

grid_idx: int

Value: None

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

Value: None

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

Value: None

current_trace_score: float

Value: None

current_trace_classification: bool

Value: None

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

Value: None

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

Value: None

low_res_csd_score: float

Value: None

low_res_csd_classification: bool

Value: None

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

Value: None

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

Value: None

high_res_csd_score: float

Value: None

high_res_csd_classification: bool

Value: None

total_score: float

is_dqd: bool

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

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

Convert to JSON-serializable dictionary.

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:

plunger_x_bounds

tuple[float, float]

(min, max) voltage bounds for X plunger

plunger_y_bounds

tuple[float, float]

(min, max) voltage bounds for Y plunger

square_size

float

Side length of each grid square

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

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:

corner

numpy.typing.NDArray[numpy.float64]

(2,) bottom-left corner coordinates

size

float

Square side length

num_points

int

Number of points along diagonal

Returns:

(num_points, 2) array of voltage coordinates

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:

corner

numpy.typing.NDArray[numpy.float64]

(2,) bottom-left corner coordinates

size

float

Square side length

num_points

int

Number of points per axis

Returns:

(num_points, num_points, 2) array of voltage coordinates

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:

grid_idx

int

Linear index of current grid square

n_x

int

Number of grid squares in X direction

n_y

int

Number of grid squares in Y direction

include_diagonals

boolDefaults to False

Use 8-connected (True) vs 4-connected (False)

Returns:

List of neighboring grid square indices

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:

idx1

int

Linear index of first square

idx2

int

Linear index of second square

n_x

int

Number of squares in X direction

n_y

int

Number of squares in Y direction

Returns:

Manhattan distance (sum of horizontal and vertical distance)

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:

candidates

list[int]

Candidate square indices

successful_squares

list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare]

High-scoring squares

n_x

int

Number of squares in X direction

n_y

int

Number of squares in Y direction

distance_decay

floatDefaults to DISTANCE_DECAY_FACTOR

Weight decay per unit distance

Returns:

Selected square index

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:

visited

list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare]

Already-visited squares

dqd_squares

list[stanza.routines.builtins.dqd_search.grid_search.SearchSquare]

Confirmed DQD squares

n_x

int

Number of squares in X direction

n_y

int

Number of squares in Y direction

include_diagonals

bool

Use 8-connected vs 4-connected neighborhoods

score_threshold

floatDefaults to HIGH_SCORE_THRESHOLD

Minimum score for high-scoring squares

Returns:

Grid index to sample next, or None if all visited