Add python layer for LGPU_MPI

.coveragerc

@@ -2,7 +2,8 @@
 [run]
 source = pennylane_lightning
 omit =
-    tests*
+    tests/*
+    mpitests/*
 
 [report]
 # Regexes for lines to exclude from consideration

.github/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ### New features since last release
 
+* Add `SparseHamiltonian` support for Lightning-GPU.
+  [(#526)] (https://github.com/PennyLaneAI/pennylane-lightning/pull/526)
+
+* Add `SparseHamiltonian` support for Lightning-Kokkos.
+  [(#527)] (https://github.com/PennyLaneAI/pennylane-lightning/pull/527)
+
+* Integrate python/pybind layer of distributed Lightning-GPU into the Lightning monorepo with python unit tests.
+  [(#518)] (https://github.com/PennyLaneAI/pennylane-lightning/pull/518)
+
 * Integrate the distributed C++ backend of Lightning-GPU into the Lightning monorepo.
   [(#514)] (https://github.com/PennyLaneAI/pennylane-lightning/pull/514)
 
@@ -46,6 +55,9 @@
 
 ### Improvements
 
+* Improve Python testing for Lightning-GPU (+MPI) by adding jobs in Actions files and adding Python tests to increase code coverage.   
+  [(#522)](https://github.com/PennyLaneAI/pennylane-lightning/pull/522)
+
 * Add support for `pip install pennylane-lightning[kokkos]` for the OpenMP backend.
   [(#515)](https://github.com/PennyLaneAI/pennylane-lightning/pull/515)
 

.github/workflows/format.yml

@@ -84,7 +84,7 @@ jobs:
           cp -rf ${{ github.workspace}}/Kokkos_install/${{ matrix.exec_model }}/* Kokkos/
 
       - name: Install dependencies
-        run: sudo apt update && sudo apt -y install clang-tidy-14 cmake g++-10 ninja-build libomp-14-dev
+        run: sudo apt update && sudo apt -y install clang-tidy-14 cmake gcc-11 g++-11 ninja-build libomp-14-dev
         env:
           DEBIAN_FRONTEND: noninteractive
 
@@ -96,5 +96,6 @@ jobs:
             -DBUILD_TESTS=ON \
             -DENABLE_WARNINGS=ON \
             -DPL_BACKEND=${{ matrix.pl_backend }} \
-            -DCMAKE_CXX_COMPILER="$(which g++-10)"
+            -DCMAKE_CXX_COMPILER="$(which g++-11)" \
+            -DCMAKE_C_COMPILER="$(which gcc-11)"
           cmake --build ./Build

.github/workflows/tests_gpu.yml → .github/workflows/tests_gpu_kokkos.yml

@@ -1,4 +1,4 @@
-name: Testing (GPU)
+name: Testing::LKokkos::GPU
 on:
   pull_request:
   push:

.github/workflows/tests_linux_x86_mpi.yml → .github/workflows/tests_linux_x86_mpi_gpu.yml

@@ -157,6 +157,112 @@ jobs:
           rm -rf * .git .gitignore .github
           pip cache purge
 
+
+  python_tests:
+    if: contains(github.event.pull_request.labels.*.name, 'ci:use-multi-gpu-runner') || (inputs.lightning-version != '' && inputs.pennylane-version != '')
+    runs-on:
+      - self-hosted
+      - linux
+      - x64
+      - ubuntu-22.04
+      - multi-gpu
+    strategy:
+      max-parallel: 1
+      matrix:
+        mpilib: ["mpich", "openmpi"]
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout pennyLane-lightning
+        uses: actions/checkout@v3
+        with:
+          fetch-tags: true
+
+      - name: Switch to stable build of Lightning
+        if: inputs.lightning-version == 'stable'
+        run: |
+          git fetch tags --force
+          git checkout $(git tag | sort -V | tail -1)
+
+      - uses: actions/setup-python@v4
+        id: setup_python
+        name: Install Python
+        with:
+          python-version: '3.9'
+
+      # Since the self-hosted runner can be re-used. It is best to set up all package
+      # installations in a virtual environment that gets cleaned at the end of each workflow run
+      - name: Setup Python virtual environment
+        id: setup_venv
+        env:
+          VENV_NAME: ${{ github.workspace }}/venv_${{ steps.setup_python.outputs.python-version }}_${{ github.sha }}
+        run: |
+          # Clear any pre-existing venvs
+          rm -rf venv_*
+
+          # Create new venv for this workflow_run
+          python --version
+          python -m venv ${{ env.VENV_NAME }}
+
+          # Add the venv to PATH for subsequent steps
+          echo ${{ env.VENV_NAME }}/bin >> $GITHUB_PATH
+
+          # Adding venv name as an output for subsequent steps to reference if needed
+          source ${{ env.VENV_NAME }}/bin/activate
+          echo "venv_name=${{ env.VENV_NAME }}" >> $GITHUB_OUTPUT
+
+      - name: Display Python-Path
+        id: python_path
+        run: |
+          py_path=$(which python)
+          echo "Python Interpreter Path => $py_path"
+          echo "python=$py_path" >> $GITHUB_OUTPUT
+
+          pip_path=$(which python)
+          echo "PIP Path => $pip_path"
+          echo "pip=$pip_path" >> $GITHUB_OUTPUT
+
+      - name: Install Latest PennyLane
+        # We want to install the latest PL on non workflow_call events
+        if: inputs.pennylane-version == 'latest'  || inputs.pennylane-version == ''
+        run: python -m pip install git+https://github.com/PennyLaneAI/pennylane.git@master
+
+      - name: Install required packages
+        run: |
+          source /etc/profile.d/modules.sh && module use /opt/modules/ && module load ${{ matrix.mpilib }}
+          python -m pip install pip~=22.0
+          python -m pip install ninja cmake custatevec-cu11 pytest pytest-mock flaky pytest-cov mpi4py
+          SKIP_COMPILATION=True PL_BACKEND=lightning_qubit python -m pip install -e . -vv
+
+      - name: Build and install package
+        env:
+          CUQUANTUM_SDK: $(python -c "import site; print( f'{site.getsitepackages()[0]}/cuquantum/lib')")
+        run: |
+          source /etc/profile.d/modules.sh && module use /opt/modules/ && module load ${{ matrix.mpilib }}
+          PL_BACKEND=lightning_gpu python setup.py build_ext -i --define="CMAKE_CXX_COMPILER=mpicxx;ENABLE_MPI=ON;CMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc;CMAKE_CUDA_ARCHITECTURES=${{ env.CI_CUDA_ARCH }};Python_EXECUTABLE=${{ steps.python_path.outputs.python }}"
+          PL_BACKEND=lightning_gpu python -m pip install -e . --verbose
+
+      - name: Run unit tests for MPI-enabled lightning.gpu device
+        run: |
+          source /etc/profile.d/modules.sh && module use /opt/modules/ && module load ${{ matrix.mpilib }}
+          PL_DEVICE=lightning.gpu /opt/mpi/${{ matrix.mpilib }}/bin/mpirun -np 2 python -m pytest ./mpitests $COVERAGE_FLAGS
+          mv coverage.xml coverage-${{ github.job }}-lightning_gpu_${{ matrix.mpilib }}-main.xml
+          # PL_DEVICE=lightning.gpu /opt/mpi/${{ matrix.mpilib }}/bin/mpirun --oversubscribe -n 4 pytest -s -x mpitests/test_device.py -k test_create_device $COVERAGE_FLAGS
+
+      - name: Upload code coverage results
+        uses: actions/upload-artifact@v3
+        with:
+          name: ubuntu-codecov-results-python
+          path: coverage-${{ github.job }}-lightning_gpu_${{ matrix.mpilib }}-*.xml
+          if-no-files-found: error
+
+      - name: Cleanup
+        if: always()
+        run: |
+          rm -rf ${{ steps.setup_venv.outputs.venv_name }}
+          rm -rf * .git .gitignore .github
+          pip cache purge
+
   upload-to-codecov-linux-cpp:
     needs: ["cpp_tests"]
     name: Upload coverage data to codecov
@@ -182,4 +288,31 @@ jobs:
         run: |
           rm -rf ${{ steps.setup_venv.outputs.venv_name }}
           rm -rf * .git .gitignore .github
-          pip cache purge
+          pip cache purge
+
+  upload-to-codecov-linux-python:
+    needs: ["python_tests"]
+    name: Upload coverage data to codecov
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Download coverage reports
+        uses: actions/download-artifact@v3
+        with:
+          name: ubuntu-codecov-results-python
+
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          fail_ci_if_error: true
+          verbose: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Cleanup
+        if: always()
+        run: |
+          rm -rf ${{ steps.setup_venv.outputs.venv_name }}
+          rm -rf * .git .gitignore .github
+          pip cache purge

.pre-commit-config.yaml

@@ -18,4 +18,4 @@ repos:
           "-sn", # Don't display the score
           "--rcfile=.pylintrc", # Link to your config file
         ]
-      exclude: ^(bin/|doc/|scripts/|setup.py|tests/)
+      exclude: ^(bin/|doc/|scripts/|setup.py|tests/|mpitests/)

Makefile

@@ -110,7 +110,7 @@ format-cpp:
 	./bin/format $(CHECK) --cfversion $(if $(version:-=),$(version),0) ./pennylane_lightning
 
 format-python:
-	black -l 100 ./pennylane_lightning/ ./tests $(CHECK)
+	black -l 100 ./pennylane_lightning/ ./mpitests ./tests $(CHECK)
 
 .PHONY: check-tidy
 check-tidy:

mpitests/.pylintrc

@@ -0,0 +1,52 @@
+[MASTER]
+# A comma-separated list of package or module names from where C extensions may
+# be loaded. Extensions are loading into the active Python interpreter and may
+# run arbitrary code
+extension-pkg-whitelist=numpy,scipy,autograd,toml,appdir,autograd.numpy,autograd.numpy.linalg,autograd.numpy.builtins,semantic_version,torch,tensorflow,tensorflow.contrib,tensorflow.contrib.eager,LazyLoader,networkx,networkx.dag
+ignore-patterns=test_legacy*
+
+[TYPECHECK]
+
+# List of module names for which member attributes should not be checked
+# (useful for modules/projects where namespaces are manipulated during runtime
+# and thus existing member attributes cannot be deduced by static analysis. It
+# supports qualified module names, as well as Unix pattern matching.
+ignored-modules=numpy,scipy,autograd,toml,appdir,autograd.numpy,autograd.numpy.linalg,autograd.numpy.builtins,semantic_version,torch,tensorflow,tensorflow.contrib,tensorflow.contrib.eager,LazyLoader,networkx,networkx.dag,math,pennylane.numpy
+
+# List of classes names for which member attributes should not be checked
+# (useful for classes with attributes dynamically set). This supports can work
+# with qualified names.
+ignored-classes=numpy,scipy,autograd,toml,appdir,autograd.numpy,autograd.numpy.linalg,autograd.numpy.builtins,semantic_version,torch,tensorflow,tensorflow.contrib,tensorflow.contrib.eager,LazyLoader,networkx,networkx.dag,math,pennylane.numpy,pennylane.numpy.random,pennylane.numpy.linalg,pennylane.numpy.builtins,pennylane.operation,rustworkx,kahypar
+
+[MESSAGES CONTROL]
+
+# Enable the message, report, category or checker with the given id(s). You can
+# either give multiple identifier separated by comma (,) or put this option
+# multiple time.
+#enable=
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifier separated by comma (,) or put this option
+# multiple time (only on the command line, not in the configuration file where
+# it should appear only once).
+# Cyclical import checks are disabled for now as they are frequently used in
+# the code base, but this can be removed in the future once cycles are resolved.
+disable=
+  line-too-long,
+  invalid-name,
+  too-many-lines,
+  redefined-builtin,
+  too-many-locals,
+  duplicate-code,
+  cyclic-import,
+  import-error,
+  bad-option-value,
+  import-outside-toplevel,
+  missing-class-docstring,
+  missing-function-docstring,
+  no-self-use
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+notes=

mpitests/conftest.py

@@ -0,0 +1,114 @@
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Pytest configuration file for PennyLane-Lightning-GPU test suite.
+"""
+# pylint: disable=missing-function-docstring,wrong-import-order,unused-import
+
+import os
+import pytest
+from pennylane import numpy as np
+import pennylane as qml
+
+import itertools
+
+# Tuple passed to distributed device ctor
+# np.complex for data type and True or False
+# for enabling MPI or not.
+fixture_params = itertools.product(
+    [np.complex64, np.complex128],
+    [True, False],
+)
+
+# defaults
+TOL = 1e-6
+TOL_STOCHASTIC = 0.05
+
+U = np.array(
+    [
+        [0.83645892 - 0.40533293j, -0.20215326 + 0.30850569j],
+        [-0.23889780 - 0.28101519j, -0.88031770 - 0.29832709j],
+    ]
+)
+
+U2 = np.array([[0, 1, 1, 1], [1, 0, 1, -1], [1, -1, 0, 1], [1, 1, -1, 0]]) / np.sqrt(3)
+A = np.array([[1.02789352, 1.61296440 - 0.3498192j], [1.61296440 + 0.3498192j, 1.23920938 + 0j]])
+
+THETA = np.linspace(0.11, 1, 3)
+PHI = np.linspace(0.32, 1, 3)
+VARPHI = np.linspace(0.02, 1, 3)
+
+
+@pytest.fixture(scope="session")
+def tol():
+    """Numerical tolerance for equality tests."""
+    return float(os.environ.get("TOL", TOL))
+
+
+@pytest.fixture(scope="session", params=[2, 3])
+def n_subsystems(request):
+    """Number of qubits or qumodes."""
+    return request.param
+
+
+# Looking for the device for testing.
+default_device = "lightning.gpu"
+supported_devices = {"lightning.gpu"}
+supported_devices.update({sb.replace(".", "_") for sb in supported_devices})
+
+
+def get_device():
+    """Return the pennylane lightning device.
+
+    The device is ``lightning.gpu`` by default.
+    Allowed values are: "lightning.gpu".
+    An underscore can also be used instead of a dot.
+    If the environment variable ``PL_DEVICE`` is defined, its value is used.
+    Underscores are replaced by dots upon exiting.
+    """
+    device = None
+    if "PL_DEVICE" in os.environ:
+        device = os.environ.get("PL_DEVICE", default_device)
+        device = device.replace("_", ".")
+    if device is None:
+        device = default_device
+    if device not in supported_devices:
+        raise ValueError(f"Invalid backend {device}.")
+    return device
+
+
+device_name = get_device()
+
+if device_name not in qml.plugin_devices:
+    raise qml.DeviceError(
+        f"Device {device_name} does not exist. Make sure the required plugin is installed."
+    )
+
+# Device specification
+if device_name == "lightning.gpu":
+    from pennylane_lightning.lightning_gpu import LightningGPU as LightningDevice
+else:
+    raise qml.DeviceError(f"The MPI tests do not apply to the {device_name} device.")
+
+
+# General qubit_device fixture, for any number of wires.
+@pytest.fixture(
+    scope="function",
+    params=fixture_params,
+)
+def qubit_device(request):
+    def _device(wires):
+        return qml.device(
+            device_name,
+            wires=wires,
+            mpi=True,
+            c_dtype=request.param[0],
+            batch_obs=request.param[1],
+        )
+
+    return _device