Skip to navigation
Stanza

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:

name: "My Quantum Device"
gates:
  G1:
    type: BARRIER
    control_channel: 1
    breakout_channel: 1
    v_lower_bound: -3.0
    v_upper_bound: 3.0
contacts:
  DRAIN:
    type: DRAIN
    control_channel: 4
    measure_channel: 2
    breakout_channel: 4
    v_lower_bound: -3.0
    v_upper_bound: 3.0
routines:
  - name: sweep_barrier
    parameters:
      gate: G1
      v_start: -2.0
      v_stop: 0.0
      n_points: 100
instruments:
  - name: qdac2-compact
    type: GENERAL
    driver: qdac2
    ip_addr: 192.168.1.1
    slew_rate: 1.0
    measurement_duration: 1e-3
    sample_time: 10e-6
    breakout_line: 9 # Breakout box relay that connects to this instrument
  - name: qswitch
    type: BREAKOUT_BOX
    driver: qswitch
    ip_addr: 192.168.1.2
    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:

import numpy as np
from stanza.routines import routine
@routine
def setup(ctx):
    """Set up breakout box instruments prior to experiment run"""
    device = ctx.resources.device
    # Unground specific lines to enable control
    device.unground_breakout_lines()
    # Connect all lines to their configured instruments
    device.connect_breakout_lines()
@routine
def sweep_barrier(ctx, gate, v_start, v_stop, n_points):
    """Sweep a gate and measure current."""
    device = ctx.resources.device
    voltages = np.linspace(v_start, v_stop, n_points)
    v_data, i_data = device.sweep_1d(gate, voltages.tolist(), "DRAIN")
    return {"voltages": v_data, "currents": i_data}
@routine
def teardown(ctx):
    """Reset breakout box instruments after experiment run"""
    device = ctx.resources.device
    # Set voltages of control channels to 0V
    device.zero()
    # Ground all breakout lines for safety
    device.ground_breakout_lines()
    # Disconnect breakout lines when not in use
    device.disconnect_breakout_lines()

Step 4: Execute

Create run.py:

from stanza.routines import RoutineRunner
from stanza.utils import load_device_config
# Load configuration
config = load_device_config("device.yaml")
# Create runner - automatically loads routine parameters from config
runner = RoutineRunner(configs=[config])
# Set up the breakout box
runner.run("setup")
# Execute with config parameters
result = runner.run("sweep_barrier")
print(f"Measured {len(result['currents'])} points")
# Teardown the breakout box
runner.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