---

name: optimizers description: "Select, configure, run, and troubleshoot Qiskit Machine Learning optimizers for classical objectives and variational training, including SciPy wrappers, SPSA/QNSPSA, gradient and steppable workflows, bounds, callbacks, serialization, and optional NLopt." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Optimizers

Use this skill when a downstream task must minimize a scalar objective over parameter vectors with qiskit_machine_learning.optimizers. It covers the optimizer contract and optimizer-specific behavior. It does not design a VQC/VQR or other trainable model, and it does not implement quantum gradients; route model embedding to algorithms and gradient construction to qnn-gradients.

Fast route

1. Define fun(x) -> scalar, a one-dimensional initial point x0, and, when available, jac(x) -> gradient. Decide whether the objective is smooth, noisy, constrained/bounded, or requires a global search.
2. Use the decision table in optimizer-selection.md. Prefer minimize(fun, x0, jac=jac, bounds=bounds) for an ordinary run.
3. Check get_support_level() before trusting jac or bounds; ignored is not the same as supported. The support matrix and constructor facts are in api-reference.md.
4. Use workflows.md for ordinary, noisy, ask/tell, QN-SPSA, serialization, and optional-NLopt procedures.
5. Interpret OptimizerResult and verify that the final point is feasible and that the reported objective was evaluated under the same noise/seed policy. If anything fails, use troubleshooting.md.

Public entry points

from qiskit_machine_learning.optimizers import (
    ADAM, AQGD, CG, COBYLA, GSLS, GradientDescent, L_BFGS_B,
    NELDER_MEAD, NFT, P_BFGS, POWELL, QNSPSA, SLSQP, SPSA, TNC,
    UMDA, SciPyOptimizer,
)

The optional NLopt-backed exports are CRS, DIRECT_L, DIRECT_L_RAND, ESCH, ISRES, and SBPLX. Instantiate them only after checking the optional dependency. Do not silently substitute an unsupported optimizer: choose a documented CPU fallback when NLopt is unavailable.

Guardrails

• Every ordinary optimizer consumes fun, x0, optional jac, and optional bounds, and returns an OptimizerResult; most optimizers require an initial point even when their support level says it is merely supported.
• Bounds are a list of (lower, upper) pairs aligned with x0. Do not pass bounds to an optimizer whose level is ignored and then assume they were enforced. Use L_BFGS_B, SLSQP, TNC, POWELL, GSLS, or finite-bound NLopt when bound enforcement is required.
• SPSA and QNSPSA are stochastic. Set qiskit_machine_learning.utils.algorithm_globals.random_seed before the run when reproducibility matters; a NumPy seed alone is not a substitute.
• If only one of SPSA's learning_rate and perturbation is supplied, construction of the run raises ValueError. Supplying neither invokes calibration and consumes extra objective evaluations.
• Callback signatures are optimizer-specific. Never reuse a callback written for one optimizer without adapting its arguments. Model-level callback behavior belongs to algorithms, not this skill.
• settings is a configuration snapshot, not generally a live optimizer state. Callables, fidelity functions, termination checkers, and custom linear solvers are not JSON values. ADAM has a separate CSV snapshot mechanism.

Verification checklist

Before handing off an optimizer choice, check: import path; constructor signature; support levels; objective and gradient shapes; finite bounds when required; seed and evaluation budget; callback arity; result.x feasibility; and result.fun, nfev, and nit interpretation. Run the bundled smoke script from any working directory with python .../optimizer_smoke.py --help or a small installed-package invocation using scripts/optimizer_smoke.py.

Read the linked references progressively rather than loading the entire catalog into every optimization task.