Constrained Quantum Optimizer - Fungsi Qiskit oleh Aqarios

Lihat rujukan API

nota

Qiskit Functions ialah ciri eksperimen yang hanya tersedia untuk pengguna Pelan Premium, Pelan Flex, dan Pelan On-Prem (melalui IBM Quantum Platform API) IBM Quantum®. Ia berstatus keluaran pratonton dan tertakluk kepada perubahan.

Gambaran Keseluruhan

Dengan Constrained Quantum Optimizer oleh Aqarios, anda boleh menyelesaikan masalah pengoptimuman binari terkekang pada perkakasan kuantum IBM® tanpa perlu memformulasi semula secara manual dan pemetaan litar. Cukup bekalkan masalah sebagai fail LP, fail MPS, atau Model Luna. Fungsi ini mengendalikan pemformulaan semula, sintesis litar, transpilasi, dan pelaksanaan perkakasan secara automatik. Penyelesai ini menggunakan warm-starting berulang [1] bagi algoritma FlexQAOA, iaitu lanjutan constraint-native bagi Quantum Approximate Optimization Algorithm (QAOA).

Pengoptimum ini menyasarkan masalah binari dengan kekangan. Khususnya, kekangan one-hot dan kekangan set-packing boleh dikuatkuasakan secara asli (natively) dengan menggunakan XY-mixers. Jenis kekangan lain diformulasi semula secara automatik sebagai terma penalti.

Jenis pemboleh ubah yang disokong

Fungsi ini hanya menyelesaikan masalah diskret. Setiap pemboleh ubah keputusan mestilah binari, atau integer dengan had bawah dan atas yang jelas, supaya boleh dikodkan ke dalam qubit. Pemboleh ubah selanjar (bernilai nyata) tidak disokong: model yang mengandunginya akan ditolak dengan kod ralat 4710.

Penerangan

Penafian

Prestasi boleh bergantung kepada kedua-dua instans masalah dan langkah pemprosesan seterusnya. Dalam sesetengah kes, sampel klasik dan sampel yang dijana secara kuantum mungkin mencapai kualiti penyelesaian akhir yang serupa selepas pasca-pemprosesan yang setara. Oleh itu, penilaian harus mempertimbangkan keseluruhan aliran kerja pengoptimuman.

Constrained Quantum Optimizer melaksanakan Iterative warm-start XY-mixer QAOA (IWS-QAOA) [1]. Algoritma ini menjalankan litar QAOA sudut-tetap pada perkakasan kuantum dan mengemas kini kebarangkalian warm-start awal bagi setiap litar menggunakan hasil pengukuran daripada lelaran sebelumnya. Latihan parameter variasi tidak diperlukan; sebaliknya, parametrisasi ramp linear tetap dipilih.

Dengan menggunakan XY-mixers untuk menguatkuasakan kekangan one-hot, anda boleh meningkatkan kualiti penyelesaian dengan ketara untuk masalah terkekang, kerana ruang carian secara praktikalnya dikurangkan kepada subruang boleh laksana yang lebih kecil — dan tiada kerumitan tambahan, akibat terma penalti, diperkenalkan dalam landskap pengoptimuman.

Aliran Kerja

Aliran kerja fungsi ini diterangkan di bawah:

1. Prapemprosesan: Sebelum sintesis litar, pengoptimum menganalisis struktur kekangan masalah input:

   • Prapemprosesan graf: Jika sesuai dengan masalah tersebut, masalah itu dianalisis sebagai graf, di mana tepi menentukan hubungan antara pemboleh ubah. Analisis graf ini membolehkan dua penambahbaikan prapemprosesan masalah. Pertama, kekangan tunggal boleh digabungkan menjadi satu kekangan besar dengan menggunakan penggabungan klik (clique merging), supaya ia diwakili oleh satu XY-mixer sahaja. Kedua, pemboleh ubah yang hanya mempunyai satu jiran boleh ditetapkan secara deterministik, mengurangkan saiz dan kerumitan masalah.

   • Penyelesaian kekangan: Praprosesor mengendalikan setiap kekangan secara berasingan: Jika kekangan itu adalah kekangan one-hot, ia boleh dikuatkuasakan melalui XY-mixers. Jika ia adalah kekangan set-packing, ia akan diubah terlebih dahulu kepada kekangan one-hot. Kekangan kesamaan dikendalikan melalui penalti kuadratik, dan kekangan ketaksamaan melalui unbalanced penalization.

   • Terbitan penalti: Kekangan yang tidak dapat dinyatakan sebagai kekangan kesamaan one-hot ditukar kepada terma penalti. Pengoptimum menerbitkan kekuatan penalti secara automatik daripada struktur masalah.

