> 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.utils



## Module Contents

### Classes

| Name | Description |
|------|-------------|
| [`SweepGeometry`](#stanzaroutinesbuiltinsdqd_searchutilssweepgeometry) | Random sweep configuration in 2D voltage space. |
| [`GateIndices`](#stanzaroutinesbuiltinsdqd_searchutilsgateindices) | Indices for different gate types in the voltage array. |

### Functions

| Name | Description |
|------|-------------|
| [`build_gate_indices`](#stanzaroutinesbuiltinsdqd_searchutilsbuild_gate_indices) | Extract indices for each gate type from the gate list. |
| [`generate_linear_sweep`](#stanzaroutinesbuiltinsdqd_searchutilsgenerate_linear_sweep) | Generate evenly-spaced points along a line segment. |
| [`generate_random_sweep`](#stanzaroutinesbuiltinsdqd_searchutilsgenerate_random_sweep) | Generate random sweep that stays within bounds. |
| [`build_full_voltages`](#stanzaroutinesbuiltinsdqd_searchutilsbuild_full_voltages) | Construct full voltage array from plunger sweep voltages. |
| [`compute_peak_spacings`](#stanzaroutinesbuiltinsdqd_searchutilscompute_peak_spacings) | Calculate inter-peak spacings in voltage space. |
| [`get_global_turn_on_voltage`](#stanzaroutinesbuiltinsdqd_searchutilsget_global_turn_on_voltage) | Get global turn-on voltage from results. |
| [`_get_gate_characterization`](#stanzaroutinesbuiltinsdqd_searchutils_get_gate_characterization) | Get combined gate characterization results. |
| [`get_voltages`](#stanzaroutinesbuiltinsdqd_searchutilsget_voltages) | Get voltages for all gates. |
| [`get_plunger_gate_bounds`](#stanzaroutinesbuiltinsdqd_searchutilsget_plunger_gate_bounds) | Get plunger bounds for all plunger gates. |
| [`get_gate_safe_bounds`](#stanzaroutinesbuiltinsdqd_searchutilsget_gate_safe_bounds) | Get safe voltage bounds. |
| [`measure_and_classify`](#stanzaroutinesbuiltinsdqd_searchutilsmeasure_and_classify) | Measure current and classify result. |
| [`log_measurement`](#stanzaroutinesbuiltinsdqd_searchutilslog_measurement) | Log measurement data to session. |
| [`log_classification`](#stanzaroutinesbuiltinsdqd_searchutilslog_classification) | Log classification result to session. |

### API

```python
class stanza.routines.builtins.dqd_search.utils.SweepGeometry
```

Random sweep configuration in 2D voltage space.

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

**Value**: `None`


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

**Value**: `None`


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

**Value**: `None`


```python
angle: float
```

**Value**: `None`


```python
total_distance: float
```

**Value**: `None`


```python
class stanza.routines.builtins.dqd_search.utils.GateIndices
```

Indices for different gate types in the voltage array.

```python
plunger: list[int]
```

**Value**: `None`


```python
reservoir: list[int]
```

**Value**: `None`


```python
barrier: list[int]
```

**Value**: `None`


```python
stanza.routines.builtins.dqd_search.utils.build_gate_indices(
    gates: list[str], device: stanza.device.Device
) -> stanza.routines.builtins.dqd_search.utils.GateIndices
```

Extract indices for each gate type from the gate list.

**Parameters:**

<ParamField path="gates" type="list[str]">
  List of gate electrode names.
</ParamField>

<ParamField path="device" type="stanza.device.Device">
  Device instance with get_gate_by_type method.
</ParamField>

**Returns:**

GateIndices with plunger, reservoir, and barrier indices.


```python
stanza.routines.builtins.dqd_search.utils.generate_linear_sweep(
    start_point: numpy.typing.NDArray[numpy.float64],
    direction: numpy.typing.NDArray[numpy.float64],
    total_sweep_dist: float,
    n_points: int
) -> numpy.typing.NDArray[numpy.float64]
```

Generate evenly-spaced points along a line segment.

**Parameters:**

<ParamField path="start_point" type="numpy.typing.NDArray[numpy.float64]">
  (d,) array with starting coordinates.
</ParamField>

<ParamField path="direction" type="numpy.typing.NDArray[numpy.float64]">
  (d,) array with normalized direction vector.
</ParamField>

<ParamField path="total_sweep_dist" type="float">
  Total sweep distance.
</ParamField>

<ParamField path="n_points" type="int">
  Number of points in the trace.
</ParamField>

**Returns:**

(n_points, d) array of coordinates along the line.


```python
stanza.routines.builtins.dqd_search.utils.generate_random_sweep(
    x_bounds: tuple[float, float],
    y_bounds: tuple[float, float],
    scale: float,
    num_points: int
) -> stanza.routines.builtins.dqd_search.utils.SweepGeometry | None
```

Generate random sweep that stays within bounds.

**Parameters:**

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

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

<ParamField path="scale" type="float">
  Voltage spacing per step.
</ParamField>

<ParamField path="num_points" type="int">
  Number of points in sweep.
</ParamField>

**Returns:**

SweepGeometry if sweep stays in bounds, None otherwise.


```python
stanza.routines.builtins.dqd_search.utils.build_full_voltages(
    sweep_voltages: numpy.typing.NDArray[numpy.float64],
    gates: list[str],
    gate_idx: stanza.routines.builtins.dqd_search.utils.GateIndices,
    transition_voltages: dict[str, float],
    saturation_voltages: dict[str, float],
    barrier_voltages: dict[str, float] | None = None
) -> numpy.typing.NDArray[numpy.float64]
```

Construct full voltage array from plunger sweep voltages.

Works with arbitrary-dimensional sweep arrays (1D, 2D, 3D, etc). Applies
fixed voltages to reservoir and barrier gates based on characterization data.

**Parameters:**

<ParamField path="sweep_voltages" type="numpy.typing.NDArray[numpy.float64]">
  (..., 2) array of plunger voltages.
</ParamField>

<ParamField path="gates" type="list[str]">
  List of all gate names.
</ParamField>

<ParamField path="gate_idx" type="stanza.routines.builtins.dqd_search.utils.GateIndices">
  Indices for each gate type.
</ParamField>

<ParamField path="transition_voltages" type="dict[str, float]">
  Transition voltages for all gates.
</ParamField>

<ParamField path="saturation_voltages" type="dict[str, float]">
  Saturation voltages for all gates.
</ParamField>

<ParamField path="barrier_voltages" type="dict[str, float] | None">
  Optional explicit barrier voltages (overrides defaults).
</ParamField>

**Returns:**

(..., num_gates) array of voltages.


```python
stanza.routines.builtins.dqd_search.utils.compute_peak_spacings(
    peak_indices: numpy.typing.NDArray[numpy.int64],
    sweep_voltages: numpy.typing.NDArray[numpy.float64]
) -> numpy.typing.NDArray[numpy.float64] | None
```

Calculate inter-peak spacings in voltage space.

**Parameters:**

<ParamField path="peak_indices" type="numpy.typing.NDArray[numpy.int64]">
  Indices of detected peaks.
</ParamField>

<ParamField path="sweep_voltages" type="numpy.typing.NDArray[numpy.float64]">
  (num_points, 2) array of voltage coordinates.
</ParamField>

**Returns:**

Array of inter-peak spacings, or None if fewer than 3 peaks.


```python
stanza.routines.builtins.dqd_search.utils.get_global_turn_on_voltage(results: stanza.registry.ResultsRegistry) -> float
```

Get global turn-on voltage from results.

**Parameters:**

<ParamField path="results" type="stanza.registry.ResultsRegistry">
  ResultsRegistry instance.
</ParamField>

**Returns:**

Global turn-on voltage.

**Raises:**

ValueError: If global accumulation results not found.


```python
stanza.routines.builtins.dqd_search.utils._get_gate_characterization(results: stanza.registry.ResultsRegistry) -> dict[str, dict[str, float]]
```

Get combined gate characterization results.

**Parameters:**

<ParamField path="results" type="stanza.registry.ResultsRegistry">
  ResultsRegistry instance.
</ParamField>

**Returns:**

Combined dict of reservoir and finger gate characterization.

**Raises:**

ValueError: If characterization results not found.


```python
stanza.routines.builtins.dqd_search.utils.get_voltages(
    gates: list[str],
    key: str,
    results: stanza.registry.ResultsRegistry
) -> dict[str, float]
```

Get voltages for all gates.

**Parameters:**

<ParamField path="gates" type="list[str]">
  List of gate names.
</ParamField>

<ParamField path="key" type="str">
  Key to extract ("saturation_voltage", "cutoff_voltage", or "transition_voltage").
</ParamField>

<ParamField path="results" type="stanza.registry.ResultsRegistry">
  ResultsRegistry instance.
</ParamField>

**Returns:**

Dict mapping gate names to voltages.


```python
stanza.routines.builtins.dqd_search.utils.get_plunger_gate_bounds(
    plunger_gates: list[str], results: stanza.registry.ResultsRegistry
) -> dict[str, tuple[float, float]]
```

Get plunger bounds for all plunger gates.

**Parameters:**

<ParamField path="plunger_gates" type="list[str]">
  List of plunger gate names.
</ParamField>

<ParamField path="results" type="stanza.registry.ResultsRegistry">
  ResultsRegistry instance.
</ParamField>

**Returns:**

Dict mapping plunger gate names to (min, max) voltage bounds.


```python
stanza.routines.builtins.dqd_search.utils.get_gate_safe_bounds(results: stanza.registry.ResultsRegistry) -> tuple[float, float]
```

Get safe voltage bounds.

**Parameters:**

<ParamField path="results" type="stanza.registry.ResultsRegistry">
  ResultsRegistry instance.
</ParamField>

**Returns:**

(min, max) safe voltage bounds.

**Raises:**

ValueError: If leakage test results not found.


```python
stanza.routines.builtins.dqd_search.utils.measure_and_classify(
    device: stanza.device.Device,
    client: conductorquantum.base_client.BaseConductorQuantum,
    gates: list[str],
    voltages: numpy.typing.NDArray[numpy.float64],
    measure_electrode: str,
    model: str,
    reshape: tuple[int, ...] | None = None
) -> tuple[numpy.typing.NDArray[numpy.float64], bool, float]
```

Measure current and classify result.

Performs device measurement sweep and classifies the resulting current data
using a specified ML model.

**Parameters:**

<ParamField path="device" type="stanza.device.Device">
  Device instance.
</ParamField>

<ParamField path="client" type="conductorquantum.base_client.BaseConductorQuantum">
  Models client.
</ParamField>

<ParamField path="gates" type="list[str]">
  Gate electrode names.
</ParamField>

<ParamField path="voltages" type="numpy.typing.NDArray[numpy.float64]">
  Voltage array.
</ParamField>

<ParamField path="measure_electrode" type="str">
  Current measurement electrode.
</ParamField>

<ParamField path="model" type="str">
  Classification model name.
</ParamField>

<ParamField path="reshape" type="tuple[int, ...] | None">
  Optional reshape dimensions for output.
</ParamField>

**Returns:**

Tuple of (currents, classification, score).


```python
stanza.routines.builtins.dqd_search.utils.log_measurement(
    session: stanza.logger.session.LoggerSession | None,
    name: str,
    measurement_id: str,
    data: dict[str, typing.Any],
    metadata: dict[str, typing.Any],
    routine_name: str
) -> None
```

Log measurement data to session.

**Parameters:**

<ParamField path="session" type="stanza.logger.session.LoggerSession | None">
  Logger session instance (optional).
</ParamField>

<ParamField path="name" type="str">
  Measurement name.
</ParamField>

<ParamField path="measurement_id" type="str">
  Unique measurement identifier.
</ParamField>

<ParamField path="data" type="dict[str, typing.Any]">
  Measurement data dict.
</ParamField>

<ParamField path="metadata" type="dict[str, typing.Any]">
  Measurement metadata dict.
</ParamField>

<ParamField path="routine_name" type="str">
  Name of the routine performing the measurement.
</ParamField>


```python
stanza.routines.builtins.dqd_search.utils.log_classification(
    session: stanza.logger.session.LoggerSession | None,
    measurement_id: str,
    measurement_type: str,
    classification: bool,
    score: float,
    metadata: dict[str, typing.Any],
    routine_name: str
) -> None
```

Log classification result to session.

**Parameters:**

<ParamField path="session" type="stanza.logger.session.LoggerSession | None">
  Logger session instance (optional).
</ParamField>

<ParamField path="measurement_id" type="str">
  Unique measurement identifier.
</ParamField>

<ParamField path="measurement_type" type="str">
  Type of measurement being classified.
</ParamField>

<ParamField path="classification" type="bool">
  Classification result (True/False).
</ParamField>

<ParamField path="score" type="float">
  Classification confidence score.
</ParamField>

<ParamField path="metadata" type="dict[str, typing.Any]">
  Classification metadata dict.
</ParamField>

<ParamField path="routine_name" type="str">
  Name of the routine performing the classification.
</ParamField>