انتقل إلى المحتوى الرئيسي

ابدأ مع Qiskit Functions

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime
# 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
from qiskit_ibm_catalog import QiskitFunctionsCatalog

service = QiskitRuntimeService()
instance = service.active_account()["instance"]
backend_name = service.least_busy().name
catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")
qesem_function = catalog.load("qedma/qesem")
circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits

يمكن لمستخدمي خطط Premium وFlex وOn-Prem (عبر واجهة برمجة تطبيقات IBM Quantum Platform) البدء باستخدام 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"، فأنت تستخدم حسابك الشخصي، وهو غير مؤهل للوصول إلى Premium.

  3. اعثر على معرّف مجموعة الوصول الخاصة بك.

    • انقر على اسم مجموعة.

    • انقر على Details.

    • انسخ معرّف مجموعة الوصول. يجب أن يبدأ بـ AccessGroup-.

تثبيت عميل كتالوج Qiskit Functions​

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

    pip install qiskit-ibm-catalog

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

    If you are working in a trusted Python environment (such as on a personal laptop or workstation), use the save_account() method to save your credentials locally. (Skip to the next step if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)

    يجب أن يكون لدى المثيل الذي تصادق به إمكانية الوصول إلى Qiskit Functions مفعّلة. لتهيئتها على مثيل موجود، راجع تهيئة الوصول إلى Qiskit Functions على مثيل.

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

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

Avoid executing code on an untrusted machine or an external cloud Python environment to minimize security risks. If you must use an untrusted environment (on, for example, a public computer), change your API key after each use by deleting it on the IBM Cloud API keys page to reduce risk. Learn more in the Managing user API keys topic. To initialize the service in this situation, use this code:

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 أو ملفات الدفاتر. عند مشاركة الكود مع الآخرين، تأكد من عدم تضمين مفتاح API مباشرة داخل نص Python. بدلاً من ذلك، شارك النص دون المفتاح وقدّم تعليمات لإعداده بأمان.

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

اسرد الدوال التي يمكنك الوصول إليها​

بعد المصادقة، يمكنك سرد الدوال من كتالوج 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>"):

qesem_function = catalog.load("qedma/qesem")

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

from qiskit.quantum_info import SparsePauliOp

avg_magnetization = SparsePauliOp.from_sparse_list(
    [("Z", [q], 1 / 5) for q in range(5)], num_qubits=5
)

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)
job.job_id
'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'
نصيحة

تتحقق run() من سعتك المتبقية والوصول إلى الـ Backend قبل إرسال المهمة. إذا نفدت سعة نسختك، أو كان الـ Backend الذي حددته غير متاح، ترفع run() خطأً فورًا بدلاً من ترك المهمة تفشل في الطابور. عندما تكون السعة منخفضة، تصدر run() تحذيرًا. مرر suppress_low_usage_warning=True لكتم التحذير.

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    suppress_low_usage_warning=True,
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)

تحقق من حالة المهمة​

باستخدام job_id الخاص بدالة Qiskit Function، يمكنك التحقق من حالة المهام الجارية. وتشمل هذه الحالات ما يلي:

  • QUEUED: البرنامج البعيد في طابور Qiskit Functions. تعتمد أولوية الطابور على مدى استخدامك لـ Qiskit Functions.

  • INITIALIZING: البرنامج البعيد يبدأ التشغيل؛ ويشمل ذلك إعداد البيئة البعيدة وتثبيت التبعيات.

  • RUNNING: البرنامج قيد التشغيل. ويشمل ذلك أيضًا عدة حالات أكثر تفصيلاً إذا كانت الدوال المحددة تدعمها.

    • RUNNING: MAPPING: تقوم الدالة حاليًا بتخطيط مدخلاتك الكلاسيكية إلى مدخلات كمومية.

    • RUNNING: OPTIMIZING_FOR_HARDWARE: تقوم الدالة بالتحسين للـ QPU المختار. يمكن أن يشمل ذلك نقل الدارة، وتوصيف QPU، والانتشار العكسي للمرصودات، وما إلى ذلك.

    • RUNNING: WAITING_FOR_QPU: أرسلت الدالة مهمة إلى IBM Quantum Compute Service، وهي في الانتظار في الطابور.

    • RUNNING: EXECUTING_QPU: لدى الدالة مهمة Quantum Compute نشطة.

    • RUNNING: POST_PROCESSING: تقوم الدالة بمعالجة النتائج لاحقًا، وقد يشمل ذلك تخفيف الأخطاء، وتخطيط النتائج الكمومية إلى كلاسيكية، وما إلى ذلك.

  • DONE: البرنامج مكتمل، ويمكنك استرجاع بيانات النتيجة باستخدام job.result().

  • ERROR: توقف البرنامج عن التشغيل بسبب مشكلة. استخدم job.result() للحصول على رسالة الخطأ.

  • CANCELED: تم إلغاء البرنامج من قِبل مستخدم أو الخدمة أو الخادم.