2. Warm-starting berulang: Pengoptimum menjalankan pelbagai rantai warm-start selari. Setiap rantai memegang taburan kebarangkalian ke atas penetapan pemboleh ubah, yang digunakan sebagai kebarangkalian permulaan litar QAOA (keadaan warm-start). Pada setiap lelaran, satu rantai mengambil sampel daripada litar kuantum, menerapkan pasca-pemprosesan klasik, dan mengemas kini taburannya berdasarkan kejadian sampel. Merentasi lelaran, ini memfokuskan carian kepada penyelesaian berkualiti tinggi tanpa gelung pengoptimuman variasi.

Bilangan rantai (num_parallel), jumlah bajet shot setiap rantai (total_shots), dan bilangan pengulangan QAOA (reps) merupakan kawalan utama untuk mengimbangi kualiti penyelesaian dengan masa jalan.

Penanda Aras

Penanda aras di bawah menunjukkan bahawa Fungsi Qiskit Constrained Quantum Optimizer mampu mencari penyelesaian berkualiti tinggi dan boleh laksana untuk masalah pengoptimuman terkekang dengan jauh melebihi 100 pemboleh ubah binari. Ketepatan (accuracy) ialah nisbah nilai objektif yang ditemui kepada optimum yang diketahui. Masa jalan (runtime) ialah masa jam-dinding daripada panggilan fungsi hingga penyampaian hasil. Penggunaan QPU ialah masa Pengkomputeran Kuantum yang boleh dicaj.

Dua masalah dikaji: masalah Maximum Independent Set (MIS) dan Max-$k$-Cut, iaitu lanjutan bagi masalah MaxCut yang terkenal kepada lebih daripada dua kategori. Max-$k$-Cut juga merupakan masalah pengoptimuman yang setara dengan masalah keputusan pewarnaan graf (graph coloring) (apabila semua tepi dipotong, graf itu boleh diwarna-$k$).

Masalah	Pemboleh ubah	Kekangan	Qubit	Ketepatan	Kebolehlaksanaan	Jumlah masa jalan (s)	Penggunaan QPU (s)	Jumlah shot
MIS es60fst02	186	280	124	100.0%	True	940.2	147.0	25.0k
MIS sloane_2dc_128	128	5173	74	100.0%	True	347.6	106.0	12.5k
Max-3-Cut Karate Club	99	33	99	98.7%	True	279.5	166.0	25.0k
Max-4-Cut Karate Club	132	33	132	100.0%	True	258.3	200.0	25.0k

Nota Penanda Aras

• Hasil di atas diperoleh pada pemproses Heron r2 ibm_marrakesh dengan pilihan lalai dan use_session diaktifkan. Untuk instans sloane_2dc_128, total_shots=12500 telah digunakan.

• Bilangan qubit yang dikurangkan untuk instans MIS (74 dan 124 berbanding 128 dan 186 pemboleh ubah) mencerminkan penetapan pemboleh ubah dalam prapemprosesan.

• Instans masalah untuk MIS diambil daripada Quantum Optimization Benchmarking Library. - Instans untuk masalah Max-$k$-Cut ialah graf Zachary Karate Club, yang mempunyai nombor kromatik 5.

Mula

Panduan ini menunjukkan penggunaan asas Constrained Quantum Optimizer dengan menunjukkan cara memuatkan fungsi dan melaksanakan masalah mudah. Untuk tutorial yang lebih mendalam, lihat Find the Maximum Independent Set with the Aqarios Constrained Quantum Optimizer.

