Using Coulomb Diamond Models

Installation

We recommend using pip, poetry, or uv to install the package.

$pip install conductorquantum

Authentication

The SDK requires an API key for authentication. Sign in and create a new API key. Remember, your API key is your access secret—keep it safe with environment variables.

Using environment variables:

Python
1from dotenv import load_dotenv
2import os
3from conductorquantum import ConductorQuantum
4
5# Load API key from .env file
6load_dotenv()
7TOKEN = os.getenv("CONDUCTOR_API_KEY")
8
9# Initialize client
10client = ConductorQuantum(token=TOKEN)

Or provide the API key directly:

Python
1from conductorquantum import ConductorQuantum
2
3# Initialize client with API key
4client = ConductorQuantum(token="YOUR_API_KEY")

Usage Examples

Using the Coulomb Diamond Segmenter v0

The Coulomb Diamond Segmenter is a binary segmentation model that segments a given conductance measurement grid into coulomb diamond regions.

You can download an example file to follow along with the example:

Python
1from dotenv import load_dotenv
2import os
3import numpy as np
4from conductorquantum import ConductorQuantum
5
6
7# Load API key from .env file
8load_dotenv()
9TOKEN = os.getenv("CONDUCTOR_API_KEY")
10
11# Initialize client
12client = ConductorQuantum(token=TOKEN)
13
14# Load Coulomb Diamond Conductance Grid data
15data = np.load("coulomb-diamond-segmenter-v0.npy") # shape (n, m)
16
17# Segment the Coulomb Diamond Conductance Grid
18result = client.models.execute(
19 model="coulomb-diamond-segmenter-v0",
20 data=data
21)
22
23# Access the binary segmentation mask result
24segmentation_mask = result.output["segmentation"]
25segmentation_mask_array = np.array(segmentation_mask)
26
27# Get non-zero indices: assume shape is (1, H, W)
28nonzero_coords = np.argwhere(segmentation_mask_array)
29coords_2d = [tuple(coord[1:]) for coord in nonzero_coords]
30
31# Format output
32summary = ", ".join(str(t) for t in coords_2d[:10])
33if len(coords_2d) > 10:
34 summary += f", ... (total {len(coords_2d)} non-zero pixels)"
35print(f"Coulomb Diamond regions at: {summary}")
Segmenter Output
1Coulomb Diamond regions at: (0, 52), (0, 53), (0, 54), (0, 55), (0, 56), (0, 57), (0, 58), (0, 59), (0, 60), (0, 61), ... (total 47046 non-zero pixels)
Coulomb Diamond Segmenter Input Data

