A quantum computing workspace in DAM, connected to IBM Quantum Platform through Qiskit Runtime and SamplerV2.
Qiskit Lab is a native Python package using the Qiskit SDK for circuit development, simulation, experiments, and hardware execution. DAM supplies the chat model and workspace. The application code lives in src/qiskit_lab and calls Qiskit directly.
flowchart LR
U[User in DAM] --> A[Qiskit Lab · DAM model]
A --> D[Qiskit / OpenQASM development]
A --> T[Python tools]
T --> S[Local simulator and QAOA]
T --> I[IBM Quantum Platform · SamplerV2]
T --> F[JSON / QASM / PNG artifacts]
| Capability | Implementation |
|---|---|
| Orchestration | DAM harness and model; instructions in AGENTS.md |
| Developer | Qiskit/OpenQASM development; Bell, GHZ, Grover and Deutsch–Jozsa examples |
| Status | Accessible QPUs, queues, status, operations and topology |
| Computing | Local simulation; ISA transpilation and one fresh SamplerV2 job when requested |
| Experiment | QAOA Max-Cut p=1, 2–8 nodes, exact classical validation and PNG |
| Results | Automatic HTML reports, job IDs, joint counts, JSON receipts, QASM, circuit diagrams and distribution comparisons |
Both qiskit and qiskit-ibm-runtime are required dependencies and must be installed before using the tools. QAOA remains experimental; this kit does not implement a general VQE optimizer. Code, documentation and agent responses use English.
New scientific receipts use an explicit schema version and shared runtime validation. Historical saved results remain supported without bulk migration. See the receipt contract for variants, missing-result handling, validation errors, and the distinction between imported and online-observed data.
Requirements: Git, Python 3.11-3.13, and uv. Run these commands in a terminal. No DAM account, IBM credentials, Node.js, or QPU access is needed for local simulation. The first sync needs network access to download the locked dependencies; simulation then runs locally.
git clone https://github.com/BrUn3y/qiskit_lab.git
cd qiskit_lab
uv sync --locked
uv run --locked qiskit-lab doctor
uv run --locked qiskit-lab execute --example bell --shots 256doctor reports installed SDK versions and optional capability metadata without
reading credentials or contacting IBM unless you add --online. Missing optional
packages do not fail a base check. For isolated, locked SQD/PySCF and fermionic
profiles, see Optional capabilities.
The execution command prints JSON with hardware: false,
backend: "local_statevector_simulator", status: "DONE", and 256 total counts
over Bell states 00 and 11. Do not expect an exact 50/50 split at finite shots.
It saves a receipt, QASM, reconstructed Python, PNG, and self-contained HTML under
artifacts/dam/<run-id>/. Open the returned report_path in a browser. The CLI
does not start a web server or publish a DAM artifact by itself.
Use uv run --locked qiskit-lab --help for commands and
uv run --locked qiskit-lab execute --help for execution options. The
scripts/dam/quantum wrapper runs the same CLI from the checkout. For development
and the full offline validation workflow, see CONTRIBUTING.md.
These screenshots show a five-node QAOA Max-Cut local simulation and its HTML report inside DAM.
Report overview. Completion status, downloads, shot count and circuit statistics.
Measurement results. Observed bitstring probabilities and searchable results.
Circuit and scientific dashboard. Circuit source, graph, convergence and sampled solutions.
The agent includes the official Qiskit AI Skills
alongside the project-specific qiskit-lab skill. It reads the matching skill
before giving guidance or developing code for these workflows:
| Skill | Used for |
|---|---|
| migrate-qiskit-ibm-runtime | Migrating Runtime code, primitives and execution APIs. |
| select-error-mitigation | Selecting and configuring error mitigation and suppression. |
| select-sqd-eigensolver | Choosing and integrating the diagonalization solver in SQD. |
| simulate-fermionic-systems | Fermionic operators, encodings, circuit construction and simulation. |
The complete skill directories, including their registries, reference guides and
helper scripts, are bundled under .agents/skills/. DAM advertises them through
kit.yaml; the CLI deployment fallback uploads them with the tracked source.
The routing instructions in AGENTS.md also make them available to agents that
read project instructions directly. A new conversation in an updated checkout
can use them without downloading the upstream repository at runtime.
The bundled copy is pinned to Qiskit/skills commit
0888fb7.
Source metadata records the upstream revision and
file hashes; the upstream Apache 2.0 license
is preserved. Skill evaluations and updates provides representative
cases, a separate transcript-based behavior-review protocol, and an offline,
review-only upstream proposal command. Deterministic routing/resource checks do
not prove model behavior. These skills provide workflow guidance. Optional packages such as
qiskit-fermions, SQD add-ons and external solvers are installed when a task
needs them, rather than added to the base SDK environment by installing the kit.
Existing DAM agents need a checkout update to receive these files; see
Update an existing deployment.
The root kit.yaml follows the
official DAM starter-kit format.
It seeds this repository at the catalog's resolved commit, installs the locked
Qiskit SDK environment, advertises qiskit-lab and the four official Qiskit skills,
and declares the two-minute job-report schedule. It uses the platform's default model and
harness selection, plus the IBM network hosts the SDK needs.
The platform runs bash scripts/dam/install.sh inside the seeded checkout before
opening onboarding. That command installs home instruction entry points and
~/.local/bin/qiskit-lab-dam, which points to the actual checkout. It does not
run a circuit, read credentials, or submit IBM work. The first conversation
follows ONBOARDING.md: choose local simulation or configure
IBM access using the owner-only hidden Terminal prompt. The platform holds
recurring schedules until onboarding completes; schedules the owner skips or
disables stay that way. No Node.js or local DAM CLI is needed for native install.
Native installation requires a catalog configured on the DAM deployment.
Curated-catalog registration is proposed in
dam-starter-kits PR #18.
After registration and catalog refresh, select Qiskit Lab from DAM's
Starter Kits page. The current dam.res.ibm.com deployment supports
catalog-listed kits; use the CLI deployment below while registration is pending.
An operator can instead configure this repository's root
catalog.yaml as a standalone catalog:
starterKits:
catalogs:
- name: quantum
url: https://github.com/BrUn3y/qiskit_labThat catalog addresses the kit as quantum/qiskit-lab. Public GitHub catalog
reads are anonymous, so the repository must be public. Preparing the manifests
and registering the catalog are separate steps. Existing regular agents retain
their deployment type.
Validate both manifests offline with uv run --locked pytest -q tests/test_kit.py.
The generated upstream schemas and their source commit are documented in
dam/README.md.
Requirements: Python 3.11–3.13 and uv. Deployment from your machine additionally requires Git, Node.js 20+ and DAM CLI 0.2.24. The root pyproject.toml declares the required Qiskit SDK packages; uv.lock pins the complete environment.
npm install -g @dam-agents/[email protected]
dam auth login --server https://dam.res.ibm.com
git clone https://github.com/BrUn3y/qiskit_lab.git
cd qiskit_lab
uv sync --locked # Required: installs Qiskit, IBM Runtime and the qiskit-lab command.
python3 scripts/dam/deploy.py --name 'Qiskit Lab'The installer uses your preferred DAM model provider, creates the agent, configures networking, imports only Git-tracked files into ~/work/qiskit-lab, and starts onboarding. The tool wrapper installs the locked Qiskit environment in DAM before its first command. If the provider offers one model, it selects it automatically; otherwise pass --model. It excludes .git, credentials, local environments and results. The agent receives the tracked source without needing a GitHub connection.
Options: --provider 'Provider name', --model ALIAS/MODEL_ID, --instance CRN (not a secret), --dry-run, and --no-run. The agent and session IDs are saved in .dam-deploy/deployment.json, which Git ignores. If deployment fails after creating the agent, use --existing to resume deliberately. Use --existing --agent AGENT_ID to target an exact agent, including when names are duplicated.
dam connection list --providers
dam agent models 'Qiskit Lab'
dam agent update 'Qiskit Lab' --model ALIAS/MODEL_IDThe CLI fallback creates a regular agent without a starter-kit badge or the
platform's kit onboarding gate. A private repository on github.com cannot be
resolved by anonymous catalog readers. A platform-managed
GitHub Enterprise catalog is a separate operator-configured capability.
The first response in a new chat checks the connection. If the account is missing, Qiskit Lab asks you to configure your API key, shows the hidden-entry command, and offers local simulation. It reuses an account that already works. The installer adds these instructions to ~/AGENTS.md and a native @AGENTS.md import to ~/CLAUDE.md, preserving existing owner instructions in both files. Claude Code can load the startup rules before its first response, as can harnesses that load AGENTS.md directly.
-
Open Qiskit Lab in DAM and open its Terminal.
-
Run the
setup_commandreturned by onboarding yourself in that terminal. It includes the actual checkout path. Equivalently, from that checkout run:uv run --locked python scripts/dam/configure-quantum.py
-
Enter your instance CRN and API key from IBM Quantum Platform. The API key uses a hidden prompt. The program verifies QPU access before saving the SDK account in
~/.qiskit/qiskit-ibm.jsonwith permissions600. -
Return to chat and say: “Verify the IBM Quantum Platform connection and show my available QPUs.”
Do not paste the key into chat or commit it to Git. The owner runs credential setup directly. DAM chat password fields also enter the transcript as plain text. DAM custom-header connections provide placeholders and cannot insert an API key into IBM IAM's form body. This kit therefore uses a persistent IBM Quantum SDK account. The API key remains on the agent's private disk and must be treated as an agent credential.
| Value | Environment variable |
|---|---|
| IBM Quantum API key | QISKIT_IBM_TOKEN |
| Supported API-key alias | QISKIT_IBM_RUNTIME_APIKEY |
| Instance CRN | QISKIT_IBM_INSTANCE |
The welcome message names these variables. Hidden setup saves the SDK account, so setting variables is optional. If you choose environment configuration, the variables must reach the tool process; exporting them in a separate terminal alone does not configure the chat's tools. The instance also accepts QISKIT_IBM_RUNTIME_INSTANCE as an alias. Tools use the ibm_quantum_platform channel. Available QPUs depend on the account, instance and region.
Create a Bell state and simulate it with 1024 shots. Show the circuit and histogram.
Which IBM Quantum computers can I access, and what are their queue lengths?
Show the topology and current status of ibm_BACKEND.
Optimize QAOA Max-Cut for five nodes and compare it with the classical optimum.
Execute the Bell circuit once on real IBM Quantum hardware with 1024 shots.
Check the status and results of job JOB_ID.
dam run 'Qiskit Lab' -p 'Create a Bell state and simulate it with 1024 shots'
dam chat 'Qiskit Lab'Simulation is the default. When you request real hardware, the agent submits one job and returns its ID without waiting through the entire queue. Query the same ID later. The default QPU execution limit is 300 seconds per job; it does not limit cost or queue time. A missing submission response is not proof that IBM rejected the job. Never retry a hardware submission automatically.
Before the single sampler.run() call, hardware execution atomically saves and
syncs submission-intent.json and receipt.json in the run's artifact directory.
They record the run_id, a full random UUID submission identifier, intent time,
backend, shots, execution limit, source-circuit identity, ISA statistics and SDK
versions. The job receives both qiskit-lab-dam and the unique
qiskit-lab-run-<submission-uuid> tag. No credentials or SDK options/exception
bodies are saved.
If the response or job ID is lost, the CLI exits 1 with
submission_outcome: "unknown", the run ID, public tags and recovery instructions. An abrupt process
exit can leave the same unknown state on disk. Use the saved run ID, original
output directory, and original IBM instance:
uv run --locked qiskit-lab recover-submission RUN_ID --output-dir artifacts/damRecovery only reads IBM's job list, filtering by both tags and the backend, across pending and terminal states. It never submits, resubmits, cancels, retags, waits for results or acknowledges notifications. It writes local tracking files:
no_match: no job is visible in the active instance yet. This does not prove submission failed; tags can take time to appear or the selected instance may differ. Repeat this read-only command later. Do not automatically retry.recovered: exactly one job matches. Its accepted ID is durably saved before returning and becomes eligible for the existingjob/poll-jobsworkflow.ambiguous: at least two jobs match. Up to two candidate IDs are returned and saved insubmission-recovery.json; none is selected automatically. Inspect those existing IDs before deciding what to do.already_tracked: the ID is already saved. No IBM query is made; completed receipts, counts, reports and acknowledgement state remain unchanged.query_error: the query was unavailable, not an empty result. The CLI exits 1 with a safe exception class and keeps the unknown intent for later recovery.
A successful recovery command exits 0 even for no_match or ambiguous; inspect
recovery_status, not just the exit code. Recovery serializes receipt repairs
with job polling and refuses a run whose submitter is still active. It is a
manual command, not a new automatic poll or retry schedule.
Reusing a saved run's submission intent is refused, including after interruption;
only the read-only recovery path can resume its tracking.
Accepted IDs are saved in both the journal and receipt before any status/result request. If one tracking file cannot be updated, the other retains the ID and the CLI exits 1 with that ID; recovery can repair a missing receipt from the journal. Preserve both files. If both writes fail, keep the returned ID and fix storage; the original unique-tag intent remains the fallback. Sync/atomic-rename guarantees depend on the local filesystem and do not survive loss of that filesystem. This is recovery assistance, not an IBM idempotency guarantee.
Historical runs without an intent or unique tag remain usable with job JOB_ID
and poll-jobs. They cannot be uniquely recovered by this command: manually
inspect existing qiskit-lab-dam jobs before any owner-authorized retry.
Every completed simulation, QAOA experiment and terminal hardware job produces
<job-or-run-id>-<circuit-description>.html alongside its JSON, QASM and PNG
artifacts. For example, a Bell job produces JOB_ID-bell-circuit.html.
The agent automatically displays the report as a rendered DAM HTML artifact and
includes its artifact and workspace file links. If artifact publication is
unavailable, it explains that limitation and preserves the downloadable report.
Use execute --title 'My circuit' to label a custom circuit; the default
description comes from the example or QASM filename. job JOB_ID --title 'My circuit'
can label an existing job when its circuit is known. Reports use a dark theme
and bundled IBM Plex fonts. They are self-contained and open offline.
Reports include the recorded job/run ID, backend, status, requested and observed shots, source/ISA circuit statistics, available timestamps and IBM QPU usage, SDK versions, measurement charts with probability/count controls, searchable and paginated state tables, downloadable JSON/OpenQASM/Python, source circuit, and the scientific dashboard. Circuit execution saves a generated Qiskit Python reconstruction script alongside the OpenQASM before simulation or hardware submission; QAOA reports also include a reconstruction script. Reports show the first 15 lines of each source, with an expand/collapse button for longer files. Hardware reports also show the transpiled OpenQASM saved before submission. The Python script rebuilds the recorded circuit without submitting a job; it is not the original author's source. Older jobs without a saved script say it is unavailable. QAOA reports also include the optimization trace and exact classical comparison. Missing IBM metadata is marked unavailable.
For IBM hardware, submission still returns immediately. The native kit declares
Qiskit Lab job reports, a DAM schedule that checks tracked jobs every two
minutes; the private CLI deployer creates its equivalent. The native precheck
uses bash ~/.local/bin/qiskit-lab-dam poll-jobs --precheck, so it works wherever
the platform seeds the checkout. It queries existing IDs and writes final HTML when DONE,
ERROR or CANCELLED; it invokes the model only when a report needs to be announced.
No report step submits another hardware job. Failed/cancelled jobs receive a
status report without fabricated counts. Report delivery appears in the DAM
scheduled run; instant delivery into the original chat is not guaranteed.
The schedule uses persistent notifications: after publishing each report artifact and presenting its link, the agent acknowledges that ID. An interrupted delivery remains pending. Network or result-download errors keep the job eligible for the next poll. DAM must be running and its schedule enabled for automatic checks. Detection occurs at the next successful poll, not at the exact moment IBM finishes.
# Inspect one existing job and create its report if it has ended.
uv run --locked qiskit-lab job JOB_ID
# Check all tracked jobs, generate completed reports, and list pending links.
uv run --locked qiskit-lab poll-jobs
# After delivering a report to the owner, acknowledge its notification.
uv run --locked qiskit-lab poll-jobs --ack JOB_IDThe default tracked directory is artifacts/dam/. If you use a custom hardware
--output-dir, use that directory for subsequent job queries and polling and
configure the schedule to match. Reports contain only explicitly recorded job
data; account files and credentials are never embedded.
Report styles and fonts ship inside the Python wheel. Node.js is only needed to rebuild these checked-in frontend assets, not to run or open reports:
cd tools/report-assets
npm ci --ignore-scripts
npm run buildThird-party licenses and exact asset versions are documented in
src/qiskit_lab/assets/NOTICE.md.
For custom experiments, use the bundled report generator instead of maintaining a separate HTML template:
scripts/dam/quantum report --input PUBLIC_RESULT.jsonProvide a public result receipt, never an SDK account or credential file. The
receipt must include terminal status (DONE, ERROR or CANCELLED). Record
hardware as a JSON boolean and preserve backend, hardware job_id or local
run_id. Missing execution type is shown as unavailable, not inferred to be a
simulation. The command preserves the input and writes new HTML and report.json
under artifacts/dam/; it does not contact IBM or submit work. An imported
receipt is labelled as not verified online. Existing reports are not overwritten.
CHSH receipts additionally contain four correlators labelled ab, ab',
a'b, a'b', each with two-bit counts and sign_in_chsh (+1 or -1, with an odd
number of negative signs). Optional alice_angle_rad, bob_angle_rad and
theory preserve the experiment's measurement convention and reference values.
The renderer recomputes correlations, S, observed shot totals and approximate
standard errors from the counts, replacing stale statistical summaries. Requested
shots remain separate; unequal observed shot counts are listed per configuration.
chsh_ideal is labelled as ideal theory. A hardware receipt with
noise_model.type: real_hardware_noise does not present an ideal reference as a
calibrated noise-model prediction.
CHSH error bars assume independent shots within and across configurations and exclude systematic hardware errors. Approximate standard errors remain available for compatibility but can vanish at parity boundaries and are not confidence intervals. Reports also recompute two-sided 95% Hoeffding confidence intervals from counts. These conservative finite-sample bounds do not collapse when a correlator is +1 or -1; tiny samples may correctly yield the full physical range. No optional statistical dependency is needed.
For observed parity mean E with N shots, the interval is E +/- r, intersected
with [-1, 1], where r = sqrt(2 * log(2 / 0.05) / N). For the signed sum S,
r = sqrt(2 * log(2 / 0.05) * sum(1 / N_i)), intersected with [-4, 4].
This follows the bounded independent-sum inequality
P(|S_hat - S_mean| >= t) <= 2 * exp(-t^2 / (2 * sum(1 / N_i))):
each signed shot contributes a range width of 2 / N_i. The S interval is
computed directly, not by adding four marginal intervals. Individual correlator
intervals are not a simultaneous 95% region. The method is conservative and may
need more shots than sharper binomial methods to exclude the classical bound.
JSON adds confidence_interval, confidence_level and confidence_method per
correlator and chsh_confidence_interval, chsh_confidence_level,
chsh_confidence_method, chsh_confidence_assumption for S. Bounds are ordered
[lower, upper]; the fixed level is 0.95 and method is hoeffding. Supplied
statistical summaries are always replaced by count-derived values.
observed_violation means observed abs(S) > 2; the historical violated field
retains exactly that meaning. statistically_supported_violation is true only
when the entire S confidence interval lies above +2 or below -2.
Inference assumes independent shots within and across configurations, a fixed outcome distribution within each configuration, and sample sizes, settings and signs fixed before observing outcomes. Optional stopping, outcome post-selection, drift and readout bias are not covered. Neither counts nor this interval verify locality, freedom of setting choice or fair sampling; this is not a loophole-free Bell test, including when the statistical flag is true. CHSH interpretation also assumes each repeated local label represents the same observable, even when angle metadata is unavailable.
When angles are supplied, repeated local settings must agree: a in ab/ab',
a' in a'b/a'b', b in ab/a'b, and b' in ab'/a'b'. Comparison uses absolute
1e-9 rad tolerance with no relative tolerance or periodic wrapping, because
the recorded angle convention is not inferred. Contradictions fail before report
artifacts are written. Missing or null angles remain supported for historical
receipts; chsh_settings_validation is complete, partial or unavailable
according to supplied angles. Consistency is a metadata check, not verification
of physical settings.
Identical histograms trigger a sampling review warning; they do not prove a seed error, and different histograms do not prove independence. For local experiments, sample all configurations together:
from qiskit_lab.sampling import sample_configurations
counts, sampling = sample_configurations(circuits, shots=8192, seed=42)This helper assigns each circuit a distinct reproducible seed using NumPy
SeedSequence. Store sampling in the receipt. Do not call the helper separately
with the same root seed for each configuration. Adoption is required in custom
experiment scripts; regenerating an old report cannot repair correlated samples.
The helper supports measured statevector-compatible circuits of up to 20 qubits.
scripts/dam/quantum chsh --shots 8192 --seed 42This local-only command prepares Bell state Phi+ and samples all four labelled
configurations (ab, ab', a'b, a'b') with one sample_configurations() call.
--shots is per configuration (1-100000), not a combined budget.
--seed is a nonnegative root integer, default 42. Each configuration uses its
own SeedSequence-derived stream; the root, ordered child seeds and each row's
configuration_seed are saved. Repeated inputs reproduce counts and scientific
results in the same locked environment, not run IDs, timestamps or output paths.
SDK and NumPy versions are recorded; cross-version random results are not promised.
The measurement convention is explicit: Alice is qubit 0, Bob is qubit 1 and
the output bitstring is Bob-Alice (c[1]c[0]). Outcome bit 0 means +1 and bit 1
means -1. An angle theta defines
M(theta) = cos(2 theta) Z + sin(2 theta) X, implemented by RY(-2 theta)
followed by Z measurement. This is a basis angle, half the Bloch rotation
angle. All four options accept finite radians:
scripts/dam/quantum chsh --shots 8192 --seed 42 \
--alice-a 0 --alice-a-prime 0.7853981633974483 \
--bob-b 0.39269908169872414 --bob-b-prime 1.1780972450961724These are the defaults: a=0, a'=pi/4, b=pi/8, b'=3pi/8.
For Phi+, ideal E(a,b) = cos(2(a-b)) and the fixed sign convention is
S = E(ab) - E(ab') + E(a'b) + E(a'b'). Default ideal S is 2 sqrt(2);
custom settings receive their own ideal reference, not an assumed maximum.
Observed correlations and uncertainty are always calculated from counts.
Shot-noise inference assumes independent samples, excludes systematic errors,
and is not a loophole-free Bell test.
The command saves receipt.json, all four QASM and generated Python
reconstructions, circuit identities/measurement layouts, settings, signs, counts,
seed provenance and execution metadata under artifacts/dam/<run-id>/.
It generates the existing native HTML report, including four charts and QASM/Python
downloads, rather than a separate renderer. Use --title and --output-dir to
customize its name and location. Science is saved before rendering; a
report_error preserves the receipt for offline regeneration with report.
The model is ideal statevector sampling only: no noise parameter, calibrated
noise prediction, backend selection or hardware submission is implemented here.
From the repository root, after uv sync --locked:
scripts/dam/quantum execute --example ghz --qubits 5
scripts/dam/quantum execute --example grover
scripts/dam/quantum execute --example deutsch-jozsa --qubits 3
scripts/dam/quantum qaoa --request 'QAOA Max-Cut on a 5-node graph'Grover uses two qubits and marked state 11; Deutsch–Jozsa uses a balanced oracle. The model can develop other circuits and export them to QASM. The local simulator supports up to 20 qubits; memory grows exponentially, so this limit is not a resource guarantee. Joint counts preserve correlations between registers. Compare distributions for the same circuit and register order. Artifacts are saved in artifacts/dam/<run>/.
Local execute and qaoa persist completed counts, scientific metadata, seed,
and timing in receipt.json or experiment.json before PNG rendering or copying.
completed_at and duration_seconds describe scientific execution, excluding
presentation time. Successful commands retain their existing PNG and HTML fields.
A PNG rendering, copy, or temporary-file cleanup failure returns a safe exception
class in dashboard_error, without exposing the exception message. A failed PNG
is not advertised through dashboard_path; a successfully copied PNG remains
available even if temporary-file cleanup fails. HTML generation is still attempted
independently. Its existing report_error protection remains in place.
Do not rerun an experiment merely to recover its scientific results: use the saved
JSON. To regenerate an HTML report offline, run
scripts/dam/quantum report --input PATH_TO_SAVED_JSON.
This regenerates HTML, not a missing PNG.
Python callers of run_maxcut_qaoa() retain automatic dashboard rendering by
default. On presentation failure the returned result has dashboard_path=None
and a safe dashboard_error. Pass render_dashboard=False to obtain the same
scientific result without rendering, persist it, and then call
render_qaoa_dashboard(result) separately.
The checked-in Bell circuit can be used directly. This complete example compares two local runs of the same source with different shot totals; it does not demonstrate IBM connectivity:
mkdir -p artifacts/dam
uv run --locked qiskit-lab execute --qasm docs/examples/bell.qasm --shots 256 > artifacts/dam/local-256.json
uv run --locked qiskit-lab execute --qasm docs/examples/bell.qasm --shots 1024 > artifacts/dam/local-1024.json
uv run --locked qiskit-lab compare --left artifacts/dam/local-256.json --right artifacts/dam/local-1024.jsonThe saved stdout files contain the same receipts returned by the CLI. A
successful comparison reports compatibility.verified: true, shot totals 256
and 1024, and total variation distance between the sampled distributions.
It is not a test of quantum-state equivalence. These commands overwrite the two
named JSON files on repeat runs; the per-run artifact directories are preserved.
QAOA's best_bitstring and best_cut describe the best observed sample,
ranked by cut value, then sample frequency, then the smallest bitstring for a
deterministic tie. exact_cut remains the separately computed classical optimum;
expected_cut and approximation_ratio describe the optimized statevector
expectation, which can differ from the best finite-shot observation.
New execution and QAOA receipts include versioned comparison_metadata: a
SHA-256 identity of the logical source circuit and its classical registers and
measurement mapping. Hardware receipts preserve this metadata from before ISA
transpilation. compare validates binary count keys, bit widths, circuit identity
and measurement order before computing total variation distance. Different shot
totals are supported. Source identity uses normalized OpenQASM 3; it does not
prove equivalence between differently expressed circuits.
Older receipts or externally supplied counts lack this provenance and require an explicit opt-in:
scripts/dam/quantum compare --left OLD_LOCAL.json --right OLD_HARDWARE.json --allow-unverifiedSuch comparisons return compatibility.verified: false and a warning. The flag
does not bypass invalid counts, differing bit widths or known metadata mismatches.
Normal comparisons return compatibility.verified: true.
The following commands contact IBM and require the account configuration above.
Replace ibm_BACKEND and JOB_ID with actual values. Do not include them in an
offline smoke test:
scripts/dam/quantum doctor --online
scripts/dam/quantum backends
scripts/dam/quantum backend ibm_BACKEND --dashboard
scripts/dam/quantum job JOB_ID --output artifacts/dam/job.jsonOnly when you deliberately authorize one potentially billable QPU job:
scripts/dam/quantum execute --qasm docs/examples/bell.qasm --hardware --shots 1024A named backend also requires --hardware. Never automatically retry a
submission after an uncertain response. See the job-retrieval and report
instructions above. Offline tests use mocks for hardware contracts; passing CI
does not establish real IBM connectivity or execute a QPU job.
Command failures return JSON with error, error_category, and next_step.
Categories distinguish local_input, filesystem, rendering, dependency,
ibm, local_execution, and an internal fallback. Only application-authored
validation messages are displayed verbatim. Other diagnostics use exception
class names, never SDK bodies, request payloads, file contents, exception
chains, missing-module names, or credential values.
For local input failures, correct the options or public QASM/JSON receipt.
For filesystem failures, check readable inputs, writable output/temp directories
and disk space. For dependency failures, restore uv sync --locked (or the
documented environment for an optional workflow). Rendering diagnostics refer
to plotting/report dependencies and saved-receipt report regeneration, not
credentials. IBM diagnostics refer to service/network and instance/backend
access; never paste keys or raw SDK errors into an issue or chat.
Exit codes are unchanged: successful commands return 0, handled command failures
return 1, and argparse usage errors return 2. Usage errors now give a controlled
--help action on stderr without echoing potentially sensitive argument values.
Help remains available even when an SDK import fails. Recoverable HTML and PNG
errors keep the existing successful command status and completed scientific
receipts. HTML failures retain report_error and add report_error_category
and report_next_step; PNG failures retain dashboard_error and add
dashboard_error_category and dashboard_next_step. Job result-download and poll
errors similarly add safe categories and actions, cleared on recovery.
Consumers should tolerate these additive fields.
Once hardware submission starts, any failure warning still requires inspecting
existing IBM jobs tagged qiskit-lab-dam before retrying. A lost response is not
proof of rejection, including when the underlying exception resembles a local
dependency failure or when saving an accepted ID fails. There are no automatic
submission retries. The structured run/job IDs and submission outcome remain in
failure responses. Use the existing recover-submission command for an ambiguous
run, and query an already accepted ID again after download failures. Storage
failures before the submission call explicitly remain not_attempted, without
claiming a job may have been accepted. These diagnostics preserve the existing
submission-recovery and result-persistence features; they do not prove live IBM access.
For a kit-created agent, use DAM's Kit Update workflow and rerun the
checkout's bash scripts/dam/install.sh after the reviewed update to refresh
the locked environment and instruction entry points. Preserve existing results
and owner files. Do not recreate skipped schedules or replace owner-selected
cadence, models or enabled states.
For the private CLI fallback:
git pull
# Preview the exact target and tracked files without changing DAM.
python3 scripts/dam/deploy.py --existing --agent AGENT_ID --dry-run
python3 scripts/dam/deploy.py --existing --agent AGENT_ID --no-run
dam run AGENT_ID -p 'In ~/work/qiskit-lab verify IBM connectivity; do not submit jobs or run demos.'Existing-agent updates upload each tracked source file with dam file put.
They preserve experiment artifacts, job receipts, notifications, the installed
environment, owner files and existing networking rules. Files removed from Git
remain in DAM; review obsolete source files separately. An interrupted upload
can leave mixed source versions: rerun the same update to finish it before using
the kit. The deployer refreshes managed reporting instructions when needed while
preserving the schedule's enabled state, recurrence, timezone and model.
The SDK account stays outside the project directory. Do not delete the agent to
update it: deletion also removes its account and data.
If IBM access fails, check the API key, instance CRN, and rules for iam.cloud.ibm.com, resource-controller.cloud.ibm.com, api.global-search-tagging.cloud.ibm.com, globalcatalog.cloud.ibm.com, quantum.cloud.ibm.com, and the regional endpoint (us-east.quantum.cloud.ibm.com or eu-de.quantum.cloud.ibm.com). For another region, add the IBM hostname to the agent's DAM networking rules.
References: official starter kits and kit architecture.
Inside a Python 3.11-3.13 virtual environment, you can also install the package
with python -m pip install .; this installs the required SDK dependencies and
exposes qiskit-lab. Unlike uv sync --locked, pip resolves the dependency
ranges in pyproject.toml, not uv.lock. Run qiskit-lab doctor to inspect the
installed SDK versions, or python -m qiskit_lab --help.
docker build -t qiskit-lab .
docker run --rm qiskit-lab execute --example bell --shots 256The container installs the locked SDK environment during its build and runs the CLI as a non-root user. It does not start an HTTP server. With --rm and no mounted output directory, generated reports disappear when the container exits. To retain them on a Linux host, mount a directory writable by container UID 1000 and pass --output-dir /results:
mkdir -p artifacts/container
# Ensure artifacts/container is writable by UID 1000 before running.
docker run --rm -v "$PWD/artifacts/container:/results" qiskit-lab execute --example bell --shots 256 --output-dir /resultsThe JSON paths use /results; open the corresponding files under
artifacts/container/ on the host.
This repository currently has no project-level license file. Do not infer a license from the bundled third-party assets: the notices in assets/NOTICE.md cover those assets only. The bundled official Qiskit skills have their own Apache 2.0 license; it applies to those third-party skills, not to the rest of this repository. The repository owner must clarify licensing before others rely on permission to redistribute or reuse the project.