Sahkan diri anda dengan kunci API IBM Quantum dan CRN instans anda, kemudian muatkan fungsi daripada katalog.

nota

Kod berikut mengandaikan anda telah menyimpan kelayakan anda. Untuk menyediakannya, ikut arahan dalam Save your IBM Cloud account credentials.

# Added by doQumentation — installs the packages this notebook needs if they are missing
import importlib.util

_needed = {"luna_model": "luna-model", "networkx": "networkx", "qiskit_addon_opt_mapper": "qiskit-addon-opt-mapper", "qiskit_ibm_catalog": "qiskit-ibm-catalog"}
_missing = [pip for module, pip in _needed.items()
            if importlib.util.find_spec(module) is None]
# One at a time, so a package that fails to install does not block the others
for _pip in _missing:
    %pip install -q {_pip}
if not _missing:
    print("\u2713 All required packages are installed")

from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

# Verify that you have access to the function
catalog.list()

[QiskitFunction(aqarios/constrained-quantum-optimizer)]

# Load the function
optimizer = catalog.load("aqarios/constrained-quantum-optimizer")

# Check the list of backends you have access to
catalog.backends()

[<IBMBackend('ibm_pittsburgh')>,
 <IBMBackend('ibm_boston')>,
 <IBMBackend('ibm_phoenix')>,
 <IBMBackend('ibm_fez')>,
 <IBMBackend('ibm_miami')>,
 <IBMBackend('ibm_marrakesh')>,
 <IBMBackend('ibm_kingston')>]

# Select the backend you want to use
backend = catalog.backend("ibm_phoenix")

Contoh 1: Masalah terkekang mudah

Contoh pertama menunjukkan cara menggunakan fungsi dengan fail-LP, spesifikasi masalah pengoptimuman biasa yang digunakan dalam penyelidikan operasi. Anda akan merumuskan contoh masalah pengoptimuman sebarang berikut yang mempunyai lima pemboleh ubah binari $x_i \in \{0,1\}$ tertakluk kepada dua kekangan:

$$\min x_1 x_2 + 2 x_2 x_3 - x_3 x_4 - 2 x_4 x_5 - 2 x_1 x_3 - 4 x_2 x_5 \\ \text{s.t.}\quad x_1 + x_2 + x_3 \leq 1 \\ \quad x_3 - x_4 + x_5 = 0$$

1. Formulasikan masalah

Nyatakan ungkapan matematik secara langsung dalam format rentetan LP berikut:

lp_str = """\\Problem name: Example
Minimize
  obj: [ 2 x_1 x_2 + 4 x_2 x_3 - 2 x_3 x_4 - 4 x_4 x_5 - 4 x_1 x_3 - 8 x_2 x_5 ] / 2
Subject To
  c1: x_1 + x_2 + x_3 <= 1
  c2: x_3 - x_4 + x_5 = 0
Binaries
  x_1 x_2 x_3 x_4 x_5
End
"""

Ambil perhatian bahawa [ ... ] / 2 ialah notasi yang diperlukan untuk objektif kuadratik daripada piawaian LP.

2. Jalankan pengoptimum

Selesaikan masalah dengan pengoptimum.

# Set up low-resource options for the simple problem
options = {"total_shots": 2000, "num_parallel": 5, "use_session": True}

# Dispatch the job
job_1 = optimizer.run(
    problem=lp_str, backend_name=backend.name, options=options
)

print(f"Job ID: {job_1.job_id}")

Job ID: 2e06a3a8-7c29-4c76-94d7-194293363f4a

# Monitor the job status
job_1.status()

'RUNNING: WAITING_FOR_QPU'

3. Dapatkan hasil

Hasil tersebut memberikan penyelesaian, iaitu pemetaan nama pemboleh ubah kepada nilai yang ditetapkan.

result = job_1.result()

result

