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

# Quickstart Guide

Get up and running with Stanza in 5 minutes.

## Installation

```bash
pip install cq-stanza
```

Or with Quantum Machines support:

```bash
pip install "cq-stanza[qm]"
```

## Step 1: Configure Your Device

Create `device.yaml`:

```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:

```bash
# 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`:

```python
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`:

```python
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:

```bash
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:

```bash
# 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:

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

Learn more in the [Live Plotting guide](/control/stanza/core-concepts/live-plotting).

## Jupyter Integration

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

```bash
# 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:

```bash
# 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](/control/stanza/core-concepts/jupyter-integration).

## Next Steps

* [Device Configuration](/control/stanza/core-concepts/device-configuration) - Gates, contacts, and instruments
* [Routines](/control/stanza/core-concepts/routines/overview) - Advanced patterns and workflows
* [Data Logging](/control/stanza/core-concepts/data-logging) - Customize logging
* [Live Plotting](/control/stanza/core-concepts/live-plotting) - Visualize data in real-time
* [Jupyter Integration](/control/stanza/core-concepts/jupyter-integration) - Manage and monitor notebook servers
* [Cookbooks](https://github.com/conductorquantum/stanza/tree/main/cookbooks) - Common measurement patterns