bqskit-qfactor-jax 1.0.1

Description:

bqskitqfactorjax 1.0.1

QFactor and QFactor-Sample Implementations on GPUs Using JAX
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.
Installation
bqskit-qfactor-jax is available for Python 3.9+ on Linux. It can be installed using pip
pip install bqskit-qfactor-jax

If you are experiencing issues with JAX please refer to JAX's installation instructions.
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.
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.
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. You may initiate it using the command line
nvidia-cuda-mps-control -d

You can disable it by running this command line:
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.
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).
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 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.