interface-unit-tests.yml

name: Unit Test - All Interfaces
on:
  workflow_call:
    secrets:
      codecov_token:
        description: The codecov token to use when uploading coverage files
        required: true
    inputs:
      branch:
        description: The PennyLane branch to checkout and run unit tests for
        required: true
        type: string
      pipeline_mode:
          description: The pipeline mode can be unit-tests, benchmarks, or reference-benchmarks
          required: false
          type: string
          default: 'unit-tests'
      pytest_coverage_flags:
        description: PyTest Coverage flags to pass to all jobs
        required: false
        type: string
        default: --cov=pennylane --cov-append --cov-report=term-missing --cov-report=xml --no-flaky-report --tb=native
      run_lightened_ci:
        description: |
          Indicate if a lightened version of the CI should be run instead of the entire suite.

          The lightened version of the CI includes the following changes:
          - Only Python 3.10 is tested against, instead of 3.10, 3.11, 3.12
        required: false
        type: boolean
        default: false
      skip_ci_test_jobs:
        description: |
          Names of jobs (comma separated) that should be skipped on a lightened CI run.
          The value of this variable is only used IF 'run_lightened_ci' is `true`.
          For a full test-suite run, all jobs are triggered.
        required: false
        type: string
        default: ''
      disable_new_opmath:
        description: Whether to disable the new op_math or not when running the tests
        required: false
        type: string
        default: "False"
      pytest_store_durations:
        description: Whether to store artifacts for test durations
        required: false
        type: boolean
        default: false

