Notebook-to-Runbook Research Operations — Operating Quantum Computers

Notebooks are useful for quantum research because the work is exploratory, visual, statistical, and iterative. They are also operationally dangerous when they become the only place where the experiment logic exists.

The CEOS notebook best-practice guidance emphasizes that notebooks can suffer from hidden dependencies, input-data ambiguity, and quality problems that harm reuse [R211]. Quantum teams should treat notebooks as research interfaces, not production control planes. The production path is notebook to script, script to workflow, workflow to runbook, runbook to reviewed evidence.

Diagram loads as you read

Notebook-to-Runbook Research Operations · Figure 1

View diagram source

flowchart LR
    Notebook[Exploratory notebook] --> Script[Parameterized script]
    Script --> Workflow[Automated workflow]
    Workflow --> Runbook[Operational runbook]
    Runbook --> Evidence[Evidence package]
    Evidence --> Review[Claim review]

Notebook roles

A notebook can serve four legitimate roles.

Role	Acceptable use
scratchpad	rapid idea testing with no claims
analysis view	interactive inspection of stored artifacts
report shell	narrative explanation backed by immutable artifacts
tutorial	training users on approved workflows

Diagram loads as you read

Notebook roles · Figure 2

View diagram source

flowchart TB
    Notebook[Notebook] --> Scratch[Scratchpad]
    Notebook --> Analysis[Analysis view]
    Notebook --> Report[Report shell]
    Notebook --> Tutorial[Tutorial]
    Scratch --> NoClaims[No claim-bearing output]
    Analysis --> Immutable[Reads immutable artifacts]
    Report --> Evidence[Links evidence package]
    Tutorial --> Synthetic[Uses synthetic or approved data]

The dangerous notebook is the fifth role: an unversioned production workflow with hidden state.

Hidden state audit

Before a notebook can support a claim, it should pass a hidden-state audit.

Diagram loads as you read

Hidden state audit · Figure 3

View diagram source

flowchart TD
    NB[Notebook] --> Restart[Restart kernel]
    Restart --> RunAll[Run all cells]
    RunAll --> Inputs{All inputs declared?}
    Inputs -- no --> Reject[Reject]
    Inputs -- yes --> Outputs{Outputs regenerated?}
    Outputs -- no --> Reject
    Outputs -- yes --> Env{Environment pinned?}
    Env -- no --> Reject
    Env -- yes --> Publish[Promote to evidence shell]

The audit should fail notebooks that depend on local files, manual cell order, ambient credentials, mutable remote state, or undeclared package versions.

Parameterization

Claim-bearing experiments should accept parameters through explicit configuration.

Illustrative listing · yaml

workload_id: vqe-molecule-042
backend_policy: production-small-superconducting
shots: 20000
optimizer: cobyla
initial_point_seed: 17
record_initial_point: true
ansatz_depth: 3
mitigation_profile: zne-lite-v2
baseline_policy: active-not-older-than-6h

Diagram loads as you read

Parameterization · Figure 4

View diagram source

flowchart LR
    Config[Experiment config] --> Validate[Schema validation]
    Validate --> Script[Headless script]
    Script --> Workflow[Workflow run]
    Workflow --> Artifacts[Artifacts]
    Artifacts --> Notebook[Notebook reads artifacts]

The notebook should read outputs from the workflow, not regenerate them through informal hidden steps.

Notebook promotion gates

Diagram loads as you read

Notebook promotion gates · Figure 5

View diagram source

stateDiagram-v2
    [*] --> Exploratory
    Exploratory --> Candidate: result looks useful
    Candidate --> Reproducible: restart-run-all passes
    Reproducible --> Parameterized: config extracted
    Parameterized --> Automated: workflow created
    Automated --> Reviewed: evidence package approved
    Reviewed --> Template: reusable pattern

Promotion does not remove creativity. It prevents fragile discoveries from becoming institutional myth.

Operational runbook

The runbook should describe how to execute the workflow without relying on the original researcher.

Diagram loads as you read

Operational runbook · Figure 6

View diagram source

flowchart TB
    Runbook[Runbook] --> Purpose[Purpose]
    Runbook --> Preconditions[Preconditions]
    Runbook --> Inputs[Inputs]
    Runbook --> Execution[Execution steps]
    Runbook --> Monitoring[Monitoring]
    Runbook --> Failure[Failure handling]
    Runbook --> Evidence[Expected artifacts]
    Runbook --> Review[Review checklist]

A good runbook states when not to run. For quantum work, that means denying execution when the backend baseline is stale, queue latency violates the experiment design, calibration drift invalidates assumptions, or cost exceeds the approved envelope.

Analysis notebooks

Analysis notebooks should prefer immutable references.

Diagram loads as you read

Analysis notebooks · Figure 7

View diagram source

flowchart LR
    Notebook[Analysis notebook] --> ArtifactURI[Artifact URI]
    ArtifactURI --> Warehouse[Experiment warehouse]
    Warehouse --> Counts[Counts and metadata]
    Warehouse --> Baseline[Baseline snapshot]
    Warehouse --> Logs[Runtime logs]
    Warehouse --> Report[Rendered report]

The notebook becomes a reader and explainer. The experiment warehouse becomes the source of truth.

Practical rule

A notebook may discover a result. It should not be the only system that can produce, explain, or defend the result.

Additional technical sources: [R281].