AdamIterationIR¶
from cascaqit import AdamIterationIR
AdamIterationIR ¶
AdamIterationIR(
iteration_index: int,
config: AdamConfig,
center_objective_evaluation_index: int,
updated_objective_evaluation_index: int,
center_parameters: Mapping[str, float],
gradient_index: int,
gradient_hash: str,
gradient: Mapping[str, float],
gradient_covariance: Mapping[str, Mapping[str, float]],
gradient_standard_errors: Mapping[str, float],
gradient_uncertainty_norm: float,
gradient_repeat_count: int,
gradient_repeat_stop_reason: Literal[
"fixed_repeats",
"target_reached",
"max_repeats_reached",
"evaluation_budget_exhausted",
"backend_budget_exhausted",
],
previous_first_moment: Mapping[str, float],
previous_second_moment: Mapping[str, float],
first_moment: Mapping[str, float],
second_moment: Mapping[str, float],
bias_corrected_first_moment: Mapping[str, float],
bias_corrected_second_moment: Mapping[str, float],
step: Mapping[str, float],
bounds: Mapping[str, tuple[float, float]],
unprojected_parameters: Mapping[str, float],
updated_parameters: Mapping[str, float],
update_norm: float,
projection_applied: bool,
gradient_objective_evaluation_count: int,
gradient_backend_execution_count: int,
gradient_total_shots: int,
iteration_hash: str = "",
schema_version: str = ADAM_SCHEMA_VERSION,
)
Store one Adam update and its gradient references. Usually read this from result.optimization_starts[i].adam_iterations. iteration_index starts at 0. center_objective_evaluation_index and updated_objective_evaluation_index identify objective records before and after the update, with the latter immediately following the former. gradient_index/hash references saved gradient data without recomputing it.
| Fields | Meaning |
|---|---|
| center_parameters, gradient | Current parameters and saved gradient, using identical ordered parameter keys |
| gradient_covariance, gradient_standard_errors, gradient_uncertainty_norm | Gradient-estimate covariance, square roots of diagonal variances and sqrt(trace(covariance)), distinct from gradient magnitude |
| gradient_repeat_count, gradient_repeat_stop_reason | Repeat count and termination by fixed repeats, target, cap or budget |
| previous_, first_moment, second_moment, bias_corrected_ | Previous, updated and bias-corrected moments |
| step, unprojected_parameters, updated_parameters, bounds | Adam step vector, parameters after subtraction, projected parameters and bounds |
| update_norm, projection_applied | Actual parameter-update norm and whether the update was projected |
| gradient_objective_evaluation_count, gradient_backend_execution_count, gradient_total_shots | Costs of this gradient estimate, not total optimization costs |
Direct construction rechecks moments, update formulas, uncertainty, projection and the digest. An omitted or empty iteration_hash is computed; a supplied digest must match. Do not assemble inconsistent calculation records manually.
from cascaqit import HamiltonianTerm, OptimizerConfig, PauliHamiltonian, PauliZ, VQE
vqe = VQE(PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
logical_order=("q0",)))
from cascaqit import AdamIterationIR
from cascaqit.algorithms import GradientConfig
result = vqe.run(optimizer=OptimizerConfig(method="ADAM", max_iterations=1,
gradient=GradientConfig(), seed=7), initial_parameters=(0.4, 0.2), final_shots=8)
iteration = result.optimization_starts[0].adam_iterations[0]
assert iteration.verify_hash()
assert iteration.updated_objective_evaluation_index == iteration.center_objective_evaluation_index + 1
assert AdamIterationIR.from_json(iteration.to_json()).iteration_hash == iteration.iteration_hash
create ¶
create(
*,
iteration_index: int,
config: AdamConfig,
center_objective_evaluation_index: int,
updated_objective_evaluation_index: int,
center_parameters: Mapping[str, float],
gradient_index: int,
gradient_hash: str,
gradient: Mapping[str, float],
gradient_covariance: Mapping[str, Mapping[str, float]],
gradient_standard_errors: Mapping[str, float],
gradient_uncertainty_norm: float,
gradient_repeat_count: int,
gradient_repeat_stop_reason: Literal[
"fixed_repeats",
"target_reached",
"max_repeats_reached",
"evaluation_budget_exhausted",
"backend_budget_exhausted",
],
previous_first_moment: Mapping[str, float],
previous_second_moment: Mapping[str, float],
bounds: Mapping[str, tuple[float, float]],
gradient_objective_evaluation_count: int,
gradient_backend_execution_count: int,
gradient_total_shots: int,
) -> AdamIterationIR
Compute moments, bias correction, step, bound projection and digest from parameters, gradient, previous moments, configuration and source indices. Return AdamIterationIR. This computes one classical update without calling a backend or evaluating updated energy; supplied references and costs must come from actual records.
Compute a SHA-256 hex digest of saved fields excluding iteration_hash itself, without changing the object. This differs from stable_hash(), which includes the embedded digest.
Compare the saved iteration_hash with its recomputed value and return a boolean. This checks content consistency without rerunning a quantum experiment.
Restore AdamIterationIR from a dictionary. Restore gradient and moment fields, rechecking update formulas, covariance-derived values and digest. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning AdamIterationIR. 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.