jobs:
  setup-ci-load:
    runs-on: ubuntu-latest

    steps:
      - name: Setup Python Versions
        id: python_versions

        # All jobs will use the 'default' python versions listed in the dictionary below.
        # Unless the job name exists as a key as well, in which case the python versions listed for the job itself will be used instead.
        run: |
          if [ "${{ inputs.run_lightened_ci }}" == "true" ];
          then
            cat >python_versions.json <<-EOF
          {
            "default": ["3.10"]
          }
          EOF
          else
            cat >python_versions.json <<-EOF
          {
            "default": ["3.10", "3.11", "3.12"],
            "torch-tests": ["3.10", "3.12"],
            "tf-tests": ["3.10", "3.12"],
            "jax-tests": ["3.10", "3.12"],
            "all-interfaces-tests": ["3.10"],
            "external-libraries-tests": ["3.10"],
            "qcut-tests": ["3.10"],
            "qchem-tests": ["3.10"],
            "gradients-tests": ["3.10"],
            "data-tests": ["3.10"],
            "device-tests": ["3.10"]
          }
          EOF
          fi

          jq . python_versions.json
          echo "python_versions=$(jq -r tostring python_versions.json)" >> $GITHUB_OUTPUT

      - name: Setup Matrix Max Parallel
        id: max_parallel
        run: |
          if [ "${{ inputs.run_lightened_ci }}" == "true" ];
          then
            cat >matrix_max_parallel.json <<-EOF
          {
            "default": 1,
            "core-tests": 5,
            "gradients-tests": 2,
            "jax-tests": 5,
            "tf-tests": 3,
            "device-tests": 2
          }
          EOF
          else
            cat >matrix_max_parallel.json <<-EOF
          {
            "default": 1,
            "core-tests": 5,
            "jax-tests": 10,
            "tf-tests": 6,
            "torch-tests": 2,
            "device-tests": 2
          }
          EOF
          fi

          jq . matrix_max_parallel.json
          echo "matrix_max_parallel=$(jq -r tostring matrix_max_parallel.json)" >> $GITHUB_OUTPUT

      - name: Setup Job to Skip
        id: jobs_to_skip
        env:
          JOBS_TO_SKIP: ${{ inputs.skip_ci_test_jobs }}
        run: |
          if [ "${{ inputs.run_lightened_ci }}" == "true" ];
          then
            skipped_jobs=$(echo -n "$JOBS_TO_SKIP" | python -c 'import json, sys; print(json.dumps(list(map(lambda job: job.strip(), filter(None, sys.stdin.read().split(","))))))')
            echo "The following jobs will be skipped: $skipped_jobs"
            echo "jobs_to_skip=$skipped_jobs" >> $GITHUB_OUTPUT
          else
            echo 'jobs_to_skip=[]' >> $GITHUB_OUTPUT
          fi

    outputs:
      matrix-max-parallel: ${{ steps.max_parallel.outputs.matrix_max_parallel }}
      python-version: ${{ steps.python_versions.outputs.python_versions }}
      jobs-to-skip: ${{ steps.jobs_to_skip.outputs.jobs_to_skip }}

  torch-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).torch-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).torch-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'torch-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: torch-tests (${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: core-interfaces-coverage-torch-${{ matrix.python-version }}
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: false
      install_tensorflow: false
      install_pytorch: true
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: torch and not qcut and not finite-diff and not param-shift
      requirements_file: ${{ github.event_name == 'schedule' && strategy.job-index == 0 && 'torch.txt' || '' }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  autograd-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).autograd-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).autograd-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'autograd-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: autograd-tests (${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: core-interfaces-coverage-autograd-${{ matrix.python-version }}
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: false
      install_tensorflow: false
      install_pytorch: false
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: autograd and not qcut and not finite-diff and not param-shift
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  tf-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).tf-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        group: [1, 2, 3]
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).tf-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'tf-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: tf-tests (${{ matrix.group }}, ${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: core-interfaces-coverage-tf-${{ matrix.python-version }}-${{ matrix.group }}
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: false
      install_tensorflow: true
      install_pytorch: false
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: tf and not qcut and not finite-diff and not param-shift
      pytest_additional_args: --splits 3 --group ${{ matrix.group }}
      pytest_durations_file_path: '.github/workflows/tf_tests_durations.json'
      pytest_store_durations: ${{ inputs.pytest_store_durations }}
      requirements_file: ${{ github.event_name == 'schedule' && strategy.job-index == 0 && 'tf.txt' || '' }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  jax-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).jax-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        group: [1, 2, 3, 4, 5]
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).jax-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'jax-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: jax-tests (${{ matrix.group }}, ${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: core-interfaces-coverage-jax-${{ matrix.python-version }}-${{ matrix.group }}
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: true
      install_tensorflow: false
      install_pytorch: false
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: jax and not qcut and not finite-diff and not param-shift
      pytest_additional_args: --dist=loadscope --splits 5 --group ${{ matrix.group }}
      pytest_durations_file_path: '.github/workflows/jax_tests_durations.json'
      pytest_store_durations: ${{ inputs.pytest_store_durations }}
      requirements_file: ${{ github.event_name == 'schedule' && strategy.job-index == 0 && 'jax.txt' || '' }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  core-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).core-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        group: [1, 2, 3, 4, 5]
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).core-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'core-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: core-tests (${{ matrix.group }}, ${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: core-interfaces-coverage-core-${{ matrix.python-version }}-${{ matrix.group }}
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: false
      install_tensorflow: false
      install_pytorch: false
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: core and not qcut and not finite-diff and not param-shift
      pytest_additional_args: --splits 5 --group ${{ matrix.group }}
      pytest_durations_file_path: '.github/workflows/core_tests_durations.json'
      pytest_store_durations: ${{ inputs.pytest_store_durations }}
      requirements_file: ${{ github.event_name == 'schedule' && strategy.job-index == 0 && 'core.txt' || '' }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  all-interfaces-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).all-interfaces-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).all-interfaces-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'all-interfaces-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: all-interfaces-tests (${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: all-interfaces-coverage
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: true
      install_tensorflow: true
      install_pytorch: true
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: all_interfaces
      requirements_file: ${{ github.event_name == 'schedule' && strategy.job-index == 0 && 'all_interfaces.txt' || '' }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  external-libraries-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).external-libraries-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).external-libraries-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'external-libraries-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: external-libraries-tests (${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: external-libraries-tests-coverage
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: true
      install_tensorflow: true
      install_pytorch: false
      # This is required during the release process when the latest released version of
      # catalyst requires the latest version of pennylane that is about to be released.
      # Installing catalyst after pennylane to make sure that the latest catalyst is used.
      install_catalyst_nightly: true
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: external
      additional_pip_packages: pyzx matplotlib stim quimb mitiq pennylane-qiskit ply
      requirements_file: ${{ github.event_name == 'schedule' && strategy.job-index == 0 && 'external.txt' || '' }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  qcut-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).qcut-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).qcut-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'qcut-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: qcut-tests (${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: qcut-coverage
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: true
      install_tensorflow: true
      install_pytorch: true
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: qcut
      additional_pip_packages: kahypar==1.1.7 opt_einsum
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  qchem-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).qchem-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).qchem-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'qchem-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: qchem-tests (${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: qchem-coverage
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: false
      install_tensorflow: false
      install_pytorch: false
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: qchem
      additional_pip_packages: openfermionpyscf basis-set-exchange
      disable_new_opmath: ${{ inputs.disable_new_opmath }}

  gradients-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).gradients-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        config:
          - suite: finite-diff
          - suite: param-shift
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).gradients-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'gradients-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: gradients-tests (${{ matrix.config.suite }}, ${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: gradients-${{ matrix.config.suite }}-coverage
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: true
      install_tensorflow: true
      install_pytorch: true
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: ${{ matrix.config.suite }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  data-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).data-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).data-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'data-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: data-tests (${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: data-coverage-${{ matrix.python-version }}
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: false
      install_tensorflow: false
      install_pytorch: false
      install_pennylane_lightning_master: true
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_markers: data
      additional_pip_packages: h5py
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  device-tests:
    needs:
      - setup-ci-load
    strategy:
      max-parallel: >-
        ${{
           fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).device-tests
           || fromJSON(needs.setup-ci-load.outputs.matrix-max-parallel).default
         }}
      matrix:
        config:
          - device: default.qubit
            shots: None
          - device: default.qubit
            shots: 10000
          - device: default.mixed
            shots: None
        python-version: >-
          ${{
            fromJSON(needs.setup-ci-load.outputs.python-version).device-tests
            || fromJSON(needs.setup-ci-load.outputs.python-version).default
           }}
    if: ${{ !contains(fromJSON(needs.setup-ci-load.outputs.jobs-to-skip), 'device-tests') }}
    uses: ./.github/workflows/unit-test.yml
    with:
      job_name: device-tests (${{ matrix.config.device }}, ${{ matrix.config.shots }}, ${{ matrix.python-version }})
      branch: ${{ inputs.branch }}
      coverage_artifact_name: devices-coverage-${{ matrix.config.device }}-${{ matrix.config.shots }}
      python_version: ${{ matrix.python-version }}
      pipeline_mode: ${{ inputs.pipeline_mode }}
      install_jax: ${{ !contains(matrix.config.skip_interface, 'jax') }}
      install_tensorflow: ${{ !contains(matrix.config.skip_interface, 'tf') }}
      install_pytorch: ${{ !contains(matrix.config.skip_interface, 'torch') }}
      install_pennylane_lightning_master: true
      pytest_test_directory: pennylane/devices/tests
      pytest_coverage_flags: ${{ inputs.pytest_coverage_flags }}
      pytest_additional_args: --device=${{ matrix.config.device }} --shots=${{ matrix.config.shots }}
      disable_new_opmath: ${{ inputs.disable_new_opmath }}


  upload-to-codecov:
    runs-on: ubuntu-latest

    needs:
      - torch-tests
      - autograd-tests
      - tf-tests
      - jax-tests
      - core-tests
      - all-interfaces-tests
      - external-libraries-tests
      - qcut-tests
      - qchem-tests
      - gradients-tests
      - data-tests
      - device-tests

    # Run this even if any of the above jobs are skipped but not if any of the jobs failed
    if: >-
      ${{
        always() &&
        !contains(needs.*.result, 'failure') &&
        !contains(needs.*.result, 'cancelled') &&
        inputs.pipeline_mode == 'unit-tests'
       }}

    steps:
      # Checkout repo so Codecov action is able to resolve git HEAD reference
      - name: Checkout
        uses: actions/checkout@v3
        with:
          ref: ${{ inputs.branch }}

      - name: Down Coverage Artifacts
        uses: actions/download-artifact@v4

      - name: Upload to Codecov
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.codecov_token }}
          fail_ci_if_error: true  # upload errors should be caught early