محسّن الكم المقيد - دالة Qiskit من Aqarios

راجع مرجع API

ملاحظة

Qiskit Functions ميزة تجريبية متاحة فقط لمستخدمي خطط IBM Quantum® Premium Plan وFlex Plan وOn-Prem (عبر IBM Quantum Platform API). وهي في حالة إصدار أولي (preview) وقابلة للتغيير.

نظرة عامة

باستخدام محسّن الكم المقيد من Aqarios، يمكنك حل مسائل التحسين الثنائي المقيدة على أجهزة IBM® الكمية دون الحاجة إلى إعادة الصياغة اليدوية أو تخطيط الدارات. ما عليك سوى تزويد المسألة كملف LP أو ملف MPS أو نموذج Luna. تتولى الدالة تلقائيًا إعادة الصياغة، وتركيب الدارة، والتحويل البرمجي، والتنفيذ على الجهاز. يستخدم المحلل البداية الدافئة التكرارية [1] لخوارزمية FlexQAOA، وهي امتداد أصلي للقيود لخوارزمية التحسين التقريبي الكمي (QAOA).

يستهدف المحسّن المسائل الثنائية ذات القيود. وعلى وجه الخصوص، يمكن فرض قيود "one-hot" وقيود "set-packing" بشكل أصلي باستخدام خلاطات XY. أما أنواع القيود الأخرى فتتم إعادة صياغتها تلقائيًا كحدود عقابية.

أنواع المتغيرات المدعومة

تحل الدالة المسائل المتقطعة فقط. يجب أن يكون كل متغير قرار ثنائياً، أو عدداً صحيحاً بحد أدنى وحد أعلى صريحين، حتى يمكن ترميزه في الكيوبتات. المتغيرات المستمرة (ذات القيم الحقيقية) غير مدعومة: النموذج الذي يحتويها يُرفض برمز الخطأ 4710.

الوصف

إخلاء مسؤولية

قد يعتمد الأداء على كل من مثيل المسألة وخطوات المعالجة اللاحقة. في بعض الحالات، قد تحقق العينات الكلاسيكية والعينات المولّدة كميًا جودة حل نهائية متشابهة بعد معالجة لاحقة متكافئة. لذا ينبغي أن يأخذ التقييم في الاعتبار سير عمل التحسين الكامل.

ينفّذ محسّن الكم المقيد خوارزمية QAOA ذات خلاط XY وبداية دافئة تكرارية (IWS-QAOA) [1]. تُشغّل الخوارزمية دارات QAOA بزوايا ثابتة على الجهاز الكمي، وتحدّث احتمالات البداية الدافئة الأولية لكل دارة باستخدام نتائج القياس من التكرار السابق. لا يلزم أي تدريب لمعاملات تبايُنية؛ بل يتم اختيار معاملة تدرّج خطي ثابتة بدلاً من ذلك.

باستخدام خلاطات XY لفرض قيود "one-hot"، يمكنك تحسين جودة الحل بشكل كبير للمسائل المقيدة، لأن مساحة البحث تُختزل عمليًا إلى فضاء جزئي أصغر قابل للتحقيق — دون إدخال أي تعقيد إضافي، بسبب الحدود العقابية، في مشهد التحسين.

سير العمل

يُوصف سير عمل الدالة أدناه:

