VQESamplingBenchmarkResult¶
from cascaqit import VQESamplingBenchmarkResult
VQESamplingBenchmarkResult ¶
VQESamplingBenchmarkResult(
benchmark_id: str,
algorithm_id: str,
hamiltonian_hash: str,
ansatz_hash: str,
logical_order: tuple[str, ...],
config: VQESamplingBenchmarkConfig,
runs: tuple[VQESamplingBenchmarkRunIR, ...],
statistics: tuple[VQESamplingStrategyStatisticsIR, ...],
optimality_claim: Literal[
"not_claimed"
] = "not_claimed",
schema_version: str = VQE_SAMPLING_BENCHMARK_SCHEMA_VERSION,
)
Retain all four strategies’ runs and summary statistics, usually from VQE.benchmark_sampling(). runs is ordered by repeat first, then the four canonical strategies. statistics follows exact, sampled_single, sampled_fixed and sampled_adaptive. Runs share the Hamiltonian, ansatz and logical order, and each paired repeat also shares seed and initial parameters.
Each run contains a complete VariationalResult. selected_estimator_energy is the strategy’s selected-point estimate; exact_selected_energy is its exact energy, with an independent exact_check for sampled strategies. estimator_error measures estimation error. paired_exact_reference_gap compares exact energy at that point with the same repeat’s exact-optimization selection, not with a true ground state. The exact strategy needs no additional exact_check.
Cost fields separate optimization evaluations, backend calls, shots, confirmation, final sampling and diagnostics. statistics summarizes repeated means, sample variances, standard errors, intervals, estimator RMSE and paired gaps. A small repeat count is suitable for demonstration, not a general superiority claim.
config retains the experimental design, while benchmark_id and referenced digests bind the content. optimality_claim remains not_claimed. Construction and restoration check the complete strategy matrix, pairing, costs, statistical sources and ID.
from cascaqit import HamiltonianTerm, OptimizerConfig, PauliHamiltonian, PauliZ, VQE
vqe = VQE(PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
logical_order=("q0",)))
from cascaqit import PauliMeasurementConfig, SampledSelectionConfig, VQESamplingBenchmarkConfig
config = VQESamplingBenchmarkConfig(
repeats=2, objective_evaluation_budget=8,
optimizer=OptimizerConfig(method="SPSA", max_iterations=1),
measurement=PauliMeasurementConfig(shots_per_group=16),
sampled_selection=SampledSelectionConfig(candidate_count=2, repeats_per_candidate=2),
final_shots=8, root_seed=7,
)
from cascaqit import VQESamplingBenchmarkResult
result = vqe.benchmark_sampling(config)
assert len(result.runs) == 8
assert tuple(item.strategy for item in result.statistics) == (
"exact", "sampled_single", "sampled_fixed", "sampled_adaptive")
assert all(item.objective_evaluation_count <= 8 for item in result.runs)
assert result.optimality_claim == "not_claimed"
assert VQESamplingBenchmarkResult.from_json(result.to_json()).stable_hash() == result.stable_hash()
create ¶
create(
*,
algorithm_id: str,
config: VQESamplingBenchmarkConfig,
runs: Sequence[VQESamplingBenchmarkRunIR],
) -> VQESamplingBenchmarkResult
Compute four strategy summaries and benchmark_id from a complete, canonically ordered sequence of completed VQESamplingBenchmarkRunIR records. It does not execute missing strategies. Input must be nonempty and cover all four strategies for every config.repeats iteration.
report ¶
report(
output: str | PathLike[str] | None = None,
*,
language: Literal["en", "zh"] = "en",
title: str | None = None,
) -> ExperimentReport
Return an algorithm-profile ExperimentReport, optionally saving HTML to output with a custom title. language affects the immediate save only; with output=None, specify language again for later rendering or saving. The directory must exist and an existing file can be overwritten, following visualize() rules.
Restore VQESamplingBenchmarkResult from a dictionary. Restore complete per-run results and exact diagnostics, rechecking strategy order, pairing, statistics and source identifiers. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning VQESamplingBenchmarkResult. Invalid JSON raises a parsing error; a non-object root raises TypeError.
Return a JSON-compatible dictionary of the complete record, including nested objects. This saves existing data without rerunning the experiment.
Return the complete record as a JSON string. indent controls formatting; no file is written.
Return the SHA-256 digest of the complete canonical JSON record for content comparison and provenance. It neither proves the experiment’s conclusion nor establishes physical equivalence.