Catalyst is officially supported on Linux (x86_64) and macOS (aarch64, x86_64) platforms, and
pre-built binaries are being distributed via the Python Package Index (PyPI) for Python versions
3.9 and higher. To install it, simply run the following
pip install pennylane-catalyst
macOS does not ship with a system compiler by default, which Catalyst depends on. Please
ensure that `XCode <https://developer.apple.com/xcode/resources/`_ or the
XCode Command Line Tools are installed on your system before using Catalyst.
The easiest method of installation is to run
xcode-select --install from the Terminal
Pre-built packages for Windows are not yet available, and comptability with other platforms is untested and cannot be guaranteed. If you are using one of these platforms, please try out our Docker and Dev Container images described in the next section.
If you wish to contribute to Catalyst or develop against our runtime or compiler, instructions for building from source are also included further down.
Try out Catalyst in self-contained, ready-to-go environments called Dev Containers:
If desired, the Docker images can also be used in a standalone fashion:
The user image provides an officially supported enviroment and automatically installs the latest
release of Catalyst. The developer image only provides the right enviroment to build Catalyst from
source, and requires launching the post-install script at
from whithin the root of the running container.
Due to a bug in the Dev Containers extension, clicking on the “Launch” badge will not prompt for a choice between the User and Dev containers. Instead, the User container is automatically chosen.
As a workaround, you can clone the Catalyst repository
first, open it as a VS Code Workspace, and then reopen the Workspace in a Dev Container via the
Reopen in Container command.
Building from source¶
To build Catalyst from source, developers should follow the instructions provided below for building all three modules: the Python frontend, the MLIR compiler, and the runtime library.
In order to build Catalyst from source, developers need to ensure the following pre-requisites are installed and available on the path (depending on the platform):
Python 3.9 or higher for the Python frontend.
The Python package manager
pipmust be version 22.3 or higher.
They can be installed on Debian/Ubuntu via:
sudo apt install clang lld ccache libomp-dev ninja-build make cmake
If the CMake version available in your system is too old, you can also install up-to-date
versions of it via
pip install cmake.
On macOS, it is strongly recommended to install the official XCode Command Line Tools
make). The remaining packages can then be installed via
pip install cmake ninja
If you install Catalyst on a macOS system with
ARM architecture (e.g. Apple M1/M2), you
additionally need to install Rust and the
llvm-tools-preview rustup component:
curl https://sh.rustup.rs -sSf | sh source "$HOME/.cargo/env" rustup component add llvm-tools-preview
All additional build and developer dependencies are managed via the repository’s
requirements.txt and can be installed as follows:
pip install -r requirements.txt
Please ensure that your local site-packages for Python are available on the
PATH - watch out
for the corresponding warning that
pip may give you during installation.
Once the pre-requisites are installed, start by cloning the project repository including all its submodules:
git clone --recurse-submodules --shallow-submodules https://github.com/PennyLaneAI/catalyst.git
For an existing copy of the repository without its submodules, they can also be fetched via:
git submodule update --init --depth=1
The build process for Catalyst is managed via a series of Makefiles for each component. To build the entire project from start to finish simply run the following make target from the top level directory:
To build each component one by one starting from the runtime, or to build additional backend devices
lightning.qubit, please follow the instructions below.
By default, the runtime builds and installs the PennyLane-Lightning simulator device, which requires C++20 standard library features. Older C++ compilers may not support this, so it is recommended to use a modern compiler with these features. An additional dependency, the QIR standard library, is automatically fetched and built on supported platforms.
From the root project directory, the runtime can then be built as follows:
Additional devices are constantly added, enabling the execution of quantum circuits on CPUs, GPUs, and remote services, such as Amazon Braket. The full list of supported backends, and additional configuration options, are available in the Catalyst Runtime page.
To install Catalyst with all available backends, simply run:
make runtime ENABLE_LIGHTNING_KOKKOS=ON ENABLE_OPENQASM=ON
You can also choose to build the custom Catalyst dialects only, with:
To install the
pennylane-catalyst Python package (the compiler frontend) in editable mode:
After following the instructions above, no configuration of environment variables should be required. However, if you are building Catalyst components in custom locations, you may need to set and update a few variables on your system by adjusting the paths in the commands below accordingly.
To make the MLIR bindings from the Catalyst dialects discoverable to the compiler:
To make runtime libraries discoverable to the compiler:
To make MLIR libraries discoverable to the compiler:
To make Enzyme libraries discoverable to the compiler:
To make required tools in
mlir/build discoverable to the compiler:
The following target runs all available test suites with the default execution device in Catalyst:
You can also test each module separately by using running the
test-runtime targets instead. Jupyter Notebook demos are also testable
Additional Device Backends¶
The runtime tests can be run on additional devices via the same flags that were used to build
them, but using the
test-runtime target instead:
make test-runtime ENABLE_LIGHTNING_KOKKOS=ON ENABLE_OPENQASM=ON
test-runtime targets rebuilds the runtime with the specified flags. Therefore,
make runtime OPENQASM=ON and
make test-runtime in succession will leave you
without the OpenQASM device installed.
In case of errors it can also help to delete the build directory.
The Python test suite is also set up to run with different device backends. Assuming the respective device is available & compatible, they can be tested individually by specifying the PennyLane plugin device name in the test command:
make pytest TEST_BACKEND="lightning.kokkos"
AWS Braket devices have their own set of tests, which can be run either locally (
LOCAL) or on
the AWS Braket service (
REMOTE) as follows:
make pytest TEST_BRAKET=LOCAL
To build and test documentation for Catalyst, you will need to install
sphinx and other packages listed in
pip install -r doc/requirements.txt
On Debian/Ubuntu, they can be installed via:
sudo apt install doxygen pandoc
On macOS, homebrew is the easiest way to install these packages:
brew install doxygen pandoc