مقدمة إلى Qiskit Functions

ملاحظات

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

إصدارات الحزم

تم تطوير الكود في هذه الصفحة باستخدام المتطلبات التالية. نوصي باستخدام هذه الإصدارات أو أحدث منها.

qiskit[all]~=1.4.1
qiskit-ibm-runtime~=0.37.0
qiskit-ibm-catalog~=0.4

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

تأتي الدوال في شكلين:

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

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime

تُقدِّم الدوال IBM® وشركاء من أطراف ثالثة. كل دالة ذات أداء عالٍ لخصائص أعباء عمل محددة، ولها خيارات فريدة لضبط الأداء.

نظرة عامة على الدوال المتاحة

دوال Circuit

الاسم	المزوِّد	الاستخدام الموصى به	الفوائد الفريدة
Tensor-Network Error Mitigation	Algorithmiq	أعباء العمل التي تحتوي على مُراقِبات خفيفة الوزن ودوائر خالية من الحلقات.	يُقلِّل من الحمل الزائد للقياس والتباين، متفوِّقًا على خطوط الأساس القياسية لتخفيف الأخطاء مثل Zero Noise Extrapolation (ZNE) وProbabilistic Error Cancellation (PEC) لفئات الدوائر ذات الصلة.
QESEM: Error Suppression and Error Mitigation	Qedma	أعباء العمل التي تتضمَّن دوائر بها بوابات كسرية أو مُعامَلة، ومُراقِبات ثقيلة الوزن، وسير عمل تتطلَّب قيم توقع غير متحيِّزة وتقديرات دقيقة لوقت التشغيل.	تُنتِج قيم توقع غير متحيِّزة مع تباين أقل وحمل زائد أقل للموارد، متفوِّقةً على ZNE وPEC لفئات الدوائر ذات الصلة.
Performance Management	Q-CTRL	أعباء العمل التي تحتوي على دوائر بارامترية أو دوائر عميقة، أو التي تتطلَّب تنفيذات دوائر كثيرة.	يُطبِّق تلقائيًا قمع الأخطاء المدفوع بالذكاء الاصطناعي على الخوارزميات الكمومية، مما يزيد من أداء أجهزة IBM لتحقيق نتائج دقيقة مع تقليل عدد اللقطات ووقت الحساب والتكلفة المطلوبة. طريقة بدون حمل زائد تُحسِّن دقة التنفيذ لكل من Sampler وEstimator primitives، متوافقة مع أي وزن من المُراقِبات.

دوال التطبيقات