Coulomb Diamond Segmenter v0 Input Data. (Data Source: Lennon, D., et al. Real measurement of Coulomb diamonds. 2019. Zenodo, https://doi.org/10.5281/zenodo.2559478.)

Coulomb Diamond Segmenter
Coulomb Diamond Segmenter v0 Output

Using the Coulomb Diamond Detector v0

The Coulomb Diamond Detector v0 is a model that detects Coulomb Diamond structures from a binary segmentation mask.

You can download an example file to follow along with the example:

Python
1from dotenv import load_dotenv
2import os
3import json
4import numpy as np
5from conductorquantum import ConductorQuantum
6
7
8# Load API key from .env file
9load_dotenv()
10TOKEN = os.getenv("CONDUCTOR_API_KEY")
11
12# Initialize client
13client = ConductorQuantum(token=TOKEN)
14
15# Load Coulomb Diamond Detection data
16detection_data = np.load("coulomb-diamond-detector-v0.npy") # shape (n, m)
17
18# Detect diamond structures via the Coulomb Diamond Detector
19result = client.models.execute(
20 model="coulomb-diamond-detector-v0",
21 data=detection_data
22)
23
24# Access the diamond vertices result
25diamond_vertices = result.output["diamond_vertices"]
26print(f"Diamond Vertices: {json.dumps(diamond_vertices, indent=2)}")
Detector Output
1Diamond Vertices: [
2 {
3 "left": [
4 127.83405292034149,
5 128.76852416992188
6 ],
7 "right": [
8 193.11397564411163,
9 128.75509643554688
10 ],
11 "bottom": [
12 131.53489315509796,
13 -137.0048828125
14 ],
15 "top": [
16 189.41313540935516,
17 394.52850341796875
18 ]
19 }
20]

The four diamond keys “left”, “right”, “bottom” and “top” correspond to each vertex of the detected Coulomb diamond.

Plotting the Output

Use the following script to visualize detected coulomb diamonds from the v0 model.

Python
1from matplotlib import pyplot as plt
2from matplotlib.colors import ListedColormap
3
4fig, ax = plt.subplots(figsize=(10, 10))
5
6colors = ["white", "#1f4e79"]
7cmap = ListedColormap(colors)
8
9ax.imshow(detection_data, cmap=cmap, aspect="auto", origin="lower")
10
11for i, diamond in enumerate(diamond_vertices):
12 x_coords = [
13 diamond["top"][0],
14 diamond["right"][0],
15 diamond["bottom"][0],
16 diamond["left"][0],
17 diamond["top"][0],
18 ]
19 y_coords = [
20 diamond["top"][1],
21 diamond["right"][1],
22 diamond["bottom"][1],
23 diamond["left"][1],
24 diamond["top"][1],
25 ]
26
27 if i == 0:
28 ax.plot(
29 x_coords,
30 y_coords,
31 "r--",
32 linewidth=2,
33 label="Predicted Coulomb Diamonds",
34 )
35 else:
36 ax.plot(x_coords, y_coords, "r--", linewidth=2)
37
38 center_x = (diamond["top"][0] + diamond["bottom"][0]) / 2
39 center_y = (diamond["top"][1] + diamond["bottom"][1]) / 2
40 ax.plot(center_x, center_y, "ro", markersize=6)
41
42ax.fill_between([0, 0], [0, 0], color="#1f4e79", label="Coulomb Diamond Region")
43ax.set_xlabel("Gate Voltage 1 (indices)", fontsize=12)
44ax.set_ylabel("Gate Voltage 2 (indices)", fontsize=12)
45
46plt.show()
Coulomb Diamond Detector
Coulomb Diamond Segmenter v0 ➞ Coulomb Diamond Detector v0 Output

The Coulomb Diamond Detector can detect multiple coulomb diamonds. Download the following example to try it.

Coulomb Diamond Detector
Coulomb Diamond Detector v0 Output

Using the Coulomb Diamond Detector v1

The Coulomb Diamond Detector v1 is a single-stage model that detects Coulomb diamond structures directly from raw conductance data. Unlike the v0 workflow that requires first segmenting the data with the Segmenter, the v1 Detector can be used standalone for end-to-end diamond detection.

You can download an example file to follow along with the example:

Python
1from dotenv import load_dotenv
2import os
3import json
4import numpy as np
5from conductorquantum import ConductorQuantum
6
7
8# Load API key from .env file
9load_dotenv()
10TOKEN = os.getenv("CONDUCTOR_API_KEY")
11
12# Initialize client
13client = ConductorQuantum(token=TOKEN)
14
15# Load Coulomb Diamond conductance data (raw conductance, not a binary mask)
16conductance_data = np.load("coulomb-diamond-detector-v1.npy") # shape (n, n)
17
18# Detect diamond structures directly from conductance data
19result = client.models.execute(
20 model="coulomb-diamond-detector-v1",
21 data=conductance_data
22)
23
24# Access the diamond vertices result
25diamond_vertices = result.output["diamond_vertices"]
26print(f"Diamond Vertices: {json.dumps(diamond_vertices, indent=2)}")
Detector v1 Output
1Diamond Vertices: [
2 {
3 "left": [
4 14.587324142456055,
5 63.440895080566406
6 ],
7 "right": [
8 78.04255676269531,
9 64.06403350830078
10 ],
11 "bottom": [
12 63.72412872314453,
13 32.74629592895508
14 ],
15 "top": [
16 29.360164642333984,
17 93.97402954101562
18 ]
19 },
20 {
21 "left": [
22 78.05448150634766,
23 63.42158508300781
24 ],
25 "right": [
26 132.01417541503906,
27 64.0471420288086
28 ],
29 "bottom": [
30 118.5890121459961,
31 42.59369659423828
32 ],
33 "top": [
34 92.44355010986328,
35 84.79678344726562
36 ]
37 }
38]

Plotting the Output

Use the following script to visualize detected coulomb diamonds from the v1 model.

Python
1from matplotlib import pyplot as plt
2from mpl_toolkits.axes_grid1 import make_axes_locatable
3
4fig, ax = plt.subplots(figsize=(10, 10))
5
6ax.imshow(conductance_data, cmap="Blues", aspect="equal", origin="lower")
7
8divider = make_axes_locatable(ax)
9cax = divider.append_axes("right", size="4.5%", pad=0.35)
10plt.colorbar(ax.images[0], cax=cax, label="Current (a.u.)")
11
12for i, diamond in enumerate(diamond_vertices):
13 x_coords = [
14 diamond["top"][0],
15 diamond["right"][0],
16 diamond["bottom"][0],
17 diamond["left"][0],
18 diamond["top"][0],
19 ]
20 y_coords = [
21 diamond["top"][1],
22 diamond["right"][1],
23 diamond["bottom"][1],
24 diamond["left"][1],
25 diamond["top"][1],
26 ]
27
28 if i == 0:
29 ax.plot(
30 x_coords,
31 y_coords,
32 "r--",
33 linewidth=2,
34 label="Predicted Coulomb Diamonds",
35 )
36 else:
37 ax.plot(x_coords, y_coords, "r--", linewidth=2)
38
39 center_x = (diamond["top"][0] + diamond["bottom"][0]) / 2
40 center_y = (diamond["top"][1] + diamond["bottom"][1]) / 2
41 ax.plot(center_x, center_y, "ro", markersize=6)
42
43ax.set_xlabel("Gate Voltage 1 (a.u.)", fontsize=10)
44ax.set_ylabel("Source Drain Bias Voltage (a.u.)", fontsize=10)
45ax.tick_params(axis="both", labelsize=8)
46ax.legend(fontsize=9)
47
48plt.show()
Coulomb Diamond Detector v1

Coulomb Diamond Detector v1 Output. (Data Source: Lennon, D., et al. Efficiently measuring a quantum device using machine learning. 2019. Zenodo, https://doi.org/10.5281/zenodo.2559478.)

Important Notes for Coulomb Diamond Models

  • Input dimensions: Input dimensions should ideally match the specified resolution of the model for the best results. You may need to interpolate or downsample your data to match the required shape. You can find the required input shapes for each model on the models overview page.
  • Data format: Input data should be a 2D numpy array representing a conductance measurement grid as a function of two gate voltages.
  • Output format:
    • The Segmenter outputs a binary mask where 1.0 indicates regions of Coulomb Blockade (i.e., the diamond region) and 0.0 indicates regions of current flow.
    • The Detector outputs diamond vertices in pixel index coordinates. Each diamond is represented by four vertices: “left”, “right”, “bottom”, and “top”.
  • Model workflow:
    • v0 (two-stage): The Coulomb Diamond Segmenter and Detector v0 models are designed to be used sequentially. First, use the Segmenter to create a binary mask, then use the Detector v0 on that mask to identify diamond vertices.
    • v1 (single-stage): The Coulomb Diamond Detector v1 is a single-stage model that detects diamond vertices directly from raw conductance data. No segmentation step is required.
  • Model versions: Higher version numbers typically indicate improved accuracy and performance. Check the models overview for the latest available versions.