Pierwsze kroki z 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

Użytkownicy planów Premium, Flex i On-Prem (poprzez IBM Quantum Platform API) mogą zacząć korzystać z IBM Qiskit Functions za darmo lub nabyć licencję od jednego z partnerów, którzy udostępnili funkcję w katalogu.

Poproś o darmowy okres próbny dla funkcji Qiskit Functions stron trzecich

Aby poprosić o darmowy okres próbny, przejdź do Qiskit Functions Catalog i zapoznaj się z panelem szczegółów. Kliknij Request a free trial i wypełnij informacje wymagane przez partnera dostarczającego funkcję, w tym AccessGroupId w IBM Cloud:

1. Przejdź do IBM Cloud IAM.

2. Sprawdź uprawnienia.

   • Przełącz swoje konto w menu na pasku nagłówka na konto o następującym formacie: XXXXXXX - [Organization Name]

   • Upewnij się, że organizacja jest taka sama jak ta powiązana z Twoim kontem Premium.

   • Jeśli widzisz „[Your Name]'s Account”, korzystasz ze swojego konta osobistego, które nie kwalifikuje się do dostępu premium.

3. Znajdź identyfikator swojej grupy dostępu.

   • Kliknij nazwę grupy.

   • Kliknij Details.

   • Skopiuj identyfikator grupy dostępu. Powinien zaczynać się od AccessGroup-.

Zainstaluj klienta Qiskit Functions Catalog

1. Aby zacząć korzystać z Qiskit Functions, zainstaluj klienta IBM Qiskit Functions Catalog:

   pip install qiskit-ibm-catalog

2. Pobierz swój klucz API z panelu IBM Quantum Platform i aktywuj swoje wirtualne środowisko Python. Zobacz instrukcje instalacji, jeśli nie masz jeszcze skonfigurowanego wirtualnego środowiska.

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

   Instancja, z którą się uwierzytelniasz, musi mieć włączony dostęp do Qiskit Functions. Aby skonfigurować go dla istniejącej instancji, zobacz Konfigurowanie dostępu do Qiskit Functions dla instancji.

   Aby użyć save_account(), uruchom python w swojej powłoce, a następnie wprowadź:

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

   Wpisz exit(). Od tej pory, gdy tylko będziesz musiał uwierzytelnić się w usłudze, możesz wczytać swoje dane uwierzytelniające za pomocą:

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   catalog = QiskitFunctionsCatalog()

   Na przykład:

# 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

Chroń swój klucz API

Nigdy nie umieszczaj swojego klucza w kodzie źródłowym, skryptach Python ani plikach notatnika. Podczas udostępniania kodu innym osobom upewnij się, że Twój klucz API nie jest osadzony bezpośrednio w skrypcie Python. Zamiast tego udostępnij skrypt bez klucza i podaj instrukcje dotyczące bezpiecznego jego skonfigurowania.

Jeśli przypadkowo udostępnisz swój klucz komuś lub umieścisz go w systemie kontroli wersji, takim jak Git, natychmiast unieważnij swój klucz, usuwając go na stronie IBM Cloud API keys, aby zmniejszyć ryzyko. Dowiedz się więcej w temacie Managing user API keys.

Wyświetl listę funkcji, do których masz dostęp

Po uwierzytelnieniu możesz wyświetlić listę funkcji z Qiskit Functions Catalog, do których masz dostęp:

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

Uruchamianie włączonych funkcji

Po utworzeniu instancji obiektu katalogu możesz wybrać funkcję za pomocą catalog.load("<provider/function-name>"):

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

Każda funkcja Qiskit Function ma niestandardowe dane wejściowe, opcje i wyniki. Sprawdź konkretne strony dokumentacji dla funkcji, którą chcesz uruchomić, aby uzyskać więcej informacji. Domyślnie wszyscy użytkownicy mogą uruchamiać tylko jedno zadanie funkcji jednocześnie:

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'

wskazówka

run() sprawdza pozostałą dostępną pojemność i dostęp do backendu przed przesłaniem zadania. Jeśli Twoja instancja nie ma dostępnej pojemności lub podany backend jest niedostępny, run() natychmiast zgłasza błąd, zamiast pozostawiać zadanie do niepowodzenia w kolejce. Gdy dostępna pojemność jest niska, run() wysyła ostrzeżenie. Przekaż suppress_low_usage_warning=True, aby je wyciszyć.

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
    # },
)

Sprawdzanie stanu zadania

Za pomocą job_id funkcji Qiskit Function możesz sprawdzić stan uruchomionych zadań. Obejmuje to następujące stany:

• QUEUED: Zdalny program znajduje się w kolejce Qiskit Functions. Priorytet w kolejce zależy od tego, jak dużo korzystałeś z Qiskit Functions.