1. المعالجة المسبقة: قبل تركيب الدارة، يحلّل المحسّن بنية القيود الخاصة بالمسألة المُدخلة:

   • المعالجة المسبقة للرسم البياني: عند إمكانية تطبيقها على المسألة، يتم تحليلها كرسم بياني، حيث تحدد الحواف العلاقة بين المتغيرات. يتيح هذا التحليل البياني تحسينين للمعالجة المسبقة للمسألة. أولاً، يمكن تجميع القيود المفردة في قيد واحد كبير باستخدام دمج الزُّمر، بحيث تُمثَّل بخلاط XY واحد. ثانيًا، يمكن تثبيت المتغيرات التي لها جار واحد فقط بشكل حتمي، مما يقلل من حجم المسألة وتعقيدها.

   • حل القيود: يتعامل المعالج المسبق مع كل قيد على حدة: إذا كان القيد من نوع "one-hot"، يمكن فرضه من خلال خلاطات XY. وإذا كان قيد "set-packing"، فسيتم تحويله أولاً إلى قيد "one-hot". أما قيود المساواة فتُعالَج من خلال حدود عقابية تربيعية، وقيود عدم المساواة من خلال العقوبة غير المتوازنة.

   • اشتقاق العقوبة: تُحوَّل القيود التي لا يمكن التعبير عنها كقيود مساواة من نوع "one-hot" إلى حدود عقابية. ويشتق المحسّن قوة العقوبة تلقائيًا من بنية المسألة.

2. البداية الدافئة التكرارية: يشغّل المحسّن عدة سلاسل بداية دافئة متوازية. تحتفظ كل سلسلة بتوزيع احتمالي على تعيينات المتغيرات، يُستخدم كاحتمال البداية لدارة QAOA (حالة البداية الدافئة). في كل تكرار، تأخذ السلسلة عينات من الدارة الكمية، وتطبّق معالجة لاحقة كلاسيكية، وتحدّث توزيعها بناءً على تكرار ظهور العينات. ومع توالي التكرارات، يوجّه ذلك البحثَ نحو الحلول عالية الجودة دون الحاجة إلى حلقة تحسين تبايُنية.

يُعد عدد السلاسل (num_parallel)، وإجمالي ميزانية اللقطات لكل سلسلة (total_shots)، وعدد تكرارات QAOA (reps) عناصر التحكم الرئيسية للموازنة بين جودة الحل ووقت التشغيل.

معايير الأداء

توضح معايير الأداء أدناه أن دالة Qiskit الخاصة بمحسّن الكم المقيد قادرة على إيجاد حلول قابلة للتحقيق وعالية الجودة لمسائل التحسين المقيدة التي تضم ما يزيد كثيرًا على 100 متغير ثنائي. الدقة هي نسبة قيمة الهدف التي عُثر عليها إلى القيمة المثلى المعروفة. وقت التشغيل هو الزمن الفعلي من استدعاء الدالة إلى تسليم النتيجة. استخدام QPU هو وقت الحوسبة الكمية القابل للفوترة.

تم فحص مسألتين: مسألة أكبر مجموعة مستقلة (MIS) ومسألة Max-$k$-Cut، وهي امتداد لمسألة MaxCut المعروفة إلى أكثر من فئتين. تُعد مسألة Max-$k$-Cut أيضًا المكافئ في مسائل التحسين لمسألة قرار تلوين الرسم البياني (عندما تُقطع جميع الحواف، يكون الرسم البياني قابلاً للتلوين بـ $k$ ألوان).

المسألة	المتغيرات	القيود	الكيوبتات	الدقة	إمكانية التحقيق	إجمالي وقت التشغيل (ثانية)	استخدام QPU (ثانية)	إجمالي اللقطات
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

ملاحظات حول معايير الأداء

• تم الحصول على النتائج أعلاه على معالج Heron r2 ibm_marrakesh باستخدام الخيارات الافتراضية وتفعيل use_session. بالنسبة لمثيل sloane_2dc_128، تم استخدام total_shots=12500.

• يعكس انخفاض عدد الكيوبتات لمثيلات MIS (74 و124 مقابل 128 و186 متغيرًا) تثبيت المتغيرات أثناء المعالجة المسبقة.

• مثيلات مسألة MIS مأخوذة من مكتبة معايير أداء التحسين الكمي. - مثيل مسألة Max-$k$-Cut هو رسم نادي كاراتيه زكاري، الذي يبلغ رقمه اللوني 5.

البدء

