qiskit-connector


Nameqiskit-connector JSON
Version 0.7.9 PyPI version JSON
download
home_pagehttps://github.com/schijioke-uche/qiskit-connector
SummaryIBM Quantum Qiskit Connector For Backend RuntimeService
upload_time2025-04-26 02:36:22
maintainerNone
docs_urlNone
authorDr. Jeffrey Chijioke-Uche
requires_python>=3.8
licenseMIT 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"
}
        
Elapsed time: 1.09902s