# qgear
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
> paper link: https://arxiv.org/pdf/2504.03967
## 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>
___ ____ _____ _ ____
/ _ \ / ___| ____| / \ | _ \
| | | | | | _| _| / _ \ | |_) |
| |_| | | |_| | |___ / ___ \| _ <
\__\_\ \____|_____/_/ \_\_| \_\
Installation successful!
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
go to nbs/example.ipynb; run example
### 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
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/gzquse/qgear",
"name": "qgear",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "gzquse",
"author_email": "ziqinguse@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1b/aa/1585c494ca9c3d2c3b543ad914d9bebbcdf8bf841bdee18b8543917c9011/qgear-1.1.2.tar.gz",
"platform": null,
"description": "# qgear\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n> paper link: https://arxiv.org/pdf/2504.03967\n\n\n\n## Preliminary\n\n- Let\u2019s assume you already have a computational GPU node allocated on\n HPC\n- Checking the NVIDIA GPU\n - `nvidia-smi`\n- Create a env (we do not recommend using default such .local / HOME)\n- Note that more than one GPU support need to enable\n [MPI](https://nvidia.github.io/cuda-quantum/latest/using/quick_start.html#install-cuda-q)\n \\> the way we choose is high performance lustre file system\n\n## 1. Install ENV\n\nclone repo\n\n``` bash\ngit clone git@github.com:gzquse/qgear.git`\n\ncd qgear\n```\n\n``` bash\nmodule load conda\nconda create --prefix=/pscratch/sd/{location}/{username}/qgear -y python=3.11 pip\nconda activate $SCRATCH/qgear\n```\n\n``` bash\npip install -u qgear \npip install -u ipykernel\npython -m ipykernel install --user --name qgear --display-name qgear\n```\n\ntest qgear install successfully\n\n``` bash\nqgear\n```\n\n<p align=\"center\">\n\n<pre>\n ___ ____ _____ _ ____ \n / _ \\ / ___| ____| / \\ | _ \\ \n | | | | | | _| _| / _ \\ | |_) | \n | |_| | | |_| | |___ / ___ \\| _ < \n \\__\\_\\ \\____|_____/_/ \\_\\_| \\_\\ \n \nInstallation successful!\n Welcome to QGEAR. Run 'qgear.run_cudaq()' to speed up.\nFun fact: We love to use Emacs! \ud83d\udc27\n</pre>\n\n</p>\n\n## 2. Open Jupyter Notebook\n\n### NERSC jupyter\n\nhttps://jupyter.nersc.gov/\n\nSelect the kernel\n\n\ngo to nbs/example.ipynb; run example\n\n\n### Pypi\n\nhttps://pypi.org/project/qgear/\n\n### Demos\n\n#### 1. simple speed up with random circuit and QFT\n\nhttps://gzquse.github.io/qgear/examples.html\n\n#### 2. quantum image encoding\n\n> see appendix F in the paper https://gzquse.github.io/qgear/apps.html\n\n\n\n## local development\n\n``` sh\n. ./pm_martin.dev.source\n\n# make sure qgear package is installed in development mode\nhttps://nbdev.fast.ai/tutorials/tutorial.html\npip3 install -e '.[dev]'\npip3 install qgear\n\n# compile to have changes apply to qgear\nnbdev_prepare\n```\n\n### Supported Quantum Gates\n\nThis is the list of quantum gates currently supported by the\nimplementation, based on the `gateId` mapping.\n\n| Gate ID | Gate Name | Description | Parameters | Example Usage |\n|----|----|----|----|----|\n| **1** | **H** (Hadamard) | Creates superposition by mapping ( | 0) and ( | 1). |\n| **2** | **RY** rotation | Rotation around the Y-axis by a given angle. | `angle` (in radians), target qubit `q0` | `ry(angles[j], q0)` |\n| **3** | **RZ** rotation | Rotation around the Z-axis by a given angle. | `angle` (in radians), target qubit `q0` | `rz(angles[j], q0)` |\n| **4** | **CX** (CNOT) | Controlled-X gate; flips target qubit if control qubit is ( | 1). | Control qubit `q0`, target qubit `q1` |\n| **5** | **Measure** | Measures the qubit in the computational basis. | Target qubit `q0` | `mz(q0)` *(example)* |\n| **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` |\n| **7** | **SWAP** | Swaps the quantum states of two qubits. | Qubit `q0`, qubit `q1` | `swap(q0, q1)` |\n| **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)` |\n\n------------------------------------------------------------------------\n\n## Notes\n\n- `q0` is the **primary target qubit**.\n- `q1` is an **additional target or control qubit** (depending on the\n gate).\n- `angles` is an array of rotation parameters in **radians**.\n- `gate_type` and `qvector` are used to determine qubit mapping for\n multi-qubit gates.\n- The **U3 gate** is the most general single-qubit gate and can\n represent any rotation.\n\n------------------------------------------------------------------------\n\n## Example Gate Sequence\n\n\\`\\`\\`python \\# Apply Hadamard to qubit 0 h(q0)\n\n# Rotate qubit 0 around Y-axis by pi/4\n\nry(math.pi/4, q0)\n\n# Apply CNOT from qubit 0 to qubit 1\n\nx.ctrl(q0, q1)\n\n# Apply a controlled-phase gate\n\nr1.ctrl(math.pi/2, q0, q1)\n\n# Swap qubits 0 and 1\n\nswap(q0, q1)\n\n# Apply a general U3 rotation\n\nu3(theta, phi, lambda\\_, q0)\n\n### Goal\n\nbuild the versatile all-in-one quantum accelerator for HPC-QPU hybrid\nregime that supports all the mainstream quantum frameworks.\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Q-Gear",
"version": "1.1.2",
"project_urls": {
"Homepage": "https://github.com/gzquse/qgear"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d44dcc71eec6a0b76780193ffb26a5bde2478e636876ff4f4328922e6df95948",
"md5": "bb5dfc46e391bebce48b3b646519b464",
"sha256": "dd1246e027d2457fb109526ae6e30e50bed89c97f6e89d335c92892ea3a22b59"
},
"downloads": -1,
"filename": "qgear-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb5dfc46e391bebce48b3b646519b464",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 442875,
"upload_time": "2025-08-28T03:28:02",
"upload_time_iso_8601": "2025-08-28T03:28:02.511829Z",
"url": "https://files.pythonhosted.org/packages/d4/4d/cc71eec6a0b76780193ffb26a5bde2478e636876ff4f4328922e6df95948/qgear-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1baa1585c494ca9c3d2c3b543ad914d9bebbcdf8bf841bdee18b8543917c9011",
"md5": "9a208912d86dd2a6585d67c2c05571bb",
"sha256": "0df328aa1d33710a912b8af004dbbbf5d3be5bf0b841be48d3214dc7af422a91"
},
"downloads": -1,
"filename": "qgear-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "9a208912d86dd2a6585d67c2c05571bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 405143,
"upload_time": "2025-08-28T03:28:04",
"upload_time_iso_8601": "2025-08-28T03:28:04.059998Z",
"url": "https://files.pythonhosted.org/packages/1b/aa/1585c494ca9c3d2c3b543ad914d9bebbcdf8bf841bdee18b8543917c9011/qgear-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 03:28:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gzquse",
"github_project": "qgear",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "qgear"
}
JSON
