# QSteed
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/BAQIS-Quantum/qsteed/releases)
[](https://pypi.org/project/qsteed/)
[//]: # ()
**QSteed** is a **Q**uantum **S**of**t**war**e** of
Compilation for supporting R**e**al Quantum **d**evice,
including a quantum compiler, a quantum resource
virtualization manager, and a task scheduler.
## Installation
### Need to install [pyquafu](https://github.com/ScQ-Cloud/pyquafu)
```bash
pip install 'pyquafu>=0.4.1'
```
### Install from PyPI
You can install QSteed via pip:
```bash
pip install qsteed
```
### Install from source
You can directly download the [source code](https://github.com/BAQIS-Quantum/qsteed/archive/refs/heads/master.zip) from GitHub
or clone the repository using the following command.
```bash
git clone https://github.com/BAQIS-Quantum/QSteed.git
```
Change to the qsteed directory install using the following command:
```bash
pip install -r requirements.txt
python setup.py install # or: pip install .
```
## Example
### Quantum circuit transpiler
To use only the quantum circuit transpiler, you can refer to the following examples.
The following code demonstrates how to customize hardware backend properties and customize the compilation process.
```python
import matplotlib.pyplot as plt
from qsteed import *
# Generating random quantum circuits (needs to be a pyquafu QuantumCircuit class)
rqc = RandomCircuit(num_qubit=5, gates_number=100, gates_list=['cx', 'rx', 'rz', 'ry', 'h'])
qc = rqc.random_circuit()
# Set chip information (the number of chip qubits needs to be consistent
# with the number of quantum circuit qubits)
basis_gates = ['cx', 'rx', 'ry', 'rz', 'id', 'h']
c_list = [(2, 3, 0.982), (3, 2, 0.982), (3, 4, 0.973), (4, 3, 0.973),
(0, 1, 0.98), (1, 0, 0.98), (1, 2, 0.97), (2, 1, 0.97)]
backend_properties = {
'name': 'ExampleBackend',
'backend_type': 'superconducting',
'qubits_num': 5,
'coupling_list': c_list,
'basis_gates': basis_gates,
}
# Predefined compilation passflow
passes = [
UnrollTo2Qubit(),
SabreLayout(heuristic='fidelity', max_iterations=3), # heuristic='distance' or 'fidelity', 'mixture'
UnrollToBasis(basis_gates=basis_gates),
GateCombineOptimization(),
OneQubitGateOptimization()
]
passflow = PassFlow(passes=passes)
backend_instance = Backend(**backend_properties)
initial_model = Model(backend=backend_instance)
transpiler = Transpiler(passflow, initial_model)
transpiled_circuit = transpiler.transpile(qc)
transpiled_circuit.plot_circuit()
plt.show()
```
You can also use preset compilation passflow with optimization_level 0-3:
Using preset compilation passflow, see [preset_passflow.py](qsteed/passflow/preset_passflow.py)
```python
transpiler = Transpiler(initial_model=initial_model)
transpiled_circuit = transpiler.transpile(qc, optimization_level=3)
```
### Quantum Compiler
> ⚠️<span style="color:#8B0000"> **Warning**</span>
> The quantum compiler requires MySQL database support, see section [Deployment](#deployment).
Using the `Compiler`, you can compile quantum circuits onto a real quantum chip.
```python
from qsteed.compiler.compiler import Compiler
qasm = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[5];
creg meas[5];
rxx(2.7757800154614016) q[3],q[2];
z q[2];
h q[3];
rxx(5.893149917736792) q[2],q[0];
cx q[4],q[1];
x q[1];
y q[4];
x q[4];
measure q[0] -> meas[0];
measure q[1] -> meas[1];
measure q[2] -> meas[2];
measure q[3] -> meas[3];
measure q[4] -> meas[4];
"""
# If 'qpu_name' is not given, the most suitable computing resource for the task is searched on all available chips.
compiler = Compiler(qasm, qpu_name='example')
compiled_openqasm, final_q2c, compiled_circuit_information = compiler.compile()
```
More convenient to use `compiler_api`, user tasks can be compiled onto available quantum computing resources.
If deployed on a real machine, users can submit a task information dictionary,
and by invoking the compilation interface, the compiled results will be sent to
the quantum computer’s measurement and control device for computation.
```python
from qsteed.apis.compiler_api import call_compiler_api
# Assume you can obtain the user's task information and store it as task_info.
task_info = {
"circuit": qasm,
"transpile": True,
"qpu_name": 'example',
"optimization_level": 2,
"task_type": 'qc',
}
compiled_info = call_compiler_api(**task_info)
print('Compiled openqasm:\n', compiled_info[0])
print('Measurement qubits to cbits:\n', compiled_info[1])
print('Compiled circuit information:\n', compiled_info[2])
```
## Deployment
### <span style="font-size:larger;">I.</span> Copy the configuration file
For convenience, you can run the following command to place the configuration file
`config.ini` in the `QSteed` folder at the root directory,
```python
from qsteed.qsteed_config import copy_config
copy_config()
```
or run the following command in the terminal:
```bash
qsteed-config
```
You can also manually copy the `config.ini` to the `~\QSteed` directory.
### <span style="font-size:larger;">II.</span> Configure MySQL Service
#### 1. Install MySQL.
You can download the appropriate [MySQL Community Server](https://dev.mysql.com/downloads/mysql/) from the MySQL official website.
For detailed installation instructions, see the official [documentation](https://dev.mysql.com/doc/refman/8.4/en/installing.html).
#### 2. Set MySQL user information
[//]: # (After installing QSteed, a folder named `QSteed` will be created in the root directory. )
[//]: # (Inside this folder, there is a configuration file called `config.ini`. )
Open the configuration file `config.ini` and enter your MySQL user information into the `mysql_config` property under section `[MySQL]`.
Please keep the following format:
```bash
mysql_config = {"host": "localhost",
"user": "user_name",
"password": "user_password",
"database": "database_name"
}
```
#### 3. Start MySQL service
Different platforms have different startup methods. For details, see [Getting Started with MySQL](https://dev.mysql.com/doc/mysql-getting-started/en/).
### <span style="font-size:larger;">III.</span> Initialize the quantum computing resource virtualization database
> ⚠️<span style="color:#8B0000"> **Warning**</span>
> If this is your first time installing QSteed, please make sure to perform the following database initialization steps after the installation is complete.
After the MySQL service starts and the `config.ini` file is configured,
initialize the quantum computing resource virtualization database by running the following command:
```python
from qsteed.first_build_db import first_build_db
first_build_db()
```
or run the following command in the terminal:
```bash
qsteed-build-db
```
### <span style="font-size:larger;">IV.</span> Configure quantum chip information
#### 1. Add a chip
Open the configuration file `config.ini` in the QSteed folder.
In section `[Chips]`, add your chip's basic information.
For example, to add a chip named `"example"`, use the following format:
```bash
example = {"name": "example",
"qubit_num": 10,
"system_id": 0,
"basis_gates": ["cx", "ry", "rz", "rx", "h", "id"]
}
```
#### 2. Add the chip's size information
Add the chip's size information (embed the qubits into a two-dimensional grid)
in the `chips_shape` property of section `[ChipsShape]`. Please keep the following format:
```bash
chips_shape = {
"example": {"dimension": 1, "row": 1, "column": 10},
}
```
#### 3. Add the mapping of the chip's name and ID.
Add the mapping in the `system_id_name` and `system_name_id` property of section `[Systems]`. Please keep the following format:
```bash
system_id_name = {0: "example",}
system_name_id = {"example": 0,}
```
For more examples of chip configuration, see the file [config.ini](qsteed/config/config.ini).
### <span style="font-size:larger;">V.</span> Build or update database
We can build the quantum computing resource virtualization database
from the chip's json data file or the chip's information dictionary.
```python
from qsteed.apis.resourceDB_api import update_chip_api
import json
chip_file = 'chipexample.json'
with open(chip_file, 'r') as file:
data_dict = json.load(file)
update_chip_api('example', data_dict)
```
For the data structure of the chip, see file [chipexample.json](tests/chipexample.json) or
[dongling.json](tests/dongling.json).
## Real quantum device deployment cases
QSteed has been successfully deployed to the [Quafu Quantum Cloud Computing Cluster](https://quafu.baqis.ac.cn/),
supporting the compilation and optimization of user tasks into quantum circuits
executable by quantum processors.
You can submit tasks through the [Quafu Composer](https://quafu.baqis.ac.cn/#/composer) web interface,
[Pyquafu](https://scq-cloud.github.io/) client,
or [QuarkStudio](https://www.yuque.com/wuming-6g8w2/ghzgfk/azika5xqlpxig3q3?singleDoc#) client.
If you want to learn more about real quantum device deployment or customize a deployment plan, please contact us.
## More Tests
See [tests](tests) for more examples.
## How to contribute
For information on how to contribute, please send an e-mail to members of developer of this project.
QSteed was developed by the quantum operating system team of the Beijing Academy of Quantum Information Sciences.
## License
QSteed is released under the Apache 2.0 license. See [LICENSE](LICENSE) for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/BAQIS-Quantum/QSteed",
"name": "qsteed",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "qsteed, quantum compiling, quantum computing, quantum operating system",
"author": "Xuhongze",
"author_email": "Xuhongze <xhzby1995@163.com>",
"download_url": "https://files.pythonhosted.org/packages/65/9a/53e83066dd27e5597a290d33b199ebc911a9468b115e68f5943028923b80/qsteed-0.2.2.tar.gz",
"platform": null,
"description": "# QSteed\n\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/BAQIS-Quantum/qsteed/releases)\n\n[](https://pypi.org/project/qsteed/)\n\n[//]: # ()\n\n\n**QSteed** is a **Q**uantum **S**of**t**war**e** of \nCompilation for supporting R**e**al Quantum **d**evice, \nincluding a quantum compiler, a quantum resource \nvirtualization manager, and a task scheduler.\n\n## Installation\n\n### Need to install [pyquafu](https://github.com/ScQ-Cloud/pyquafu)\n```bash\npip install 'pyquafu>=0.4.1'\n```\n### Install from PyPI\nYou can install QSteed via pip:\n```bash\npip install qsteed\n```\n\n### Install from source\nYou can directly download the [source code](https://github.com/BAQIS-Quantum/qsteed/archive/refs/heads/master.zip) from GitHub\nor clone the repository using the following command.\n```bash\ngit clone https://github.com/BAQIS-Quantum/QSteed.git\n```\nChange to the qsteed directory install using the following command:\n```bash\npip install -r requirements.txt\npython setup.py install # or: pip install .\n```\n\n## Example\n### Quantum circuit transpiler\nTo use only the quantum circuit transpiler, you can refer to the following examples.\nThe following code demonstrates how to customize hardware backend properties and customize the compilation process.\n```python\nimport matplotlib.pyplot as plt\nfrom qsteed import *\n\n# Generating random quantum circuits (needs to be a pyquafu QuantumCircuit class)\nrqc = RandomCircuit(num_qubit=5, gates_number=100, gates_list=['cx', 'rx', 'rz', 'ry', 'h'])\nqc = rqc.random_circuit()\n\n# Set chip information (the number of chip qubits needs to be consistent\n# with the number of quantum circuit qubits)\nbasis_gates = ['cx', 'rx', 'ry', 'rz', 'id', 'h']\nc_list = [(2, 3, 0.982), (3, 2, 0.982), (3, 4, 0.973), (4, 3, 0.973), \n (0, 1, 0.98), (1, 0, 0.98), (1, 2, 0.97), (2, 1, 0.97)]\nbackend_properties = {\n 'name': 'ExampleBackend',\n 'backend_type': 'superconducting',\n 'qubits_num': 5,\n 'coupling_list': c_list,\n 'basis_gates': basis_gates,\n}\n\n# Predefined compilation passflow\npasses = [\n UnrollTo2Qubit(),\n SabreLayout(heuristic='fidelity', max_iterations=3), # heuristic='distance' or 'fidelity', 'mixture'\n UnrollToBasis(basis_gates=basis_gates),\n GateCombineOptimization(),\n OneQubitGateOptimization()\n]\npassflow = PassFlow(passes=passes)\n\nbackend_instance = Backend(**backend_properties)\ninitial_model = Model(backend=backend_instance)\n\ntranspiler = Transpiler(passflow, initial_model)\ntranspiled_circuit = transpiler.transpile(qc)\ntranspiled_circuit.plot_circuit()\nplt.show()\n```\n\nYou can also use preset compilation passflow with optimization_level 0-3:\nUsing preset compilation passflow, see [preset_passflow.py](qsteed/passflow/preset_passflow.py)\n```python\ntranspiler = Transpiler(initial_model=initial_model)\ntranspiled_circuit = transpiler.transpile(qc, optimization_level=3)\n```\n\n### Quantum Compiler\n> \u26a0\ufe0f<span style=\"color:#8B0000\"> **Warning**</span> \n> The quantum compiler requires MySQL database support, see section [Deployment](#deployment).\n\nUsing the `Compiler`, you can compile quantum circuits onto a real quantum chip.\n```python\nfrom qsteed.compiler.compiler import Compiler\n\nqasm = \"\"\"\nOPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[5];\ncreg meas[5];\nrxx(2.7757800154614016) q[3],q[2];\nz q[2];\nh q[3];\nrxx(5.893149917736792) q[2],q[0];\ncx q[4],q[1];\nx q[1];\ny q[4];\nx q[4];\nmeasure q[0] -> meas[0];\nmeasure q[1] -> meas[1];\nmeasure q[2] -> meas[2];\nmeasure q[3] -> meas[3];\nmeasure q[4] -> meas[4];\n\"\"\"\n\n# If 'qpu_name' is not given, the most suitable computing resource for the task is searched on all available chips. \ncompiler = Compiler(qasm, qpu_name='example')\ncompiled_openqasm, final_q2c, compiled_circuit_information = compiler.compile()\n```\n\nMore convenient to use `compiler_api`, user tasks can be compiled onto available quantum computing resources.\nIf deployed on a real machine, users can submit a task information dictionary, \nand by invoking the compilation interface, the compiled results will be sent to \nthe quantum computer\u2019s measurement and control device for computation.\n```python\nfrom qsteed.apis.compiler_api import call_compiler_api\n\n# Assume you can obtain the user's task information and store it as task_info. \ntask_info = {\n \"circuit\": qasm,\n \"transpile\": True,\n \"qpu_name\": 'example',\n \"optimization_level\": 2,\n \"task_type\": 'qc',\n}\ncompiled_info = call_compiler_api(**task_info)\nprint('Compiled openqasm:\\n', compiled_info[0])\nprint('Measurement qubits to cbits:\\n', compiled_info[1])\nprint('Compiled circuit information:\\n', compiled_info[2])\n```\n\n\n## Deployment\n### <span style=\"font-size:larger;\">I.</span> Copy the configuration file\nFor convenience, you can run the following command to place the configuration file\n`config.ini` in the `QSteed` folder at the root directory, \n```python\nfrom qsteed.qsteed_config import copy_config\ncopy_config()\n```\nor run the following command in the terminal:\n```bash\nqsteed-config\n```\nYou can also manually copy the `config.ini` to the `~\\QSteed` directory.\n\n### <span style=\"font-size:larger;\">II.</span> Configure MySQL Service\n#### 1. Install MySQL. \nYou can download the appropriate [MySQL Community Server](https://dev.mysql.com/downloads/mysql/) from the MySQL official website.\nFor detailed installation instructions, see the official [documentation](https://dev.mysql.com/doc/refman/8.4/en/installing.html).\n\n#### 2. Set MySQL user information\n[//]: # (After installing QSteed, a folder named `QSteed` will be created in the root directory. )\n[//]: # (Inside this folder, there is a configuration file called `config.ini`. )\nOpen the configuration file `config.ini` and enter your MySQL user information into the `mysql_config` property under section `[MySQL]`.\nPlease keep the following format:\n```bash\nmysql_config = {\"host\": \"localhost\",\n \"user\": \"user_name\",\n \"password\": \"user_password\",\n \"database\": \"database_name\"\n }\n```\n\n#### 3. Start MySQL service\nDifferent platforms have different startup methods. For details, see [Getting Started with MySQL](https://dev.mysql.com/doc/mysql-getting-started/en/).\n\n\n### <span style=\"font-size:larger;\">III.</span> Initialize the quantum computing resource virtualization database\n\n> \u26a0\ufe0f<span style=\"color:#8B0000\"> **Warning**</span> \n> If this is your first time installing QSteed, please make sure to perform the following database initialization steps after the installation is complete.\n\nAfter the MySQL service starts and the `config.ini` file is configured, \ninitialize the quantum computing resource virtualization database by running the following command:\n```python\nfrom qsteed.first_build_db import first_build_db\nfirst_build_db()\n```\nor run the following command in the terminal:\n```bash\nqsteed-build-db\n```\n\n### <span style=\"font-size:larger;\">IV.</span> Configure quantum chip information\n#### 1. Add a chip\nOpen the configuration file `config.ini` in the QSteed folder. \nIn section `[Chips]`, add your chip's basic information. \nFor example, to add a chip named `\"example\"`, use the following format:\n```bash\nexample = {\"name\": \"example\",\n \"qubit_num\": 10,\n \"system_id\": 0,\n \"basis_gates\": [\"cx\", \"ry\", \"rz\", \"rx\", \"h\", \"id\"]\n }\n```\n\n#### 2. Add the chip's size information\nAdd the chip's size information (embed the qubits into a two-dimensional grid) \nin the `chips_shape` property of section `[ChipsShape]`. Please keep the following format:\n```bash\nchips_shape = {\n \"example\": {\"dimension\": 1, \"row\": 1, \"column\": 10},\n }\n```\n\n#### 3. Add the mapping of the chip's name and ID.\nAdd the mapping in the `system_id_name` and `system_name_id` property of section `[Systems]`. Please keep the following format:\n```bash\nsystem_id_name = {0: \"example\",}\nsystem_name_id = {\"example\": 0,}\n```\n\nFor more examples of chip configuration, see the file [config.ini](qsteed/config/config.ini).\n\n\n\n### <span style=\"font-size:larger;\">V.</span> Build or update database\nWe can build the quantum computing resource virtualization database\nfrom the chip's json data file or the chip's information dictionary.\n```python\nfrom qsteed.apis.resourceDB_api import update_chip_api\nimport json\nchip_file = 'chipexample.json'\nwith open(chip_file, 'r') as file:\n data_dict = json.load(file)\nupdate_chip_api('example', data_dict)\n```\nFor the data structure of the chip, see file [chipexample.json](tests/chipexample.json) or \n[dongling.json](tests/dongling.json).\n\n\n## Real quantum device deployment cases\nQSteed has been successfully deployed to the [Quafu Quantum Cloud Computing Cluster](https://quafu.baqis.ac.cn/), \nsupporting the compilation and optimization of user tasks into quantum circuits \nexecutable by quantum processors. \nYou can submit tasks through the [Quafu Composer](https://quafu.baqis.ac.cn/#/composer) web interface,\n[Pyquafu](https://scq-cloud.github.io/) client, \nor [QuarkStudio](https://www.yuque.com/wuming-6g8w2/ghzgfk/azika5xqlpxig3q3?singleDoc#) client.\n\nIf you want to learn more about real quantum device deployment or customize a deployment plan, please contact us.\n\n## More Tests\nSee [tests](tests) for more examples.\n\n\n## How to contribute\nFor information on how to contribute, please send an e-mail to members of developer of this project.\n\nQSteed was developed by the quantum operating system team of the Beijing Academy of Quantum Information Sciences.\n\n## License\nQSteed is released under the Apache 2.0 license. See [LICENSE](LICENSE) for more details.\n",
"bugtrack_url": null,
"license": "Apache-2.0 License",
"summary": "Quantum Software of Compilation for supporting Real Quantum device",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://github.com/BAQIS-Quantum/QSteed/wiki",
"Homepage": "https://github.com/BAQIS-Quantum/QSteed",
"Issues": "https://github.com/BAQIS-Quantum/QSteed/issues",
"Source": "https://github.com/BAQIS-Quantum/QSteed"
},
"split_keywords": [
"qsteed",
" quantum compiling",
" quantum computing",
" quantum operating system"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "29a0140b77dfface8fbd0799f8655466dffbc1e3970211179e4388e8e99d88fe",
"md5": "0f0fcf680a22f154db095f0e321499c4",
"sha256": "3ea89192fb8f8e766d871f799cc45d5e6088a5e87eeee19d02c686c91881219d"
},
"downloads": -1,
"filename": "qsteed-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f0fcf680a22f154db095f0e321499c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 193520,
"upload_time": "2024-10-22T12:29:28",
"upload_time_iso_8601": "2024-10-22T12:29:28.610567Z",
"url": "https://files.pythonhosted.org/packages/29/a0/140b77dfface8fbd0799f8655466dffbc1e3970211179e4388e8e99d88fe/qsteed-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "659a53e83066dd27e5597a290d33b199ebc911a9468b115e68f5943028923b80",
"md5": "91de08660ab511c377289792f48c577f",
"sha256": "562674b6c230f29de3bea4558ba086dfc706d0bef71db33808a1cc8408ae4c89"
},
"downloads": -1,
"filename": "qsteed-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "91de08660ab511c377289792f48c577f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 113502,
"upload_time": "2024-10-22T12:29:30",
"upload_time_iso_8601": "2024-10-22T12:29:30.791156Z",
"url": "https://files.pythonhosted.org/packages/65/9a/53e83066dd27e5597a290d33b199ebc911a9468b115e68f5943028923b80/qsteed-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 12:29:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BAQIS-Quantum",
"github_project": "QSteed",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "dill",
"specs": [
[
">=",
"0.3.8"
]
]
},
{
"name": "ipython",
"specs": [
[
">=",
"8.14.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.2"
]
]
},
{
"name": "networkx",
"specs": [
[
">=",
"2.6.3"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.20.3"
],
[
"<",
"2.0.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"10.4.0"
]
]
},
{
"name": "graphviz",
"specs": [
[
">=",
"0.14.2"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.7.1"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.8.1"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "sqlalchemy",
"specs": [
[
">=",
"2.0.28"
]
]
},
{
"name": "flask",
"specs": [
[
">=",
"3.0.2"
]
]
},
{
"name": "pymysql",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "flask_sqlalchemy",
"specs": [
[
">=",
"3.1.1"
]
]
}
],
"lcname": "qsteed"
}
JSON
