OptimizerConfig¶
from cascaqit import OptimizerConfig
OptimizerConfig ¶
OptimizerConfig(
method: OptimizerMethod = "COBYLA",
max_iterations: int = 80,
max_evaluations: int | None = None,
max_backend_executions: int | None = None,
starts: int = 1,
initialization: InitializationStrategy = "random",
tolerance: float = 1e-06,
seed: int | None = None,
bounds: tuple[tuple[float, float], ...] = (),
options: Mapping[str, bool | int | float] = dict(),
gradient: GradientConfig | None = None,
spsa: SPSAConfig | None = None,
adam: AdamConfig | None = None,
schema_version: str = ALGORITHM_SCHEMA_VERSION,
)
Configure the method, initialization and budget for variational optimization. Pass this to the optimizer argument of VQE.run() or QAOA.run(). Construction alone does not solve a problem.
| Parameter | Current behavior |
|---|---|
| method | COBYLA, Nelder-Mead, Powell, L-BFGS-B, SPSA or ADAM; case-sensitive |
| max_iterations | Positive integer; COBYLA interprets it as a function-evaluation limit, while other methods use their own iteration rules |
| max_evaluations | Optional positive objective-evaluation budget; repeated estimates also consume evaluations |
| max_backend_executions | Optional positive limit on optimization backend calls; one objective or gradient evaluation can require several calls |
| starts | Positive number of initial points; each start receives the configured budget, so a per-start budget is not a whole-experiment cap |
| initialization | random or layerwise; layerwise also requires a compatible parameter mapping from the previous layer |
| tolerance | Positive method tolerance, not a bound on error relative to the true ground-state energy |
| seed | Nonnegative integer or None for optimizer randomness; backend sampling has its own seed |
| bounds | Finite (lower, upper) pairs in algorithm parameter order, with lower < upper; dimensions are checked at execution |
| options | Additional numeric/boolean SciPy options; maxiter, maxfev and maxfun are managed by the dedicated budget fields and cannot be repeated here |
L-BFGS-B and ADAM require cascaqit.algorithms.GradientConfig. SPSA uses spsa and ADAM uses adam, inserting their respective defaults when omitted. Other methods reject these dedicated configurations. SPSA/ADAM reject SciPy options. A stopping rule’s minimum iterations cannot exceed max_iterations.
Optimization budgets do not cover all later candidate-confirmation and final-sampling costs. Inspect actual counts and termination reasons in the result. Exhausting a budget, reaching small local updates and finding a ground state are different conclusions.
from cascaqit import HamiltonianTerm, OptimizerConfig, PauliHamiltonian, PauliZ, VQE
hamiltonian = PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
logical_order=("q0",))
config = OptimizerConfig(method="Nelder-Mead", max_iterations=4,
max_evaluations=8, seed=7)
result = VQE(hamiltonian, layers=1).run(optimizer=config, final_shots=16)
assert 1 <= len(result.evaluations) <= 8
assert sum(result.final_result.counts.values()) == 16
assert OptimizerConfig.from_json(config.to_json()) == config
See the VQE experiment for a full workflow.
Restore OptimizerConfig 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 OptimizerConfig. Invalid JSON raises a parsing error; a non-object root raises TypeError.
The adam field is omitted when Adam is unused. 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.