Documentation version

Standard Experiment Visualization¶

Use visualize() to turn an existing result into a complete standalone HTML report. The report is derived from the result you already executed; it does not run the program again.

from cascaqit import visualize

report = visualize(result, program=program, output="experiment.html")

program is optional, but passing it for a single Digital, Analog, or Hybrid result adds the program design to the report. The output embeds the core BokehJS runtime, needs no web service or CDN, and can be opened locally. Use the language selector in the report header to switch the standard interface between English and Chinese. The switch also updates supported chart axes, legends, tool descriptions and hover labels, including plots that finish loading later. It preserves chart data, current pan/zoom ranges and the embedded result JSON. The returned ExperimentReport also provides sections, section(), to_dict(), to_json(), to_html(), stable_hash(), html_hash(), and save().

What The Report Shows¶

Every profile follows the same experiment lifecycle:

Stage	Evidence
Design	Program kind and hash, parameters, measurements, register snapshot/status, phase patterns, site-addressing frames, available program structure, canonical Problem facts, and explicit penalty model when present.
Validate	Diagnostics grouped by stage and severity, including control-constraint checks, blocking errors, and warnings.
Plan	Compile or simulation plan, control schedule, mappings, Hamiltonian term assignment, selected method, resource estimate, and noisy objective request when present.
Execute	Backend, method, device, seed, steps, workers, wall time, memory evidence, trace, selected objective execution, and source/runtime Program lineage.
State / Noise	State summary and hash, Hybrid state handoff, runtime register snapshot, addressing/phase-pattern consumers, and physical-noise injection records.
Measure	Shots, counts, probabilities, bit or occupation encoding, uncertainty fields, and final-sampling noise execution.
Analyze	Observables, scan trends, decoded Problem candidates, business/penalty/total energy decomposition, observed and running-best objectives, feasibility and constraint metrics, parameter trajectories, bounded baseline gaps, item failures, or differences between aligned runs.

Missing source facts are shown as unavailable with a reason. The renderer does not infer hardware facts or present roadmap intent as completed behavior.

Atom arrangements, the combined Rabi/detuning/phase waveform plot, measurement distributions, and scan trends use interactive Bokeh plots with pan, zoom, reset, save, and hover tools. Bokeh is a required CASCAQit runtime dependency. Each standalone report embeds the core BokehJS runtime once. Model-id normalization keeps html_hash() stable for identical report content; a new simulation may record different wall time or process RSS and therefore produce different report content and hashes.

Profiles¶

visualize() detects the source and selects the matching report profile:

Source	Profile-specific content
Digital `ResultIR`	Circuit gates, qubit order, measurement registers, counts, probabilities, and Z observables.
Analog `ResultIR`	Atom arrangement and status, active order, global/local controls, addressing, phase patterns, control diagnostics, waveforms, occupation, and probabilities.
Hybrid `ResultIR`	Digital/Analog block order, mapping, register/control evidence, atom and waveform views, state handoff, noise trace, and terminal measurement.
Scan result	Parameter table, item status, counts, observable trends, failures, and resource plan.
`ResultIR` mapping	Source alignment plus counts, probability, observable, method, noise, and resource differences.
Batch result	Aggregate status, item/result references, partial failures, and diagnostics.
`SampledObjectiveEvaluationIR`	QWC plan and basis rotations, group Jobs and raw counts, Pauli contributions, covariance-aware uncertainty, and final energy. Readout-mitigated evaluations add calibration identity and condition numbers, side-by-side raw/mitigated contributions and group statistics, variance amplification, and both confidence intervals.
`VariationalResult`	Hamiltonian, ansatz, optimizer-start boundaries and termination, SPSA online stopping configuration/window/checks when enabled, objective history, final-center objective, final counts, decoded candidate, baseline, gap, and provenance. Noisy runs also show the requested channels/options, selected SimulationPlan and NoiseReport, estimator, uncertainty, Backend Job/cost, and separate final-sampling execution.
`VQEStabilityDiagnosticResult`	Selected-start status, configured thresholds, terminal objective proxies, update and gradient norms, sampled uncertainty and repeats, optimizer termination, budget limits, and explicit no-optimality/no-convergence claims.
`VQERepeatedLayerExperimentResult`	Every stored VQE layer/repeat run, raw objectives, Student-t intervals, paired improvement lower bounds, selection and stopping evidence, cumulative execution cost, and the selected run's complete Algorithm lifecycle and counts.
`ProblemExecutionResult`	Canonical objective, logical Hamiltonian, penalty sufficiency when defined, Target mapping, term assignment, parameter schema, generated Native Program, per-start execution and SPSA stopping evidence, counts, decoded candidates, expected and per-candidate energy decomposition, objective history, feasibility, constraint violations, parameter trajectories, and bounded baseline gaps. Noisy Digital runs retain source and runtime Program hashes instead of hiding the physical-noise wrapper.
`ProblemExecutionResult` mapping	Completed runs for one Problem, including layer/configuration comparisons and Digital QAOA, Digital VQE, Hybrid QAOA, or Analog QAA route comparisons.
`ProblemLayerExperimentResult`	Completed contiguous layer runs plus the minimum-improvement threshold, numeric tolerance, patience, warm-start source, per-layer improvement, incumbent, selected depth, stop reason, and total evaluation count.
`ProblemRepeatedLayerExperimentResult`	Every completed layer/repeat optimization, raw objective samples, mean and Student-t interval, paired improvement and lower confidence bound, selected depth, stop reason, and complete optimization/evaluation cost.

