# QFactor and QFactor-Sample Implementations on GPUs Using JAX
`bqskit-qfactor-jax` is a Python package that implements circuit instantiation using the [QFactor](https://ieeexplore.ieee.org/abstract/document/10313638) and [QFactor-Sample](https://arxiv.org/abs/2405.12866) algorithms on GPUs to accelerate [BQSKit](https://github.com/bqskit/bqskit). It uses [JAX](https://jax.readthedocs.io/en/latest/index.html) as an abstraction layer of the GPUs, seamlessly utilizing JIT compilation and GPU parallelism.
## Installation
`bqskit-qfactor-jax` is available for Python 3.9+ on Linux. It can be installed using pip
```sh
pip install bqskit-qfactor-jax
```
If you are experiencing issues with JAX please refer to JAX's [installation instructions](https://github.com/google/jax#installation).
## Basic Usage
QFactor and QFactor-Sample are instantiation algorithms that, given a unitary matrix and a parameterized circuit, optimize the circuit parameters to best approximate the target unitary matrix.
```python
import numpy as np
from bqskit import Circuit
from bqskit.ir.gates import VariableUnitaryGate
from bqskit.qis.unitary import UnitaryMatrix
from qfactorjax.qfactor_sample_jax import QFactorSampleJax
# Load a circuit from QASM
circuit = Circuit.from_file("template.qasm")
# Load the target unitary
unitary_target = UnitaryMatrix.from_file("target.mat")
# Create the instantiator object
qfactor_sample_gpu_instantiator = QFactorSampleJax()
# Perform the instantiation
circuit.instantiate(
unitary_target,
multistarts=16,
method=qfactor_sample_gpu_instantiator,
)
# Calculate and print final distance
dist = circuit.get_unitary().get_distance_from(unitary_target, 1)
print('Final Distance: ', dist)
```
Please look at the [examples](https://github.com/BQSKit/bqskit-qfactor-jax/tree/main/examples) for a more detailed usage, especially at performance comparison between QFactor and QFactor-Sample.
## GPU Configuration and Memory Management
Please set the environment variable XLA_PYTHON_CLIENT_PREALLOCATE=False when using this package. Also, if you encounter OOM issues consider setting XLA_PYTHON_CLIENT_ALLOCATOR=platform.
When using several workers on the same GPU, we recommend using [Nvidia's MPS](https://docs.nvidia.com/deploy/mps/index.html). You may initiate it using the command line
```sh
nvidia-cuda-mps-control -d
```
You can disable it by running this command line:
```sh
echo quit | nvidia-cuda-mps-control
```
## References
If you are using QFactor please cite:\
Kukliansky, Alon, et al. "QFactor: A Domain-Specific Optimizer for Quantum Circuit Instantiation." 2023 IEEE International Conference on Quantum Computing and Engineering (QCE). Vol. 1. IEEE, 2023. [Link](https://ieeexplore.ieee.org/abstract/document/10313638).
If you are using QFactor-Sample please cite:\
Kukliansky, Alon, et al. "Leveraging Quantum Machine Learning Generalization to Significantly Speed-up Quantum Compilation" arXiv preprint [arXiv:2405.12866](https://arxiv.org/abs/2405.12866) (2024).
## License
The software in this repository is licensed under a **BSD free software
license** and can be used in source or binary form for any purpose as long
as the simple licensing requirements are followed. See the
**[LICENSE](https://github.com/BQSKit/bqskit-qfactor-jax/blob/main/LICENSE)** file
for more information.
## Copyright
Quantum Fast Circuit Optimizer (QFactor) JAX implementation Copyright (c) 2024,
U.S. Federal Government and the Government of Israel. All rights reserved.
Raw data
{
"_id": null,
"home_page": "https://github.com/BQSKit/bqskit-qfactor-jax",
"name": "bqskit-qfactor-jax",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "bqskit quantum partitioning qfactor instantiation",
"author": "Alon Kukliansky",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8c/21/4becdbd7a4e8bbecccb2d176764061dfa5178443c6cc56a4091de49b7d4a/bqskit_qfactor_jax-1.0.1.tar.gz",
"platform": null,
"description": "# QFactor and QFactor-Sample Implementations on GPUs Using JAX\n`bqskit-qfactor-jax` is a Python package that implements circuit instantiation using the [QFactor](https://ieeexplore.ieee.org/abstract/document/10313638) and [QFactor-Sample](https://arxiv.org/abs/2405.12866) algorithms on GPUs to accelerate [BQSKit](https://github.com/bqskit/bqskit). It uses [JAX](https://jax.readthedocs.io/en/latest/index.html) as an abstraction layer of the GPUs, seamlessly utilizing JIT compilation and GPU parallelism.\n\n## Installation\n`bqskit-qfactor-jax` is available for Python 3.9+ on Linux. It can be installed using pip\n\n```sh\npip install bqskit-qfactor-jax\n```\n\nIf you are experiencing issues with JAX please refer to JAX's [installation instructions](https://github.com/google/jax#installation).\n\n\n## Basic Usage\nQFactor and QFactor-Sample are instantiation algorithms that, given a unitary matrix and a parameterized circuit, optimize the circuit parameters to best approximate the target unitary matrix.\n\n```python\nimport numpy as np\nfrom bqskit import Circuit\nfrom bqskit.ir.gates import VariableUnitaryGate\nfrom bqskit.qis.unitary import UnitaryMatrix\n\nfrom qfactorjax.qfactor_sample_jax import QFactorSampleJax\n\n\n\n# Load a circuit from QASM\ncircuit = Circuit.from_file(\"template.qasm\")\n\n# Load the target unitary\nunitary_target = UnitaryMatrix.from_file(\"target.mat\")\n\n# Create the instantiator object\nqfactor_sample_gpu_instantiator = QFactorSampleJax()\n\n# Perform the instantiation\ncircuit.instantiate(\n unitary_target,\n multistarts=16,\n method=qfactor_sample_gpu_instantiator,\n )\n\n# Calculate and print final distance\ndist = circuit.get_unitary().get_distance_from(unitary_target, 1)\n\nprint('Final Distance: ', dist)\n```\n\nPlease look at the [examples](https://github.com/BQSKit/bqskit-qfactor-jax/tree/main/examples) for a more detailed usage, especially at performance comparison between QFactor and QFactor-Sample.\n\n\n## GPU Configuration and Memory Management\nPlease set the environment variable XLA_PYTHON_CLIENT_PREALLOCATE=False when using this package. Also, if you encounter OOM issues consider setting XLA_PYTHON_CLIENT_ALLOCATOR=platform.\n\n\nWhen using several workers on the same GPU, we recommend using [Nvidia's MPS](https://docs.nvidia.com/deploy/mps/index.html). You may initiate it using the command line\n```sh\nnvidia-cuda-mps-control -d\n```\n\nYou can disable it by running this command line:\n```sh\necho quit | nvidia-cuda-mps-control\n```\n\n## References\nIf you are using QFactor please cite:\\\nKukliansky, Alon, et al. \"QFactor: A Domain-Specific Optimizer for Quantum Circuit Instantiation.\" 2023 IEEE International Conference on Quantum Computing and Engineering (QCE). Vol. 1. IEEE, 2023. [Link](https://ieeexplore.ieee.org/abstract/document/10313638).\n\nIf you are using QFactor-Sample please cite:\\\nKukliansky, Alon, et al. \"Leveraging Quantum Machine Learning Generalization to Significantly Speed-up Quantum Compilation\" arXiv preprint [arXiv:2405.12866](https://arxiv.org/abs/2405.12866) (2024).\n\n## License\nThe software in this repository is licensed under a **BSD free software\nlicense** and can be used in source or binary form for any purpose as long\nas the simple licensing requirements are followed. See the\n**[LICENSE](https://github.com/BQSKit/bqskit-qfactor-jax/blob/main/LICENSE)** file\nfor more information.\n\n## Copyright\n\nQuantum Fast Circuit Optimizer (QFactor) JAX implementation Copyright (c) 2024,\nU.S. Federal Government and the Government of Israel. All rights reserved.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "QFactor GPU implementation in BQSKit using JAX",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/BQSKit/bqskit-qfactor-jax/issues",
"Documentation": "https://bqskit.readthedocs.io/en/latest",
"Homepage": "https://github.com/BQSKit/bqskit-qfactor-jax",
"Source Code": "https://github.com/BQSKit/bqskit-qfactor-jax"
},
"split_keywords": [
"bqskit",
"quantum",
"partitioning",
"qfactor",
"instantiation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d0e1db3655d85f911bfdbbf3a9295f1bd7732abcdc932b437ce4ce0386b798c0",
"md5": "8d3afe601f2821af65e3ccea6ecd2ba6",
"sha256": "39e1958d4b50f4b5ef100db6102bb5860d7ba053cada215430383cf7e7fe0647"
},
"downloads": -1,
"filename": "bqskit_qfactor_jax-1.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d3afe601f2821af65e3ccea6ecd2ba6",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "<4,>=3.9",
"size": 24200,
"upload_time": "2024-09-16T16:26:05",
"upload_time_iso_8601": "2024-09-16T16:26:05.101975Z",
"url": "https://files.pythonhosted.org/packages/d0/e1/db3655d85f911bfdbbf3a9295f1bd7732abcdc932b437ce4ce0386b798c0/bqskit_qfactor_jax-1.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8c214becdbd7a4e8bbecccb2d176764061dfa5178443c6cc56a4091de49b7d4a",
"md5": "9b13a3dec87a4423434d33c99d41d181",
"sha256": "43e26a59bd3277e3e36bed62c9c1f4d408b3e4bd203b016416cb32c5b46c2cae"
},
"downloads": -1,
"filename": "bqskit_qfactor_jax-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9b13a3dec87a4423434d33c99d41d181",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 21136,
"upload_time": "2024-09-16T16:26:06",
"upload_time_iso_8601": "2024-09-16T16:26:06.359356Z",
"url": "https://files.pythonhosted.org/packages/8c/21/4becdbd7a4e8bbecccb2d176764061dfa5178443c6cc56a4091de49b7d4a/bqskit_qfactor_jax-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-16 16:26:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BQSKit",
"github_project": "bqskit-qfactor-jax",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bqskit-qfactor-jax"
}
JSON