الاسم	المزوِّد	الاستخدام الموصى به	الفوائد الفريدة
QUICK-PDE	ColibriTD	استخدام الحوسبة الكمومية لمعادلات الفيزياء المتعددة PDEs. إعداد سير عمل المحاكاة للعتاد الكمومي، مع الاحتفاظ بالتحكم الكامل في كل من معامِلات النمذجة الكمومية والفيزيائية.	يُقدِّم إطار عمل هجيني قوي لـ VQA يُحقِّق حلولًا دقيقة وقابلة للتوسُّع لـ PDE من خلال الترميز المتقدِّم للحلول والطرق الطيفية، مما يجعله نقطة دخول مثالية للفِرق التي تسعى إلى بناء قدرات محاكاة جاهزة للكم.
Quantum Portfolio Optimizer	Global Data Quantum	أعباء عمل التحسين المالي، بحثًا عن استراتيجيات المحفظة المثلى عبر الزمن مع تقليل المخاطر وتعظيم العوائد، وتمكين الاختبار العكسي لاستراتيجيات التداول.	تحل مشاكل التحسين التوافقي من خلال تكيُّف متخصَّص للغاية لخوارزمية VQE الكمومية لهذه الحالة الاستخدامية المالية، باستخدام استراتيجيات تنفيذ محسَّنة ومُحسِّنات، إلى جانب تقنيات تخفيف الأخطاء الواعية بالضجيج المصمَّمة لتحسين المحفظة.
HI-VQE Chemistry	Qunova Computing	أعباء عمل في الكيمياء الحسابية ومحاكاة الجزيئات وعلوم المواد، أو أي محاكاة هاميلتونية تتطلَّب حل مشاكل البنية الإلكترونية متعددة الأجسام.	تحل البنى الإلكترونية الجزيئية باستخدام SQD المُحسَّن لتحقيق دقة كيميائية (1 kcal/mol، 1.6 mHa) للمسائل المُصمَّمة بـ 40 إلى 60 كيوبت، متفوِّقةً على بعض الحلول الكلاسيكية على الحواسب الفائقة أو SQD القياسي في سرعة التقارب أو الدقة، على التوالي، بفوارق بمراتب من الحجم.
Iskay Quantum Optimizer	Kipu Quantum	أعباء عمل التحسين مثل الجدولة والخدمات اللوجستية والتوجيه ومشاكل QUBO/HUBO.	طرق معالجة مسبقة ولاحقة كلاسيكية قابلة للضبط ومُدمَجة لروتين التحسين الكمومي. تُحقِّق ميزة وقت تشغيل على الحلول الكلاسيكية (CPLEX والتلدين المحاكى والبحث التابو) على معايير HUBO المختارة. تم حل ms_5_100 من Market Split، وهو تحدٍّ صعب، في غضون ساعات (انظر هذا البرنامج التعليمي).
Singularity Machine Learning	Multiverse Computing	سير عمل تصنيف التعلم الآلي الكلاسيكي التي يمكنها الاستفادة من تحسين الدقة أو الكفاءة الحسابية من خلال الاستفادة من التحسين الكمومي المُنفَّذ على عتاد IBM.	تُحقِّق دقة مماثلة أو تتجاوز النماذج الكلاسيكية مثل Random Forest أو XGBoost، مع العمل بعدد أقل بكثير من المُتعلِّمين وبناء مجموعة أكثر إحكامًا. مدعومة بالتصويت المُحسَّن كميًا، تختار أكثر المُتعلِّمين إفادةً وتُصقِّل حدود القرار، مما يُتيح كفاءة أعلى وتعقيدًا أقل في النموذج وأداءً أكثر متانة.
Optimization Solver	Q-CTRL	مشاكل التحسين الثنائية أو أي مشكلة توافقية يمكن تعيينها إلى دالة تكلفة ثنائية. تُدعَم دوال التكلفة من أي رتبة وأحجام مشاكل تصل إلى الحد الأقصى لمقياس الجهاز.	حل تحسين كمومي شامل وواعٍ بالضجيج يُتيح مدخلات من تعريفات المشاكل عالية المستوى ويجد تلقائيًا حلولًا دقيقة للمشاكل التوافقية الصعبة كلاسيكيًا على عتاد كمومي بمقياس الفائدة. يُجرِّد التعقيد من خلال التعامل مع قمع الأخطاء والتعيين الفعّال والتحسين الهجين الكمومي الكلاسيكي لحل مهام التحسين على مقياس الجهاز الكامل دون الحاجة إلى خبرة كمومية عميقة.

ابدأ مع Qiskit Functions

يمكن لمستخدمي خطط Premium وFlex وOn-Prem (عبر IBM Quantum Platform API) البدء في استخدام IBM Qiskit Functions مجانًا، أو الحصول على ترخيص من أحد الشركاء الذين أضافوا دالة إلى الكتالوج.

طلب تجربة مجانية لـ Qiskit Functions من أطراف ثالثة

لطلب تجربة مجانية جديدة، انتقل إلى كتالوج Qiskit Functions واستكشف لوحة التفاصيل. انقر على Request a free trial واملأ المعلومات المطلوبة من شريك الدوال، بما في ذلك AccessGroupId من IBM Cloud:

1. انتقل إلى IBM Cloud IAM.
2. تحقَّق من الأهلية.
   • قم بتبديل حسابك في الشريط العلوي إلى حساب بالتنسيق التالي: XXXXXXX - [Organization Name]
   • تأكَّد من أن المؤسسة هي نفسها المرتبطة بحساب Premium الخاص بك.
   • إذا رأيت "[Your Name]'s Account"، فأنت تستخدم حسابك الشخصي، وهو غير مؤهَّل للوصول المميَّز.
3. ابحث عن معرِّف مجموعة الوصول الخاص بك.
   • انقر على اسم مجموعة.
   • انقر على Details.
   • انسخ معرِّف مجموعة الوصول. يجب أن يبدأ بـ AccessGroup-.

تثبيت عميل Qiskit Functions Catalog

1. لبدء استخدام Qiskit Functions، ثبِّت عميل IBM Qiskit Functions Catalog:

   pip install qiskit-ibm-catalog

