Core Concepts

Device Groups

Groups: Organizing Pads for Isolated Testing

Groups let you define logical subsets of your device for independent characterization and control. This is essential for devices with multiple quantum dots, charge sensors, or when you want to test different regions separately.

Creating Groups

Define groups by specifying which pads belong to each group:

1name: "Sample Device"
2
3gates:
4  # Control region gates (G1-G5)
5  G1: {type: BARRIER, control_channel: 3, v_lower_bound: -3.0, v_upper_bound: 3.0}
6  G2: {type: PLUNGER, control_channel: 4, v_lower_bound: -3.0, v_upper_bound: 3.0}
7  G3: {type: BARRIER, control_channel: 5, v_lower_bound: -3.0, v_upper_bound: 3.0}
8  G4: {type: PLUNGER, control_channel: 6, v_lower_bound: -3.0, v_upper_bound: 3.0}
9  G5: {type: BARRIER, control_channel: 7, v_lower_bound: -3.0, v_upper_bound: 3.0}
10
11  # Sensor region gates (G6-G8)
12  G6: {type: BARRIER, control_channel: 8, v_lower_bound: -1.5, v_upper_bound: 1.5}
13  G7: {type: PLUNGER, control_channel: 9, v_lower_bound: -1.5, v_upper_bound: 1.5}
14  G8: {type: BARRIER, control_channel: 10, v_lower_bound: -1.0, v_upper_bound: 1.0}
15
16  # Shared reservoir gates
17  G9: {type: RESERVOIR, control_channel: 11, v_lower_bound: -3.0, v_upper_bound: 3.0}
18  G10: {type: RESERVOIR, control_channel: 12, v_lower_bound: -3.0, v_upper_bound: 3.0}
19
20contacts:
21  IN: {type: SOURCE, control_channel: 1, measure_channel: 1, v_lower_bound: -3.0, v_upper_bound: 3.0}
22  OUT: {type: DRAIN, control_channel: 2, measure_channel: 2, v_lower_bound: -3.0, v_upper_bound: 3.0}
23
24gpios:
25  MUX1: {type: OUTPUT, control_channel: 30, v_lower_bound: 0.0, v_upper_bound: 5.0}
26  MUX2: {type: OUTPUT, control_channel: 31, v_lower_bound: 0.0, v_upper_bound: 5.0}
27  SENSOR_ENABLE: {type: OUTPUT, control_channel: 32, v_lower_bound: 0.0, v_upper_bound: 5.0}
28
29groups:
30  control:
31    name: "Control DUT"
32    gates: [G1, G2, G3, G4, G5, G9, G10]
33    contacts: [IN, OUT]
34    gpios: [MUX1]
35
36  sensor:
37    name: "Charge Sensor"
38    gates: [G6, G7, G8, G9, G10]
39    contacts: [IN, OUT]
40    gpios: [MUX2, SENSOR_ENABLE]

Use groups in Python to create filtered device views:

1from stanza.utils import device_from_yaml
2
3device = device_from_yaml("device.yaml")
4
5# Filter to control region
6control_device = device.filter_by_group("control")
7print(control_device.gates)     # ['G1', 'G2', 'G3', 'G4', 'G5', 'G9', 'G10']
8print(control_device.contacts)  # ['IN', 'OUT']
9print(control_device.gpios)     # ['MUX1']
10
11# Filter to sensor region
12sensor_device = device.filter_by_group("sensor")
13print(sensor_device.gates)      # ['G6', 'G7', 'G8', 'G9', 'G10']
14print(sensor_device.contacts)   # ['IN', 'OUT']
15print(sensor_device.gpios)      # ['MUX2', 'SENSOR_ENABLE']

Gate Sharing Rules

Critical constraint: Only RESERVOIR gates can be shared between groups. Other gate types cannot be shared.

In the example above, notice that both the control and sensor groups include gates G9 and G10:

1gates:
2  G9: {type: RESERVOIR, ...}   # Shared reservoir
3  G10: {type: RESERVOIR, ...}  # Shared reservoir
4
5groups:
6  control:
7    gates: [G1, G2, G3, G4, G5, G9, G10]  # Includes G9, G10
8
9  sensor:
10    gates: [G6, G7, G8, G9, G10]          # Also includes G9, G10 - OK!

This is valid because G9 and G10 are RESERVOIR gates. If you tried to share a PLUNGER or BARRIER gate:

1# INVALID - PLUNGER shared between groups
2gates:
3  G2: {type: PLUNGER, ...}
4
5groups:
6  control: {gates: [G2]}
7  sensor: {gates: [G2]}  # ERROR: PLUNGER cannot be shared

You would get an error: Gate 'G2' is assigned to multiple groups: control, sensor. Only RESERVOIR gates can be shared between groups.

Rationale: RESERVOIR gates are voltage references designed to be shared. Other gate types (PLUNGER and BARRIER) control individual quantum dots and sharing them can cause interference or device damage.

Contacts and GPIOs can be freely shared between groups with no restrictions. In the example, both groups share the IN and OUT contacts.

What Happens When You Omit Pads

Stanza uses conditional filtering to determine which pads are accessible when you filter by group. The behavior depends on whether you omit, explicitly list, or use an empty list:

Pad TypeOmitted from GroupEmpty List []Explicit List
GatesNot includedNot includedONLY specified
ContactsALL includedNot includedONLY specified
GPIOsALL includedNot includedONLY specified

Let’s explore three variations of our Sample Device groups to see how this works.

Variation 1: Explicit Lists (Precise Control)

This is what we saw in the Sample Device - each group explicitly specifies its pads:

1groups:
2  control:
3    gates: [G1, G2, G3, G4, G5, G9, G10]
4    contacts: [IN, OUT]                    # Explicit: only these contacts
5    gpios: [MUX1]                          # Explicit: only MUX1
6
7  sensor:
8    gates: [G6, G7, G8, G9, G10]
9    contacts: [IN, OUT]                    # Explicit: only these contacts
10    gpios: [MUX2, SENSOR_ENABLE]           # Explicit: only these GPIOs

Result: Each group gets exactly what’s listed. The control group can access MUX1 but not MUX2 or SENSOR_ENABLE. The sensor group can access MUX2 and SENSOR_ENABLE but not MUX1.

Variation 2: Omit GPIOs (Share All Infrastructure)

If we want both groups to access all GPIOs, we can omit the gpios field:

1groups:
2  control:
3    gates: [G1, G2, G3, G4, G5, G9, G10]
4    contacts: [IN, OUT]
5    # gpios omitted - gets ALL GPIOs: [MUX1, MUX2, SENSOR_ENABLE]
6
7  sensor:
8    gates: [G6, G7, G8, G9, G10]
9    contacts: [IN, OUT]
10    # gpios omitted - gets ALL GPIOs: [MUX1, MUX2, SENSOR_ENABLE]

Result: Both groups can now access all GPIO pins. This is useful when you want maximum flexibility or have shared infrastructure like power supplies that every group needs.

Variation 3: Empty Lists (Restricted Access)

If we want to restrict the sensor group to gate-only testing, we can use empty lists:

1groups:
2  control:
3    gates: [G1, G2, G3, G4, G5, G9, G10]
4    contacts: [IN, OUT]
5    gpios: [MUX1]
6
7  sensor:
8    gates: [G6, G7, G8, G9, G10]
9    contacts: []  # Explicit empty: NO contacts accessible
10    gpios: []     # Explicit empty: NO GPIOs accessible

Result: The control group works normally, but the sensor group can only control its gates (G6-G8, G9, G10) without any ability to measure current or control GPIO pins. Useful for isolated voltage sweeps without measurement.