Add support for Pennylane Lightning backend to QIR-EE

.github/workflows/build-fast.yml

@@ -1,4 +1,3 @@
-# Build directly on the GitHub runner with caching
 name: build-fast
 on:
   workflow_dispatch:
@@ -10,10 +9,10 @@ concurrency:
 
 jobs:
   linux:
-    name: ${{matrix.runner}}-${{matrix.compiler}}-${{matrix.version}}-llvm${{matrix.llvm}}
+    name: ${{matrix.build-config.runner}}-${{matrix.build-config.compiler}}-${{matrix.build-config.version}}-llvm${{matrix.build-config.llvm}}${{ matrix.use-lightning == true && '-lightning' || '' }}
     strategy:
       matrix:
-        include:
+        build-config:
           - runner: jammy
             compiler: gcc
             version: 12
@@ -22,43 +21,65 @@ jobs:
             compiler: clang
             version: 15
             llvm: 15
+        use-lightning: [false, true]
     runs-on: >-
-      ${{  matrix.runner == 'focal' && 'ubuntu-20.04'
-        || matrix.runner == 'jammy' && 'ubuntu-22.04'
+      ${{  matrix.build-config.runner == 'focal' && 'ubuntu-20.04'
+        || matrix.build-config.runner == 'jammy' && 'ubuntu-22.04'
         || null
       }}
     env:
       CCACHE_DIR: "${{github.workspace}}/.ccache"
       CCACHE_MAXSIZE: "10G"
-      CC: ${{matrix.compiler}}-${{matrix.version}}
-      CXX: ${{matrix.compiler == 'gcc' && 'g++' || 'clang++'}}-${{matrix.version}}
+      CC: ${{matrix.build-config.compiler}}-${{matrix.build-config.version}}
+      CXX: ${{matrix.build-config.compiler == 'gcc' && 'g++' || 'clang++'}}-${{matrix.build-config.version}}
     steps:
+      - name: Install Python (if building for Lightning)
+        if: matrix.use-lightning == true
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
       - name: Install dependencies
         run: |
           sudo apt-get -q -y update
           sudo apt-get -q -y install \
             ccache cmake ninja-build libgtest-dev \
-            llvm-${{matrix.llvm}}-dev \
-            ${{matrix.compiler}}-${{matrix.version}} \
-            ${{matrix.compiler == 'gcc' && format('g++-{0}', matrix.version) || ''}}
+            llvm-${{matrix.build-config.llvm}}-dev \
+            ${{matrix.build-config.compiler}}-${{matrix.build-config.version}} \
+            ${{matrix.build-config.compiler == 'gcc' && format('g++-{0}', matrix.build-config.version) || ''}}
+
+          if [[ "${{ matrix.use-lightning }}" == "true" ]]; then
+            echo "Installing Lightning Python dependencies..."
+            python -m pip install pennylane-lightning==0.43.0
+          fi
+
           echo "Installed toolchain:"
           ld --version | head -1
           $CC --version | head -1
           $CXX --version | head -1
-          llvm-config-${{matrix.llvm}} --version | head -1
+          llvm-config-${{matrix.build-config.llvm}} --version | head -1
+
       - name: Check out
         uses: actions/checkout@v4
+
       - name: Set up ccache
         uses: actions/cache@v4
         with:
           path: ${{env.CCACHE_DIR}}
-          key: ccache-${{matrix.runner}}-${{matrix.compiler}}-${{matrix.version}}-${{github.run_id}}
-          restore-keys: ccache-${{matrix.runner}}-${{matrix.compiler}}-${{matrix.version}}
+          key: ccache-${{matrix.build-config.runner}}-${{matrix.build-config.compiler}}-${{matrix.build-config.version}}-${{github.run_id}}
+          restore-keys: ccache-${{matrix.build-config.runner}}-${{matrix.build-config.compiler}}-${{matrix.build-config.version}}
+
       - name: Zero ccache stats
         run: |
           ccache -z
+
       - name: Configure
         run: |
+          if [[ "${{ matrix.use-lightning }}" == "true" ]]; then
+            export LIGHTNING_PATH=$(bash ./scripts/lightning-path.sh qubit)
+          else
+            export LIGHTNING_PATH=""
+          fi
           mkdir build && cd build
           cmake -GNinja \
             -DQIREE_GIT_DESCRIBE="${{github.event.pull_request
@@ -67,23 +88,29 @@ jobs:
             -DQIREE_BUILD_TESTS:BOOL=ON \
             -DQIREE_DEBUG:BOOL=ON \
             -DQIREE_USE_XACC:BOOL=OFF \
+            -DQIREE_USE_LIGHTNING:BOOL=${{ matrix.use-lightning == true && 'ON' || 'OFF' }} \
+            -DQIREE_LIGHTNING_SIM_PATH="$LIGHTNING_PATH" \
             -DCMAKE_BUILD_TYPE="Release" \
             -DCMAKE_INSTALL_PREFIX="${{github.workspace}}/install" \
             -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
             -DCMAKE_CXX_FLAGS="-Wall -Wextra -pedantic" \
             ..
+
       - name: Build all
         working-directory: build
         run: |
           ninja
+
       - name: Run tests
         working-directory: build
         run: |
           ctest --parallel 2 --timeout 15 --output-on-failure
+
       - name: Install
         working-directory: build
         run: |
           ninja install
+
       - name: Show ccache stats
         run: |
           ccache -s

CMakeLists.txt

@@ -38,6 +38,7 @@ option(QIREE_BUILD_TESTS "Build QIR-EE unit tests" ON)
 option(QIREE_BUILD_EXAMPLES "Build QIR-EE examples" OFF)
 option(QIREE_USE_QSIM "Download and build Google qsim backend" ON)
 option(QIREE_USE_XACC "Build XACC interface" OFF)
+option(QIREE_USE_LIGHTNING "Build Pennylane Lightning backend" OFF)
 
 qiree_set_default(BUILD_TESTING ${QIREE_BUILD_TESTS})
 
@@ -137,6 +138,27 @@ if(QIREE_USE_QSIM)
   )
 endif()
 
+if(QIREE_USE_LIGHTNING)
+  qiree_add_library(qiree_lightning INTERFACE)
+  add_library(QIREE::lightning ALIAS qiree_lightning)
+  # Fetch Catalyst runtime include files
+  include("${CMAKE_CURRENT_LIST_DIR}/cmake/support_catalyst.cmake")
+  FindCatalyst(qiree_lightning)
+  target_include_directories(qiree_lightning SYSTEM INTERFACE
+    "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/external>"
+    "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/external>"
+  )
+  set(QIREE_LIGHTNING_SIM_PATH "" CACHE FILEPATH "Path to the Lightning simulator shared library")
+  if(NOT QIREE_LIGHTNING_SIM_PATH)
+    message(FATAL_ERROR "QIREE_LIGHTNING_SIM_PATH is not set. Please specify the path using: -DQIREE_LIGHTNING_SIM_PATH=/path/to/lib")
+  endif()
+  message(STATUS "Using Lightning simulator shared library: ${QIREE_LIGHTNING_SIM_PATH}")
+  target_compile_definitions(qiree_lightning INTERFACE
+    QIREE_LIGHTNING_RTDLIB="${QIREE_LIGHTNING_SIM_PATH}"
+  )
+endif()
+
+
 if(QIREE_USE_XACC)
   find_package(XACC REQUIRED)
 endif()

app/CMakeLists.txt

@@ -28,6 +28,20 @@ if(QIREE_USE_QSIM)
   )
 endif()
 
