bqskit-qfactor-jax is a Python package that implements circuit instantiation using the QFactor and QFactor-Sample algorithms on GPUs to accelerate BQSKit. It uses JAX as an abstraction layer of the GPUs, seamlessly utilizing JIT compilation and GPU parallelism. You may refer the GPU cluster guide for detailed information on how to utilize this package on a node with several GPUs or on a GPU cluster.
bqskit-qfactor-jax is available for Python 3.9+ on Linux. It can be installed using pip
pip install bqskit-qfactor-jaxIf you are experiencing issues with JAX please refer to JAX's installation instructions.
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.
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 for a more detailed usage, especially at performance comparison between QFactor and QFactor-Sample.
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. You may initiate it using the command line
nvidia-cuda-mps-control -dYou can disable it by running this command line:
echo quit | nvidia-cuda-mps-controlIf 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.
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 (2024).
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 file for more information.
Quantum Fast Circuit Optimizer (QFactor) JAX implementation Copyright (c) 2024, U.S. Federal Government and the Government of Israel. All rights reserved.