job.status()
'QUEUED'

استرجاع النتائج​

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

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.cancel()
'Job has been stopped.'

الوصول إلى مهام Quantum Compute المرتبطة​

يمكن لدالة Qiskit Function إرسال مهمة واحدة أو أكثر من مهام Quantum Compute إلى QPU أثناء تشغيلها. لاسترجاع معرّفات مهام وقت التشغيل هذه، استخدم job.runtime_jobs(). يمكنك استخدام هذه المعرّفات لاسترجاع كائنات مهام وقت التشغيل من نسخة QiskitRuntimeService، أو للعثور على أحمال العمل في لوحة معلومات IBM Quantum® Platform.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

إذا جمّعت دالة ما مهام وقت التشغيل الخاصة بها في جلسات أو دفعات، استخدم job.runtime_sessions() لسرد معرّفات الجلسات. مرر معرّف جلسة واحدة إلى job.runtime_jobs() لإرجاع مهام وقت التشغيل الموجودة في تلك الجلسة فقط:

sessions = job.runtime_sessions()
if sessions:
    session_runtime_jobs = job.runtime_jobs(runtime_session=sessions[0])
    print(session_runtime_jobs)
else:
    print("No runtime sessions for this job.")
ملاحظة

يمكن أن تكون القائمة المُعادة فارغة. تُبلغ الدالة عن مهام وقت التشغيل (runtime jobs) الخاصة بها فقط عندما ترسلها عبر خدمة وقت التشغيل التي تتلقاها الدالة أثناء التشغيل، وبعض الدوال لا ترسل مهام وقت التشغيل مباشرة.

عرض سجلات المهمة​

استخدم job.logs() لاسترجاع مخرجات السجل التي تنتجها الدالة أثناء تشغيلها. تفيد السجلات في تتبع التقدم وفي تصحيح مهمة تنتهي بحالة ERROR.

print(job.logs().splitlines())

بالنسبة لمهمة طويلة التشغيل تنتج العديد من أسطر السجل، استخدم job.filtered_logs() لإرجاع الأسطر التي تريدها فقط. مرر تعبيرًا نمطيًا إلى include لإبقاء الأسطر المطابقة، أو إلى exclude لحذف الأسطر المطابقة:

print(job.filtered_logs(include="iteration"))

سرد مهام 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>]

لتضييق النتائج، مرر عوامل تصفية. صفِّ حسب الدالة باستخدام function، وحسب الحالة باستخدام status، وحسب تاريخ الإرسال باستخدام created_after. تصفّح النتائج صفحة بصفحة باستخدام limit وoffset:

recent_errors = catalog.jobs(
    function=qesem_function,
    status="ERROR",
    created_after="2024-01-01T00:00:00Z",
    limit=5,
)
recent_errors

إذا كان لديك بالفعل معرّف المهمة لمهمة معينة، يمكنك استرجاع المهمة باستخدام catalog.job():

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

# We can also get that same job with `catalog.job`
job_by_id = catalog.job(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'

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

التوصيات
المصدر: IBM Quantum docs — تم التحديث في 3 سبتمبر 2026
النسخة الإنجليزية على doQumentation — تم التحديث في 3 سبتمبر 2026
مشكلة في الموقع أو الترجمة؟مشكلة في المحتوى؟ حرّر في IBM Quantum docs