Qiskit Support

The MaxCut problem¶

We use the same small 5-node graph from the QAOA for MaxCut tutorial so the focus stays on the Qiskit integration. Maximizing $\sum_{(i,j) \in E}(1 - s_i s_j)/2$ is equivalent, up to a constant, to minimizing the antiferromagnetic Ising Hamiltonian $H_C = \sum_{(i,j) \in E} s_i s_j$. For unweighted MaxCut, every $J_{ij} = 1$ and every $h_i = 0$, so we pass these coefficients directly to BinaryModel.from_ising.

Building the QAOA ansatz with @qkernel¶

We write the QAOA quantum circuit for solving MaxCut as a @qkernel. The recipe is the same as in the QAOA for MaxCut tutorial. After preparing a uniform superposition in the computational basis, we alternately apply cost and mixer layers $p$ times, then measure in the computational basis. The expectation-value qkernel is introduced later in the run() section so the circuit diagram below shows the sampling ansatz directly rather than a wrapper around a state-preparation helper.

qaoa_ansatz.draw(...) renders the Qamomile circuit diagram. We pass values for the arguments that determine the problem structure (p, quad, linear, n) so the number of layers and graph structure are reflected in the diagram. Meanwhile, gammas / betas are left as parameters whose values are supplied later.

Transpile to Qiskit¶

A quantum circuit defined as a Qamomile qkernel can be converted to a Qiskit QuantumCircuit with QiskitTranspiler. You call QiskitTranspiler.transpile() the same way as with any other quantum SDK. We bind the arguments that determine the problem structure and keep gammas / betas as runtime parameters. For reproducible tutorial output, we specify an AerSimulator execution target with a fixed seed and max_parallel_threads=1.

executable.get_first_circuit() returns the generated Qiskit QuantumCircuit. The $2p$ QAOA angles (gammas[0..p-1], betas[0..p-1]) remain as Qiskit Parameter objects until execution time. Here we inspect the circuit transpiled into a Qiskit QuantumCircuit with Qiskit’s text drawer.

Each runtime parameter remains unbound until execution time. Binding gammas / betas is handled by ExecutableProgram.sample(...) and ExecutableProgram.run(...) through Qiskit’s assign_parameters, so the Qiskit circuit can be created once and reused across many parameter vectors. The problem structure, such as the Ising coefficients, qubit count, and number of layers, is fixed when the circuit is transpiled, leaving only the variational angles as runtime inputs.

Sampling QAOA with QiskitExecutor¶

executable.sample(executor, bindings=..., shots=...) returns a SampleJob. Calling .result() gives a SampleResult, which BinaryModel.decode_from_sampleresult decodes into a BinarySampleSet of spin variables $(+1 / -1)$. This lets us count cut edges without any additional conversion. QiskitExecutor() runs against AerSimulator by default when qiskit-aer is installed; here we use the seeded simulator from above.

Optimizing the QAOA parameters¶

A QAOA optimization loop reuses the same executable across many (gammas, betas) vectors. Call transpiler.transpile() once, then call executable.sample() many times. In this example, we define the sampling and decoding work as cost_fn() and optimize it with SciPy’s minimize function. The classical optimization routine updates (gammas, betas) while lowering the mean sampled Ising energy. Each iteration reuses the same executable and QiskitExecutor.

Because the AerSimulator above was constructed with a fixed seed_simulator, re-running this page yields a reproducible sampling stream for the same sequence of circuits. The optimizer should converge close to the ground-state energy of $H_C$ on this 5-node graph. The optimized parameters from this run (opt_gammas, opt_betas) are reused throughout the rest of this page.

Expectation values with run()¶

In Qamomile, you write expectation values in a qkernel with qmc.expval(...). When this is transpiled to Qiskit, it becomes an executable object that can be called with ExecutableProgram.run(executor, bindings=...). run() uses Qamomile’s recorded parameter information to bind runtime parameters before calling Qiskit’s estimator.

First build a Qamomile Hamiltonian for $H_C = \sum_{(i,j) \in E} Z_i Z_j$. Then transpile the expectation-value qkernel and evaluate it at the optimized QAOA parameters.

