Skip to content

Jupyter Notebook

This pattern enables interactive quantum computing development in Jupyter notebooks on a local machine using QLAM Core with browser-based authentication.

Overview

Jupyter notebooks are ideal for:

  • Interactive quantum program development
  • Exploring QLAM APIs
  • Visualizing results
  • Prototyping before production deployment

Authentication

Use the Authorization Code Flow for seamless browser-based authentication on your local machine.

Setup

Step 1: Install QLAM Core

pip install qlam-core

Or if you want the full CLI as well:

pip install qlam-shell

Step 2: Configure QLAM

Create a configuration file at ~/.qsh/config.json:

{
  "current_context": "production",
  "contexts": [
    {
      "name": "production",
      "qpu": "gemini",
      "defaults": {
        "api_base_url": "https://api.quera.com"
      },
      "auth_providers": [
        {
          "name": "oauth",
          "provider": "oauth",
          "client_id": "your-client-id",
          "grant_type": "authorization_code",
          "scope": "openid profile offline_access",
          "issuer": "https://auth.quera.com"
        }
      ],
      "plugins": {
        "tasks": { "auth_provider": "oauth" },
        "results": { "auth_provider": "oauth" }
      }
    }
  ]
}

Note

Contact QuEra to obtain your client_id, issuer, and other deployment-specific values.

Step 3: Authenticate

You can authenticate either before starting your notebook or directly within it.

Option A: Using QLAM Shell (before starting notebook)

qsh auth login

This opens your browser for authentication. Credentials are stored in ~/.qsh/credentials/ and automatically used by QLAM Core.

Option B: Using QLAM Core (in the notebook)

from qlam_core.common import AppContext
from qlam_core.auth import AuthClient

ctx = AppContext()
auth = AuthClient(ctx)

# Triggers browser-based OAuth flow
auth.login("oauth")

This opens your browser directly from the notebook. Credentials are cached for subsequent cells.

Notebook Example

# Cell 1: Setup
from qlam_core.common import AppContext
from qlam_core.plugins.tasks import TasksClient
from qlam_core.plugins.results import ResultsClient

ctx = AppContext()

# Cell 2: Submit a task
task_payload = {
    "programs": [
        {
            "content": "your-quantum-program-ir"
        }
    ],
    "subtasks": [
        {
            "program_index": 0,
            "num_shots": 100
        }
    ]
}

with TasksClient(ctx) as client:
    task = client.create(body=task_payload)
    print(f"Task submitted: {task.id}")
    print(f"Status: {task.status}")

# Cell 3: Check status
with TasksClient(ctx) as client:
    task = client.get(id=task.id)
    print(f"Status: {task.status}")

# Cell 4: Get results (when complete)
with ResultsClient(ctx) as client:
    results = client.get(
        id=task.id,
        qpu_mode="squin-256q"
    )

    # Process results
    for result in results:
        print(result)

Token Management

QLAM Core handles token refresh automatically. For long-running notebook sessions:

from qlam_core.sdk import refresh_credentials

# Refresh if needed before a long operation
refresh_credentials(ctx)

Tips

  1. Authenticate once per session - Run qsh auth login before starting Jupyter, and credentials persist for the session

  2. Use context managers - Always use with statements for API clients to ensure proper cleanup

  3. Handle errors gracefully - Wrap API calls in try/except for better notebook experience:

from qlam_core.errors import AuthenticationError, NetworkError

try:
    with TasksClient(ctx) as client:
        tasks = client.list()
except AuthenticationError:
    print("Please run: qsh auth login")
except NetworkError as e:
    print(f"Network error: {e.message}")

Next Steps