Qiskit Functions 시작하기
# Added by doQumentation — installs the packages this notebook needs if they are missing
import importlib.util
_needed = {"qiskit": "qiskit", "qiskit_ibm_catalog": "qiskit-ibm-catalog", "qiskit_ibm_runtime": "qiskit-ibm-runtime"}
_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")
# 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 API를 통한) Plan 사용자는 IBM Qiskit Functions를 무료로 시작하거나, 카탈로그에 함수를 제공한 파트너 중 한 곳에서 라이선스를 구매할 수 있어요.
타사 Qiskit Functions에 대한 무료 평가판 요청하기
무료 평가판을 요청하려면 Qiskit Functions Catalog로 이동하여 세부 정보 패널을 살펴보세요. Request a free trial을 클릭하고, IBM Cloud AccessGroupId를 포함하여 Functions 파트너가 요구하는 정보를 입력하세요:
-
IBM Cloud IAM으로 이동합니다.
-
자격을 확인합니다.
-
헤더의 메뉴 바에서 계정을 다음 형식의 계정으로 전환하세요:
XXXXXXX - [Organization Name] -
조직이 Premium 계정과 연결된 조직과 동일한지 확인합니다.
-
"[Your Name]'s Account"가 표시되면 개인 계정을 사용하고 있는 것이며, 이는 프리미엄 액세스 대상이 아니에요.
-
-
액세스 그룹 ID를 찾습니다.
-
그룹 이름을 클릭합니다.
-
Details를 클릭합니다.
-
액세스 그룹 ID를 복사합니다.
AccessGroup-으로 시작해야 합니다.
-
Qiskit Functions Catalog 클라이언트 설치하기
-
Qiskit Functions를 사용하기 시작하려면 IBM Qiskit Functions Catalog 클라이언트를 설치하세요:
pip install qiskit-ibm-catalog -
IBM Quantum Platform 대시보드에서 API 키를 가져오고, Python 가상 환경을 활성화하세요. 가상 환경이 아직 설정되어 있지 않다면 설치 지침을 참조하세요.
신뢰할 수 있는 Python 환경(예: 개인 노트북이나 워크스테이션)에서 작업하는 경우,
save_account()메서드를 사용하여 자격 증명을 로컬에 저장하세요. (공유 컴퓨터나 공용 컴퓨터처럼 신뢰할 수 없는 환경에서 IBM Quantum Platform에 인증하는 경우에는 다음 단계로 건너뛰세요.)인증할 때 사용하는 인스턴스는 Qiskit Functions 액세스가 활성화되어 있어야 합니다. 기존 인스턴스에서 이를 구성하려면 인스턴스에서 Qiskit Functions 액세스 구성을 참조하세요.
save_account()를 사용하려면, 셸에서python을 실행한 다음 다음을 입력하세요:from qiskit_ibm_catalog import QiskitFunctionsCatalogQiskitFunctionsCatalog.save_account(channel="ibm_quantum_platform", token="<your-token>", instance="<instance-crn>")exit()를 입력해요. 이제부터 서비스에 인증해야 할 때마다 다음과 같이 자격 증명을 불러올 수 있어요:from qiskit_ibm_catalog import QiskitFunctionsCatalogcatalog = QiskitFunctionsCatalog()예를 들면:
# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog
catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")
보안 위험을 최소화하려면 신뢰할 수 없는 머신이나 외부 클라우드 Python 환경에서 코드를 실행하지 마세요. 공용 컴퓨터와 같이 신뢰할 수 없는 환경을 반드시 사용해야 하는 경우, 위험을 줄이기 위해 사용할 때마다 IBM Cloud API 키 페이지에서 API 키를 삭제하여 변경하세요. 자세한 내용은 사용자 API 키 관리 항목에서 확인할 수 있어요. 이러한 상황에서 서비스를 초기화하려면 다음 코드를 사용하세요.
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
소스 코드, Python 스크립트, 노트북 파일에 절대 API 키를 포함하지 마세요. 다른 사람과 코드를 공유할 때는 API 키가 Python 스크립트에 직접 포함되지 않도록 하세요. 대신 키 없이 스크립트를 공유하고, 안전하게 설정하는 방법을 안내하세요.
실수로 키를 다른 사람과 공유했거나 Git 같은 버전 관리 시스템에 포함시켰다면, IBM Cloud API keys 페이지에서 키를 즉시 삭제하여 위험을 줄이세요. 자세한 내용은 Managing user API keys 항목을 참조하세요.
접근 가능한 함수 목록 확인하기
인증 후, Qiskit Functions Catalog에서 접근할 수 있는 함수 목록을 확인할 수 있어요:
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()은 작업을 제출하기 전에 남은 용량과 백엔드 접근 권한을 확인합니다. 인스턴스의 용량이 모두 소진되었거나 지정한 백엔드에 접근할 수 없는 경우, 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
# },
)
작업 상태 확인하기
Qiskit Function job_id를 사용하여 실행 중인 작업의 상태를 확인할 수 있어요. 여기에는 다음과 같은 상태가 포함돼요:
-
QUEUED: 원격 프로그램이 Qiskit Function 대기열에 있어요. 대기열 우선순위는 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에 제출할 수 있어요. 이러한 런타임 작업의 ID를 가져오려면 job.runtime_jobs()를 사용하세요. 이 ID를 사용하여 QiskitRuntimeService 인스턴스에서 런타임 작업 객체를 가져오거나, IBM Quantum® Platform 대시보드에서 워크로드를 찾을 수 있어요.
runtime_job_ids = job.runtime_jobs()
runtime_job_ids
함수가 런타임 작업을 세션이나 배치로 그룹화하는 경우, job.runtime_sessions()를 사용하여 세션 ID 목록을 확인하세요. job.runtime_jobs()에 세션 ID 하나를 전달하면 해당 세션의 런타임 작업만 반환됩니다:
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.")
반환된 목록은 비어 있을 수 있어요. 함수는 실행 시점에 받은 런타임 서비스를 통해 작업을 제출하는 경우에만 런타임 작업을 보고하며, 일부 함수는 런타임 작업을 직접 제출하지 않아요.
작업 로그 보기
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
특정 작업의 작업 ID를 이미 알고 있다면, 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'
다음 단계
-
트랜스파일이나 오류 처리를 관리할 필요 없이 새로운 알고리즘과 애플리케이션을 구축하려면 circuit functions 살펴보기를 참조하세요.
-
고전적 입력과 출력으로 도메인별 작업을 해결하려면 application functions 살펴보기를 참조하세요.
-
Qiskit Functions에 대한 API 참조 문서를 확인하세요.
-
Qiskit Functions 활용법을 보여주는 튜토리얼을 직접 따라 해 보세요.