ExecutableProgram.run(...) is the recommended route when you work through the Qamomile API. Direct executor.estimate(...) calls are still available when you intentionally manage Qiskit circuits yourself, but then you are responsible for Qiskit’s parameter ordering and whether the circuit has already been bound. For local execution, QiskitExecutor creates Qiskit’s StatevectorEstimator by default when it is available, so current Qiskit installs use the V2 primitive interface. If a custom estimator, or an older Qiskit / Aer estimator, does not accept the V2 run([(circuit, observable, params)]) call, Qamomile falls back to the V1 run(circuits, observables, parameter_values) form.

Advanced Qiskit features¶

Qiskit is available through Qamomile’s optional Qiskit integration. Qamomile provides several ways to use advanced Qiskit features.

This section shows three features exposed by the Qiskit integration that are useful when running generated circuits on Qiskit execution targets:

• native classical control flow (for_loop, if_else, while_loop) for dynamic circuits,

• direct translation of parametric time evolution qmc.pauli_evolve(...) as a native PauliEvolutionGate,

• native QFTGate / inverse QFTGate for Qamomile’s composite QFT operations.

Classical control flow and runtime classical expressions¶

For Qamomile programs that use classical control flow and runtime classical expressions, the Qiskit integration can translate them directly into Qiskit’s dynamic-circuit instructions and classical expressions. qmc.range(...) loops become Qiskit for_loop. Measurement-backed if / else and while become Qiskit dynamic-circuit instructions. Compound predicates such as a & b can be converted directly into Qiskit classical expressions through qiskit.circuit.classical.expr.

Qiskit’s classical expression system currently covers the logical, comparison, and arithmetic operations that Qamomile uses in dynamic conditions. However, FLOORDIV and POW do not have matching Qiskit classical expressions, so target-legality verification raises TargetCapabilityError before Qiskit circuit construction if either one remains in a runtime condition. If you need those operations, make sure their values are fixed before transpilation.

Native PauliEvolutionGate¶

qmc.pauli_evolve(q, H, gamma) represents the time evolution $e^{-i\gamma H}$. The Qiskit integration writes that operation as a PauliEvolutionGate when use_native_pauli_evolution=True (the default). An unbound gamma becomes a Qiskit Parameter, so the same circuit can be reused while trying different variational parameters.

Pass QiskitTranspiler(use_native_pauli_evolution=False) when you want a gate-by-gate decomposition instead. This flag controls only Pauli evolution. Native QFT/IQFT output is controlled independently by use_native_composite.

Native QFTGate¶

Qamomile provides high-level operations for QFT and inverse QFT through qmc.qft(...) / qmc.iqft(...). The Qiskit integration can translate these qkernels directly to Qiskit’s native QFTGate, without decomposing them into elementary quantum gates. With use_native_composite=False, Qamomile keeps a named Qiskit gate backed by the portable fallback body. Call Qiskit’s decompose() when you need to inspect its H/controlled-phase/SWAP implementation.

Using other Qiskit execution targets¶

QiskitExecutor keeps the generated circuit separate from the Qiskit execution target that runs it. By passing an execution target with transpiler.executor(backend=...), you can run the same circuit on various Qiskit execution targets. For example, you can use a noiseless local simulator, an Aer noise model, or IBM Quantum hardware through the same QiskitExecutor as shown below.

Here, we build an Aer noise model with depolarizing noise and pass it to AerSimulator. We compare the clean and noisy sample-mean energies at the same optimized parameters.

Running on IBM Quantum hardware¶

Install Qiskit support with pip install "qamomile[qiskit]"; this extra includes Qiskit IBM Runtime for hardware execution. Then pass a device name, IBM Quantum API key, and instance CRN to transpiler.executor(...). It returns the same QiskitExecutor used for local simulation. With no arguments it uses local Aer; with an IBM device name it authenticates through Qiskit IBM Runtime and selects that backend for executable.sample() and executable.run(). The following examples submit remote jobs when run manually; they are not executed as part of this notebook.

import os

from qamomile.qiskit import QiskitExecutionOptions

hardware_options = QiskitExecutionOptions(
    max_execution_time=300,
    resilience_level=1,
)
hardware_executor = transpiler.executor(
    backend="your_backend_name",
    api_key=os.environ["IBM_QUANTUM_API_KEY"],
    instance_crn=os.environ["IBM_QUANTUM_INSTANCE_CRN"],
    options=hardware_options,
)
runtime_bindings = {"gammas": opt_gammas, "betas": opt_betas}

hardware_job = executable.sample(
    hardware_executor,
    bindings=runtime_bindings,
    shots=1024,
)
print(hardware_job.status())
snapshot_data = hardware_job.snapshot().to_dict()
hardware_result = hardware_job.result()

