UnifiedQuantum 0.0.16 — Pre-Release Test Report

Generated by /uniqc-test-before-release.

Second execution (2026-07-19, HEAD b17988b). The first run (2026-07-18) validated the release content as an uncommitted working tree and set one gating condition: commit the release content and re-validate. The maintainer committed everything (fea3d8b, 5d3bf3a, 5c0d0b3, b17988b) and rotated the CHANGELOG to [0.0.16] - 2026-07-19. This report supersedes the first one; the condition is met and the full suite was re-run against the committed candidate.

Verdict

Recommendation: RELEASE WITH KNOWN GAPS

All seven mandatory phases pass against the committed candidate at b17988b: the default test suite is green (2044 passed / 270 skipped / 0 failed), the full documentation example suite executes (49 pass / 5 skip / 0 fail, incl. all 12 best-practices chapters), the docs HTML build succeeds, the CLI matches its docs and executes every recommended workflow, the headline 0.0.16 feature (user-defined noisy virtual machines) works end-to-end through CLI, API, WebUI and noisy simulation, and the Gateway frontend builds and serves a healthy API. This validation produced three small follow-up fixes now in the worktree (regenerated C++ stub, three stale doc references) that should be committed before or with the tag — none affects runtime behavior. The remaining gaps are external and off the recommended path: IBM live discovery is rejected by IBM Quantum (invalid/expired token), Quark has no configured token, no real quantum task was executed (no quota authorization this session), and the uv sync developer path still fails on the pre-existing [quark]-extra resolution problem (documented; user-facing uv pip install / pip install works).

Release Candidate

  • Repository: UnifiedQuantum (IAI-USTC-Quantum/UnifiedQuantum, public)

  • Branch: main (aligned with origin/main, 0 ahead / 0 behind)

  • Commit: b17988b (fix(test): normalize whitespace in backend-virtual CLI assertion)

  • Tested state: committed HEAD (worktree clean at start: only untracked .agents/ and the plan file)

  • Tag/version candidate: v0.0.16 (git describe → v0.0.15-18-gb17988b; tag not yet created)

  • Version: 0.0.16.dev14 (uniqc/_version.py, regenerated at install; __commit_id__ = gd7001b7d4)

  • Test time: 2026-07-19 21:14–21:55 (+0800)

  • Tester/agent: Kimi Code CLI (/uniqc-test-before-release)

  • Machine/OS/Python/Node: WSL2 Linux, Python 3.10.20 (.venv), Node v22.22.2 / npm 10.9.7, uv 0.11.21

Executive Summary

Area

Status

Evidence

Notes

Python tests (default)

PASS

2044 passed, 270 skipped, 0 failed (276.1 s)

identical counts to first run; warnings are upstream qiskit-aer/qutip-qip deprecations

Python tests (--real-cloud-test)

NOT RUN

2312 collected (--collect-only)

no maintainer quota authorization this session

Best practices

PASS

build_docs.py --only 3_best_practices → pass=12 skip=0 fail=0

CJK-font warnings on matplotlib figures only

Docs HTML build (full)

PASS

make html → pass=49 skip=5 listed=3 fail=0, “build succeeded.”

pre-doc execution ran all examples, not just best-practices

C++ stubs

PASS (updated)

scripts/stubgen.py + ruff format → +6 lines

committed stub was stale: missing measure_qubit/reset_qubit (both classes) and qram(control_qubits=...); regenerated stub in worktree, matches UniqcCpp/Pybinder/uniqc_cpp.cpp:81-83,138-140

CLI

PASS

all 20 subcommand help captures + behavior workflows

backend virtual group works end-to-end

AI hints

PASS

always-ai-hint on/off/inspect, --ai-hint, UNIQC_AI_HINTS

banner appears on bare command when enabled; left off

Docs alignment

PASS (3 fixes)

scripted import/help/semantic checks

3 stale references found and fixed in worktree (below)

Gateway frontend

PASS

npm ci + npm run build → 2216 modules, dist/

tsc + vite, index-iAbyOz8y.js

Gateway API

PASS

health/version/backends/tasks; React app serves dist

/api/backends excludes chip-backed dummy, includes virtual:*

Cloud discovery (OriginQ)

PASS

backend update --platform originq → 7 backends (live)

chip-display originq/WK_C180 --update live calibration OK

Cloud discovery (IBM)

BLOCKED

“Unable to retrieve instances … valid API token”

3 cached backends still listed; external token issue

Cloud discovery (Quark)

BLOCKED

no backends; no quark section in config

external

Real-device execution