+#-----------------------------------------------------------------------------#
+# LIGHTNING FRONT END
+#-----------------------------------------------------------------------------#
+
+if(QIREE_USE_LIGHTNING)
+  qiree_add_executable(qir-lightning
+    qir-lightning.cc
+  )
+  target_link_libraries(qir-lightning
+    PUBLIC QIREE::qiree QIREE::qirlightning
+    PRIVATE CLI11::CLI11
+  )
+endif()
+
 #-----------------------------------------------------------------------------#
 # XACC FRONT END
 #-----------------------------------------------------------------------------#

app/qir-lightning.cc

@@ -0,0 +1,74 @@
+//----------------------------------*-C++-*----------------------------------//
+// Copyright 2024 UT-Battelle, LLC, and other QIR-EE developers.
+// See the top-level COPYRIGHT file for details.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//---------------------------------------------------------------------------//
+//! \file app/qir-lightning.cc
+//---------------------------------------------------------------------------//
+#include <cstdlib>
+#include <iostream>
+#include <string>
+#include <CLI/CLI.hpp>
+
+#include "qiree/Executor.hh"
+#include "qiree/Module.hh"
+#include "qiree/ResultDistribution.hh"
+#include "qirlightning/LightningQuantum.hh"
+#include "qirlightning/LightningRuntime.hh"
+
+using namespace std::string_view_literals;
+
+namespace qiree
+{
+namespace app
+{
+//---------------------------------------------------------------------------//
+void run(std::string const& filename, int num_shots)
+{
+    // Load the input
+    Executor execute{Module{filename}};
+
+    // Set up qsim
+    LightningQuantum sim(std::cout, 0);
+    LightningRuntime rt(std::cout, sim);
+    ResultDistribution distribution;
+
+    // Run several time = shots (default 1)
+    for (int i = 0; i < num_shots; i++)
+    {
+        execute(sim, rt);
+        distribution.accumulate(rt.result());
+    }
+
+    std::cout << distribution.to_json() << std::endl;
+}
+
+//---------------------------------------------------------------------------//
+}  // namespace app
+}  // namespace qiree
+
+//---------------------------------------------------------------------------//
+/*!
+ * Execute and run.
+ */
+int main(int argc, char* argv[])
+{
+    int num_shots{1};
+    std::string filename;
+
+    CLI::App app;
+
+    auto* filename_opt
+        = app.add_option("--input,-i,input", filename, "QIR input file");
+    filename_opt->required();
+
+    auto* nshot_opt
+        = app.add_option("-s,--shots", num_shots, "Number of shots");
+    nshot_opt->capture_default_str();
+
+    CLI11_PARSE(app, argc, argv);
+
+    qiree::app::run(filename, num_shots);
+
+    return EXIT_SUCCESS;
+}

