Getting Started

Quickstart Guide

Get up and running with Stanza in 5 minutes.

Installation

$pip install cq-stanza

Or with Quantum Machines support:

$pip install "cq-stanza[qm]"

Step 1: Configure Your Device

Create device.yaml:

1name: "My Quantum Device"
2
3gates:
4  G1:
5    type: BARRIER
6    control_channel: 1
7    breakout_channel: 1
8    v_lower_bound: -3.0
9    v_upper_bound: 3.0
10
11contacts:
12  DRAIN:
13    type: DRAIN
14    control_channel: 4
15    measure_channel: 2
16    breakout_channel: 4
17    v_lower_bound: -3.0
18    v_upper_bound: 3.0
19
20routines:
21  - name: sweep_barrier
22    parameters:
23      gate: G1
24      v_start: -2.0
25      v_stop: 0.0
26      n_points: 100
27
28instruments:
29  - name: qdac2-compact
30    type: GENERAL
31    driver: qdac2
32    ip_addr: 192.168.1.1
33    slew_rate: 1.0
34    measurement_duration: 1e-3
35    sample_time: 10e-6
36    breakout_line: 9 # Breakout box relay that connects to this instrument
37
38  - name: qswitch
39    type: BREAKOUT_BOX
40    driver: qswitch
41    ip_addr: 192.168.1.2
42    port: 5025

Step 2: Initialize a Session

Initialize a session directory for your experiment data:

$# Initialize a new timestamped session directory
>stanza init
>
># Or with a custom name
>stanza init --name my_experiment
>
># Check current session
>stanza status

This creates a directory structure like:

your-project/
├── .stanza/
│   └── active_session.json                            # Tracks the active session
├── {timestamp}_my_experiment/                         # Timestamped session directory
│   ├── {timestamp}_my_experiment.ipynb                # Jupyter notebook for the session
│   └── .stanza/
│       └── config.json                                # Session metadata
└── device.yaml                                        # Your device config

If stanza init is called without the --name flag, the session directory name is {timestamp}_untitled and the jupyter notebook name is {timestamp}_untitled_notebook.ipynb.

The Jupyter notebook is pre-configured with Stanza imports and ready for running your routines. All data will be logged to the active session directory.

Step 3: Write a Routine

Create routines.py:

1import numpy as np
2from stanza.routines import routine
3
4@routine
5def setup(ctx):
6    """Set up breakout box instruments prior to experiment run"""
7    device = ctx.resources.device
8
9    # Unground specific lines to enable control
10    device.unground_breakout_lines()
11
12    # Connect all lines to their configured instruments
13    device.connect_breakout_lines()
14
15@routine
16def sweep_barrier(ctx, gate, v_start, v_stop, n_points):
17    """Sweep a gate and measure current."""
18    device = ctx.resources.device
19    voltages = np.linspace(v_start, v_stop, n_points)
20    v_data, i_data = device.sweep_1d(gate, voltages.tolist(), "DRAIN")
21    return {"voltages": v_data, "currents": i_data}
22
23@routine
24def teardown(ctx):
25    """Reset breakout box instruments after experiment run"""
26    device = ctx.resources.device
27
28    # Set voltages of control channels to 0V
29    device.zero()
30
31    # Ground all breakout lines for safety
32    device.ground_breakout_lines()
33
34    # Disconnect breakout lines when not in use
35    device.disconnect_breakout_lines()

Step 4: Execute

Create run.py:

1from stanza.routines import RoutineRunner
2from stanza.utils import load_device_config
3
4# Load configuration
5config = load_device_config("device.yaml")
6
7# Create runner - automatically loads routine parameters from config
8runner = RoutineRunner(configs=[config])
9
10# Set up the breakout box
11runner.run("setup")
12
13# Execute with config parameters
14result = runner.run("sweep_barrier")
15print(f"Measured {len(result['currents'])} points")
16
17# Teardown the breakout box
18runner.run("teardown")

Run it:

$python run.py

Data Logging

All routine data is automatically logged to your active session directory when you run routines. The session initialization (Step 2) sets up the logging infrastructure, so your data is persisted without any additional configuration.

Live Plotting

Want to visualize your data in real-time as measurements run? Enable live plotting with a single command:

$# Enable browser-based live plotting
>stanza live-plot enable

Now when you run routines, plots automatically update in your browser at http://localhost:5006. This is especially useful for monitoring long measurements and catching issues early.

For notebook users, you can also display plots inline:

$# Enable inline plotting (requires: pip install "cq-stanza[notebook]")
>stanza live-plot enable --backend inline

Learn more in the Live Plotting guide.

Jupyter Integration

Stanza provides built-in Jupyter server management for interactive development. Start a persistent server that survives terminal closure:

$# Start Jupyter server in background
>stanza jupyter start
>
># Check server status
>stanza jupyter status
>
># Open Jupyter in browser
>stanza jupyter open

Monitor running notebooks in real-time:

$# List active notebook sessions
>stanza jupyter list
>
># Stream a notebook's output (Ctrl+C to detach)
>stanza jupyter logs my_notebook.ipynb
>
># Attach with kernel control (Ctrl+C kills kernel, ESC exits)
>stanza jupyter attach my_notebook.ipynb

The server automatically logs all cell outputs to .log files, making it easy to monitor long-running experiments from the command line. Learn more in the Jupyter Integration guide.

Next Steps