Python tools for Jaqal
Project description
JaqalPaq
JaqalPaq is a python package used to parse, manipulate, emulate, and generate quantum assembly code written in Jaqal (Just another quantum assembly language). JaqalPaq can be installed with optional transpilers that convert code written in other quantum assembly languages to a version of Jaqal whose native gates are relevant for QSCOUT (Quantum Scientific Computing Open User Testbed).
Code
JaqalPaq is available on GitLab under the Apache 2.0 License.
Installation
TLDR: Inside a venv/conda env:
pip install --upgrade Cython numpy pip wheel pip install ipykernel JaqalPaq'[pygsti-integration]' QSCOUT-gatemodels ipython kernel install --name=jaqal --user
Step 0: Prepare base dependencies
JaqalPaq requires Python 3.6 (or later), but Python 3.7 (or later) is recommended. To check your installed version, run
python3 --version
Windows users are encouraged to install under WSL2. You may also consider conda, which provides a platform-independent Python installation.
We also recommend having a functional C compiler and Python headers installed. Depending on your Python version and platform, this may be entirely unneccessary. You can confirm the presence of these headers by running
python3-config --includes
When properly configured, this will output a list of include directives that will be passed to your compiler, e.g.,
-I/usr/include/python3.6m
On apt-based systems, these dependencies can be installed by running (as root)
apt install python3-dev build-essential
On rpm-based ones,
yum install python3-devel gcc gcc-c++
Mac users may need to install XCode to ensure they have a functional C++ compiler. Similarly Windows users may need to install VS build tools.
Conda users should have these header files and compilers installed automatically.
Step 1: (recommended) Prepare a virtual environment
WARNING: JaqalPaq's dependencies may sometimes conflict with each other. Upgrading may introduce incompatible versions, and for this reason we STRONGLY recommend installing within some kind of virtual environment.
To create a Python virtual environment, run
python3 -m venv /path/to/venv
The location of the venv is left to your discretion, but please be aware that a full installation will be ~100s of megabytes.
To create a conda virtual environment, run
conda create --name your-preferred-name python=3.9
To enter the virtual environment, run
source /path/to/venv/bin/activate
or
conda activate your-preferred-name
respectively.
NOTE: All following steps should be performed inside the virtual environment. If you close your terminal, you will have to enter the virtual environment again, using the appropriate command above.
If you are using a venv, upgrade pip and install wheel:
pip install --upgrade pip wheel
Jupyter users can install a kernel to access this virtual environment by running
pip install ipykernel
ipython kernel install --name=preferred-name --user
NOTE: Restart the Jupyter server. A new kernel will be available.
If you no longer want that kernel, you can remove it with
jupyter kernelspec remove pip-jaqal
NOTE: Unlike every other command, this must be performed from the environment in which Jupyter is installed, and NOT the JaqalPaq environment.
Step 2: Install JaqalPaq and friends
JaqalPaq packages are provided with pip.
WARNING: Some dependencies may conflict with each other. Be sure to include all desired dependencies on this line. It is safe to re-run the whole command with a new desired feature set.
pip install JaqalPaq'[pygsti-integration,notebooks]' QSCOUT-gatemodels \
JaqalPaq-extras'[qiskit,pyquil,cirq,projectq,pytket,tutorial]'
pygsti-integration
provides the emulator.notebooks
installs all dependencies for the chemistry example notebookQSCOUT-gatemodels
provides the native gates of the QSCOUT project , which are modeled as pure-state preparations, unitary transformations, and destructive measurements. See QSCOUT-gatemodels for details.- The five transpiler targets for JaqalPaq-extras each install a compatible version of the respective third-party package.
tutorial
installs an additional dependency required for the JaqalPaq-extras tutorial notebook to run.
NOTE: The
notebooks
,qiskit
,pyquil
,cirq
,projectq
,pytket
, andtutorial
targets will install a large number of third-party packages. You should consider only installing the subset of these packages that you plan on using.
Usage
The following simple example is from examples/usage_example.py
import jaqalpaq
from jaqalpaq.parser import parse_jaqal_file
from jaqalpaq.emulator import run_jaqal_circuit
from jaqalpaq.generator import generate_jaqal_program
JaqalCircuitObject = parse_jaqal_file("jaqal/Sxx_circuit.jaqal")
JaqalCircuitResults = run_jaqal_circuit(JaqalCircuitObject)
print(f"Probabilities: {JaqalCircuitResults.subcircuits[0].probability_by_str}")
JaqalProgram = generate_jaqal_program(JaqalCircuitObject)
The Jaqal file processed by this example, examples/jaqal/Sxx_circuit.jaqal
, is
from qscout.v1.std usepulses *
register q[2]
prepare_all
Sxx q[1] q[0]
measure_all
More extensive examples, including detailed Jupyter notebooks implementing the
variational quantum eigensolver (VQE) quantum algorithm for some simple
molecules, can be found in the examples
directory.
For information on the JaqalPaq emulator's command-line interface, run the following in your shell:
jaqal-emulate --help
Testing and examples
Underneath your environment prefix, navigate to share/jaqalpaq
. Inside a
venv, run
cd "$VIRTUAL_ENV/share/jaqalpaq"
or, inside a conda environment,
cd "$CONDA_PREFIX/share/jaqalpaq"
Example Jaqal files, as well as tutorials and example quantum chemistry
calculations are in the examples/
directory. To run the tests, first
install pytest,
pip install pytest
and then run it on the tests/
directory:
pytest tests
Documentation
Online documentation is hosted on Read the Docs.
License
Questions?
For help and support, please contact qscout@sandia.gov.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.