| Name | qiskit-connector JSON |
| Version |
0.7.9
JSON |
| download |
| home_page | https://github.com/schijioke-uche/qiskit-connector |
| Summary | IBM Quantum Qiskit Connector For Backend RuntimeService |
| upload_time | 2025-04-26 02:36:22 |
| maintainer | None |
| docs_url | None |
| author | Dr. Jeffrey Chijioke-Uche |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Dr. Jeffrey Chijioke-Uche, IBM
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
qiskit
quantum
ibm
connector
runtimeservice
backends
qpu
compute
circuit
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
qiskit
qiskit-ibm-runtime
python-dotenv
requests
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# qiskit-connector
**⚛️Qiskit Connector for IBM Quantum Backends in Realtime**
A Quantum helper package which streamlines authentication, plan detection, and backend selection for Qiskit RuntimeService. This connector prevents repeated writing of runtimeservice instead allows you to directly use the `backend` object all over your quantum application code in realtime. This package performs the following:
- Loads environment variables from config file (e.g. `.env`) to configure your IBM Quantum account plan and make the `backend` object available within your quantum application code for reuse in real-time.
- Detects your active plan (Open, Standard, Premium, Dedicated) and sets up the correct channel/instance.
- It has functions to save your account using its (`qiskit_smart`), to verify QPU resources using (`qpu_verify`, `is_verified`), and retrieve a ready-to-use backend using (`connector()`). Presents you with the least-busy backend to run your quantum application code in realtime instead of you using simulators.
###### 🐍 Package built and maintained by Dr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Research Scientist.
---
## 📋 Features & API
All of the following functions are available after you import the module:
```python
from qiskit_connector import (
connector,
plan_type
)
```
- **`qiskit_smart(plan_type: str)`**
Saves your IBM Quantum account into QiskitRuntimeService using the environment variables for the given plan (`"open"`, `"standard"`, `"premium"`, or `"dedicated"`).
- **`qpu_verify()`**
Lists available QPUs for your plan by querying `QiskitRuntimeService.backends()` or falling back to `paid_plans()` for paid plans.
- **`is_verified()`**
Verifies real‐time least-busy QPU for the active plan and prints details (name, qubit count, online date).
- **`connector() -> IBMBackend`**
**Main entry point**: Loads your saved account, picks the least busy QPU (or first available for open or paid plans), prints diagnostics, and returns an `IBMBackend` instance ready for circuit execution.
- **`plan_type() -> str`**
Returns either **"Open Plan"** or **"Paid Plan"** depending on your `.env` toggles.
---
## 🔧 Installation
```bash
pip install qiskit-connector
```
This will also pull in functionalities powered by:
- `qiskit>=2.0.0`
and any other Qiskit dependencies. (Qiskit 1.x is not supported).
---
## 🗂️ Environment Variable Setup
🔐 Security Practice: Do not check-in `.env` or any environment variable files into version control. Add it to your .gitignore. During development, create a file named `.env` at your project root. The connector will automatically load it.Use the template below as the content of your .env file or variable config file.
```dotenv
# @author: Dr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Researcher
# This file is used to store environment variables for the Qiskit installation wizard: Update it.
# The "ibm_quantum" channel option is deprecated and will be sunset on 1 July 2025.
# After this date, ibm_cloud will be the only valid channel.
# For information on migrating to the new IBM Quantum Platform on the "ibm_cloud" channel,
# review the migration guide https://quantum.cloud.ibm.com/docs/migration-guides/classic-iqp-to-cloud-iqp .
# GENERAL PURPOSE
#--------------------------------------------
IQP_API_TOKEN="<PROVIDE_YOUR_API_TOKEN>"
# Channels:
#------------------------------------------
OPEN_PLAN_CHANNEL="<PROVIDE_YOUR_CHANNEL>"
PAID_PLAN_CHANNEL="<PROVIDE PAID PLAN CHANNEL>" # After July 1, 2025, use ibm_cloud for Paid Plans.
# API Access:
#-------------------------------------
IQP_API_URL=<PROVIDE_YOUR_API_URL>
IQP_RUNTIME_API_URL=<PROVIDE_YOUR_RUNTIME_API_URL>
# Quantum Url:
# The API URL. Defaults to https://cloud.ibm.com (when channel=ibm_cloud)
# The API URL:Default to: https://auth.quantum.ibm.com/api (when channel=ibm_quantum)"
#-------------------------------------
CLOUD_API_URL=<PROVIDE_YOUR_CLOUD_API_URL>
QUANTUM_API_URL="<PROVIDE_YOUR_QUANTUM_API_URL>"
# Instance:
#-------------------------------------
OPEN_PLAN_INSTANCE="<PROVIDE_YOUR_OPEN_PLAN_INSTANCE>"
PAID_PLAN_INSTANCE="<PROVIDE_YOUR_PAID_PLAN_INSTANCE>"
# Default (Open plan) - free
#----------------------------------------
OPEN_PLAN_NAME="open"
# Optional (Upgrade) - Standard
#-----------------------------------------
STANDARD_PLAN_NAME="standard"
# Optional (Upgrade) - Premium
#-----------------------------------------
PREMIUM_PLAN_NAME="premium"
# Optional (Upgrade) - Dedicated
#-----------------------------------------
DEDICATED_PLAN_NAME="dedicated"
# Switch "on" one plan: Use one or the other at a time. You cannot switch both on at the same time.
#--------------------------------------------------------------------------------------------------
OPEN_PLAN="on" # [Default & switched on] This plan is free - Signup
STANDARD_PLAN="off" # This plan is paid. Switched "Off" by default - Turn it "on" after purchase.
PREMIUM_PLAN="off" # This plan is paid. Switched "Off" by default - Turn it "on" after purchase.
DEDICATED_PLAN="off" # This plan is paid. Switched "Off" by default - Turn it "on" after purchase.
```
> **⚠️ Only one** of `OPEN_PLAN`, `STANDARD_PLAN`, `PREMIUM_PLAN`, or `DEDICATED_PLAN` may be set to **"on"** at a time.
---
## 📖 Usage
### Open Plan (default free tier) and Paid Plan
```python
from qiskit_connector import connector, plan_type
from qiskit_ibm_runtime import SamplerV2 as Sampler, Session
# QPU execution mode by plan: Use of 'backend' object.
current = plan_type()
backend = connector()
if current == "Open Plan": # session not supported
sampler = Sampler(mode=backend)
print("Your Plan",current)
print("Least Busy QPU:", backend.name)
if isinstance(backend, IBMBackend):
print("This is a real & live QPU device")
else:
print("This is a simulator")
print(f"\n")
elif current == "Paid Plan": # supports session
with Session(backend=backend.name) as session:
sampler = Sampler(mode=session)
print("Your Plan",current)
print("Least Busy QPU:", backend.name)
if isinstance(backend, IBMBackend):
print("This is a real & live QPU device")
else:
print("This is a simulator")
print(f"\n")
else:
raise ValueError(f"Unknown plan type: {current}")
# --- do other things below with backend, quantum circuit, sampler & transpilation ------
```
## Sample Output
```python
[✓] Quantum environment variables loaded successfully!
--------------------------------------------------------------------------------
[⚛] Connected [Open Plan] -> Realtime Least Busy QPU: ibm_torino
--------------------------------------------------------------------------------
Available QPUs (Open Plan):
- ibm_brisbane
- ibm_sherbrooke
- ibm_torino
Default QPU: ibm_torino
Qubit Version: 2
Number Qubits: 133
--------------------------------------------------------------------------------
Your Plan: Open Plan
Least Busy QPU: ibm_torino
This is a real & live QPU device
#-------- remaining code below ------
```
---
## Authors and Citation
Qiskit Connector was inspired, authored and brought about by the research carried out by Dr. Jeffrey Chijioke-Uche(IBM Quantum Ambassador & Research Scientist). This software is expected to continues to grow with the help and work of existing research at different levels in the Information Technology industry. If you use Qiskit for Quantum, please cite as per the provided BibTeX file.
---
## 📜 Software Publisher
Dr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Research Scientist (All Rights Reserved)
---
## 📜 License
This project uses the MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/schijioke-uche/qiskit-connector",
"name": "qiskit-connector",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "qiskit, quantum, ibm, connector, runtimeservice, backends, qpu, compute, circuit",
"author": "Dr. Jeffrey Chijioke-Uche",
"author_email": "\"Dr. Jeffrey Chijioke-Uche\" <sj@chijioke-uche.com>",
"download_url": "https://files.pythonhosted.org/packages/87/99/ca069bea8602a7445d3c2613f81d67a267181a33b07e8378c10ec6532a8a/qiskit_connector-0.7.9.tar.gz",
"platform": null,
"description": "# qiskit-connector\n\n**\u269b\ufe0fQiskit Connector for IBM Quantum Backends in Realtime**\n\nA Quantum helper package which streamlines authentication, plan detection, and backend selection for Qiskit RuntimeService. This connector prevents repeated writing of runtimeservice instead allows you to directly use the `backend` object all over your quantum application code in realtime. This package performs the following:\n- Loads environment variables from config file (e.g. `.env`) to configure your IBM Quantum account plan and make the `backend` object available within your quantum application code for reuse in real-time.\n- Detects your active plan (Open, Standard, Premium, Dedicated) and sets up the correct channel/instance.\n- It has functions to save your account using its (`qiskit_smart`), to verify QPU resources using (`qpu_verify`, `is_verified`), and retrieve a ready-to-use backend using (`connector()`). Presents you with the least-busy backend to run your quantum application code in realtime instead of you using simulators.\n\n###### \ud83d\udc0d Package built and maintained by Dr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Research Scientist.\n---\n\n## \ud83d\udccb Features & API\n\nAll of the following functions are available after you import the module:\n\n```python\nfrom qiskit_connector import (\n connector,\n plan_type\n)\n```\n\n- **`qiskit_smart(plan_type: str)`** \n Saves your IBM Quantum account into QiskitRuntimeService using the environment variables for the given plan (`\"open\"`, `\"standard\"`, `\"premium\"`, or `\"dedicated\"`).\n\n- **`qpu_verify()`** \n Lists available QPUs for your plan by querying `QiskitRuntimeService.backends()` or falling back to `paid_plans()` for paid plans.\n\n- **`is_verified()`** \n Verifies real\u2010time least-busy QPU for the active plan and prints details (name, qubit count, online date).\n\n- **`connector() -> IBMBackend`** \n **Main entry point**: Loads your saved account, picks the least busy QPU (or first available for open or paid plans), prints diagnostics, and returns an `IBMBackend` instance ready for circuit execution.\n\n- **`plan_type() -> str`** \n Returns either **\"Open Plan\"** or **\"Paid Plan\"** depending on your `.env` toggles.\n\n---\n\n## \ud83d\udd27 Installation\n\n```bash\npip install qiskit-connector\n```\n\nThis will also pull in functionalities powered by:\n- `qiskit>=2.0.0` \n \n\nand any other Qiskit dependencies. (Qiskit 1.x is not supported).\n\n---\n\n## \ud83d\uddc2\ufe0f Environment Variable Setup\n\ud83d\udd10 Security Practice: Do not check-in `.env` or any environment variable files into version control. Add it to your .gitignore. During development, create a file named `.env` at your project root. The connector will automatically load it.Use the template below as the content of your .env file or variable config file.\n\n```dotenv\n\n# @author: Dr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Researcher\n# This file is used to store environment variables for the Qiskit installation wizard: Update it.\n# The \"ibm_quantum\" channel option is deprecated and will be sunset on 1 July 2025. \n# After this date, ibm_cloud will be the only valid channel. \n# For information on migrating to the new IBM Quantum Platform on the \"ibm_cloud\" channel, \n# review the migration guide https://quantum.cloud.ibm.com/docs/migration-guides/classic-iqp-to-cloud-iqp .\n\n\n# GENERAL PURPOSE\n#--------------------------------------------\nIQP_API_TOKEN=\"<PROVIDE_YOUR_API_TOKEN>\" \n\n\n# Channels:\n#------------------------------------------\nOPEN_PLAN_CHANNEL=\"<PROVIDE_YOUR_CHANNEL>\" \nPAID_PLAN_CHANNEL=\"<PROVIDE PAID PLAN CHANNEL>\" # After July 1, 2025, use ibm_cloud for Paid Plans.\n\n\n# API Access:\n#-------------------------------------\nIQP_API_URL=<PROVIDE_YOUR_API_URL> \nIQP_RUNTIME_API_URL=<PROVIDE_YOUR_RUNTIME_API_URL> \n\n\n# Quantum Url:\n# The API URL. Defaults to https://cloud.ibm.com (when channel=ibm_cloud) \n# The API URL:Default to: https://auth.quantum.ibm.com/api (when channel=ibm_quantum)\"\n#-------------------------------------\nCLOUD_API_URL=<PROVIDE_YOUR_CLOUD_API_URL> \nQUANTUM_API_URL=\"<PROVIDE_YOUR_QUANTUM_API_URL>\" \n\n\n# Instance:\n#-------------------------------------\nOPEN_PLAN_INSTANCE=\"<PROVIDE_YOUR_OPEN_PLAN_INSTANCE>\" \nPAID_PLAN_INSTANCE=\"<PROVIDE_YOUR_PAID_PLAN_INSTANCE>\" \n\n\n# Default (Open plan) - free\n#----------------------------------------\nOPEN_PLAN_NAME=\"open\"\n\n\n# Optional (Upgrade) - Standard\n#-----------------------------------------\nSTANDARD_PLAN_NAME=\"standard\"\n\n\n# Optional (Upgrade) - Premium\n#-----------------------------------------\nPREMIUM_PLAN_NAME=\"premium\"\n\n\n# Optional (Upgrade) - Dedicated\n#-----------------------------------------\nDEDICATED_PLAN_NAME=\"dedicated\"\n\n\n# Switch \"on\" one plan: Use one or the other at a time. You cannot switch both on at the same time.\n#--------------------------------------------------------------------------------------------------\nOPEN_PLAN=\"on\" # [Default & switched on] This plan is free - Signup\nSTANDARD_PLAN=\"off\" # This plan is paid. Switched \"Off\" by default - Turn it \"on\" after purchase. \nPREMIUM_PLAN=\"off\" # This plan is paid. Switched \"Off\" by default - Turn it \"on\" after purchase. \nDEDICATED_PLAN=\"off\" # This plan is paid. Switched \"Off\" by default - Turn it \"on\" after purchase. \n```\n\n> **\u26a0\ufe0f Only one** of `OPEN_PLAN`, `STANDARD_PLAN`, `PREMIUM_PLAN`, or `DEDICATED_PLAN` may be set to **\"on\"** at a time.\n\n---\n\n## \ud83d\udcd6 Usage\n\n### Open Plan (default free tier) and Paid Plan\n\n```python\n\nfrom qiskit_connector import connector, plan_type\nfrom qiskit_ibm_runtime import SamplerV2 as Sampler, Session\n\n# QPU execution mode by plan: Use of 'backend' object.\ncurrent = plan_type()\nbackend = connector()\n\nif current == \"Open Plan\": # session not supported\n sampler = Sampler(mode=backend)\n print(\"Your Plan\",current)\n print(\"Least Busy QPU:\", backend.name)\n if isinstance(backend, IBMBackend):\n print(\"This is a real & live QPU device\")\n else:\n print(\"This is a simulator\")\n print(f\"\\n\")\nelif current == \"Paid Plan\": # supports session\n with Session(backend=backend.name) as session:\n sampler = Sampler(mode=session)\n print(\"Your Plan\",current)\n print(\"Least Busy QPU:\", backend.name)\n if isinstance(backend, IBMBackend):\n print(\"This is a real & live QPU device\")\n else:\n print(\"This is a simulator\")\n print(f\"\\n\")\nelse:\n raise ValueError(f\"Unknown plan type: {current}\")\n\n# --- do other things below with backend, quantum circuit, sampler & transpilation ------\n```\n\n\n## Sample Output\n```python\n[\u2713] Quantum environment variables loaded successfully!\n\n--------------------------------------------------------------------------------\n[\u269b] Connected [Open Plan] -> Realtime Least Busy QPU: ibm_torino\n--------------------------------------------------------------------------------\n\nAvailable QPUs (Open Plan):\n - ibm_brisbane\n - ibm_sherbrooke\n - ibm_torino\n\nDefault QPU: ibm_torino\nQubit Version: 2\nNumber Qubits: 133\n\n--------------------------------------------------------------------------------\n\nYour Plan: Open Plan\nLeast Busy QPU: ibm_torino\nThis is a real & live QPU device\n\n#-------- remaining code below ------\n\n```\n\n\n---\n## Authors and Citation\n\nQiskit Connector was inspired, authored and brought about by the research carried out by Dr. Jeffrey Chijioke-Uche(IBM Quantum Ambassador & Research Scientist). This software is expected to continues to grow with the help and work of existing research at different levels in the Information Technology industry. If you use Qiskit for Quantum, please cite as per the provided BibTeX file.\n\n---\n\n## \ud83d\udcdc Software Publisher\nDr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Research Scientist (All Rights Reserved) \n\n---\n\n## \ud83d\udcdc License\n\nThis project uses the MIT License\n\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Dr. Jeffrey Chijioke-Uche, IBM\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "IBM Quantum Qiskit Connector For Backend RuntimeService",
"version": "0.7.9",
"project_urls": {
"Homepage": "https://github.com/schijioke-uche/qiskit-connector",
"Source": "https://github.com/schijioke-uche/qiskit-connector",
"Tracker": "https://github.com/schijioke-uche/qiskit-connector/issues"
},
"split_keywords": [
"qiskit",
" quantum",
" ibm",
" connector",
" runtimeservice",
" backends",
" qpu",
" compute",
" circuit"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1f3c23e897af09aee30bccadcac589bd5d9905aeb58334cbe6fb53325fe72e4f",
"md5": "e897879b3b4116e273026f59d47c0055",
"sha256": "96f1aef670ad107881b5d39c95630b9979300dd4189ee09961f43095ed108934"
},
"downloads": -1,
"filename": "qiskit_connector-0.7.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e897879b3b4116e273026f59d47c0055",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8009,
"upload_time": "2025-04-26T02:36:20",
"upload_time_iso_8601": "2025-04-26T02:36:20.351942Z",
"url": "https://files.pythonhosted.org/packages/1f/3c/23e897af09aee30bccadcac589bd5d9905aeb58334cbe6fb53325fe72e4f/qiskit_connector-0.7.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8799ca069bea8602a7445d3c2613f81d67a267181a33b07e8378c10ec6532a8a",
"md5": "952806f9b6cc52e1a1279da10964c43e",
"sha256": "91eeb6f4929330e10b7ed04a5f779ed7743971ec10475f66254a811fa188913d"
},
"downloads": -1,
"filename": "qiskit_connector-0.7.9.tar.gz",
"has_sig": false,
"md5_digest": "952806f9b6cc52e1a1279da10964c43e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8693,
"upload_time": "2025-04-26T02:36:22",
"upload_time_iso_8601": "2025-04-26T02:36:22.005697Z",
"url": "https://files.pythonhosted.org/packages/87/99/ca069bea8602a7445d3c2613f81d67a267181a33b07e8378c10ec6532a8a/qiskit_connector-0.7.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-26 02:36:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "schijioke-uche",
"github_project": "qiskit-connector",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "qiskit",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "qiskit-ibm-runtime",
"specs": [
[
"==",
"0.38.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "requests",
"specs": []
}
],
"lcname": "qiskit-connector"
}