The Analog and Hybrid waveform panels include duration, time/value units, and global or local control scope. A separate addressing timeline lists every frame, active site/weight, source kind, and addressing hash; the State section identifies the numerical consumer recorded by the runtime.

Common Calls¶

Save a single result with design context:

visualize(result, program=program, output="experiment.html")

Save later or inspect the structured report first:

report = visualize(result)
measurement = report.section("experiment.measure")
report.save("experiment.html")

Compare aligned results without rerunning them:

visualize(
    {"ideal": ideal_result, "noisy": noisy_result},
    output="comparison.html",
)

Render a completed parameter scan:

visualize(scan_job.result(), output="sweep.html")

Render an existing QAOA or VQE result without rerunning the optimizer:

visualize(variational_result, output="algorithm.html")

A fixed-parameter sampled VQE evaluation uses the same call. When readout mitigation is enabled, read the calibration source/hash and condition numbers first, then compare raw and mitigated Pauli contributions and each group's variance amplification. The counts plot remains the raw integer Backend evidence; the report does not replace it with quasi probabilities or rerun the measurement.

Render a completed VQE stability diagnosis without adding Backend work:

diagnostic.report("vqe-stability.html", language="en")
# Equivalent generic entry:
visualize(diagnostic, output="vqe-stability.html")

Render a compiled Problem execution without rerunning or recompiling it:

visualize(problem_execution, output="problem.html", language="en")
# Equivalent convenience API:
problem_execution.report("problem.html", language="en")

Render a completed automatic layer experiment without adding optimizer or Backend work:

visualize(layer_experiment, output="problem-layer-experiment.html")
# Equivalent convenience API:
layer_experiment.report("problem-layer-experiment.html", language="en")

For sampled Digital VQE, the layer table labels independently confirmed energy as Layer objective and keeps the final computational-basis Problem objective separate. The cost summary splits objective, confirmation, and final-sampling Jobs and shots. Rendering reads these stored facts and does not add work.

Render a completed repeated-layer experiment from its stored statistical evidence:

visualize(
    repeated_layer_experiment,
    output="problem-repeated-layer-experiment.html",
)
# Equivalent convenience API:
repeated_layer_experiment.report(
    "problem-repeated-layer-experiment.html",
    language="en",
)

The same calls accept a standalone VQERepeatedLayerExperimentResult. Its report uses the algorithm profile and shows the lowest-objective run at the statistically selected layer as the detailed lifecycle view.

Compare completed results after each execution has finished. Different layers are one case:

visualize(
    {
        "p=1": result_p1,
        "p=2": result_p2,
        "p=3": result_p3,
    },
    output="qaoa-layers.html",
)

The same API accepts different routes:

visualize(
    {
        "Digital QAOA": digital_qaoa_result,
        "Digital VQE": digital_vqe_result,
        "Hybrid QAOA": hybrid_qaoa_result,
        "Analog QAA": analog_qaa_result,
    },
    output="problem-routes.html",
)

