Metadata-Version: 2.4
Name: qsteed
Version: 0.2.3
Summary: Quantum Software of Compilation for supporting Real Quantum device
Home-page: https://github.com/BAQIS-Quantum/QSteed
Author: Xuhongze
Author-email: Xuhongze <xhzby1995@163.com>
License: Apache-2.0 License
Project-URL: Homepage, https://github.com/BAQIS-Quantum/QSteed
Project-URL: Documentation, https://github.com/BAQIS-Quantum/QSteed/wiki
Project-URL: Source, https://github.com/BAQIS-Quantum/QSteed
Project-URL: Issues, https://github.com/BAQIS-Quantum/QSteed/issues
Keywords: qsteed,quantum compiling,quantum computing,quantum operating system
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dill>=0.3.8
Requires-Dist: ipython>=8.14.0
Requires-Dist: matplotlib>=3.5.2
Requires-Dist: networkx>=2.6.3
Requires-Dist: numpy<2.0.0,>=1.20.3
Requires-Dist: Pillow>=10.4.0
Requires-Dist: pyquafu==0.4.4
Requires-Dist: graphviz>=0.14.2
Requires-Dist: rich>=13.7.1
Requires-Dist: scipy>=1.8.1
Requires-Dist: tabulate>=0.9.0
Requires-Dist: sqlalchemy>=2.0.28
Requires-Dist: flask>=3.0.2
Requires-Dist: pymysql>=1.1.0
Requires-Dist: flask_sqlalchemy>=3.1.1
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# QSteed

[![License](https://img.shields.io/github/license/BAQIS-Quantum/qsteed.svg?)](https://opensource.org/licenses/Apache-2.0)
[![Current Release](https://img.shields.io/github/release/BAQIS-Quantum/qsteed.svg?)](https://github.com/BAQIS-Quantum/qsteed/releases)
![Python versions](https://img.shields.io/badge/python-%3E%3D%203.10-blue)
[![Downloads](https://img.shields.io/pypi/dm/qsteed.svg?)](https://pypi.org/project/qsteed/)

[//]: # (![PyPI - Python Version]&#40;https://img.shields.io/pypi/pyversions/qsteed&#41;)


**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

### Install from PyPI
You can install QSteed via pip:
```bash
python -m pip install qsteed
```

### Install from source
Clone the repository and install it from the project root:
```bash
git clone https://github.com/BAQIS-Quantum/QSteed.git
cd QSteed
python -m pip install .
```

For development, use editable mode:
```bash
python -m pip install -e .
```

## 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 device may contain more physical qubits than the
# circuit has logical qubits; SABRE will select an exact-size connected subgraph.
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,
        initial_layout_method='fidelity',  # 'random', 'fidelity', or 'dense'
    ),
    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 a resource database. QSteed supports SQLite or MySQL; 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 resource database
Open the configuration file `config.ini` and select the database backend in section `[Database]`.
The default configuration uses SQLite:
```bash
db_type = "sqlite"
sqlite_config = {"path": "~/QSteed/qsteed.db"}
```

To use MySQL instead, set:
```bash
db_type = "mysql"
```

#### 1. Install MySQL if using 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 if using MySQL
[//]: # (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 if using MySQL
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 database backend 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
```

If the SQLite database file, for example `~/QSteed/qsteed.db`, is deleted manually, the compiler cannot use it until
the resource database is rebuilt. Re-run the database initialization and chip update steps before calling
`Compiler` or `call_compiler_api`.

### <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/) and [Quafu Superconducting Quantum Computing](https://quafu-sqc.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 [quafusqc](https://quafu-sqc.readthedocs.io/en/latest/) 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.