2. استرجع مفتاح API الخاص بك من لوحة تحكم IBM Quantum Platform، وقم بتفعيل بيئتك الافتراضية في Python. راجع تعليمات التثبيت إذا لم تكن قد أعددت بيئة افتراضية بعد.

   إذا كنت تعمل في بيئة Python موثوقة (مثل جهاز الكمبيوتر المحمول الشخصي أو محطة العمل)، استخدم طريقة save_account() لحفظ بيانات الاعتماد محليًا. (انتقل إلى الخطوة التالية إذا لم تكن تستخدم بيئة موثوقة، مثل جهاز مشترك أو عام، للمصادقة على IBM Quantum Platform.)

   لاستخدام save_account()، شغِّل python في الصدفة (shell)، ثم أدخل ما يلي:

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   
   QiskitFunctionsCatalog.save_account(channel="ibm_quantum_platform", token="<your-token>", instance="<instance-crn>")

   اكتب exit(). من الآن فصاعدًا، في كل مرة تحتاج فيها إلى المصادقة على الخدمة، يمكنك تحميل بيانات الاعتماد الخاصة بك بـ

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   catalog = QiskitFunctionsCatalog()

# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

3. تجنَّب تنفيذ الكود على جهاز غير موثوق أو بيئة Python خارجية على السحابة لتقليل مخاطر الأمان. إذا كان عليك استخدام بيئة غير موثوقة (مثل جهاز كمبيوتر عام)، فغيِّر مفتاح API الخاص بك بعد كل استخدام بحذفه من صفحة IBM Cloud API keys لتقليل المخاطر. تعرَّف على المزيد في موضوع Managing user API keys. لتهيئة الخدمة في هذه الحالة، قم بتوسيع القسم التالي للاطلاع على الكود الذي يمكنك استخدامه:

   تهيئة الخدمة في بيئة غير موثوقة

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   
   # After using the following code, delete your API key on the IBM Quantum Platform home dashboard
   catalog = QiskitFunctionsCatalog(token="<YOUR_API_KEY>") # Use the 44-character API_KEY you created and saved from the IBM Quantum Platform Home dashboard

   تنبيه

   احمِ مفتاح API الخاص بك! لا تُدرِج مفتاحك أبدًا في الكود المصدري أو سكربت Python أو ملف notebook. عند مشاركة الكود مع الآخرين، تأكَّد من أن مفتاح API الخاص بك غير مُضمَّن مباشرةً في سكربت Python. بدلاً من ذلك، شارك السكربت بدون المفتاح وقدِّم تعليمات لإعداده بأمان.

   إذا شاركت مفتاحك مع شخص ما عن طريق الخطأ أو أدرجته في نظام التحكم في الإصدار مثل Git، فأبطِل مفتاحك فورًا بحذفه من صفحة IBM Cloud API keys لتقليل المخاطر. تعرَّف على المزيد في موضوع Managing user API keys.

4. بعد المصادقة، يمكنك سرد الدوال من كتالوج Qiskit Functions التي يمكنك الوصول إليها:

catalog.list()

[QiskitFunction(qunova/hivqe-chemistry),
 QiskitFunction(global-data-quantum/quantum-portfolio-optimizer),
 QiskitFunction(algorithmiq/tem),
 QiskitFunction(qedma/qesem),
 QiskitFunction(multiverse/singularity),
 QiskitFunction(ibm/circuit-function),
 QiskitFunction(q-ctrl/optimization-solver),
 QiskitFunction(colibritd/quick-pde),
 QiskitFunction(q-ctrl/performance-management),
 QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]

تشغيل الدوال المُفعَّلة

بعد إنشاء كائن كتالوج، يمكنك تحديد دالة باستخدام catalog.load(provider/function-name):

ibm_cf = catalog.load("ibm/circuit-function")

لكل Qiskit Function مدخلات وخيارات ومخرجات مخصَّصة. راجع صفحات التوثيق المحددة للدالة التي تريد تشغيلها للحصول على مزيد من المعلومات. بشكل افتراضي، يمكن لجميع المستخدمين تشغيل وظيفة دالة واحدة فقط في كل مرة:

# This cell is hidden from users
# It gets these details programmatically so we can test this notebook
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit.circuit.random import random_circuit

service = QiskitRuntimeService()
instance = service.active_account()["instance"]
backend_name = service.least_busy().name

circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits

job = ibm_cf.run(
    pubs=[(circuit, observable)],
    instance=instance,
    backend_name=backend_name,  # E.g. "ibm_fez"
)

job.job_id

'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'

التحقق من حالة الوظيفة

نصيحة

حاليًا، يعكس جدول أعباء العمل في IBM Quantum فقط أعباء عمل Qiskit Runtime. استخدم job.status() لرؤية الحالة الراهنة لعبء عمل Qiskit Function الخاص بك.

بامتلاكك job_id الخاص بـ Qiskit Function، يمكنك التحقق من حالة الوظائف قيد التشغيل. يشمل ذلك الحالات التالية:

