QAOA¶
from cascaqit import QAOA
QAOA ¶
QAOA(
problem: OptimizationProblem,
layers: int = 1,
mis_penalty: float = 2.0,
mwis_penalty: float | None = None,
algorithm_id: str | None = None,
)
Construct QAOA from GraphProblemIR, MISInstance, MWISProblemIR, QUBOProblemIR or IsingModelIR. Graph input is interpreted as MIS; arbitrary PauliHamiltonian input is not accepted by this constructor. The projected objective may contain single-Z terms, two-qubit ZZ terms and a constant. layers must be a positive integer. The default algorithm_id derives from the problem identifier.
mis_penalty applies to MIS projection and must be finite and greater than one. mwis_penalty applies to MWIS: it must be positive and strictly exceed the maximum, over edges, of the smaller endpoint weight. Its default is computed from problem weights. QUBO/Ising inputs already specify their objective and do not use these penalties to rebuild constraints.
Parameter order places all gamma values before all beta values. Angles are in radians. A mapping must exactly match parameter_names; a sequence must follow that order and have the same length. Values must be finite real numbers, excluding booleans.
Setting every angle to zero gives a uniform distribution whose energy is the mean over four binary assignments. The example then runs a short optimization.
from math import isclose
from cascaqit import OptimizerConfig, QAOA, QUBOProblemIR
problem = QUBOProblemIR.from_terms(problem_id="pair", linear_terms={"a": -1, "b": -2},
quadratic_terms={("a", "b"): 3}, offset=0.25)
qaoa = QAOA(problem, layers=2)
assert qaoa.parameter_names == ("gamma_0", "gamma_1", "beta_0", "beta_1")
assert isclose(qaoa.evaluate((0.0, 0.0, 0.0, 0.0)).energy, -0.5, abs_tol=1e-12)
result = qaoa.run(optimizer=OptimizerConfig(method="SPSA", max_iterations=1, seed=7),
initial_parameters=(0.1, 0.2, 0.3, 0.4), final_shots=16)
assert sum(result.final_result.counts.values()) == 16
assert result.optimality_claim == "not_claimed"
assert qaoa.build_circuit() is not qaoa.build_circuit()
Execution uses the local CPU backend, with backend=None selecting the default. Noisy exact objectives require supported density-matrix execution. This entry point does not expose finite-shot objective configuration. See the optimization course.
Return the projected PauliHamiltonian, including constant offset and logical-qubit order. The constant affects reported energy but not circuit measurement probabilities.
Return gamma_0…gamma_(p-1) followed by beta_0…beta_(p-1), where p is the layer count. Values are not interleaved by layer.
Return a fresh parameterized Circuit. Apply H to every qubit, then each layer uses RZ(2coefficientgamma) for single-Z terms, CX–RZ–CX for ZZ terms, and RX(2*beta) on each qubit. The returned circuit has no terminal measurement. The constant contributes only a global phase and is omitted from the gate sequence.
Return QAOAAnsatzPlanIR before gate decomposition, retaining problem, Hamiltonian, layered operations and parameters for inspecting cost layers. It does not execute the circuit.
Return canonical QAOALogicalScheduleResultIR describing the arrangement of logical operations. It is not a device pulse schedule or evidence of hardware compilation or execution.
Return AnsatzSpecIR recording QAOA depth, logical-qubit order, parameter names and construction metadata for checking result provenance.
Return ParameterSchemaIR from a freshly built circuit’s declarations without evaluating an objective.
evaluate ¶
evaluate(
parameters: ParameterValues,
*,
backend: LocalBackend | None = None,
evaluation_index: int = 0,
algorithm_run_id: str | None = None,
seed: int | None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
) -> ObjectiveEvaluationIR
Synchronously execute one backend Job and return ObjectiveEvaluationIR for an exact objective. parameters is a complete mapping or ordered sequence; energy includes the constant. evaluation_index identifies the record, algorithm_run_id links the experiment, and seed/noise/options configure supported execution. There is no measurement argument; objective energy is not a finite-shot estimate.
gradient ¶
gradient(
parameters: ParameterValues,
*,
backend: LocalBackend | None = None,
gradient_index: int = 0,
objective_evaluation_offset: int = 0,
max_backend_executions: int | None = None,
algorithm_run_id: str | None = None,
seed: int | None = None,
config: GradientConfig | None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
) -> ObjectiveGradientIR
Return parameter-shift ObjectiveGradientIR, using default GradientConfig when config=None. Shared gamma/beta can control multiple gates; gradients combine gate-level shifts with the chain rule. Applying a two-point formula directly to an entire shared parameter is generally invalid. gradient_index and objective_evaluation_offset number records; max_backend_executions bounds this call’s budget. This interface exposes exact-objective gradients only.
run ¶
run(
*,
backend: LocalBackend | None = None,
optimizer: OptimizerConfig | None = None,
initial_parameters: ParameterValues | None = None,
algorithm_run_id: str | None = None,
final_shots: int = 2048,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
) -> VariationalResult
Synchronously return VariationalResult after exact-objective optimization and final_shots computational-basis samples at selected_evaluation. optimizer=None uses OptimizerConfig(); omitted initial_parameters follows configured initialization. final_shots does not change how optimization energy is evaluated. Inspect termination for the stop reason and compare candidates with the problem baseline where available. Reaching an iteration or budget limit does not establish convergence.