You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refactor notebook testing framework with enhanced logging and configuration
- Introduced logging configuration to output messages to console with INFO level.
- Added constants for default timeout and environment variable names in a new constants module.
- Refactored notebook execution tests to use parameterization and improved error handling.
- Created a helper function to print formatted section headers for better readability.
- Updated the main execution block to provide a summary of notebook tests with detailed logging.
- Added an __init__.py file to the tests directory for package recognition.
This repository contains Python samples exploring quantum computing on IonQ's platform using various quantum programming libraries. These examples are a great place to start if you're interested in quantum computation, but aren't familiar with any of the libraries out there.
3
+
Python samples demonstrating quantum computing on IonQ's platform using popular quantum libraries. A great starting point for exploring quantum computation.
4
4
5
-
If you're looking for advanced and in-depth examples for a given library that implement a specific algorithm, check out some of the other projects in the [ionq-samples](https://github.com/ionq-samples) organization on GitHub.
5
+
For advanced examples implementing specific algorithms, check out the [ionq-samples](https://github.com/ionq-samples) organization.
6
6
7
7
---
8
8
9
-
## Prerequisites
9
+
## Quick Start
10
10
11
-
There are a wide variety of ways to run these notebooks, but for starters you'll need:
11
+
### Prerequisites
12
12
13
-
1.[Python](https://www.python.org/downloads/) installed, using a version between 3.10 and 3.13.
14
-
2. A [virtual environment](https://docs.python.org/3/library/venv.html) to help ensure your dependencies don't conflict with anything else you have installed.
15
-
3. An [IonQ API key](https://cloud.ionq.com/settings/keys), which optionally you can store as an environment variable for ease of use. Our notebooks expect to find it stored as `IONQ_API_KEY`.
16
-
4. An installation of the library you're wanting to run. You can install all libraries using one of the following methods:
13
+
- Python 3.10-3.13
14
+
-[IonQ API key](https://cloud.ionq.com/settings/keys) (set as `IONQ_API_KEY` environment variable)
17
15
18
-
**Option 1: Using uv (Fastest - Recommended)**
16
+
### Installation
19
17
20
-
[uv](https://github.com/astral-sh/uv) is an extremely fast Python package installer and resolver:
18
+
**Using pip:**
19
+
```bash
20
+
pip install -e .
21
+
```
21
22
22
-
```shell
23
-
# Install uv (if not already installed)
24
-
curl -LsSf https://astral.sh/uv/install.sh | sh
23
+
**Using uv (faster):**
24
+
```bash
25
+
curl -LsSf https://astral.sh/uv/install.sh | sh
26
+
uv pip install -e .
27
+
```
25
28
26
-
# Install all dependencies
27
-
uv pip install -e .
28
-
```
29
+
**Using conda:**
30
+
```bash
31
+
conda env create -f environment.yml
32
+
```
29
33
30
-
**Option 2: Using Conda**
34
+
### Running Notebooks
31
35
32
-
```shell
33
-
conda env create -f environment.yml
34
-
```
36
+
**Jupyter:**
37
+
```bash
38
+
jupyter notebook
39
+
```
35
40
36
-
**Option 3: Using pip**
41
+
**VS Code:**
42
+
Open any `.ipynb` file and select a Python kernel.
37
43
38
-
```shell
39
-
pip install -e .
40
-
```
44
+
**Cloud:**
45
+
Click the  badge in each notebook.
41
46
42
47
---
43
48
44
49
## Docker
45
50
46
-
For a reproducible environment with all dependencies pre-installed:
51
+
Run in a containerized environment:
47
52
48
-
```shell
49
-
# Build the image (linux/x86_64 required for cudaq)
docker run -p 8888:8888 -e IONQ_API_KEY="your_api_key_here" ionq-notebooks
57
+
# Run
58
+
docker run -p 8888:8888 -e IONQ_API_KEY="your_api_key" ionq-notebooks
54
59
```
55
60
56
-
Then open your browser to [http://localhost:8888](http://localhost:8888)
57
-
58
-
To persist notebook changes, mount the workspace as a volume:
59
-
60
-
```shell
61
-
docker run -p 8888:8888 -e IONQ_API_KEY="your_api_key_here" -v $(pwd):/workspace ionq-notebooks
62
-
```
61
+
Open [http://localhost:8888](http://localhost:8888) in your browser.
63
62
64
63
---
65
64
66
-
## Usage
67
-
68
-
The samples are in the form of Jupyter notebooks, and you can view and run them using a local [Jupyter](http://jupyter.org/) installation, [VS Code](https://code.visualstudio.com/) (using the built-in Jupyter plugin), or [Google Colab](https://colab.research.google.com).
69
-
70
-
If you're unfamiliar with Jupyter but you're used to a traditional IDE or code editor, VS Code is probably the right choice for you.
65
+
## Development
71
66
72
-
#### Jupyter Notebooks
67
+
###Running Tests
73
68
74
-
1. From your terminal, navigate to this repository and run the following command from within this directory:
69
+
```bash
70
+
# All tests
71
+
pytest tests/
75
72
76
-
```shell
77
-
jupyter notebook
78
-
```
73
+
# Parallel execution
74
+
pytest -n auto tests/
79
75
80
-
1. Once the server is started, it should automatically open your browser. In case it doesn't, you can navigate directly to it by pointing your browser at [http://localhost:8888](http://localhost:8888)
81
-
1. Navigate to the location of a `.ipynb` file and open it. If you don't have a particular SDK in mind, we recommend starting with `qiskit`, as its the most commonly used library today.
1. Open the folder in VS Code and navigate to a `.ipynb` file and open it.
86
-
1. If it's your first time using it, it will suggest a number of plugins that you may need to install before the notebook will be fully functional.
87
-
1. At the top-right of the screen, click on `Select Kernel` and choose an appropriate Python runtime to run the notebook in.
88
-
89
-
#### Cloud
79
+
# With custom timeout
80
+
NBEXEC_TIMEOUT_SECONDS=900 pytest tests/
81
+
```
90
82
91
-
1. Open the notebook by clicking on the  badge located in each notebook. Or open this repository in [](https://mybinder.org/v2/gh/ionq-samples/getting-started/HEAD)
83
+
GitHub Actions automatically tests all notebooks on every push.
92
84
93
85
---
94
86
95
87
## Support
96
88
97
-
For support, you can submit issues or PRs in this repository. Alternatively, you can contact us at[support@ionq.com](mailto:support@ionq.com?subject=SDK%20help).
89
+
Submit issues or PRs in this repository, or contact [support@ionq.com](mailto:support@ionq.com?subject=SDK%20help).
"source": "import json\nimport time\n\nimport requests\n\nfrom helpers import get_ionq_api_key\n\n# Before you begin, get your API key from https://cloud.ionq.com/settings/keys\n\n# If your API key is stored as \"IONQ_API_KEY\" in your local environment, this\n# should find it. Otherwise you'll be prompted to enter your API key manually.\n\napi_key = get_ionq_api_key()"
19
+
"source": [
20
+
"import json\n",
21
+
"import time\n",
22
+
"\n",
23
+
"import requests\n",
24
+
"\n",
25
+
"from helpers import get_ionq_api_key\n",
26
+
"\n",
27
+
"# Before you begin, get your API key from https://cloud.ionq.com/settings/keys\n",
28
+
"\n",
29
+
"# If your API key is stored as \"IONQ_API_KEY\" in your local environment, this\n",
30
+
"# should find it. Otherwise you'll be prompted to enter your API key manually.\n",
31
+
"\n",
32
+
"api_key = get_ionq_api_key()\n",
33
+
"\n",
34
+
"# Configuration\n",
35
+
"SHOTS = 100"
36
+
]
20
37
},
21
38
{
22
39
"cell_type": "code",
23
-
"execution_count": null,
40
+
"execution_count": 2,
24
41
"metadata": {},
25
42
"outputs": [],
26
-
"source": "# Define helper functions for interacting with IonQ's API.\n\ndef submit_job(headers, data):\n \"\"\"Submit a quantum job to IonQ's API.\"\"\"\n url = \"https://api.ionq.co/v0.3/jobs\"\n response = requests.post(url, headers=headers, data=data)\n response_json = response.json()\n assert response.status_code == 200, f\"Error: {response_json.get('message', 'Unknown error')}\"\n return response_json[\"id\"]\n\ndef query_job(job_id, headers):\n \"\"\"Query the status of a submitted job.\"\"\"\n url = f\"https://api.ionq.co/v0.3/jobs/{job_id}\"\n response = requests.get(url, headers=headers)\n response_json = response.json()\n assert response.status_code == 200, f\"Error: {response_json.get('message', 'Unknown error')}\"\n return response_json[\"status\"]\n\ndef get_job_results(job_id, headers):\n \"\"\"Retrieve the results of a completed job.\"\"\"\n url = f\"https://api.ionq.co/v0.3/jobs/{job_id}/results\"\n response = requests.get(url, headers=headers)\n response_json = response.json()\n assert response.status_code == 200, f\"Error: {response_json.get('message', 'Unknown error')}\"\n return response_json"
43
+
"source": [
44
+
"# Define helper functions for interacting with IonQ's API.\n",
45
+
"\n",
46
+
"def submit_job(headers, data):\n",
47
+
"\"\"\"Submit a quantum job to IonQ's API.\"\"\"\n",
"source": "# Set up the request headers and define our circuit.\n# This circuit creates a Bell state with two qubits using IonQ's native format.\n\nheaders = {\n\"Authorization\": f\"apiKey {api_key}\",\n\"Content-Type\": \"application/json\",\n}\n\ndata = {\n\"name\": \"API Example Circuit\",\n\"shots\": 100,\n\"target\": \"simulator\",\n\"input\": {\n\"format\": \"ionq.circuit.v0\",\n\"gateset\": \"qis\",\n\"qubits\": 2,\n\"circuit\": [\n {\n\"gate\": \"h\",\n\"target\": 0\n },\n {\n\"gate\": \"cnot\",\n\"control\": 0,\n\"target\": 1\n }\n ]\n }\n}\n"
76
+
"source": [
77
+
"# Set up the request headers and define our circuit.\n",
78
+
"# This circuit creates a Bell state with two qubits using IonQ's native format.\n",
79
+
"\n",
80
+
"headers = {\n",
81
+
"\"Authorization\": f\"apiKey {api_key}\",\n",
82
+
"\"Content-Type\": \"application/json\",\n",
83
+
"}\n",
84
+
"\n",
85
+
"data = {\n",
86
+
"\"name\": \"API Example Circuit\",\n",
87
+
"\"shots\": SHOTS,\n",
88
+
"\"target\": \"simulator\",\n",
89
+
"\"input\": {\n",
90
+
"\"format\": \"ionq.circuit.v0\",\n",
91
+
"\"gateset\": \"qis\",\n",
92
+
"\"qubits\": 2,\n",
93
+
"\"circuit\": [\n",
94
+
" {\n",
95
+
"\"gate\": \"h\",\n",
96
+
"\"target\": 0\n",
97
+
" },\n",
98
+
" {\n",
99
+
"\"gate\": \"cnot\",\n",
100
+
"\"control\": 0,\n",
101
+
"\"target\": 1\n",
102
+
" }\n",
103
+
" ]\n",
104
+
" }\n",
105
+
"}\n"
106
+
]
34
107
},
35
108
{
36
109
"cell_type": "markdown",
@@ -62,10 +135,34 @@
62
135
},
63
136
{
64
137
"cell_type": "code",
65
-
"execution_count": null,
138
+
"execution_count": 4,
66
139
"metadata": {},
67
-
"outputs": [],
68
-
"source": "# Now we'll send the job to our backend for processing.\n\njob_id = submit_job(headers, json.dumps(data))\n\n# And wait for the job to complete.\n\nstatus = \"ready\"\nwhile status != \"completed\":\n time.sleep(1) # Wait for 1 second before querying again.\n status = query_job(job_id, headers)\n\n# Once the job has completed, we can retrieve and display the results.\n\nresults = get_job_results(job_id, headers)\nprint(results)"
140
+
"outputs": [
141
+
{
142
+
"name": "stdout",
143
+
"output_type": "stream",
144
+
"text": [
145
+
"{'0': 0.5, '3': 0.5}\n"
146
+
]
147
+
}
148
+
],
149
+
"source": [
150
+
"# Now we'll send the job to our backend for processing.\n",
0 commit comments