Documentation version

SPSALearningRateCalibrationConfig¶

from cascaqit import SPSALearningRateCalibrationConfig

SPSALearningRateCalibrationConfig ¶

SPSALearningRateCalibrationConfig(
    directions: int = 5,
    target_update_rms: float = 0.1,
    gradient_rms_floor: float = 1e-08,
    max_learning_rate: float | None = None,
    schema_version: str = ALGORITHM_SCHEMA_VERSION,
)

Estimate a gradient scale before SPSA iterations and use it to choose the learning rate. directions must be a positive calibration-direction count; target_update_rms is the positive intended RMS of the first update. Calibration evaluates the objective and consumes evaluation and backend budgets.

Let g be the RMS of the mean calibration gradient across parameters. The learning-rate scale is target_update_rms * (1 + stability_constant)**learning_rate_exponent / g. A g below the positive gradient_rms_floor raises rather than flooring the denominator. If the computed rate exceeds an optional positive max_learning_rate, it also raises rather than clipping the rate.

Supply this as SPSAConfig.learning_rate_calibration and set learning_rate=None. Bound projection and estimation noise can make the actual update differ from the target RMS; inspect the saved calibration record.

from cascaqit import SPSAConfig, SPSALearningRateCalibrationConfig

calibration = SPSALearningRateCalibrationConfig(directions=3, target_update_rms=0.05)
config = SPSAConfig(learning_rate=None, learning_rate_calibration=calibration)
assert config.learning_rate is None
assert SPSALearningRateCalibrationConfig.from_json(calibration.to_json()) == calibration

from_dict ¶

from_dict(
    data: Mapping[str, Any],
) -> SPSALearningRateCalibrationConfig

Restore SPSALearningRateCalibrationConfig 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.

from_json ¶

from_json(text: str) -> SPSALearningRateCalibrationConfig

Parse a JSON object and call from_dict(), returning SPSALearningRateCalibrationConfig. Invalid JSON raises a parsing error; a non-object root raises TypeError.

to_dict ¶

to_dict() -> dict[str, Any]

Return a JSON-compatible dictionary, serializing nested objects and converting tuples to arrays. This stores the declaration, not an execution result.

to_json ¶

to_json(*, indent: int | None = None) -> str

Return a JSON string without writing a file. indent=None uses compact formatting; supply an indentation width for readable output.

stable_hash ¶

stable_hash() -> str

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.