Domain-specific helper layer for quantum combinatorial optimization.
Design center¶
This package turns classical combinatorial optimization problems
(OMMX Instance or Qamomile BinaryModel) into quantum programs and
decodes measurement results back into classical solutions. It hosts the
converter family: QAOAConverter (qaoa.py, QUBO/Ising and HUBO via
phase gadgets), FQAOAConverter (fqaoa.py, fermionic mixers with
particle-number constraints), the QRAC converters (qrao/),
PCEConverter (pce.py, Pauli correlation encoding), and
GASConverter (gas.py, oracle-based Grover Adaptive Search over
QFT-encoded QUBO/HUBO arithmetic).
Layering constraint (inviolable)¶
optimization → circuit ← engines. This package is a consumer of
qamomile.circuit’s public transpiler and algorithm APIs
(Transpiler, ExecutableProgram, qamomile.circuit.algorithm
ansatz builders) — it must never be imported by qamomile.circuit or
by engine packages, and it must never reach into circuit internals
(passes, IR rewriting). A converter builds a qkernel / Hamiltonian and
hands it to whatever engine Transpiler the caller supplies; engine
choice stays out of this layer entirely.
Extension points¶
New algorithms subclass
MathematicalProblemConverter(converter.py), whosenormalize_problem_inputis the single canonical entry point for OMMX/BinaryModel intake (deep-copy +to_hubosemantics live there, in exactly one place). Converters whose contract genuinely differs (no single cost Hamiltonian, noSampleResultdecode — e.g. PCE) may skip the base class, but should still delegate intake tonormalize_problem_input.binary_model/is the problem representation;post_process/holds classical refinement of decoded samples. Both are quantum-agnostic and must stay importable without any SDK installed.