• QUEUED: البرنامج البعيد في قائمة انتظار Qiskit Function. تعتمد أولوية القائمة على مقدار استخدامك لـ Qiskit Functions.
• INITIALIZING: البرنامج البعيد يبدأ التشغيل؛ يشمل ذلك إعداد البيئة البعيدة وتثبيت التبعيات.
• RUNNING: البرنامج قيد التشغيل. يشمل أيضًا عدة حالات أكثر تفصيلاً إذا كانت مدعومة من دوال محددة:
  • RUNNING: MAPPING: الدالة تُعيِّن حاليًا مدخلاتك الكلاسيكية إلى مدخلات كمومية
  • RUNNING: OPTIMIZING_FOR_HARDWARE: الدالة تُحسِّن للـ QPU المختار. قد يشمل ذلك تحويل الدوائر (Transpilation) وتوصيف QPU وانتشار المُراقِب العكسي وما إلى ذلك
  • RUNNING: WAITING_FOR_QPU: قدَّمت الدالة وظيفة إلى Qiskit Runtime، وهي في انتظار دورها في القائمة
  • RUNNING: EXECUTING_QPU: الدالة لديها وظيفة Qiskit Runtime نشطة
  • RUNNING: POST_PROCESSING: الدالة تُجري المعالجة اللاحقة للنتائج. قد يشمل ذلك تخفيف الأخطاء وتعيين النتائج الكمومية إلى الكلاسيكية وما إلى ذلك
• DONE: البرنامج مكتمل، ويمكنك استرداد بيانات النتائج بـ job.results().
• ERROR: توقَّف البرنامج بسبب مشكلة. استخدم job.result() للحصول على رسالة الخطأ.
• CANCELED: تم إلغاء البرنامج؛ إما من قِبَل مستخدم أو الخدمة أو الخادم.

job.status()

'QUEUED'

استرداد النتائج

بعد أن يصبح البرنامج في حالة DONE، يمكنك استخدام job.results() لجلب النتيجة. يتفاوت تنسيق هذا المخرج مع كل دالة، لذا تأكَّد من اتباع التوثيق المحدد:

result = job.result()
print(result)

PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': True, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})

يمكنك أيضًا إلغاء وظيفة في أي وقت:

job.stop()

'Job has been stopped.'

سرد الوظائف السابقة المُشغَّلة مع Qiskit Functions

يمكنك استخدام jobs() لسرد جميع الوظائف المُقدَّمة إلى Qiskit Functions:

old_jobs = catalog.jobs()
old_jobs

[<Job | f6c29f49-4d5f-4fff-aca6-2e9a115b9763>,
 <Job | 7f08c9d5-471b-4da2-92e7-4f2cb94c23a8>,
 <Job | 62fe9176-d1e5-467e-b2bd-7a3f3c7be4e5>,
 <Job | af525b2e-16b1-45a1-80bb-dbd94ce30258>,
 <Job | b95a7a57-c1ad-4958-b7ac-953e4e1ee824>,
 <Job | 7bfa33da-0f17-4e67-84b6-f556f7eeb436>,
 <Job | ca46c191-9eb9-4de6-bfa7-b60d7eb29b5e>,
 <Job | 6ac0ba93-3831-43fb-9fb9-760da2225e06>,
 <Job | f0e38071-060d-47e8-988d-9cc1f69358e3>,
 <Job | 629cf110-e490-4675-8a07-f6d298d166b0>]

إذا كان لديك بالفعل معرِّف الوظيفة لوظيفة معينة، يمكنك استرداد الوظيفة بـ catalog.get_job_by_id():

# First, get the most recent job that has been executed.
latest_job = old_jobs[0]

# We can also get that same job with get_job_by_id
job_by_id = catalog.get_job_by_id(latest_job.job_id)

# Verify that the job is the same using both retrieval methods.
assert job_by_id.job_id == latest_job.job_id

# Print the job_id for this job.
print(job_by_id.job_id)

f6c29f49-4d5f-4fff-aca6-2e9a115b9763

جلب رسائل الخطأ

إذا كانت حالة البرنامج ERROR، استخدم job.error_message() لجلب رسالة الخطأ كما يلي:

job.error_message()

qiskit.exceptions.QiskitError: 'Workflow execution failed -- https://docs.quantum.ibm.com/errors#9999'

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

توصيات

• استكشف دوال Circuit لبناء خوارزميات وتطبيقات جديدة، دون الحاجة إلى إدارة عملية التحويل (Transpilation) أو معالجة الأخطاء.
• استكشف دوال التطبيقات لحل المهام الخاصة بالمجال، مع مدخلات ومخرجات كلاسيكية.