NOT RUN

—

no quota authorization

Calibration/QEM/XEB

PASS (code path)

best-practices 09/10 (dummy noise), new ThermalRelaxation covered by virtual-machine tests

real-chip calibration not run

Install (uv sync)

FAIL (pre-existing, documented)

uv sync ... --dry-run re-confirmed: universal resolver can’t solve quarkcircuit for 3.12–3.14

user-facing uv pip install/pip install works; not a 0.0.16 regression

Blocking Issues

None. The first run’s blocker B-1 (release content uncommitted) is resolved: HEAD b17988b contains the full 0.0.16 feature set, the CHANGELOG is rotated to [0.0.16] - 2026-07-19, and the worktree was clean at test start. B-2 (uv sync resolution) is reclassified as a non-blocking documented limitation (below) — unchanged from v0.0.15, and the recommended user install path is unaffected.

Non-Blocking Gaps

  • IBM discovery degraded (external). Failed to fetch ibm backends: 'Unable to retrieve instances. Please check that you are using a valid API token.' Token present but rejected by IBM Quantum; 3 cached backends (ibm_fez, ibm_kingston, ibm_marrakesh, 45 d stale) still listed. Nested-proxy config path re-verified: config set ibm.proxy.https http://127.0.0.1:7890 creates nested default.ibm.proxy.https (config restored byte-identical afterwards; note uniqc config has no unset subcommand).

  • Quark discovery unavailable (external). No quark section in ~/.uniqc/config.yaml.

  • Real-device execution not validated. --real-cloud-test collected (2312) but not executed; no real quantum task submitted — not authorized in this session. Discovery + dry-run paths covered instead.

  • uv sync universal resolution fails (pre-existing, documented). Re-confirmed this run: unsatisfiable quarkcircuit{python_full_version >= '3.12' and < '3.14' and sys_platform != 'win32'} under uv’s universal resolver. pyproject.toml unchanged from v0.0.15; docs/source/1_basic_usage/best_practices.md already documents the uv pip install path. Not a 0.0.16 regression.

  • Help inconsistency (minor, cosmetic). backend list --platform advertises quark, but backend update --platform and result --platform list only originq/quafu/ibm.

  • WK_C180 dry-run topology (correct behavior). Naive 2-qubit Bell (CNOT q[0],q[1]) --dry-run on dummy:originq:WK_C180 is rejected with Unsupported topology (qubits 0–1 not coupled on WK_C180); single-qubit dry-run passes. Worth a doc sentence showing region compilation before chip-backed dry-run.

  • Gateway visual coverage. No browser automation available; verified via HTTP responses + built-asset inspection. Interaction coverage is a gap.

Environment and Setup

  • Existing .venv (Python 3.10.20) built with uv pip install --python .venv/bin/python -e ".[all]" + dev/docs deps (because uv sync fails, above). Commands invoked as .venv/bin/uniqc / .venv/bin/python.

  • .venv/bin/uniqc --version → uniqc 0.0.16.dev14; import uniqc OK; CLI entry uniqc = "uniqc.cli.main:app" present; python -m uniqc.cli works (bare python -m uniqc correctly fails and docs say so).

  • Frontend: cd frontend && npm ci → clean; npm run build → success.

  • Config: ~/.uniqc/config.yaml, profile default. Tokens: originq, ibm (rejected server-side), quafu (deprecated) present; quark absent. always_ai_hints left false.

  • Note for maintainers: scripts/stubgen.py invokes pybind11-stubgen by bare name — run it with .venv/bin on PATH.

Best-Practices Validation

.venv/bin/python scripts/build_docs.py --only 3_best_practices → pass=12 skip=0 listed=0 fail=0. The subsequent full cd docs && make html re-executed the entire example suite (pass=49 skip=5 listed=3 fail=0) and finished with “build succeeded.”; _build/html produced.

Per-notebook status: all 12 best-practices chapters (00_config_and_backend_cache … 11_native_torch_training) executed cleanly, including the Torch examples (08/11) and calibration/QEM/XEB dummy-noise examples (09/10). No doc/software mismatch in generated chapters; command names match current help. Regenerated chapter diffs vs HEAD are stochastic only (task IDs, shot counts) — e.g. 04_api_submit_dummy_result.md differs solely in task_id. 7_releases/_generated/strict_history.md correctly reflects 18 commits / v0.0.15…HEAD. Best-practices chapter is aligned with software behavior.

(Cosmetic only: matplotlib CJK “glyph missing from DejaVu Sans” warnings for Chinese figure labels; figures still generated.)

