VariationalResult¶
from cascaqit import VariationalResult
VariationalResult ¶
VariationalResult(
algorithm_run_id: str,
algorithm_kind: AlgorithmKind,
hamiltonian: PauliHamiltonian,
ansatz: AnsatzSpecIR,
optimizer: OptimizerConfig,
evaluations: tuple[VariationalObjectiveT, ...],
best_evaluation_index: int,
termination: OptimizerTerminationIR,
gradients: tuple[ObjectiveGradientIR, ...] = (),
optimization_starts: tuple[
OptimizationStartIR, ...
] = (),
selected_start_index: int | None = None,
sampled_selection: SampledSelectionIR | None = None,
final_result: ResultIR | None = None,
most_probable_candidate: AlgorithmCandidateIR
| None = None,
best_observed_candidate: AlgorithmCandidateIR
| None = None,
baseline: ClassicalBaselineIR | None = None,
cardinality_subspace: CardinalitySubspaceEvidenceIR
| None = None,
problem_id: str | None = None,
problem_hash: str | None = None,
optimality_claim: Literal[
"not_claimed"
] = "not_claimed",
metadata: Mapping[str, Any] = dict(),
schema_version: str = ALGORITHM_SCHEMA_VERSION,
)
Complete VQE or QAOA workflow result linking the Hamiltonian, ansatz, optimizer, objective evaluations, gradients, multiple starts, confirmation measurements and final backend result. Usually returned by an algorithm’s run(). Direct construction mainly serves restoration or advanced integration and validates references, provenance, selection and record consistency.
evaluations retains optimization history. With repeated SPSA estimates, best_evaluation_index identifies the source record for the selected pooled objective; otherwise it selects the lowest observed energy. Independent confirmation can select a different point, so read selected_evaluation for final sampling. It returns the corresponding optimization-history record; pooled confirmation statistics are in sampled_selection. termination and each optimization_starts[i].termination explain why execution stopped. success alone does not establish global optimality.
Optional final_result is a ResultIR containing final computational-basis samples. most_probable_candidate is the most frequent candidate, while best_observed_candidate is the best observed candidate by the problem objective. General Pauli Hamiltonians may have no classical candidates or baseline. cardinality_subspace retains applicable fixed-cardinality subspace records, problem_id/hash retains provenance, and optimality_claim remains not_claimed.
Account for optimization, confirmation, final sampling and independent diagnostics separately. The length of evaluations is not a substitute for backend calls or total shots.
from cascaqit import HamiltonianTerm, OptimizerConfig, PauliHamiltonian, PauliZ, VQE
vqe = VQE(PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
logical_order=("q0",)))
result = vqe.run(optimizer=OptimizerConfig(method="SPSA", max_iterations=2, seed=7),
initial_parameters=(0.4, 0.2), final_shots=16)
from cascaqit import VariationalResult
assert result.best_evaluation.energy == min(item.energy for item in result.evaluations)
assert result.selected_evaluation is result.best_evaluation
assert sum(result.final_result.counts.values()) == 16
restored = VariationalResult.from_json(result.to_json())
assert restored.stable_hash() == result.stable_hash()
assert restored.optimality_claim == "not_claimed"
Return evaluations[best_evaluation_index]. Repeated SPSA estimation selects by pooled objective across starts, so this source record need not have the lowest individual sampled energy. Inspect each start’s best_objective and the pooled estimates. Other paths select minimum observed energy. Neither establishes a true minimum.
Equal to best_evaluation without confirmation; otherwise return the original evaluation indexed by sampled_selection.selected_source_evaluation_index. Confirmation statistics do not overwrite that source record.
Return the first gradient record’s shared ParameterShiftPlanIR, or None without explicit gradients. SPSA perturbation records live in each start’s spsa_iterations and are not returned here.
diagnose_stability ¶
diagnose_stability(
config: VQEStabilityConfig | None = None,
) -> VQEStabilityDiagnosticResult
Derive VQEStabilityDiagnosticResult from saved records without rerunning optimization. config=None uses default thresholds. Currently requires native-SPSA VQE with optimization_starts; QAOA, Adam and other optimizers are rejected.
Restore VariationalResult from a dictionary. Restore exact or sampled evaluations, gradients, starts, confirmation and final ResultIR, then recheck links and derived results. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning VariationalResult. 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.