qamomile.optimization.qaoa

Overview¶

Functions¶

hubo_qaoa_state [source]¶

def hubo_qaoa_state(
    p_val: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    higher: qmc.Dict[qmc.Vector[qmc.UInt], qmc.Float],
    n: qmc.UInt,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate HUBO QAOA state.

Creates a uniform superposition and applies p layers of the HUBO QAOA circuit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: HUBO QAOA state vector.

is_close_zero [source]¶

def is_close_zero(value: float, abs_tol = 1e-15) -> bool

Check if a given floating-point value is close to zero within a small tolerance.

Parameters:

Returns:

bool — True if the value is close to zero, False otherwise.

qaoa_state [source]¶

def qaoa_state(
    p: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    n: qmc.UInt,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate QAOA State for Ising model.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: QAOA state vector.

Classes¶

ExecutableProgram [source]¶

class ExecutableProgram(Generic[T])

A fully compiled program ready for execution.

This is the Orchestrator - manages execution of mixed classical/quantum programs.

Example:

executable = transpiler.compile(kernel)

# Sample: multiple shots, returns counts
job = executable.sample(executor, shots=1000)
result = job.result()  # SampleResult with counts

# Run: single shot, returns typed result
job = executable.run(executor)
result = job.result()  # Returns kernel's return type

Constructor¶

def __init__(
    self,
    compiled_quantum: list[CompiledQuantumSegment[T]] = list(),
    compiled_classical: list[CompiledClassicalSegment] = list(),
    compiled_expval: list[CompiledExpvalSegment] = list(),
    execution_order: list[tuple[str, int]] = list(),
    output_refs: list[str] = list(),
    num_output_bits: int = 0,
) -> None

Attributes¶

• compiled_classical: list[CompiledClassicalSegment]

• compiled_expval: list[CompiledExpvalSegment]

• compiled_quantum: list[CompiledQuantumSegment[T]]

• execution_order: list[tuple[str, int]]

• has_parameters: bool Check if this program has unbound parameters.

• num_output_bits: int

• output_refs: list[str]

• parameter_names: list[str] Get list of parameter names that need binding.

• quantum_circuit: T Get the single quantum circuit.

Methods¶

get_circuits¶

def get_circuits(self) -> list[T]

Get all quantum circuits in execution order.

get_first_circuit¶

def get_first_circuit(self) -> T | None

Get the first quantum circuit, or None if no quantum segments.

run¶

def run(
    self,
    executor: QuantumExecutor[T],
    bindings: dict[str, Any] | None = None,
) -> RunJob[Any] | ExpvalJob

Execute once and return single result.

Parameters:

Returns:

RunJob[Any] | ExpvalJob — RunJob that resolves to the kernel’s return type, or RunJob[Any] | ExpvalJob — ExpvalJob if the program contains expectation value computation.

Raises:

• ExecutionError — If no quantum circuit to execute

• ValueError — If required parameters are missing

Example:

job = executable.run(executor, bindings={"gamma": [0.5]})
result = job.result()
print(result)  # 0.25 (for QFixed) or (0, 1) (for bits)

sample¶

def sample(
    self,
    executor: QuantumExecutor[T],
    shots: int = 1024,
    bindings: dict[str, Any] | None = None,
) -> SampleJob[Any]

Execute with multiple shots and return counts.

Parameters:

Returns:

SampleJob[Any] — SampleJob that resolves to SampleResult with results.

Raises:

• ExecutionError — If no quantum circuit to execute

• ValueError — If required parameters are missing

Example:

job = executable.sample(executor, shots=1000, bindings={"gamma": [0.5]})
result = job.result()
print(result.results)  # [(0.25, 500), (0.75, 500)]

MathematicalProblemConverter [source]¶

class MathematicalProblemConverter(abc.ABC)

Constructor¶

def __init__(self, instance: ommx.v1.Instance | BinaryModel) -> None

Attributes¶

• instance

• original_vartype

• spin_model

Methods¶

decode¶

def decode(self, samples: SampleResult[list[int]]) -> BinarySampleSet

Decode quantum measurement results.

Returns results in the original vartype (BINARY or SPIN) that was provided when constructing the converter.

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Construct the cost Hamiltonian.

Subclasses must implement this method to build the appropriate Hamiltonian for their specific algorithm (e.g., Pauli-Z for QAOA, QRAC-encoded for QRAO).

Returns:

qm_o.Hamiltonian — qm_o.Hamiltonian: The cost Hamiltonian.

QAOAConverter [source]¶

class QAOAConverter(MathematicalProblemConverter)

Converter for Quantum Approximate Optimization Algorithm (QAOA).

Supports both standard quadratic (QUBO/Ising) models and higher-order binary optimization (HUBO) models. When higher-order terms are present, automatically uses phase-gadget decomposition for k-body Z-rotations.

Example:

>>> model = BinaryModel.from_hubo({(0, 1, 2): 1.0, (0,): -2.0})
>>> converter = QAOAConverter(model)
>>> executable = converter.transpile(QiskitTranspiler(), p=2)

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Construct the Ising cost Hamiltonian from the spin model.

Builds a Pauli-Z Hamiltonian from the spin model’s linear, quadratic, and higher-order terms.

Returns:

qm_o.Hamiltonian — qm_o.Hamiltonian: The cost Hamiltonian.

transpile¶

def transpile(self, transpiler: Transpiler, *, p: int) -> ExecutableProgram

Transpile the model into an executable QAOA circuit.

Dispatches to the quadratic-only fast path when no higher-order terms are present, otherwise uses the HUBO path with phase-gadget decomposition.

Parameters:

Returns:

ExecutableProgram — The compiled circuit program.

Transpiler [source]¶

class Transpiler(ABC, Generic[T])

Base class for backend-specific transpilers.

Provides the full compilation pipeline from QKernel to executable program.

Usage:

transpiler = QiskitTranspiler()

Option 1: Full pipeline¶

executable = transpiler.compile(kernel, bindings={“theta”: 0.5}) results = executable.run(transpiler.executor())

Option 2: Step-by-step¶

block = transpiler.to_block(kernel) substituted = transpiler.substitute(block) affine = transpiler.inline(substituted) validated = transpiler.affine_validate(affine) folded = transpiler.constant_fold(validated, bindings={“theta”: 0.5}) analyzed = transpiler.analyze(folded) separated = transpiler.separate(analyzed) executable = transpiler.emit(separated, bindings={“theta”: 0.5})

Option 3: Just get the circuit (no execution)¶

circuit = transpiler.to_circuit(kernel, bindings={“theta”: 0.5})

With configuration (strategy overrides)¶

config = TranspilerConfig.with_strategies({“qft”: “approximate”}) transpiler = QiskitTranspiler(config=config)

Attributes¶

• config: TranspilerConfig Get the transpiler configuration.

Methods¶

affine_validate¶

def affine_validate(self, block: Block) -> Block

Pass 1.5: Validate affine type semantics.

This is a safety net to catch affine type violations that may have bypassed frontend checks. Validates that quantum values are used at most once.

analyze¶

def analyze(self, block: Block) -> Block

Pass 2: Validate and analyze dependencies.

constant_fold¶

def constant_fold(self, block: Block, bindings: dict[str, Any] | None = None) -> Block

Pass 1.5: Fold constant expressions.

Evaluates BinOp operations when all operands are constants or bound parameters. This prevents quantum segment splitting from parametric expressions like phase * 2.

emit¶

def emit(
    self,
    separated: SimplifiedProgram,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> ExecutableProgram[T]

Pass 4: Generate backend-specific code.

Parameters:

executor¶

def executor(self, **kwargs: Any = {}) -> QuantumExecutor[T]

Create a quantum executor for this backend.

inline¶

def inline(self, block: Block) -> Block

Pass 1: Inline all CallBlockOperations.

lower_compile_time_ifs¶

def lower_compile_time_ifs(self, block: Block, bindings: dict[str, Any] | None = None) -> Block

Pass 1.75: Lower compile-time resolvable IfOperations.

Evaluates IfOperation conditions (including expression-derived conditions via CompOp/CondOp/NotOp) and replaces resolved ones with selected-branch operations. Phi outputs are substituted with selected-branch values throughout the block.

This prevents SeparatePass from seeing classical-only compile-time IfOperations that would otherwise split quantum segments.

separate¶

def separate(self, block: Block) -> SimplifiedProgram

Pass 3: Lower and split into quantum and classical segments.

Validates C→Q→C pattern with single quantum segment.

set_config¶

def set_config(self, config: TranspilerConfig) -> None

Set the transpiler configuration.

Parameters:

substitute¶

def substitute(self, block: Block) -> Block

Pass 0.5: Apply substitutions (optional).

This pass replaces CallBlockOperation targets and sets strategy names on CompositeGateOperations based on config.

Parameters:

Returns:

Block — Block with substitutions applied

to_block¶

def to_block(
    self,
    kernel: QKernel,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> Block

Convert a QKernel to a Block.

Parameters:

When bindings or parameters are provided, uses kernel.build() to properly resolve array shapes from the bound data. Otherwise uses the cached block_value for efficiency.

to_circuit¶

def to_circuit(self, kernel: QKernel, bindings: dict[str, Any] | None = None) -> T

Compile and extract just the quantum circuit.

This is a convenience method for when you just want the backend circuit without the full executable.

Parameters:

Returns:

T — Backend-specific quantum circuit

transpile¶

def transpile(
    self,
    kernel: QKernel,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> ExecutableProgram[T]

Full compilation pipeline from QKernel to executable.

Parameters:

Returns:

ExecutableProgram[T] — ExecutableProgram ready for execution

Raises:

• QamomileCompileError — If compilation fails (validation, dependency errors)

Pipeline:

1. to_block: Convert QKernel to Block

2. substitute: Apply substitutions (if configured)

3. inline: Inline CallBlockOperations

4. affine_validate: Validate affine type semantics

5. constant_fold: Fold constant expressions 5.5. lower_compile_time_ifs: Lower compile-time IfOperations 5.8. validate_while_contract: Validate while conditions are measurement-backed

6. analyze: Validate and analyze dependencies

7. separate: Split into quantum/classical segments

8. emit: Generate backend-specific code

validate_while_contract¶

def validate_while_contract(self, block: Block) -> Block

Pass 1.8: Validate WhileOperation conditions are measurement-backed.

Rejects while patterns whose condition is not a measurement result (Bit from qmc.measure()). This prevents late ValueError at emit time for unsupported while forms.