cmake/support_catalyst.cmake

@@ -0,0 +1,80 @@
+###############################################################################################
+# This file provides macros to process Catalyst.
+###############################################################################################
+
+# Include this only once
+include_guard()
+
+macro(FindCatalyst target_name)
+  if(LIGHTNING_CATALYST_SRC_PATH)
+    if(NOT IS_ABSOLUTE ${LIGHTNING_CATALYST_SRC_PATH})
+      message(FATAL_ERROR " LIGHTNING_CATALYST_SRC_PATH=${LIGHTNING_CATALYST_SRC_PATH} must be set to an absolute path")
+    endif()
+    if(CATALYST_GIT_TAG)
+      message(WARN " Setting `LIGHTNING_CATALYST_SRC_PATH=${LIGHTNING_CATALYST_SRC_PATH}` overrides `CATALYST_GIT_TAG=${CATALYST_GIT_TAG}`")
+    endif()
+
+    # Acquire local git hash and use for CATALYST_GIT_TAG
+    execute_process(COMMAND git rev-parse --short HEAD
+      WORKING_DIRECTORY ${LIGHTNING_CATALYST_SRC_PATH}
+      OUTPUT_VARIABLE CATALYST_GIT_TAG
+    )
+    message(INFO " Building against local Catalyst - path: ${LIGHTNING_CATALYST_SRC_PATH} - GIT TAG: ${CATALYST_GIT_TAG}")
+
+    target_include_directories(${target_name} INTERFACE
+      $<BUILD_INTERFACE:${LIGHTNING_CATALYST_SRC_PATH}/runtime/lib/backend/common>
+      $<BUILD_INTERFACE:${LIGHTNING_CATALYST_SRC_PATH}/runtime/include>
+    )
+
+  else()
+    if(NOT CATALYST_GIT_TAG)
+      set(CATALYST_GIT_TAG "v0.13.0" CACHE STRING "GIT_TAG value to build Catalyst")
+    endif()
+    message(INFO " Building against Catalyst GIT TAG ${CATALYST_GIT_TAG}")
+
+    set(CATALYST_DOWNLOAD_INCLUDE_DIR "${PROJECT_BINARY_DIR}/catalyst-headers")
+
+    # Fetching /lib/backend/common hpp headers
+    set(LIB_BACKEND_COMMON_HEADERS  CacheManager.hpp
+                                    QubitManager.hpp
+                                    Utils.hpp
+    )
+
+    foreach(HEADER ${LIB_BACKEND_COMMON_HEADERS})
+      string(REGEX REPLACE "\\.[^.]*$" "" HEADER_NAME ${HEADER})
+      FetchContent_Declare(
+        ${HEADER_NAME}
+        URL         https://raw.githubusercontent.com/PennyLaneAI/catalyst/${CATALYST_GIT_TAG}/runtime/lib/backend/common/${HEADER}
+        DOWNLOAD_NO_EXTRACT True
+        SOURCE_DIR    ${CATALYST_DOWNLOAD_INCLUDE_DIR}
+      )
+
+      FetchContent_MakeAvailable(${HEADER_NAME})
+    endforeach()
+
+    # Fetching include hpp headers
+    set(INCLUDE_HEADERS DataView.hpp
+                        Exception.hpp
+                        QuantumDevice.hpp
+                        RuntimeCAPI.h
+                        Types.h
+    )
+
+    foreach(HEADER ${INCLUDE_HEADERS})
+      string(REGEX REPLACE "\\.[^.]*$" "" HEADER_NAME ${HEADER})
+      FetchContent_Declare(
+        ${HEADER_NAME}
+        URL         https://raw.githubusercontent.com/PennyLaneAI/catalyst/${CATALYST_GIT_TAG}/runtime/include/${HEADER}
+        DOWNLOAD_NO_EXTRACT True
+        SOURCE_DIR    ${CATALYST_DOWNLOAD_INCLUDE_DIR}
+      )
+
+      FetchContent_MakeAvailable(${HEADER_NAME})
+    endforeach()
+
+    target_include_directories(${target_name} INTERFACE
+      $<BUILD_INTERFACE:${CATALYST_DOWNLOAD_INCLUDE_DIR}>
+    )
+
+  endif()
+endmacro()