{'solutions': [{'x_1': 0, 'x_2': 1, 'x_3': 0, 'x_4': 1, 'x_5': 1}],
 'solution_bitstrings': ['01011'],
 'raw_energy': -6.0,
 'objective_value': -6.0,
 'feasible': True,
 'metadata': {'resource_usage': {'RUNNING: MAPPING': {'CPU': 5.405},
   'RUNNING: OPTIMIZING_FOR_HARDWARE': {'CPU': 9.902},
   'RUNNING: WAITING_FOR_QPU': {'CPU': 25.456},
   'RUNNING: EXECUTING_QPU': {'CPU': 25.202},
   'RUNNING: POST_PROCESSING': {'CPU': 6.481}},
  'circuit_metrics': {'before_transpilation': {'num_qubits': 6,
    'gate_count': 42,
    'depth': 15,
    'two_qubit_gate_count': 12,
    'two_qubit_gate_depth': 7,
    'operations': {'rz': 12,
     'p': 8,
     'ry': 7,
     'rzz': 4,
     'cx': 3,
     'xx_plus_yy': 3,
     'global_phase': 2,
     'cry': 2,
     'x': 1}},
   'after_transpilation': {'num_qubits': 6,
    'gate_count': 254,
    'depth': 100,
    'two_qubit_gate_count': 48,
    'two_qubit_gate_depth': 33,
    'operations': {'rz': 78, 'sx': 122, 'cz': 48, 'measure': 6, 'x': 0}}},
  'solver_info': {'variable_mapping': {'x_1': 0,
    'x_2': 1,
    'x_3': 2,
    'x_4': 3,
    'x_5': 4}}}}

Medan solutions dalam kamus yang dikembalikan mengandungi semua penyelesaian terbaik yang degenerat, dalam bentuk kamus yang memetakan setiap nama pemboleh ubah kepada nilai yang ditetapkan kepadanya. Penyelesaian yang sama juga dikembalikan sebagai bitstring dalam solution_bitstrings; metadata.solver_info.variable_mapping memberitahu anda kedudukan aksara mana dalam bitstring yang menjadi milik pemboleh ubah mana. Selain data penyelesaian, objective_value, bendera feasible, dan metadata tambahan turut disediakan.

Contoh 2: Maximum Independent Set

Masalah Maximum Independent Set (MIS) meminta subset bucu (vertices) terbesar dalam graf supaya tiada dua bucu dalam subset itu berkongsi tepi. Contoh ini menyelesaikan MIS pada graf sekata 12-nod. Untuk maklumat lanjut mengenai masalah ini dan contoh yang lebih besar, rujuk tutorial.

Masalah ini dibina dengan qiskit-addon-opt-mapper. Pasang pakej yang diperlukan jika perlu:

# %pip install networkx qiskit-addon-opt-mapper

Langkah 1: Takrifkan masalah

Bina graf 3-regular rawak dan cipta masalah pengoptimuman MIS. Setiap nod graf menjadi pemboleh ubah binari, dan setiap tepi memperkenalkan kekangan yang memastikan paling banyak satu titik akhir dipilih.

import networkx as nx
from qiskit_addon_opt_mapper.applications import IndependentSet
from qiskit_addon_opt_mapper.translators import to_docplex_mp

# 12-node random 3-regular graph
G = nx.random_regular_graph(3, 12, seed=7)

# Build MIS problem and export as LP string
mis = IndependentSet(G)
mis_problem = mis.to_optimization_problem()
lp_str = to_docplex_mp(mis_problem).export_as_lp_string()

print(lp_str)

\ This file has been generated by DOcplex
\ ENCODING=ISO-8859-1
\Problem name: Independent set

Maximize
 obj: x_0 + x_1 + x_2 + x_3 + x_4 + x_5 + x_6 + x_7 + x_8 + x_9 + x_10 + x_11
Subject To
 c0: x_0 + x_4 <= 1
 c1: x_0 + x_9 <= 1
 c2: x_0 + x_8 <= 1
 c3: x_1 + x_2 <= 1
 c4: x_1 + x_7 <= 1
 c5: x_1 + x_3 <= 1
 c6: x_2 + x_4 <= 1
 c7: x_2 + x_11 <= 1
 c8: x_3 + x_10 <= 1
 c9: x_3 + x_11 <= 1
 c10: x_4 + x_5 <= 1
 c11: x_5 + x_10 <= 1
 c12: x_5 + x_6 <= 1
 c13: x_6 + x_8 <= 1
 c14: x_6 + x_7 <= 1
 c15: x_7 + x_9 <= 1
 c16: x_8 + x_11 <= 1
 c17: x_9 + x_10 <= 1