Set the two environment variables to your API key and instance CRN before running this example. You can also construct QiskitExecutor(backend=..., api_key=..., instance_crn=..., options=hardware_options) directly with the same arguments. QiskitExecutionOptions configures Runtime through Qamomile, without importing SDK option classes. max_execution_time limits quantum execution time in seconds for both sampling and estimation; queue wait time and the local .result(timeout=...) wait are separate. resilience_level (0, 1, or 2) applies to expectation estimation. These settings require a Runtime target. Qamomile passes the credentials to QiskitRuntimeService using the ibm_quantum_platform channel and requests the named backend within that instance. If that account and instance cannot access the backend, Qiskit’s error is raised while constructing the executor; execution does not switch to another device or a simulator. Both api_key and instance_crn must be nonempty strings supplied together with a backend name; incomplete credentials raise ValueError. The executor does not save the credentials to disk. If you already configured a saved account with Qiskit IBM Runtime, omit both credentials and use transpiler.executor(backend="your_backend_name").

With an IBM backend, QiskitExecutor binds the runtime parameters and transpiles the circuit to the selected backend’s instruction set before submission to Runtime V2 primitives. For expectation values, it also maps the observable to the transpiled circuit’s physical qubit layout, so changing the hardware layout preserves the intended observable.

Sampling and expectation jobs expose status(), cancel(), and snapshot() while .result() waits for the result. Store snapshot_data as JSON to reconnect later. Recreate the same executable and an executor for the original backend, then restore the typed result with the original runtime bindings:

from qamomile.circuit.transpiler.job import JobSnapshot

restored_job = executable.restore(
    hardware_executor,
    JobSnapshot.from_dict(snapshot_data),
    bindings=runtime_bindings,
)
restored_result = restored_job.result()

Snapshots contain provider job identifiers, completed local values, and result metadata; credentials and runtime bindings remain caller-owned. Deterministic local results, such as constant observables and empty circuits, can be saved and restored, including in groups that also contain remote jobs. Restoring provider references uses the Runtime service created when the executor authenticates. If you already manage a QiskitRuntimeService, pass service=service with the backend name instead of api_key and instance_crn, or pass its IBMBackend object as backend.

The expectation executable from above also works with Runtime. Use TargetPrecision to request an absolute target precision for one evaluation:

from qamomile.circuit.transpiler.execution_request import TargetPrecision

energy_job = expval_executable.run(
    hardware_executor,
    bindings=runtime_bindings,
    estimation=TargetPrecision(0.05),
)
hardware_energy = energy_job.result()

Sampling shots and estimation TargetPrecision are still specified per execution call. Omitting TargetPrecision uses the Runtime estimator’s configured defaults. For additional Runtime settings, pass dictionaries as sampler_options and estimator_options when constructing QiskitExecutionOptions. You can also pass native options directly through the executor’s sampler_options=... and estimator_options=... arguments, but these cannot be combined with options=.... Supply a backend-specific pass_manager=... to control hardware transpilation. To use an existing Runtime Session or Batch, pass it as mode=... with its preconfigured backend object as backend=...; a backend name cannot be combined with mode. The caller manages its context and lifetime; the executor does not create or close it.

Summary¶

• QiskitTranspiler().transpile(kernel, bindings=..., parameters=[...]) converts the qkernel to an ExecutableProgram[QuantumCircuit]; to_circuit(...) returns the Qiskit QuantumCircuit directly when you want to stay inside the Qiskit ecosystem.

• QiskitExecutor supports both executable.sample() for measured qkernels and executable.run() / executor.estimate(...) for expectation values, using AerSimulator by default. Pass an IBM backend name with api_key and instance_crn, or an existing IBMBackend, to use Runtime V2 with the same API.

• The Qiskit integration uses native mid-circuit measurement, dynamic for_loop / if_else / while_loop, runtime classical expressions, PauliEvolutionGate, and QFTGate where Qiskit provides a high-level representation.

• Switching from Aer to IBM Quantum reuses the Qamomile executable; QiskitExecutor handles hardware transpilation, observable layout, and asynchronous job restoration.

See also¶

• CUDA-Q Support covers the same MaxCut QAOA workflow with CUDA-Q, including CUDA-Q targets and observe.

• QURI Parts Support covers the same workflow on QURI Parts, including Qulacs sampling and QURI Parts estimator paths.