All executions must share problem_hash and logical variable order. Mode, algorithm, Target, compile/program identity, layer count, optimizer budget, and shots may differ and remain visible per source. Objective and energy decomposition use the same canonical Problem and are directly aligned. Candidate distributions remain qualified by shots and probability source; convergence and local resource measurements are evidence only and are not ranked. The comparison does not call a Backend or optimizer.

The serialized ProblemExecutionContextIR carries the analysis, penalty model when defined, term mapping, parameter schema, and exact Digital, Analog, or Hybrid Native Program snapshot. A Problem report can therefore be rebuilt after JSON round-trip without the original compiler object. For plain QUBO/Ising, the report labels penalty analysis as not applicable instead of inferring penalty semantics from coefficients.

For the most complete offline 3x3 atom-array example, run:

python3 examples/user/complete_physical_hybrid_demo.py \
  --output examples/user/assets/complete_physical_hybrid_report.html

This preserves separate Hybrid, Comparison, ideal Sweep, and noisy Sweep reports. digital_workflow.py and analog_workflow.py demonstrate the same API for single-mode results.

To focus on register preparation, Target control constraints, and per-site phase, run:

python3 examples/user/experiment_control_and_register.py \
  --output examples/user/assets/experiment_control_register_report.html

To compare all three Problem compilation modes on one 3x3 MIS instance, run:

PYTHONPATH=src python3 examples/user/problem_compiler_3x3_mis.py \
  --output-dir artifacts/problem_compiler_3x3_mis \
  --language en

The command saves separate Digital, Hybrid, and Analog Problem reports plus a cross-route report. Each mode evaluates two real parameter points; the comparison reuses those completed results rather than executing more Jobs.

For weighted result semantics and all four executable routes, run:

PYTHONPATH=src python3 examples/user/problem_compiler_mwis.py \
  --output-dir artifacts/problem_compiler_mwis \
  --language en

MWIS reports add a node-weight table, selected weight per candidate, and expected selected weight for the complete result distribution. The comparison includes Digital QAOA, Digital VQE, Hybrid QAOA, and Analog QAA results from the same canonical problem.

To run and retain the automatic Hybrid QAOA layer example:

PYTHONPATH=src python3 examples/user/problem_layer_experiment.py \
  --output artifacts/problem_layer_experiment.html

The script executes p=1 and p=2 with the same per-layer optimizer budget. The report states whether p=2 met the configured improvement threshold, which layer remained selected, why execution stopped, and how many objective evaluations were used.

To compare layer depths from independent optimizer repeats:

PYTHONPATH=src python3 examples/user/problem_repeated_layer_experiment.py \
  --output artifacts/problem_repeated_layer_experiment.html

The example runs two complete Digital QAOA optimizations at p=1 and p=2. Its report shows every run, each layer's mean and Student-t interval, the paired lower confidence bound, the selected depth, and the four optimization runs' total Backend evaluation cost.

To run the same statistical depth workflow for a general Pauli Hamiltonian:

PYTHONPATH=src python3 examples/user/vqe_repeated_layer_workflow.py \
  --output artifacts/vqe_repeated_layer_experiment.html \
  --language en

The report keeps all four VQE optimizations, confidence evidence, cumulative Backend cost, and final-sampling Jobs. The selected-run panels show the lowest-objective repeat at the selected depth; they do not replace the other repeats or imply global optimality.

Current Limits¶

HTML is the only report export format; PNG and PDF export are not provided.
The standard UI switches between English and Chinese; user data, identifiers, diagnostics, and units are not translated. Reports are static artifacts rather than live dashboards.
Comparison accepts aligned ResultIR values, ProblemExecutionResult values for one canonical Problem, one ProblemLayerExperimentResult, or one ProblemRepeatedLayerExperimentResult. A mapping cannot mix result types, and comparison does not accept separate program context. Cross-route output does not normalize unequal optimizer budgets, shots, host load, or route-specific resource units.
Repeated-layer intervals and paired lower bounds describe the stored independent optimizer runs under one configuration. They do not establish global optimality, hardware performance, or quantum advantage.
A Batch result currently exposes aggregate status and result references; child result measurements are unavailable when the Batch contract does not carry their payloads.
Rendering reads structured program/result metadata only. It does not execute a Job, access the network, load credentials, or read external artifact bytes.

SDK 1.0.8a · `8b227bff`