Bounds
 0 <= x_0 <= 1
 0 <= x_1 <= 1
 0 <= x_2 <= 1
 0 <= x_3 <= 1
 0 <= x_4 <= 1
 0 <= x_5 <= 1
 0 <= x_6 <= 1
 0 <= x_7 <= 1
 0 <= x_8 <= 1
 0 <= x_9 <= 1
 0 <= x_10 <= 1
 0 <= x_11 <= 1

Binaries
 x_0 x_1 x_2 x_3 x_4 x_5 x_6 x_7 x_8 x_9 x_10 x_11
End

Langkah 2: Jalankan pengoptimum

Selesaikan masalah dengan pengoptimum.

options = {"total_shots": 2000, "use_session": True}

# Dispatch the job
job_2 = optimizer.run(
    problem=lp_str, backend_name=backend.name, options=options
)

print(f"Job ID: {job_2.job_id}")

Job ID: f041431c-b42e-4627-afe5-522fea61faf6

# Monitor the job status
job_2.status()

'QUEUED'

Langkah 3: Dapatkan dan tafsirkan hasil

Akhir sekali kita dapatkan penyelesaian dan sahkan ketepatannya.

result = job_2.result()

print(f"Feasible: {result['feasible']}")
print(f"Independent set size: {int(result['objective_value'])}")

# Extract the selected nodes
solution = result["solutions"][0]
independent_set = [
    int(k.split("_")[1]) for k, v in solution.items() if v == 1
]
print(f"Selected nodes: {sorted(independent_set)}")

# Verify no two selected nodes share an edge
conflicts = [
    (u, v)
    for u, v in G.edges()
    if u in independent_set and v in independent_set
]
print(f"Edge conflicts: {conflicts}")

Feasible: True
Independent set size: 5
Selected nodes: [1, 4, 6, 9, 11]
Edge conflicts: []

Contoh 3: Pewarnaan-3 graf (Max-3-Cut)

Masalah Max-$k$-Cut mempartisikan bucu graf kepada $k$ kumpulan untuk memaksimumkan bilangan tepi yang titik akhirnya tergolong dalam kumpulan yang berbeza. Untuk $k = 3$ ini setara dengan mencari pewarnaan-3 yang memaksimumkan tepi silang warna.

Secara formal, tetapkan setiap nod $i \in V$ kepada salah satu daripada $k$ kumpulan dengan pemboleh ubah binari $x_{i,c}$ untuk warna $c \in \{1, \ldots, k\}$. Kekangan one-hot $\sum_c x_{i,c} = 1$ untuk setiap nod menguatkuasakan penetapan yang unik. Objektif memaksimumkan tepi silang kumpulan:

$$\min \sum_{(u,v) \in E} \sum_c x_{u,c} \, x_{v,c}\\ \text{s.t.} \sum_{c} x_{i,c} = 1 \quad \forall i \in V$$

Kekangan one-hot adalah ideal untuk XY-mixers, yang dikendalikan secara asli oleh pengoptimum.

Contoh ini menggunakan graf Zachary Karate Club (34 nod, 78 tepi) dan membina model dengan Model Luna. Pasang pakej yang diperlukan jika perlu:

# %pip install networkx matplotlib luna-model

Langkah 1: Takrifkan masalah

Pertama, jana pemboleh ubah binari dengan pakej luna-model. Kemudian, takrifkan objektif dan tambahkan kekangan pada model.

import networkx as nx
from luna_model import Model, quicksum

k = 3
G = nx.karate_club_graph()

# Instantiate the Model object
model = Model(name="Max-3-Cut")

# Add binary variables
x = model.add_variables("x", shape=(G.number_of_nodes(), k))

