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 notebook
• QSCOUT-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, and tutorial 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

Apache 2.0

Questions?

For help and support, please contact qscout@sandia.gov.