scripts/lightning-path.sh

@@ -0,0 +1,61 @@
+#!/bin/bash -e
+#
+# This script determines the absolute path to a PennyLane-Lightning simulator
+# library to be used with QIREE's Lightning backend.
+#
+# Usage:
+#   ./scripts/lightning-path.sh <simulator_type>
+#
+# Example:
+#   ./scripts/lightning-path.sh qubit
+
+if [ -z "$1" ]; then
+  echo "Error: Missing argument. Usage: $0 <simulator_type>" >&2
+  echo "Example: $0 qubit" >&2
+  exit 1
+fi
+
+# Validate simulator type
+case "$1" in
+  qubit|gpu|kokkos)
+    ;;
+  *)
+    echo "Error: Invalid simulator type '$1'. Must be one of 'qubit', 'gpu', or 'kokkos'." >&2
+    exit 1
+    ;;
+esac
+
+SIM_TYPE="$1"
+
+# Determine OS-specific library suffix
+UNAME_S=$(uname -s)
+case "$UNAME_S" in
+  Linux*)   LIB_SUFFIX=".so";;
+  Darwin*)  LIB_SUFFIX=".dylib";;
+  *)
+    echo "Error: Unsupported platform '$UNAME_S'. QIREE with PennyLane-Lightning only supports Linux and macOS." >&2
+    exit 1
+    ;;
+esac
+
+# Find the base PennyLane-Lightning installation directory using Python
+BASE_PATH=$(python -c "import site; print(f'{site.getsitepackages()[0]}/pennylane_lightning')")
+
+if [ -z "$BASE_PATH" ]; then
+  echo "Error: Could not determine pennylane_lightning path via Python." >&2
+  echo "Is pennylane-lightning installed in your current Python environment?" >&2
+  exit 1
+fi
+
+# Construct the full library path
+LIB_NAME="liblightning_${SIM_TYPE}_catalyst${LIB_SUFFIX}"
+FULL_PATH="${BASE_PATH}/${LIB_NAME}"
+
+# Check if the file actually exists
+if [ ! -f "$FULL_PATH" ]; then
+  echo "Error: Simulator library not found at: $FULL_PATH" >&2
+  echo "Ensure you have installed the correct simulator type ('$SIM_TYPE')" >&2
+  exit 1
+fi
+
+echo "$FULL_PATH"