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



## Module Contents

### Classes

| Name | Description |
|------|-------------|
| [`Device`](#stanzadevicedevice) | Interface for controlling quantum devices through voltage sweeps and current measurements. |

### API

```python
class stanza.device.Device(name: str, device_config: stanza.models.DeviceConfig, channel_configs: dict[str, stanza.base.channels.ChannelConfig], control_instrument: typing.Any | None, measurement_instrument: typing.Any | None, breakout_box_instrument: typing.Any | None = None)
```

Interface for controlling quantum devices through voltage sweeps and current measurements.

The Device class provides a high-level abstraction for interacting with quantum
devices by coordinating between control instruments (for setting voltages) and
measurement instruments (for reading currents). It supports various sweep patterns
(1D, 2D, N-dimensional) and manages the mapping between logical pad names and
physical instrument channels.

Attributes:
    name: Human-readable name of the device
    device_config: Configuration object containing device specifications
    channel_configs: Dictionary mapping pad names to their channel configurations
    control_instrument: Instrument used for setting voltages (must implement ControlInstrument protocol)
    measurement_instrument: Instrument used for measuring currents (must implement MeasurementInstrument protocol)

The class distinguishes between different pad types (gates vs contacts) and
electrode types (e.g., BARRIER, PLUNGER for gates; SOURCE, DRAIN for contacts),
providing convenient properties and methods for filtering and accessing specific
electrodes based on their characteristics.

```python
breakout_lines: list[str]
```

List of all breakout box line names in the device.


```python
gates: list[str]
```

List of all gate pad names in the device.


```python
contacts: list[str]
```

List of all contact pad names in the device.


```python
gpios: list[str]
```

List of all gpio pad names in the device.


```python
control_gates: list[str]
```

List of gate pads that have a control channel configured.


```python
control_contacts: list[str]
```

List of contact pads that have a control channel configured.


```python
control_gpios: list[str]
```

List of gpio pads that have a control channel configured.


```python
measurement_gates: list[str]
```

List of gate pads that have a measurement channel configured.


```python
measurement_contacts: list[str]
```

List of contact pads that have a measurement channel configured.


```python
group_names() -> list[str]
```

List of configured device group names.


```python
_get_group(group_name: str) -> stanza.models.DeviceGroup
```


```python
group_gates(group_name: str) -> list[str]
```

List of gate pad names associated with a specific group.


```python
group_contacts(group_name: str) -> list[str]
```

List of contact pad names associated with a specific group.


```python
group_gpios(group_name: str) -> list[str]
```

List of GPIO pad names associated with a specific group.


```python
filter_by_group(group_name: str) -> dict[str, stanza.base.channels.ChannelConfig]
```

Get filtered channel configurations for electrodes in the specified group.

This method returns a dictionary of channel configurations containing only the pads
(gates, contacts, gpios) that belong to the specified group. This is useful for
getting configuration information about a subset of device pads without creating
a separate device instance.

Filtering behavior:
- Gates: Always explicitly filtered (only listed gates included)
- Contacts: If specified in group, only those contacts. If omitted, ALL device contacts.
- GPIOs: If specified in group, only those GPIOs. If omitted, ALL device GPIOs.

**Parameters:**

<ParamField path="group_name" type="str">
  Name of the group to filter by. Must exist in device_config.groups.
</ParamField>

**Returns:**

Dictionary mapping pad names to their channel configurations, filtered to
include only pads in the specified group.

**Raises:**

DeviceError: If the specified group does not exist.
Example:
>>> # Group with explicit GPIO list
>>> control_configs = device.filter_by_group("control")
>>> control_pads = list(control_configs.keys())
>>> device.jump(\{pad: 0.5 for pad in control_pads\})
>>> # Check what pads are in a group
>>> sensor_configs = device.filter_by_group("sensor")
>>> print(f"Sensor pads: \{list(sensor_configs.keys())\}")


```python
get_gates_by_type(gate_type: str | stanza.models.GateType) -> list[str]
```

Get the gate electrodes of a given type.

Filters all gate channels in the device to return only those matching
the specified gate type (e.g., BARRIER, PLUNGER, SCREENING).

**Parameters:**

<ParamField path="gate_type" type="str | stanza.models.GateType">
  The type of gate electrodes to retrieve. Can be provided
</ParamField>

**Returns:**

List of gate electrode names matching the specified type. Returns
an empty list if no gates of the specified type are found.


```python
get_contacts_by_type(contact_type: str | stanza.models.ContactType) -> list[str]
```

Get the contact electrodes of a given type.

Filters all contact channels in the device to return only those matching
the specified contact type (e.g., SOURCE, DRAIN, RESERVOIR).

**Parameters:**

<ParamField path="contact_type" type="str | stanza.models.ContactType">
  The type of contact electrodes to retrieve. Can be
</ParamField>

**Returns:**

List of contact electrode names matching the specified type. Returns
an empty list if no contacts of the specified type are found.


```python
is_configured() -> bool
```

Check if both instruments are configured.

Verifies that the device has both a control instrument (for setting
voltages) and a measurement instrument (for reading currents) properly
configured and available for use.

**Returns:**

True if both control_instrument and measurement_instrument are not
None, False otherwise.


```python
_jump(
    voltage: float,
    pad: str,
    wait_for_settling: bool = False
) -> None
```

Set the voltage of a single gate


```python
jump(
    pad_voltages: dict[str, float], wait_for_settling: bool = False
) -> None
```

Set the voltages of the device.

**Parameters:**

<ParamField path="pad_voltages" type="dict[str, float]">
  A dictionary of pads and their voltages.
</ParamField>

<ParamField path="wait_for_settling" type="bool" default="False">
  Whether to wait for the device to settle after setting the voltages.
</ParamField>

**Raises:**

DeviceError: If the control instrument is not configured.


```python
_measure(pad: str) -> float
```

Measure the current of a single gate


```python
measure(pad: str | list[str]) -> float | list[float]
```

Measure the current of the device.

Performs current measurement on one or more pads using the measurement
instrument. For multiple pads, attempts to use the instrument's batch
measurement capability if available, otherwise measures sequentially.

**Parameters:**

<ParamField path="pad" type="str | list[str]">
  Either a single pad name or a list of pad names to measure.
</ParamField>

**Returns:**

If a single pad name is provided, returns a single float current value.
If a list of pad names is provided, returns a list of float current values
corresponding to each pad in the input list.

**Raises:**

DeviceError: If the measurement instrument is not configured, if a
specified pad is not found in channel configs, or if a pad has
no measure channel configured.


```python
_check(pad: str) -> float
```

Check the current voltage of a single gate electrode.


```python
check(pad: str | list[str]) -> float | list[float]
```

Check the current voltage of the device.

Reads the current voltage setting from one or more pads using the control
instrument. This returns the voltage that the control instrument believes
it has set, not a measured value from the device itself.

**Parameters:**

<ParamField path="pad" type="str | list[str]">
  Either a single pad name or a list of pad names to check.
</ParamField>

**Returns:**

If a single pad name is provided, returns a single float voltage value.
If a list of pad names is provided, returns a list of float voltage values
corresponding to each pad in the input list.

**Raises:**

DeviceError: If the control instrument is not configured, if a
specified pad is not found in channel configs, or if a pad has
no control channel configured.


```python
sweep_1d(
    gate_electrode: str,
    voltages: list[float],
    measure_electrode: str,
    session: stanza.logger.session.LoggerSession | None = None
) -> tuple[list[float], list[float]]
```

Sweep a single gate electrode and measure the current of a single contact electrode.

Performs a 1D voltage sweep by stepping through a list of voltages on a
specified gate electrode while measuring the current through a contact
electrode at each step. Optionally logs the sweep data to a session.

**Parameters:**

<ParamField path="gate_electrode" type="str">
  Name of the gate electrode to sweep
</ParamField>

<ParamField path="voltages" type="list[float]">
  List of voltage values to apply to the gate electrode
</ParamField>

<ParamField path="measure_electrode" type="str">
  Name of the contact electrode to measure current from
</ParamField>

<ParamField path="session" type="stanza.logger.session.LoggerSession | None">
  Optional LoggerSession to log the sweep data. If provided,
</ParamField>

**Returns:**

Tuple of (voltage_measurements, current_measurements) where:
- voltage_measurements: List of actual voltages read from the gate
- current_measurements: List of measured current values at each voltage


```python
sweep_2d(
    gate_1: str,
    voltages_1: list[float],
    gate_2: str,
    voltages_2: list[float],
    measure_electrode: str,
    session: stanza.logger.session.LoggerSession | None = None
) -> tuple[list[list[float]], list[float]]
```

Sweep two gate electrodes and measure the current of a single contact electrode.

Performs a 2D voltage sweep by iterating through all combinations of
voltages on two gate electrodes while measuring current through a contact
electrode. The sweep iterates through gate_1 voltages in the outer loop
and gate_2 voltages in the inner loop.

**Parameters:**

<ParamField path="gate_1" type="str">
  Name of the first gate electrode to sweep
</ParamField>

<ParamField path="voltages_1" type="list[float]">
  List of voltage values for the first gate electrode
</ParamField>

<ParamField path="gate_2" type="str">
  Name of the second gate electrode to sweep
</ParamField>

<ParamField path="voltages_2" type="list[float]">
  List of voltage values for the second gate electrode
</ParamField>

<ParamField path="measure_electrode" type="str">
  Name of the contact electrode to measure current from
</ParamField>

<ParamField path="session" type="stanza.logger.session.LoggerSession | None">
  Optional LoggerSession to log the sweep data. If provided,
</ParamField>

**Returns:**

Tuple of (voltage_measurements, current_measurements) where:
- voltage_measurements: List of [gate_1_voltage, gate_2_voltage] pairs
- current_measurements: List of measured current values at each voltage pair


```python
sweep_all(
    voltages: list[float],
    measure_electrode: str,
    session: stanza.logger.session.LoggerSession | None = None
) -> tuple[list[list[float]], list[float]]
```

Sweep all gate electrodes and measure the current of a single contact electrode.

Performs a voltage sweep by setting all control gates to the same voltage
at each step, while measuring current through a contact electrode. This is
useful for characterizing device response to overall gate bias.

**Parameters:**

<ParamField path="voltages" type="list[float]">
  List of voltage values to apply to all control gates simultaneously
</ParamField>

<ParamField path="measure_electrode" type="str">
  Name of the contact electrode to measure current from
</ParamField>

<ParamField path="session" type="stanza.logger.session.LoggerSession | None">
  Optional LoggerSession to log the sweep data. If provided,
</ParamField>

**Returns:**

Tuple of (voltage_measurements, current_measurements) where:
- voltage_measurements: List of lists, each containing voltage values for
all control gates at that sweep step
- current_measurements: List of measured current values at each voltage


```python
sweep_nd(
    gate_electrodes: list[str],
    voltages: list[list[float]],
    measure_electrode: str,
    session: stanza.logger.session.LoggerSession | None = None
) -> tuple[list[list[float]], list[float]]
```

Sweep multiple gate electrodes and measure the current of a single contact electrode.

Performs an N-dimensional voltage sweep where each specified gate can have
a different voltage at each sweep step. This provides maximum flexibility
for arbitrary multi-gate sweeps and trajectories through voltage space.

**Parameters:**

<ParamField path="gate_electrodes" type="list[str]">
  List of gate electrode names to sweep
</ParamField>

<ParamField path="voltages" type="list[list[float]]">
  List of voltage lists, where each inner list contains the
</ParamField>

<ParamField path="measure_electrode" type="str">
  Name of the contact electrode to measure current from
</ParamField>

<ParamField path="session" type="stanza.logger.session.LoggerSession | None">
  Optional LoggerSession to log the sweep data. If provided,
</ParamField>

**Returns:**

Tuple of (voltage_measurements, current_measurements) where:
- voltage_measurements: List of lists, each containing the actual voltage
values read from each gate at that sweep step
- current_measurements: List of measured current values at each voltage combination


```python
zero(type: str | stanza.models.PadType = PadType.ALL) -> None
```

Set all controllable gates and/or controllable contacts to 0V.

Safely brings specified electrodes to ground voltage (0V) with settling
time and verification. This is typically used for device initialization
or safe shutdown.

**Parameters:**

<ParamField path="type" type="str | stanza.models.PadType" default="PadType.ALL">
  Specifies which pads to zero. Options are:
</ParamField>

**Raises:**

DeviceError: If an invalid pad type is provided, or if any pad fails
to reach 0V within tolerance (1e-6V) after the operation.


```python
ground_breakout_lines() -> None
```

Ground all breakout box lines.

This method sets all breakout box lines to a grounded state.

**Raises:**

DeviceError: If the breakout box instrument is not configured.


```python
unground_breakout_lines() -> None
```

Unground all breakout box lines.

This method sets all breakout box lines to an ungrounded state.

**Raises:**

DeviceError: If the breakout box instrument is not configured.


```python
connect_breakout_lines() -> None
```

Connect all breakout box lines.

This method connects all breakout box lines to the instrument.

**Raises:**

DeviceError: If the breakout box instrument is not configured.


```python
disconnect_breakout_lines() -> None
```

Disconnect all breakout box lines.

This method disconnects all breakout box lines from the instrument.

**Raises:**

DeviceError: If the breakout box instrument is not configured.


```python
_get_lines_by_channel(has_channel: collections.abc.Callable[[stanza.base.channels.ChannelConfig], bool]) -> list[str]
```

Filter breakout box lines by channel type.

This method filters the breakout box lines by the channel type.

**Parameters:**

<ParamField path="has_channel" type="collections.abc.Callable[[stanza.base.channels.ChannelConfig], bool]">
  A callable that returns True if the channel has the specified type.
</ParamField>

**Returns:**

A list of breakout box lines that have the specified channel type.


```python
_apply_breakout_connection(
    lines: list[str],
    instrument: stanza.base.protocols.ControlInstrument | stanza.base.protocols.MeasurementInstrument | None,
    instrument_name: str,
    connection_method: collections.abc.Callable[[list[str], int], None]
) -> None
```

Apply connection method to a list of lines for a specific instrument.

This method applies the connection method to a list of lines for a specific instrument.

**Parameters:**

<ParamField path="lines" type="list[str]">
  A list of breakout box lines to apply the connection method to.
</ParamField>

<ParamField path="instrument" type="stanza.base.protocols.ControlInstrument | stanza.base.protocols.MeasurementInstrument | None">
  The instrument to apply the connection method to.
</ParamField>

<ParamField path="instrument_name" type="str">
  The name of the instrument.
</ParamField>

<ParamField path="connection_method" type="collections.abc.Callable[[list[str], int], None]">
  The connection method to apply.
</ParamField>


```python
_set_breakout_connection(connection_method: collections.abc.Callable[[list[str], int], None]) -> None
```

Set breakout box connection state for all lines, grouped by instrument type.

This method sets the breakout box connection state for all lines, grouped by instrument type.

**Parameters:**

<ParamField path="connection_method" type="collections.abc.Callable[[list[str], int], None]">
  The connection method to apply to the control and measurement instruments.
</ParamField>