SPSAConfig¶
from cascaqit import SPSAConfig
SPSAConfig ¶
SPSAConfig(
learning_rate: float | None = 0.2,
perturbation: float = 0.1,
stability_constant: float = 0.0,
learning_rate_exponent: float = 0.602,
perturbation_exponent: float = 0.101,
directions_per_iteration: int = 1,
objective_repeats: int = 1,
max_objective_repeats: int | None = None,
objective_standard_error_target: float | None = None,
learning_rate_calibration: SPSALearningRateCalibrationConfig
| None = None,
stopping: SPSAStoppingConfig | None = None,
schema_version: str = ALGORITHM_SCHEMA_VERSION,
)
Configure simultaneous perturbation stochastic approximation (SPSA): gain schedules, random directions and repeated objective estimates. Random plus/minus perturbations estimate gradients without separately differentiating every parameter. Each direction still needs both objective values, and repeats add cost.
For zero-based iteration k, the learning rate is a / (k + 1 + A)**alpha and perturbation is c / (k + 1)**gamma. Here a is learning_rate, c is perturbation and A is stability_constant. Require c > 0, A >= 0, alpha in (0.5, 1], gamma in [0, 0.5] and alpha-gamma > 0.5. A fixed learning-rate scale a must be positive. With learning_rate_calibration enabled, explicitly set learning_rate=None.
directions_per_iteration is the positive number of directions per update. objective_repeats is either the fixed repeats per logical objective or the initial count for adaptive estimation. Adaptive mode requires both max_objective_repeats and a positive objective_standard_error_target, at least 2 initial repeats, and a strictly larger maximum. The target concerns repeated-estimate standard error, not error relative to the true energy. Repetition also stops at its cap or budget.
Currently objective_repeats > 1 requires sampled VQE and cannot be used directly with exact objectives. Plus/minus points and updates are projected into parameter bounds; a direction collapsing to the same point raises. Optional SPSAStoppingConfig adds stopping rules whose uncertainty conditions require enough directions or repeats.
from cascaqit import SPSAConfig
fixed = SPSAConfig(learning_rate=0.2, perturbation=0.1)
adaptive = SPSAConfig(objective_repeats=2, max_objective_repeats=5,
objective_standard_error_target=0.02)
assert fixed.objective_repeat_mode == "fixed"
assert adaptive.objective_repeat_mode == "adaptive"
assert adaptive.effective_max_objective_repeats == 5
assert SPSAConfig.from_json(adaptive.to_json()) == adaptive
Return fixed when max_objective_repeats is unset, otherwise adaptive. This describes configuration, not whether a run reached its error target.
Return objective_repeats in fixed mode or max_objective_repeats in adaptive mode. The limit applies to one logical objective, not the entire optimization.
Restore SPSAConfig from a dictionary. Omitted fields use defaults; nested configurations are restored and validated. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning SPSAConfig. Invalid JSON raises a parsing error; a non-object root raises TypeError.
Fixed mode omits the two adaptive fields; unused stopping and learning_rate_calibration fields are also omitted. Return a JSON-compatible dictionary, serializing nested objects and converting tuples to arrays. This stores the declaration, not an execution result.
Return a JSON string without writing a file. indent=None uses compact formatting; supply an indentation width for readable output.
Return the SHA-256 hex digest of canonical JSON. Fields, identifiers and metadata can affect it. Use it to compare saved content, not to decide physical equivalence.