• INITIALIZING: Zdalny program się uruchamia; obejmuje to konfigurację zdalnego środowiska i instalację zależności.

• RUNNING: Program jest uruchomiony. Obejmuje to również kilka bardziej szczegółowych stanów, jeśli są obsługiwane przez konkretne funkcje.

  • RUNNING: MAPPING: Funkcja aktualnie mapuje Twoje dane wejściowe klasyczne na dane wejściowe kwantowe.

  • RUNNING: OPTIMIZING_FOR_HARDWARE: Funkcja optymalizuje pod wybrany QPU. Może to obejmować transpilację obwodu, charakterystykę QPU, propagację wsteczną obserwabli i tak dalej.

  • RUNNING: WAITING_FOR_QPU: Funkcja przesłała zadanie do IBM Quantum Compute Service i czeka w kolejce.

  • RUNNING: EXECUTING_QPU: Funkcja ma aktywne zadanie Quantum Compute.

  • RUNNING: POST_PROCESSING: Funkcja przetwarza wyniki końcowo, co może obejmować łagodzenie błędów, mapowanie wyników kwantowych na klasyczne i tak dalej.

• DONE: Program jest zakończony i możesz pobrać dane wynikowe za pomocą job.result().

• ERROR: Program przestał działać z powodu problemu. Użyj job.result(), aby uzyskać komunikat o błędzie.

• CANCELED: Program został anulowany przez użytkownika, usługę lub serwer.

job.status()

'QUEUED'

Pobieranie wyników

Po tym, jak program ma stan DONE, możesz użyć job.result(), aby pobrać wynik. Format wyjściowy różni się w zależności od funkcji, więc koniecznie zapoznaj się z konkretną dokumentacją:

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

Możesz również anulować zadanie w dowolnym momencie:

job.cancel()

'Job has been stopped.'

Dostęp do powiązanych zadań Quantum Compute

Funkcja Qiskit Function może przesłać jedno lub więcej zadań Quantum Compute do QPU podczas działania. Aby pobrać identyfikatory tych zadań środowiska uruchomieniowego, użyj job.runtime_jobs(). Możesz użyć tych identyfikatorów, aby pobrać obiekty zadań środowiska uruchomieniowego z instancji QiskitRuntimeService lub znaleźć obciążenia w panelu IBM Quantum® Platform.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

Jeśli funkcja grupuje swoje zadania środowiska uruchomieniowego w sesje lub grupy zadań, użyj job.runtime_sessions(), aby wyświetlić listę identyfikatorów sesji. Przekaż jeden identyfikator sesji do job.runtime_jobs(), aby zwrócić tylko zadania środowiska uruchomieniowego w tej sesji:

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

uwaga

Zwrócona lista może być pusta. Funkcja zgłasza swoje zadania środowiska uruchomieniowego tylko wtedy, gdy przesyła je za pośrednictwem usługi środowiska uruchomieniowego, którą funkcja otrzymuje w czasie wykonywania, a niektóre funkcje nie przesyłają zadań środowiska uruchomieniowego bezpośrednio.

Wyświetlanie dzienników zadania

Użyj job.logs(), aby pobrać dane wyjściowe dziennika generowane przez funkcję podczas działania. Dzienniki są przydatne do śledzenia postępu i debugowania zadania, które kończy się stanem ERROR.

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

W przypadku długo trwającego zadania, które generuje wiele linii dziennika, użyj job.filtered_logs(), aby zwrócić tylko potrzebne linie. Przekaż wyrażenie regularne do include, aby zachować pasujące linie, lub do exclude, aby odrzucić pasujące linie:

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

Wyświetlanie listy wcześniej uruchomionych zadań Qiskit Functions

Możesz użyć jobs(), aby wyświetlić listę wszystkich zadań przesłanych do 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>]

Aby zawęzić wyniki, przekaż filtry. Filtruj według funkcji za pomocą function, według stanu za pomocą status i według daty przesłania za pomocą created_after. Przeglądaj wyniki stronami za pomocą limit i offset:

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

Jeśli masz już identyfikator zadania dla określonego zadania, możesz je pobrać za pomocą 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

Pobieranie komunikatów o błędach

Jeśli stan programu to ERROR, użyj job.error_message(), aby pobrać komunikat o błędzie w następujący sposób:

job.error_message()

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

Kolejne kroki

Zalecenia

• Poznaj funkcje obwodów, aby budować nowe algorytmy i aplikacje bez konieczności zarządzania transpilacją lub obsługą błędów.

• Poznaj funkcje aplikacji, aby rozwiązywać zadania specyficzne dla danej dziedziny, z klasycznymi danymi wejściowymi i wyjściowymi.

• Zobacz dokumentację referencyjną API dla Qiskit Functions.

• Aby zdobyć praktyczne doświadczenie, wypróbuj niektóre samouczki, które demonstrują Qiskit Functions.