Metadata-Version: 2.1
Name: qgear
Version: 1.1.2
Summary: Q-Gear
Home-page: https://github.com/gzquse/qgear
Author: gzquse
Author-email: ziqinguse@gmail.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cudaq
Requires-Dist: fastcore
Requires-Dist: ffsim
Requires-Dist: h5py
Requires-Dist: huggingface-hub
Requires-Dist: ipywidgets
Requires-Dist: joblib
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: omegaconf
Requires-Dist: open-clip-torch
Requires-Dist: pillow
Requires-Dist: pyfiglet
Requires-Dist: pylatexenc
Requires-Dist: pynvml
Requires-Dist: qiskit
Requires-Dist: qiskit-addon-sqd
Requires-Dist: qiskit-ibm-runtime
Requires-Dist: qiskit-aer
Requires-Dist: rich
Requires-Dist: safetensors
Requires-Dist: scipy
Requires-Dist: tensordict
Requires-Dist: torch
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: jupyterlab ; extra == 'dev'
Requires-Dist: nbdev ; extra == 'dev'
Requires-Dist: pennylane ; extra == 'dev'

# qgear


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

> paper link: https://arxiv.org/pdf/2504.03967

![image.png](index_files/figure-commonmark/05381a41-1-image.png)

## Preliminary

- Let’s assume you already have a computational GPU node allocated on
  HPC
- Checking the NVIDIA GPU
  - `nvidia-smi`
- Create a env (we do not recommend using default such .local / HOME)
- Note that more than one GPU support need to enable
  [MPI](https://nvidia.github.io/cuda-quantum/latest/using/quick_start.html#install-cuda-q)
  \> the way we choose is high performance lustre file system

## 1. Install ENV

clone repo

``` bash
git clone git@github.com:gzquse/qgear.git`

cd qgear
```

``` bash
module load conda
conda create --prefix=/pscratch/sd/{location}/{username}/qgear -y python=3.11 pip
conda activate $SCRATCH/qgear
```

``` bash
pip install -u qgear 
pip install -u ipykernel
python -m ipykernel install --user --name qgear --display-name qgear
```

test qgear install successfully

``` bash
qgear
```

<p align="center">

<pre>
   ___     ____ _____    _    ____                                                      
  / _ \   / ___| ____|  / \  |  _ \                                                     
 | | | | | |  _|  _|   / _ \ | |_) |                                                    
 | |_| | | |_| | |___ / ___ \|  _ <                                                     
  \__\_\  \____|_____/_/   \_\_| \_\                                                    
&#10;
Installation successful!
&#10;Welcome to QGEAR. Run 'qgear.run_cudaq()' to speed up.
Fun fact: We love to use Emacs! 🐧
</pre>

</p>

## 2. Open Jupyter Notebook

### NERSC jupyter

https://jupyter.nersc.gov/

Select the kernel
![image.png](index_files/figure-commonmark/efeebc44-3-image.png)

go to nbs/example.ipynb; run example
![image-2.png](index_files/figure-commonmark/efeebc44-2-image-2.png)

### Pypi

https://pypi.org/project/qgear/

### Demos

#### 1. simple speed up with random circuit and QFT

https://gzquse.github.io/qgear/examples.html

#### 2. quantum image encoding

> see appendix F in the paper https://gzquse.github.io/qgear/apps.html

![image.png](index_files/figure-commonmark/efeebc44-1-f37fd8db-fa15-4b4a-989b-df3d7a05f0a5.png)

## local development

``` sh
. ./pm_martin.dev.source

# make sure qgear package is installed in development mode
https://nbdev.fast.ai/tutorials/tutorial.html
pip3 install -e '.[dev]'
pip3 install qgear

# compile to have changes apply to qgear
nbdev_prepare
```

### Supported Quantum Gates

This is the list of quantum gates currently supported by the
implementation, based on the `gateId` mapping.

| Gate ID | Gate Name | Description | Parameters | Example Usage |
|----|----|----|----|----|
| **1** | **H** (Hadamard) | Creates superposition by mapping ( | 0) and ( | 1). |
| **2** | **RY** rotation | Rotation around the Y-axis by a given angle. | `angle` (in radians), target qubit `q0` | `ry(angles[j], q0)` |
| **3** | **RZ** rotation | Rotation around the Z-axis by a given angle. | `angle` (in radians), target qubit `q0` | `rz(angles[j], q0)` |
| **4** | **CX** (CNOT) | Controlled-X gate; flips target qubit if control qubit is ( | 1). | Control qubit `q0`, target qubit `q1` |
| **5** | **Measure** | Measures the qubit in the computational basis. | Target qubit `q0` | `mz(q0)` *(example)* |
| **6** | **CP** (Controlled-Phase) | Applies a phase shift to the target qubit if control qubit is ( | 1). | `angle` (phase in radians), control qubit `q0`, target qubit `q1` |
| **7** | **SWAP** | Swaps the quantum states of two qubits. | Qubit `q0`, qubit `q1` | `swap(q0, q1)` |
| **8** | **U** (U3 gate) | General single-qubit rotation parameterized by three Euler angles. | `theta`, `phi`, `lambda_` (all in radians), target qubit `q0` | `u3(theta, phi, lambda_, q0)` |

------------------------------------------------------------------------

## Notes

- `q0` is the **primary target qubit**.
- `q1` is an **additional target or control qubit** (depending on the
  gate).
- `angles` is an array of rotation parameters in **radians**.
- `gate_type` and `qvector` are used to determine qubit mapping for
  multi-qubit gates.
- The **U3 gate** is the most general single-qubit gate and can
  represent any rotation.

------------------------------------------------------------------------

## Example Gate Sequence

\`\`\`python \# Apply Hadamard to qubit 0 h(q0)

# Rotate qubit 0 around Y-axis by pi/4

ry(math.pi/4, q0)

# Apply CNOT from qubit 0 to qubit 1

x.ctrl(q0, q1)

# Apply a controlled-phase gate

r1.ctrl(math.pi/2, q0, q1)

# Swap qubits 0 and 1

swap(q0, q1)

# Apply a general U3 rotation

u3(theta, phi, lambda\_, q0)

### Goal

build the versatile all-in-one quantum accelerator for HPC-QPU hybrid
regime that supports all the mainstream quantum frameworks.


