# iqscli
iqscli is an unofficial CLI for IBM Quantum Systems.
*This project has NO connection with IBM. It is my personal project. As of 2024-01-03, I am not employed by IBM and I have no connection with IBM other than having an IBM Quantum and IBM Cloud user account. All information in this repository is acquired from the public documents for example from docs.quantum.ibm.com and cloud.ibm.com/docs.*
## IBM Quantum Systems
### Channels and Plans
There are two channels and four plans (two on each channel) to use IBM Quantum Systems.
The channels are:
- [IBM Quantum](https://quantum.ibm.com) (`ibm_quantum` in qiskit)
- [IBM Cloud](https://cloud.ibm.com) (`ibm_cloud` in qiskit)
The credentials (API tokens) on these systems are not the same. Tokens are created separately.
IBM Quantum has:
- Open Plan: provides a 10 minute monthly access to 127-qubit systems and unlimited access to Simulators. This plan is free.
- Premium Plan: provides access to both 127-qubit and 27-qubit systems as well as exploratory systems and Simulators and support. This is a paid plan and the price varies.
IBM Cloud has:
- Lite Plan: provides unlimited access to Simulators only. This plan is free.
- Standard Plan: provides Pay-As-You-Go access to 127-qubit and 27-qubit systems and unlimited access to Simulators. This is a paid plan and the price at the moment (2024-01-03) is 1.60 USD/second.
At the moment (2024-01-03), the best (free) way to access the simulators is IBM Quantum Open plan or IBM Cloud Lite plan. The best (free) way to access the real IBM Quantum Systems is IBM Quantum Open plan. Thus, IBM Quantum Open plan seems to be the best starting point.
### Instances
The services both on IBM Quantum and IBM Cloud are controlled by instances. An instance is identified by:
- hub/group/project in IBM Quantum
- CRN in IBM Cloud
When a user is signed up on IBM Quantum, it is assigned to the Open plan, and the Open plan's instance, which is `ibm-q/open/main` (i.e. hub is IBM Quantum called ibm, group is open, project is main). When a user is assigned to a premium plan, a particular hub/group/project is given.
When a Qiskit Runtime instance is created on IBM Cloud, the plan, lite or standard, has to be chosen. When a Qiskit Runtime instance is created, its CRN is displayed on the instance details.
### Quantum Systems
At the moment, I see the following Eagle based 127-qubit systems in both of my IBM Quantum and IBM Cloud accounts: `ibm_brisbane`, `ibm_kyoto` and `ibm_osaka`. IBM Cloud account also shows a Falcon based 27-qubit system called `ibm_algiers`.
These are not all the systems. A comprehensive listing can be found in [Compute resources @ IBM Cloud](https://cloud.ibm.com/quantum/resources/systems) and [Compute resources @ IBM Quantum Platform](https://quantum.ibm.com/services/resources?tab=systems).
## Installation
```
pip install iqscli
```
## Usage
*The account information and the credentials including the token is saved to an open file, it is not encrypted. Thus, it is readable by anyone. On Linux, the credentials file is $HOME/.qiskit/qiskit-ibm.json.*
### save-account, saved-accounts, delete-account
Before using any other command, `save-account` command should be run to save the credentials (API token) for later use. One account can be marked as default with `--set-as-default` and it is used when no `--account-name` or `--channel` is provided with the commands.
With `save-account`, if no `--account-name` is provided, account is saved with a default name, `default-ibm-quantum` or `default-ibm-cloud` depending on the channel. Thus, each channel can have one default account. This account is selected if `--channel` is provided. Thus, all commands (except `saved-accounts`) have `--channel` and `--account-name` options. The account selection is (as described in Qiskit Runtime IBM Client):
- when `--account-name` is given, corresponding account is used
- when `--account-name` is not given but `--channel` is given, the default account for the channel is used (default-ibm-quantum or default-ibm-cloud)
- when neither `--account-name` nor `--channel` is given, the default account is used
After the credentials are saved once, the subsequent runs to `save-account` works successfully only with `--overwrite`, since the credentials file should be overwritten.
For example, save a default IBM Quantum Open instance account:
```
$ iqscli save-account --channel ibm_quantum --instance ibm-q/open/main --token <token>
```
List saved accounts:
```
$ iqscli saved-accounts
default-ibm-quantum @ ibm_quantum = ibm-q/open/main
```
### backends
List all backends:
```
$ iqscli backends
ibm-q/open/main @ ibm_quantum
ibm_brisbane ONLINE (13 jobs)
ibm_kyoto ONLINE (13 jobs)
ibm_osaka ONLINE (0 jobs)
ibmq_qasm_simulator ONLINE (0 jobs)
simulator_mps ONLINE (0 jobs)
simulator_statevector ONLINE (0 jobs)
```
Show details of a particular backend:
```
$ iqscli backends --show-details --name ibm_brisbane
ibm-q/open/main @ ibm_quantum
ibm_brisbane ONLINE (13 jobs)
processor: Eagle r3
num_qubits: 127
max_shots: 100000
basis_gates: ecr, id, rz, sx, x
instructions: ecr, id, delay, measure, reset, rz, sx, x, if_else, for_loop, switch_case
meas_kernels: hw_qmfk
```
### jobs
Show jobs:
```
$ iqscli jobs
ibm-q/open/main @ ibm_quantum
cma3f8oiidfp3m905ft0 ibmq_qasm_simulator sampler DONE 20240102171947812375
cma3688iidfp3m904dq0 ibmq_qasm_simulator sampler DONE 20240102170033755981
cma32c6879ps6bbv1mb0 ibmq_qasm_simulator sampler DONE 20240102165216597386
```
## Changes
0.4:
- improvements to existing commands
0.3:
- jobs command added
0.2:
- first pypi release
Raw data
{
"_id": null,
"home_page": "https://github.com/metebalci/iqscli",
"name": "iqscli",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "cli ibm quantum",
"author": "Mete Balci",
"author_email": "metebalci@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/f7/25de6abceffbdcde9526cbb67f62cde92a737f3f6e46e4305a3592072f8a/iqscli-0.4.tar.gz",
"platform": null,
"description": "# iqscli\n\niqscli is an unofficial CLI for IBM Quantum Systems.\n\n*This project has NO connection with IBM. It is my personal project. As of 2024-01-03, I am not employed by IBM and I have no connection with IBM other than having an IBM Quantum and IBM Cloud user account. All information in this repository is acquired from the public documents for example from docs.quantum.ibm.com and cloud.ibm.com/docs.*\n\n## IBM Quantum Systems\n\n### Channels and Plans\n\nThere are two channels and four plans (two on each channel) to use IBM Quantum Systems. \n\nThe channels are:\n\n- [IBM Quantum](https://quantum.ibm.com) (`ibm_quantum` in qiskit)\n- [IBM Cloud](https://cloud.ibm.com) (`ibm_cloud` in qiskit)\n\nThe credentials (API tokens) on these systems are not the same. Tokens are created separately. \n\nIBM Quantum has:\n\n- Open Plan: provides a 10 minute monthly access to 127-qubit systems and unlimited access to Simulators. This plan is free.\n\n- Premium Plan: provides access to both 127-qubit and 27-qubit systems as well as exploratory systems and Simulators and support. This is a paid plan and the price varies.\n\nIBM Cloud has:\n\n- Lite Plan: provides unlimited access to Simulators only. This plan is free.\n\n- Standard Plan: provides Pay-As-You-Go access to 127-qubit and 27-qubit systems and unlimited access to Simulators. This is a paid plan and the price at the moment (2024-01-03) is 1.60 USD/second.\n\nAt the moment (2024-01-03), the best (free) way to access the simulators is IBM Quantum Open plan or IBM Cloud Lite plan. The best (free) way to access the real IBM Quantum Systems is IBM Quantum Open plan. Thus, IBM Quantum Open plan seems to be the best starting point.\n\n### Instances\n\nThe services both on IBM Quantum and IBM Cloud are controlled by instances. An instance is identified by:\n\n- hub/group/project in IBM Quantum\n- CRN in IBM Cloud\n\nWhen a user is signed up on IBM Quantum, it is assigned to the Open plan, and the Open plan's instance, which is `ibm-q/open/main` (i.e. hub is IBM Quantum called ibm, group is open, project is main). When a user is assigned to a premium plan, a particular hub/group/project is given.\n\nWhen a Qiskit Runtime instance is created on IBM Cloud, the plan, lite or standard, has to be chosen. When a Qiskit Runtime instance is created, its CRN is displayed on the instance details.\n\n### Quantum Systems\n\nAt the moment, I see the following Eagle based 127-qubit systems in both of my IBM Quantum and IBM Cloud accounts: `ibm_brisbane`, `ibm_kyoto` and `ibm_osaka`. IBM Cloud account also shows a Falcon based 27-qubit system called `ibm_algiers`. \n\nThese are not all the systems. A comprehensive listing can be found in [Compute resources @ IBM Cloud](https://cloud.ibm.com/quantum/resources/systems) and [Compute resources @ IBM Quantum Platform](https://quantum.ibm.com/services/resources?tab=systems).\n\n## Installation\n\n```\npip install iqscli\n```\n\n## Usage\n\n*The account information and the credentials including the token is saved to an open file, it is not encrypted. Thus, it is readable by anyone. On Linux, the credentials file is $HOME/.qiskit/qiskit-ibm.json.*\n\n### save-account, saved-accounts, delete-account\n\nBefore using any other command, `save-account` command should be run to save the credentials (API token) for later use. One account can be marked as default with `--set-as-default` and it is used when no `--account-name` or `--channel` is provided with the commands.\n\nWith `save-account`, if no `--account-name` is provided, account is saved with a default name, `default-ibm-quantum` or `default-ibm-cloud` depending on the channel. Thus, each channel can have one default account. This account is selected if `--channel` is provided. Thus, all commands (except `saved-accounts`) have `--channel` and `--account-name` options. The account selection is (as described in Qiskit Runtime IBM Client):\n\n- when `--account-name` is given, corresponding account is used\n- when `--account-name` is not given but `--channel` is given, the default account for the channel is used (default-ibm-quantum or default-ibm-cloud)\n- when neither `--account-name` nor `--channel` is given, the default account is used\n\nAfter the credentials are saved once, the subsequent runs to `save-account` works successfully only with `--overwrite`, since the credentials file should be overwritten.\n\nFor example, save a default IBM Quantum Open instance account:\n\n```\n$ iqscli save-account --channel ibm_quantum --instance ibm-q/open/main --token <token>\n```\n\nList saved accounts:\n\n```\n$ iqscli saved-accounts\ndefault-ibm-quantum @ ibm_quantum = ibm-q/open/main\n```\n\n### backends\n\nList all backends:\n\n```\n$ iqscli backends\nibm-q/open/main @ ibm_quantum\nibm_brisbane ONLINE (13 jobs)\nibm_kyoto ONLINE (13 jobs)\nibm_osaka ONLINE (0 jobs)\nibmq_qasm_simulator ONLINE (0 jobs)\nsimulator_mps ONLINE (0 jobs)\nsimulator_statevector ONLINE (0 jobs)\n```\n\nShow details of a particular backend:\n\n```\n$ iqscli backends --show-details --name ibm_brisbane\nibm-q/open/main @ ibm_quantum\nibm_brisbane ONLINE (13 jobs)\n processor: Eagle r3\n num_qubits: 127\n max_shots: 100000\n basis_gates: ecr, id, rz, sx, x\n instructions: ecr, id, delay, measure, reset, rz, sx, x, if_else, for_loop, switch_case\n meas_kernels: hw_qmfk\n```\n\n### jobs\n\nShow jobs:\n\n```\n$ iqscli jobs\nibm-q/open/main @ ibm_quantum\ncma3f8oiidfp3m905ft0 ibmq_qasm_simulator sampler DONE 20240102171947812375\ncma3688iidfp3m904dq0 ibmq_qasm_simulator sampler DONE 20240102170033755981\ncma32c6879ps6bbv1mb0 ibmq_qasm_simulator sampler DONE 20240102165216597386\n```\n\n## Changes\n\n0.4:\n- improvements to existing commands\n\n0.3:\n- jobs command added\n\n0.2:\n- first pypi release\n\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "iqscli is an unofficial CLI for IBM Quantum Systems",
"version": "0.4",
"project_urls": {
"Homepage": "https://github.com/metebalci/iqscli"
},
"split_keywords": [
"cli",
"ibm",
"quantum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e5f725de6abceffbdcde9526cbb67f62cde92a737f3f6e46e4305a3592072f8a",
"md5": "3f66ad23b13a2453e15f99595ee78335",
"sha256": "96d04d97518ef67b1dd09d77330056c816f7ea2df46110bd5d43988f8d90d346"
},
"downloads": -1,
"filename": "iqscli-0.4.tar.gz",
"has_sig": false,
"md5_digest": "3f66ad23b13a2453e15f99595ee78335",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9956,
"upload_time": "2024-01-03T06:23:39",
"upload_time_iso_8601": "2024-01-03T06:23:39.700115Z",
"url": "https://files.pythonhosted.org/packages/e5/f7/25de6abceffbdcde9526cbb67f62cde92a737f3f6e46e4305a3592072f8a/iqscli-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-03 06:23:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "metebalci",
"github_project": "iqscli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "iqscli"
}
JSON