يوضّح هذا الدليل الاستخدام الأساسي لمحسّن الكم المقيد من خلال بيان كيفية تحميل الدالة وتنفيذ مسائل بسيطة. للاطلاع على درس تعليمي أكثر تفصيلاً، راجع إيجاد أكبر مجموعة مستقلة باستخدام محسّن الكم المقيد من Aqarios.

قم بالمصادقة باستخدام مفتاح IBM Quantum API الخاص بك وCRN للمثيل، ثم حمّل الدالة من الكتالوج.

ملاحظة

تفترض الشيفرة التالية أنك قد حفظت بيانات الاعتماد الخاصة بك. لإعدادها، اتبع التعليمات الواردة في حفظ بيانات اعتماد حساب IBM Cloud.

# 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")

المثال 1: مسألة مقيدة بسيطة

يوضّح المثال الأول كيفية استخدام الدالة مع ملفات LP، وهي مواصفة شائعة لمسائل التحسين تُستخدم في بحوث العمليات. ستصوغ مسألة التحسين التوضيحية التالية، المكوّنة من خمسة متغيرات ثنائية $x_i \in \{0,1\}$، والتي تخضع لقيدين:

$$\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. صياغة المسألة

اذكر التعبير الرياضي مباشرة بصيغة سلسلة LP التالية:

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
"""

لاحظ أن [ ... ] / 2 هي علامة مطلوبة للأهداف التربيعية وفق معيار LP.

2. تشغيل المحسّن

حل المسألة باستخدام المحسّن.

# 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. استرجاع النتيجة

يوفر ناتج التنفيذ الحل، الذي يربط أسماء المتغيرات بالقيم المخصصة لها.

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}}}}

يحتوي الحقل solutions في القاموس المُعاد على جميع أفضل الحلول المتكافئة التي تم العثور عليها، على شكل قواميس تربط اسم كل متغير بقيمته المسندة. كما تُعاد الحلول نفسها على شكل سلاسل بتات في solution_bitstrings؛ ويخبرك metadata.solver_info.variable_mapping بموضع الحرف في سلسلة البتات الذي يخص كل متغير. وإلى جانب بيانات الحلول، يتم توفير objective_value ومؤشر feasible وmetadata إضافية.

المثال 2: أكبر مجموعة مستقلة

تطلب مسألة أكبر مجموعة مستقلة (MIS) إيجاد أكبر مجموعة جزئية من رؤوس رسم بياني بحيث لا يشترك أي رأسين في تلك المجموعة في حافة واحدة. يحل هذا المثال مسألة MIS على رسم بياني منتظم مكوّن من 12 عقدة. لمزيد من المعلومات حول المسألة ومثال أكبر، راجع الدرس التعليمي.

تُبنى المسألة باستخدام qiskit-addon-opt-mapper. ثبّت الحزم المطلوبة إذا لزم الأمر:

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

الخطوة 1: تعريف المسألة

ابنِ رسمًا بيانيًا عشوائيًا منتظمًا من الدرجة 3، وأنشئ مسألة تحسين MIS. تصبح كل عقدة في الرسم البياني متغيرًا ثنائيًا، وتقدّم كل حافة قيدًا يضمن اختيار طرف واحد على الأكثر من طرفيها.

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

الخطوة 2: تشغيل المحسّن

حل المسألة باستخدام المحسّن.

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'

الخطوة 3: استرجاع النتائج وتفسيرها

أخيرًا، نسترجع الحل ونتحقق من صحته.

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: []

المثال 3: تلوين الرسم البياني بثلاثة ألوان (Max-3-Cut)

تقسّم مسألة Max-$k$-Cut رؤوس الرسم البياني إلى $k$ مجموعات بهدف تعظيم عدد الحواف التي ينتمي طرفاها إلى مجموعتين مختلفتين. عند $k = 3$، يعادل ذلك إيجاد تلوين بثلاثة ألوان يعظّم عدد الحواف بين الألوان المختلفة.

رسميًا، يتم تعيين كل عقدة $i \in V$ إلى إحدى مجموعات $k$ باستخدام متغيرات ثنائية $x_{i,c}$ للون $c \in \{1, \ldots, k\}$. يفرض قيد "one-hot" $\sum_c x_{i,c} = 1$ لكل عقدة تعيينًا فريدًا. يعظّم الهدف عدد الحواف بين المجموعات المختلفة:

$$\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$$

قيود "one-hot" مثالية لخلاطات XY، التي يتعامل معها المحسّن بشكل أصلي.

يستخدم هذا المثال رسم نادي كاراتيه زكاري (34 عقدة، 78 حافة) ويبني النموذج باستخدام نموذج Luna. ثبّت الحزم المطلوبة إذا لزم الأمر:

# %pip install networkx matplotlib luna-model

الخطوة 1: تعريف المسألة

أولاً، أنشئ المتغيرات الثنائية باستخدام حزمة luna-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()

الخطوة 2: تشغيل المحسّن

حل المسألة باستخدام المحسّن.

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'

الخطوة 3: استرجاع النتائج وتصويرها

استرجع النتائج واعرضها بصريًا.

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

سجل التغييرات

[0.4.0] - 2026-09-22

تغييرات غير متوافقة مع الإصدارات السابقة

• تمت إعادة تسمية معامل الإدخال model إلى problem.
• تمت إعادة تسمية حقل الإخراج obj_value إلى objective_value.
• تم استبدال الخيار postprocessing بالخيار postprocessing_level، الذي يأخذ عدداً صحيحاً ضمن النطاق [0, 3] بدلاً من سلسلة نصية. تُقابَل القيم السابقة كما يلي: "off" -> 0، و"weak" -> 1، و"medium" -> 2، و"strong" -> 3، وتبقى القيمة الافتراضية دون تغيير عند 3.
• تمت إعادة هيكلة metadata.circuit_metrics. أصبح يُبلغ عن num_qubits وgate_count وdepth وtwo_qubit_gate_count وtwo_qubit_gate_depth وoperations بشكل منفصل لكل من before_transpilation وafter_transpilation، بدلاً من قاموس مسطح واحد لمتوسطات عدد البوابات. يكون الحقل None عندما تم حل المسألة أثناء المعالجة المسبقة ولم يتم تشغيل أي دارة (رمز الخطأ 4712).

الميزات

• تمت إضافة الخيار seed_transpiler لجعل تركيب الدارات وتوجيهها قابلاً لإعادة الإنتاج عبر التشغيلات.
• تمت إضافة الخيار job_tags لإرفاق وسومك الخاصة بكل مهمة Qiskit Runtime تقدمها الدالة.
• تمت إضافة حقل الإخراج solution_bitstrings، الذي يعيد الحلول نفسها الموجودة في solutions على شكل سلاسل بتات.
• تمت إضافة metadata.solver_info.variable_mapping، الذي يربط اسم كل متغير بموضع حرفه في عناصر solution_bitstrings.

التوثيق

• تم توثيق أن المتغيرات المستمرة (ذات القيم الحقيقية) غير مدعومة، وأن المتغيرات الصحيحة تتطلب حدوداً صريحة. تفشل هذه النماذج برمز الخطأ 4710.

الحصول على الدعم

للأسئلة أو المشكلات، تواصل مع support@aqarios.com مع ذكر معرّف المهمة الخاص بك.

الخطوات التالية

توصيات

• اطلب الوصول إلى محسّن الكم المقيد من Aqarios.
• قم بزيارة مرجع API للاطلاع على التوثيق الكامل للمعاملات والمخرجات.
• جرّب درس إيجاد أكبر مجموعة مستقلة باستخدام محسّن الكم المقيد من Aqarios للتعمق في مثيل حقيقي من معايير أداء QOBLIB.
• راجع المنشور Constrained Quantum Optimization via Iterative Warm-Start XY-Mixers.

المراجع

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