469 lines
17 KiB
Plaintext
469 lines
17 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "a47ac9aa-4bb9-4240-806e-9beabfd2dda2",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Introduction to Qiskit Functions"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "0be0fe02-bc50-45a6-aaf6-2120dac862c2",
|
|
"metadata": {
|
|
"tags": [
|
|
"version-info"
|
|
]
|
|
},
|
|
"source": [
|
|
"<details>\n",
|
|
"<summary><b>Package versions</b></summary>\n",
|
|
"\n",
|
|
"The code on this page was developed using the following requirements.\n",
|
|
"We recommend using these versions or newer.\n",
|
|
"\n",
|
|
"```\n",
|
|
"qiskit[all]~=1.3.2\n",
|
|
"qiskit-ibm-runtime~=0.34.0\n",
|
|
"qiskit-aer~=0.15.1\n",
|
|
"qiskit-serverless~=0.18.1\n",
|
|
"qiskit-ibm-catalog~=0.2\n",
|
|
"qiskit-addon-sqd~=0.9.0\n",
|
|
"qiskit-addon-utils~=0.1.0\n",
|
|
"qiskit-addon-mpf~=0.2.0\n",
|
|
"qiskit-addon-aqc-tensor~=0.1.2\n",
|
|
"qiskit-addon-obp~=0.1.0\n",
|
|
"scipy~=1.15.1\n",
|
|
"pyscf~=2.8.0; sys.platform != 'win32'\n",
|
|
"```\n",
|
|
"</details>"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "098d8fd4-1558-40df-a1b1-ad70fdef8863",
|
|
"metadata": {},
|
|
"source": [
|
|
"<Admonition type=\"note\">\n",
|
|
"Qiskit Functions are an experimental feature available only to IBM Quantum™ Premium Plan users. They are in preview release status and subject to change.\n",
|
|
"</Admonition>\n",
|
|
"\n",
|
|
"Qiskit Functions simplify and accelerate utility-scale algorithm discovery and application development, by abstracting away parts of the quantum software development workflow. In this way, Qiskit Functions free up time normally spent hand-writing code and fine-tuning experiments.\n",
|
|
"\n",
|
|
"\n",
|
|
"Functions come in two forms:\n",
|
|
"\n",
|
|
"| Type | What does it do? | Example inputs and outputs | Who is it for? |\n",
|
|
"| - | - | - | - |\n",
|
|
"| Circuit function | Simplified interface for running circuits. Abstracts transpilation, error suppression, error mitigation | **Input**: Abstract `PUB`s <br/> **Output**: Mitigated expectation values | Researchers using Qiskit to discover new algorithms and applications, without needing to focus on optimizing for hardware or handling error. Circuit functions can be used to build custom application functions. |\n",
|
|
"| Application function | Covers higher-level tasks, like exploring algorithms and domain-specific use cases. Abstracts quantum workflow to solve tasks, with classical inputs and outputs | **Input**: Molecules, graphs <br/> **Output**: Energy, cost | Researchers in non-quantum domains, integrating quantum into existing large-scale classical workflows, without needing to map classical data to quantum circuits. |"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "df18227b-787a-4dc6-a8c7-7abd0f67110c",
|
|
"metadata": {},
|
|
"source": [
|
|
"Functions are provided by IBM® and third-party partners. Each is performant for specific workload characteristics and have unique performance-tuning options. Premium Plan users can get started with IBM Qiskit Functions for free, or procure a license from one of the partners who have contributed a function to the catalog.\n",
|
|
"\n",
|
|
"## Get started with Qiskit Functions\n",
|
|
"\n",
|
|
"### Install Qiskit Functions Catalog client\n",
|
|
"\n",
|
|
"1. To start using Qiskit Functions, install the IBM Qiskit Functions Catalog client:\n",
|
|
"\n",
|
|
" ```\n",
|
|
" pip install qiskit-ibm-catalog\n",
|
|
" ```\n",
|
|
"1. Retrieve your API token from the [IBM Quantum account page](https://quantum.ibm.com/account), and activate your Python virtual environment. See the [installation instructions](/guides/install-qiskit#local) if you do not already have a virtual environment set up.\n",
|
|
"\n",
|
|
" <span id=\"save-account\"></span>**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](#functions-untrusted) if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)\n",
|
|
"\n",
|
|
" To use `save_account()`, run `python` in your shell to open a REPL (read-eval-print loop), then enter the following:\n",
|
|
"\n",
|
|
" ```python\n",
|
|
" from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
|
|
"\n",
|
|
" QiskitFunctionsCatalog.save_account(token=\"<your-token>\")\n",
|
|
" ```\n",
|
|
"\n",
|
|
" Close out of the REPL with `exit()`. From now on, whenever you need to authenticate to the service, you can load your credentials with `QiskitFunctionsCatalog()`."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 1,
|
|
"id": "e872c222-aee9-40eb-8778-9a8e5434a11c",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"# Load saved credentials\n",
|
|
"from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
|
|
"\n",
|
|
"catalog = QiskitFunctionsCatalog()"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "80441467-1d9a-4107-8570-22afa6e369f7",
|
|
"metadata": {},
|
|
"source": [
|
|
"3. <span id=\"functions-untrusted\"></span>**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 token after each use by expiring it on the [IBM Quantum Platform dashboard](https://quantum.ibm.com/) (click the refresh button in the API token field) to reduce risk. To initialize the service in this situation, expand the following section to view code you can use:\n",
|
|
"\n",
|
|
" <details>\n",
|
|
" <summary>Initialize the service in an untrusted environment</summary>\n",
|
|
"\n",
|
|
" ```python\n",
|
|
" from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
|
|
"\n",
|
|
" # After using the following code, go to your dashboard (https://quantum.ibm.com/)\n",
|
|
" # and expire your API token (click the refresh button in the API token field)\n",
|
|
" catalog = QiskitFunctionsCatalog(token=\"<MY_IBM_QUANTUM_TOKEN>\")\n",
|
|
" ```\n",
|
|
" </details>"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6f2d0a37-1c6d-4cad-a9ce-c4d05c7aaaf1",
|
|
"metadata": {},
|
|
"source": [
|
|
" <Admonition type=\"caution\">\n",
|
|
" **Protect your API token!** Never include your token in source code, Python script, or notebook file. When sharing code with others, ensure that your API token is not embedded directly within the Python script. Instead, share the script without the token and provide instructions for securely setting it up.\n",
|
|
"\n",
|
|
" If you accidentally share your token with someone or include it in version control like Git, immediately revoke your token by expiring it on the [IBM Quantum Platform dashboard](https://quantum.ibm.com/) (click the refresh button in the API token field) to reduce risk.\n",
|
|
" </Admonition>"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "5154cbea-ccfa-42ea-a9ef-c31699c3b2c0",
|
|
"metadata": {},
|
|
"source": [
|
|
"4. Once you have authenticated, you can list the functions from the Qiskit Functions Catalog that you have access to:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 2,
|
|
"id": "55b73ad8-6e3b-4b76-8ba5-ae7ea339ffcc",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"data": {
|
|
"text/plain": [
|
|
"[QiskitFunction(q-ctrl/performance-management),\n",
|
|
" QiskitFunction(qedma/qesem-dev),\n",
|
|
" QiskitFunction(qunasys/quri-chemistry),\n",
|
|
" QiskitFunction(algorithmiq/tem-dev),\n",
|
|
" QiskitFunction(algorithmiq/tem),\n",
|
|
" QiskitFunction(q-ctrl/performance-management-dev),\n",
|
|
" QiskitFunction(qedma/qesem),\n",
|
|
" QiskitFunction(kipu-quantum/iskay-quantum-optimizer-dev),\n",
|
|
" QiskitFunction(ibm/circuit-function),\n",
|
|
" QiskitFunction(multiverse/singularity),\n",
|
|
" QiskitFunction(q-ctrl/optimization-solver),\n",
|
|
" QiskitFunction(qunasys/quri-chemistry-dev),\n",
|
|
" QiskitFunction(algorithmiq/tem-gpu),\n",
|
|
" QiskitFunction(q-ctrl/optimization-solver-dev)]"
|
|
]
|
|
},
|
|
"execution_count": 2,
|
|
"metadata": {},
|
|
"output_type": "execute_result"
|
|
}
|
|
],
|
|
"source": [
|
|
"catalog.list()"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "a1c73799-30ec-44dc-b4b9-06e59d521d8c",
|
|
"metadata": {},
|
|
"source": [
|
|
"### Run enabled functions\n",
|
|
"\n",
|
|
"Once a catalog object has been instantiated, you can select a function using `catalog.load(provider/function-name)`:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 3,
|
|
"id": "4ac22236-2a34-46fb-890f-30d6ba70081e",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"ibm_cf = catalog.load(\"ibm/circuit-function\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "deb844d3-051a-4db1-b0a1-4ba9801ef95e",
|
|
"metadata": {},
|
|
"source": [
|
|
"Each Qiskit Function has custom inputs, options, and outputs. Check the specific documentation pages for the function you want to run for more information. By default, all users can only run one function job at a time:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 4,
|
|
"id": "139ac1d5-3727-4f44-a26c-0d8a1d8a58f2",
|
|
"metadata": {
|
|
"tags": [
|
|
"remove-cell"
|
|
]
|
|
},
|
|
"outputs": [],
|
|
"source": [
|
|
"# This cell is hidden from users\n",
|
|
"# It gets these details programatically so we can test this notebook\n",
|
|
"from qiskit_ibm_runtime import QiskitRuntimeService\n",
|
|
"from qiskit.circuit.random import random_circuit\n",
|
|
"\n",
|
|
"service = QiskitRuntimeService()\n",
|
|
"instance = service.active_account()[\"instance\"]\n",
|
|
"backend_name = service.least_busy().name\n",
|
|
"\n",
|
|
"circuit = random_circuit(num_qubits=2, depth=2, seed=42)\n",
|
|
"observable = \"Z\" * circuit.num_qubits"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 5,
|
|
"id": "9b9a7a3c-cc98-4c19-93cd-f59793515c70",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"data": {
|
|
"text/plain": [
|
|
"'d76b6abf-3a16-4dd6-a9ac-a7ffa780d2f7'"
|
|
]
|
|
},
|
|
"execution_count": 5,
|
|
"metadata": {},
|
|
"output_type": "execute_result"
|
|
}
|
|
],
|
|
"source": [
|
|
"job = ibm_cf.run(\n",
|
|
" pubs=[(circuit, observable)],\n",
|
|
" instance=instance, # E.g. \"ibm-q/open/main\"\n",
|
|
" backend_name=backend_name, # E.g. \"ibm_kyiv\"\n",
|
|
")\n",
|
|
"\n",
|
|
"job.job_id"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "b1518e8e-04ea-4e4e-9f30-10f87dd4ee82",
|
|
"metadata": {},
|
|
"source": [
|
|
"### Check job status\n",
|
|
"\n",
|
|
"<Admonition type=\"tip\">\n",
|
|
"Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workloads. Use `job.status()` to see your Qiskit Function workload's current status.\n",
|
|
"</Admonition>\n",
|
|
"\n",
|
|
"With your Qiskit Function `job_id`, you can check the status of running jobs. This includes the following statuses:\n",
|
|
"\n",
|
|
"- **`QUEUED`**: The remote program is in the Qiskit Function queue. The queue priority is based on how much you've used Qiskit Functions.\n",
|
|
"- **`INITIALIZING`**: The remote program is starting; this includes setting up the remote environment and installing dependencies.\n",
|
|
"- **`RUNNING`**: The program is running.\n",
|
|
"- **`DONE`**: The program is complete, and you can retrieve result data with `job.results()`.\n",
|
|
"- **`ERROR`**: The program stopped running because of a problem. Use `job.result()` to get the error message.\n",
|
|
"- **`CANCELED`**: The program was canceled; either by a user, the service, or the server."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 6,
|
|
"id": "d811be20-cf0d-4070-a126-b40af6a33132",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"data": {
|
|
"text/plain": [
|
|
"'QUEUED'"
|
|
]
|
|
},
|
|
"execution_count": 6,
|
|
"metadata": {},
|
|
"output_type": "execute_result"
|
|
}
|
|
],
|
|
"source": [
|
|
"job.status()"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "8e6528b5-c36f-48e1-bb2f-2416ccb12902",
|
|
"metadata": {},
|
|
"source": [
|
|
"### Retrieve results\n",
|
|
"\n",
|
|
"Once a program is `DONE`, you can use `job.results()` to fetch the result. This output format varies with each function, so be sure to follow the specific documentation:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 7,
|
|
"id": "04f6a446-fbc6-438a-bc07-00fc9d551d83",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"name": "stdout",
|
|
"output_type": "stream",
|
|
"text": [
|
|
"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})\n"
|
|
]
|
|
}
|
|
],
|
|
"source": [
|
|
"result = job.result()\n",
|
|
"print(result)"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "76c32136-f449-454c-896b-ff9d0edf9abc",
|
|
"metadata": {},
|
|
"source": [
|
|
"At any time, you can also cancel a job:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 8,
|
|
"id": "7ddc2394-64a9-4fdd-bb3d-7729433fcd9c",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"data": {
|
|
"text/plain": [
|
|
"'Job has been stopped.'"
|
|
]
|
|
},
|
|
"execution_count": 8,
|
|
"metadata": {},
|
|
"output_type": "execute_result"
|
|
}
|
|
],
|
|
"source": [
|
|
"job.stop()"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "5b5d7c8d-7a96-41e2-93aa-528513acdd21",
|
|
"metadata": {},
|
|
"source": [
|
|
"### List previously run jobs run with Qiskit Functions\n",
|
|
"\n",
|
|
"You can use `jobs()` to list all jobs submitted to Qiskit Functions:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 9,
|
|
"id": "c1a2832b-1ca3-4ef1-9a8a-3f3804b3aedf",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"data": {
|
|
"text/plain": [
|
|
"[<Job | bd136829-041d-4fc5-b3b3-594b51dbac35>,\n",
|
|
" <Job | 7996260a-09bb-4844-a7ac-87d949f4c81d>,\n",
|
|
" <Job | febe221b-197f-482c-a7af-6e8be22713e1>,\n",
|
|
" <Job | d76b6abf-3a16-4dd6-a9ac-a7ffa780d2f7>,\n",
|
|
" <Job | 0f279d61-598d-44e3-8416-fee964c3aebb>,\n",
|
|
" <Job | 29fe757a-6740-4c4d-b636-587e3cf805bb>,\n",
|
|
" <Job | 4ee6ad70-0727-43e0-b843-982b031a1b2e>,\n",
|
|
" <Job | 91d3ee72-cfb9-4188-b9f6-702d8cc73b2e>,\n",
|
|
" <Job | 24e6f587-b56a-4401-8cfc-97099cbd2b12>,\n",
|
|
" <Job | c6e4f12f-5b00-4abe-b9f3-6af3d9b8e1bf>]"
|
|
]
|
|
},
|
|
"execution_count": 9,
|
|
"metadata": {},
|
|
"output_type": "execute_result"
|
|
}
|
|
],
|
|
"source": [
|
|
"old_jobs = catalog.jobs()\n",
|
|
"old_jobs"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "9137071a-e39c-4b66-afbd-697db38cc670",
|
|
"metadata": {},
|
|
"source": [
|
|
"### Fetch error messages\n",
|
|
"\n",
|
|
"If a program status is `ERROR`, use `job.result()` to fetch the error message to help debug as follows:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": 10,
|
|
"id": "abfdf746-bc46-4df7-85b3-4a7a61ab7ca7",
|
|
"metadata": {},
|
|
"outputs": [
|
|
{
|
|
"name": "stdout",
|
|
"output_type": "stream",
|
|
"text": [
|
|
"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})\n"
|
|
]
|
|
}
|
|
],
|
|
"source": [
|
|
"print(job.result())"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "7c8c3e5d-1de2-4fed-be03-d134dc3fd907",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Next steps\n",
|
|
"\n",
|
|
"<Admonition type=\"info\" title=\"Recommendations\">\n",
|
|
"\n",
|
|
"- [Explore circuit functions](./ibm-circuit-function) to build new algorithms and applications, without needing to manage transpilation or error handling.\n",
|
|
"- [Explore application functions](./q-ctrl-optimization-solver) to solve domain-specific tasks, with classical inputs and outputs.\n",
|
|
"\n",
|
|
"</Admonition>"
|
|
]
|
|
}
|
|
],
|
|
"metadata": {
|
|
"description": "Explore IBM Qiskit Functions Catalog, abstracted circuit function and application function services designed to accelerate research and application prototyping.",
|
|
"kernelspec": {
|
|
"display_name": "Python 3",
|
|
"language": "python",
|
|
"name": "python3"
|
|
},
|
|
"language_info": {
|
|
"codemirror_mode": {
|
|
"name": "ipython",
|
|
"version": 3
|
|
},
|
|
"file_extension": ".py",
|
|
"mimetype": "text/x-python",
|
|
"name": "python",
|
|
"nbconvert_exporter": "python",
|
|
"pygments_lexer": "ipython3",
|
|
"version": "3"
|
|
},
|
|
"title": "Introduction to Qiskit Functions"
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 2
|
|
}
|