CLI Validation

Help captured (20/20 exit 0): root, python -m uniqc.cli, circuit, simulate, submit, result, config, task, backend + list/show/update/chip-display, backend virtual + init/list/show/validate, calibrate, gateway. All commands in docs/source/4_cli/*.md exist in --help and all documented option spellings match (--format/--output/--info, --shots, --wait/--timeout, --update, --force, --status/--all/--info, xeb/readout/pattern, start/stop/restart/status, init/set/get/list/validate/profile/always-ai-hint). No doc recommends uniqc workflow (docs explicitly negate it) or bare python -m uniqc. submit has a single --backend/-b flag and no --platform; --platform exists on backend list/update, task list, result.

Behavioral workflows (Bell-state OriginIR, /tmp/cli_check/bell.originir):

  • circuit --info → Qubits 2 / Cbits 2 / Depth 2 / Gates 2 + QASM dump.

  • simulate → 00 50.0% / 11 50.0% (statevector, 1024 shots).

  • submit --backend dummy:local:simulator --wait → 50/50. submit --backend dummy:local:virtual-line-3 --wait → 50/50.

  • submit --backend dummy:originq:WK_C180 --dry-run → correctly rejected (Unsupported topology, no 0–1 coupling); single-qubit dry-run → ✓ [DRY-RUN PASSED].

  • backend show originq:WK_C180 → 180 qubits, 1Q 0.9983 / 2Q 0.9638 / readout 0.9557, edge table.

Headline 0.0.16 feature (all pass): backend virtual init release-check-r2 → ~/.uniqc/backend/virtual/release-check-r2.yaml; list → 4 qubits / 3 edges / all noise layers, status ok; show → uniform depol (1q 0.001 / 2q 0.01), gate-type CZ 0.02, instance overrides (CZ[0,1] 0.05, H[2] 0.003), T1/T2 + readout tables; validate → valid; submit --backend dummy:virtual:release-check-r2 --wait → noisy Bell: 00 47.8% / 11 47.6% / 01 2.3% / 10 2.3% (noise model applied). backend list shows virtual:release-check-r2; no dummy:<platform>:<backend> ID is enumerable.

AI hints: config list --ai-hint prints the banner; config always-ai-hint on → a bare backend list prints the AI Workflow Hints banner without any flag; config always-ai-hint off → banner gone; final state confirmed off (always_ai_hints: false). All --ai-hints / --ai-hint / UNIQC_AI_HINTS=1 / always-ai-hint surfaces consistent with docs (4_cli/config.md:53-72, backend.md:17, walkthrough.md:31, 1_basic_usage/best_practices.md:20-25).

Docs match help output and behavior (after the three fixes below).

Gateway Frontend/API Validation

  • cd frontend && npm ci && npm run build → tsc + vite, 2216 modules, dist/{index.html,assets/index-iAbyOz8y.js,index-Bc1qIVFS.css}.

  • .venv/bin/uniqc gateway start --host 127.0.0.1 --port 18765 → running (status confirms PID/URL); gateway stop → clean shutdown.

  • GET /api/health → {"status":"ok"}.

  • GET /api/version → {"version":"0.0.16.dev14", github_url, docs_url}.

  • GET /api/backends → {originq:7, quafu:16, quark:0, ibm:3, dummy:5}. Dummy entries exactly: dummy:local:simulator, dummy:local:virtual-line-3, dummy:local:virtual-grid-2x2, dummy:local:mps-linear-3, dummy:virtual:release-check-r2. No chip-backed dummy:originq:… enumerated (correct); user virtual machine present (release feature visible in WebUI).

  • GET /api/tasks → dummy tasks incl. the virtual-machine task with full metadata (circuit_ir, circuit_language, dummy_backend_id) — task pages can render dummy tasks.

  • GET / → serves built index-iAbyOz8y.js + <div id="root"> (React app mounts dist).

  • Visual gap: no browser automation available; interaction coverage marked as a gap.

Cloud and Real-Device Validation

  • Discovery — OriginQ: PASS (live). backend update --platform originq → “Updated: originq (7 backends)”; backend list --platform originq; backend show originq:WK_C180; backend chip-display originq/WK_C180 --update → live per-qubit/per-edge calibration (CX fidelities 0.91–0.97 sampled).

  • Discovery — IBM: BLOCKED (external). Unable to retrieve instances. Please check that you are using a valid API token. 3 cached backends still listed (45 d stale). Cause: invalid/expired IBM token.

  • Discovery — Quark: BLOCKED (external). No quark section in config; no backends.

  • Discovery — Quafu: deprecated. SDK not installed; 16 cached backends (81 d stale). Quafu documented as archived, not in [all].

  • Dry-run: PASS. submit --backend dummy:originq:WK_C180 --dry-run validates translation/gates/topology without network (correct 2q-Bell topology rejection; 1q passes).

  • Execution: NOT RUN. No real quantum task submitted; --real-cloud-test suite collected (2312) but not executed — no maintainer quota authorization this session.

Programmatic Documentation Alignment

  • Scripts vs docs: pyproject.toml [project.scripts] → uniqc = "uniqc.cli.main:app"; docs use uniqc / python -m uniqc.cli only. ✓

  • CLI docs vs help: every docs/source/4_cli/*.md command exists in --help; option spellings match. ✓

  • Removed top-level imports: uniqc.transpiler/task/qasm/originir/pytorch/analyzer all ModuleNotFoundError; docs/examples reference them only as negative guidance (“新代码不应继续依赖…”). Best-practices examples import current APIs (from uniqc import …, uniqc.backend_adapter, uniqc.simulator, uniqc.compile.originir, uniqc.calibration.readout, uniqc.qem, uniqc.circuit_builder.qcircuit, uniqc.torch_adapter.expectation). ✓

  • Dummy semantics: docs (submit_task.md:189-195, submit.md:30-49, backend.md:19, workflow.md:98-113, 2_advanced/virtual_backends.md) match observed CLI + /api/backends behavior. ✓

  • Config path: ~/.uniqc/config.yaml consistent everywhere after fix F-2 (below). Unified state dir ~/.uniqc/backend/ in use; tasks DB at ~/.uniqc/cache/tasks.sqlite after fix F-3. ✓

  • AI hints: all surfaces verified (above). ✓

  • IBM proxy nested key: ibm.proxy.https dotted-key nesting verified; config restored. ✓

  • Quafu deprecation: pyproject has no quafu extra; all = [pyqpanda3, qutip, qutip-qip, matplotlib, seaborn, pandas, torch, dill]; docs call Quafu archived/deprecated after fix F-1. ✓

Mismatches found this run — fixed in worktree (uncommitted)

  • F-1 docs/source/0_quickstart/installation.md:226-227 — claimed [all] includes [quafu]; the extra was removed. Fixed to list [simulation]+[visualization]+[pytorch]+[originq] and note Quafu’s removal (now consistent with the same page’s deprecation list at line 249).

  • F-2 docs/source/4_cli/gateway.md:3,53 — stale ~/.uniqc/uniqc.yml and ~/.uniqc/gateway.pid. Fixed to ~/.uniqc/config.yaml (gateway: section) and ~/.uniqc/cache/gateway.pid / gateway.log (matches uniqc/gateway/cli.py:27,132 and live behavior).

  • F-3 docs/source/4_cli/walkthrough.md:21, docs/source/5_webui/index.md:35 — stale ~/.uniqc/tasks.db. Fixed to ~/.uniqc/cache/tasks.sqlite (verified on disk; doctor.md:32 was already correct).

  • F-4 uniqc/simulator/uniqc_cpp.pyi — committed stub stale vs the built extension: missing measure_qubit / reset_qubit on both StatevectorSimulator and DensityOperatorSimulator, and qram(..., control_qubits=[]). Regenerated via scripts/stubgen.py + ruff format (+6 lines, matches UniqcCpp/Pybinder/uniqc_cpp.cpp bindings). Type-stub only — no runtime impact.

All four are in the worktree pending commit. Additionally the docs build refreshed 32 generated chapters + example-exec-logs/ run records (stochastic outputs and the new strict-history range) — commit them as a routine generated-artifacts refresh, as was done in 5c0d0b3.

Final Recommendation

RELEASE WITH KNOWN GAPS. The first run’s gating condition is satisfied — v0.0.16 can be tagged at a commit containing the full release content. Before (or with) tagging, commit this validation’s follow-up fixes: the regenerated C++ stub (F-4), the three doc fixes (F-1…F-3), and optionally the refreshed generated docs artifacts. None of them changes runtime behavior, so no re-test cycle is required after committing them (the stub is type-only; doc fixes are prose).

Accepted gaps (do not block release): IBM discovery (invalid token, external), Quark (no token, external), real-device execution (not authorized this session), gateway visual coverage (no browser tool), and the documented pre-existing uv sync/[quark] resolver limitation. When IBM/Quark credentials are restored and/or quota is authorized, re-run discovery and the --real-cloud-test suite as a follow-up.