# Add the objective by using the numpy dot abstraction
model.objective = quicksum(x[i].dot(x[j]) for i, j in G.edges)

# Bulk-add the one-hot constraints
model.add_constraints(x.sum(axis=1) == 1)

# Encode the model to send via API
model_enc = model.encode_b64()

Langkah 2: Jalankan pengoptimum

Selesaikan masalah dengan pengoptimum.

options = {"use_session": True}

# Dispatch the job
job_3 = optimizer.run(
    problem=model_enc, backend_name=backend.name, options=options
)

print(f"Job ID: {job_3.job_id}")

Job ID: df911d83-9df7-44a1-bfad-5d66e08676c3

# Monitor the job status
job_3.status()

'RUNNING: WAITING_FOR_QPU'

Langkah 3: Dapatkan dan visualisasikan hasil

Dapatkan dan visualisasikan hasil.

result = job_3.result()
solution = result["solutions"][0]

# Map each node to its assigned color group
node_group = {}
for i in G.nodes:
    for c in range(k):
        if solution[f"x{i},{c}"] == 1:
            node_group[i] = c

print(f"Feasible: {result['feasible']}")
print(f"Violations: {int(result['objective_value'])}")

# Visualize the partition
colors = ["tab:blue", "tab:orange", "tab:green"]
node_colors = [colors[node_group[i]] for i in G.nodes()]
nx.draw(G, nx.kamada_kawai_layout(G), node_color=node_colors, node_size=200)

Feasible: True
Violations: 4

Log perubahan

[0.4.0] - 2026-09-22

Perubahan yang memecahkan keserasian

• Menamakan semula parameter input model kepada problem.
• Menamakan semula medan output obj_value kepada objective_value.
• Menggantikan pilihan postprocessing dengan postprocessing_level, yang menerima integer dalam julat [0, 3] dan bukannya rentetan. Nilai sebelumnya dipetakan seperti berikut: "off" -> 0, "weak" -> 1, "medium" -> 2, dan "strong" -> 3, dan nilai lalai kekal 3.
• Menyusun semula metadata.circuit_metrics. Ia kini melaporkan num_qubits, gate_count, depth, two_qubit_gate_count, two_qubit_gate_depth, dan operations secara berasingan untuk before_transpilation dan after_transpilation, dan bukannya satu kamus rata bagi purata bilangan gate. Medan ini ialah None apabila masalah diselesaikan semasa prapemprosesan dan tiada litar dijalankan (kod ralat 4712).

Ciri

• Menambah pilihan seed_transpiler supaya sintesis dan penghalaan circuit boleh dihasilkan semula merentas larian.
• Menambah pilihan job_tags untuk melampirkan tag anda sendiri pada setiap job Qiskit Runtime yang dihantar oleh fungsi ini.
• Menambah medan output solution_bitstrings, yang mengembalikan penyelesaian yang sama seperti solutions dalam bentuk bitstring.
• Menambah metadata.solver_info.variable_mapping, yang memetakan setiap nama pemboleh ubah kepada kedudukan aksaranya dalam entri solution_bitstrings.

Dokumentasi

• Mendokumenkan bahawa pemboleh ubah selanjar (bernilai nyata) tidak disokong dan pemboleh ubah integer memerlukan had yang jelas. Model sedemikian gagal dengan kod ralat 4710.

Dapatkan sokongan

Untuk soalan atau isu, hubungi support@aqarios.com dengan ID kerja anda.

Langkah seterusnya

Cadangan

• Request access to the Constrained Quantum Optimizer by Aqarios.
• Lawati rujukan API untuk dokumentasi parameter dan output yang lengkap.
• Cuba tutorial Find the Maximum Independent Set with the Aqarios Constrained Quantum Optimizer untuk penerokaan mendalam ke dalam instans penanda aras QOBLIB sebenar.
• Semak penerbitan Constrained Quantum Optimization via Iterative Warm-Start XY-Mixers.

Rujukan

1. Bucher et al. (2026), Constrained Quantum Optimization via Iterative Warm-Start XY-Mixers 10.1088/1367-2630/ae8ea2