build-wheel-macos-arm64.yaml

name: Build Catalyst Wheel on macOS (arm64)
permissions:
  contents: read
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - labeled
      - ready_for_review
  push:
    branches: [ main ]
  schedule:
    # Thursdays we test the standalone plugin
    - cron: '35 4 * * 4'
  workflow_dispatch:
    inputs:
      build_standalone_plugin:
        description: 'Build the standalone plugin wheel'
        type: choice
        options:
          - 'true'
          - 'false'
        required: false
        default: 'false'
  workflow_call:
    inputs:
      build_standalone_plugin:
        description: 'Build the standalone plugin wheel'
        type: boolean
        required: false
        default: false
      branch:
        description: 'Branch to build from'
        required: false
        default: 'main'
        type: string
      build_dev_package:
        description: 'Build and upload the catalyst-dev archives'
        required: false
        default: false
        type: boolean

env:
  MACOSX_DEPLOYMENT_TARGET: 15.0

  # If the `inputs.build_standalone_plugin` is set to a value (true/false), then that is used.
  # If the input is empty (meaning this workflow was not triggered by a workflow_call/workflow_dispatch), then check if event_name is schedule.
  # If event_name is NOT schedule, default to false
  BUILD_STANDALONE_PLUGIN: ${{ format('{0}', inputs.build_standalone_plugin) || github.event_name == 'schedule' }}

concurrency:
  group: Build Catalyst Wheel on macOS (arm64)-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check_if_wheel_build_required:
    if: github.event.pull_request.draft == false
    uses: ./.github/workflows/check-for-wheel-build.yml

  constants:
    needs: [check_if_wheel_build_required]
    if: needs.check_if_wheel_build_required.outputs.build-wheels == 'true'
    name: "Set build matrix"
    uses: ./.github/workflows/constants.yaml

  build-dependencies:
    needs: [constants, check_if_wheel_build_required]

    strategy:
      fail-fast: false
      matrix:
        python_version: ${{ fromJson(format('["{0}"]', needs.constants.outputs.primary_python_version)) }}

    name: Build Dependencies (Python ${{ matrix.python_version }})
    runs-on: macos-15

    if: needs.check_if_wheel_build_required.outputs.build-wheels == 'true'

    steps:
    - name: Checkout Catalyst repo
      uses: actions/checkout@v4
      with:
        ref: ${{ inputs.branch || github.ref }}

    # Cache external project sources
    # Hopefully these can be shared with the main check-catalyst action since we don't run this
    # build in a container.
    - name: Cache LLVM Source
      id: cache-llvm-source
      uses: actions/cache@v4
      with:
        path: ${{ github.workspace }}/mlir/llvm-project
        key: llvm-${{ needs.constants.outputs.llvm_version }}-default-source
        enableCrossOsArchive: True

    - name: Cache Stablehlo Source
      id: cache-stablehlo-source
      uses: actions/cache@v4
      with:
        path: ${{ github.workspace }}/mlir/stablehlo
        key: stablehlo-${{ needs.constants.outputs.stablehlo_version }}-container-source
        enableCrossOsArchive: True

    - name: Cache Enzyme Source
      id: cache-enzyme-source
      uses: actions/cache@v4
      with:
        path: ${{ github.workspace }}/mlir/Enzyme
        key: enzyme-${{ needs.constants.outputs.enzyme_version }}-default-source
        enableCrossOsArchive: True

    - name: Clone LLVM Submodule
      if: steps.cache-llvm-source.outputs.cache-hit != 'true'
      uses: actions/checkout@v4
      with:
        repository: llvm/llvm-project
        ref: ${{ needs.constants.outputs.llvm_version }}
        path: ${{ github.workspace }}/mlir/llvm-project

    - name: Patch LLVM Source
      if: steps.cache-llvm-source.outputs.cache-hit != 'true'
      run: |
        cd $GITHUB_WORKSPACE/mlir/llvm-project
        git apply $GITHUB_WORKSPACE/mlir/patches/llvm-bufferization-segfault.patch
        git apply $GITHUB_WORKSPACE/mlir/patches/llvm-python-bindinggen-annotations.patch

    - name: Clone Stablehlo Submodule
      if: steps.cache-stablehlo-source.outputs.cache-hit != 'true'
      uses: actions/checkout@v4
      with:
        repository: openxla/stablehlo
        ref: ${{ needs.constants.outputs.stablehlo_version }}
        path: ${{ github.workspace }}/mlir/stablehlo

    - name: Clone Enzyme Submodule
      if: steps.cache-enzyme-source.outputs.cache-hit != 'true'
      uses: actions/checkout@v4
      with:
        repository: EnzymeAD/Enzyme
        ref: ${{ needs.constants.outputs.enzyme_version }}
        path: ${{ github.workspace }}/mlir/Enzyme

    - name: Patch Enzyme Source
      if: steps.cache-enzyme-source.outputs.cache-hit != 'true'
      run: |
        cd $GITHUB_WORKSPACE/mlir/Enzyme
        git apply $GITHUB_WORKSPACE/mlir/patches/enzyme-nvvm-fabs-intrinsics.patch

    # Cache external project builds
    - name: Restore LLVM Build
      id: cache-llvm-build
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/llvm-build
        key: ${{ runner.os }}-${{ runner.arch }}-llvm-${{ needs.constants.outputs.llvm_version }}-${{ matrix.python_version }}-wheel-build

    - name: Check Stablehlo Build Cache
      id: cache-stablehlo-build
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/stablehlo-build
        key: ${{ runner.os }}-${{ runner.arch }}-stablehlo-${{ needs.constants.outputs.stablehlo_version }}-wheel-build
        lookup-only: True

    - name: Check Enzyme Build Cache
      id: cache-enzyme-build
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/enzyme-build
        key: ${{ runner.os }}-${{ runner.arch }}-enzyme-${{ needs.constants.outputs.llvm_version }}-${{ needs.constants.outputs.enzyme_version }}-wheel-build
        lookup-only: True

    - name: Setup Python version
      # There are multiple Python versions installed on the GitHub image, 3.12 - 3.14 is already
      # available under /Library/Frameworks/Python.framework/Versions/, but homebrew also provides
      # 3.12 - 3.14. Make sure to consistently use the system versions.
      run: |
        echo /Library/Frameworks/Python.framework/Versions/${{ matrix.python_version }}/bin >> $GITHUB_PATH

    - name: Install Dependencies (Python)
      run: |
        python${{ matrix.python_version }} -m pip install numpy "nanobind<2.13" pybind11 PyYAML cmake ninja

    - name: Build LLVM / MLIR
      if: steps.cache-llvm-build.outputs.cache-hit != 'true'
      run: |
        PYTHON=$(which python${{ matrix.python_version }}) \
        LLVM_BUILD_DIR="$GITHUB_WORKSPACE/llvm-build" \
        LLVM_TARGETS="check-mlir" \
        ENABLE_ZLIB=FORCE_ON \
        make llvm

    - name: Save LLVM Build
      id: save-llvm-build
      if: steps.cache-llvm-build.outputs.cache-hit != 'true'
      uses: actions/cache/save@v4
      with:
        path: ${{ github.workspace }}/llvm-build
        key: ${{ runner.os }}-${{ runner.arch }}-llvm-${{ needs.constants.outputs.llvm_version }}-${{ matrix.python_version }}-wheel-build

    - name: Build Stablehlo Dialect
      if: steps.cache-stablehlo-build.outputs.cache-hit != 'true'
      run: |
        LLVM_BUILD_DIR="$(pwd)/llvm-build" \
        STABLEHLO_BUILD_DIR="$GITHUB_WORKSPACE/stablehlo-build" \
        COMPILER_LAUNCHER="" \
        make stablehlo

    - name: Save Stablehlo Build
      id: save-stablehlo-build
      if: steps.cache-stablehlo-build.outputs.cache-hit != 'true'
      uses: actions/cache/save@v4
      with:
        path: ${{ github.workspace }}/stablehlo-build
        key: ${{ runner.os }}-${{ runner.arch }}-stablehlo-${{ needs.constants.outputs.stablehlo_version }}-wheel-build

    - name: Build Enzyme
      if: steps.cache-enzyme-build.outputs.cache-hit != 'true'
      run: |
        cmake -S mlir/Enzyme/enzyme -B $GITHUB_WORKSPACE/enzyme-build -G Ninja \
              -DCMAKE_BUILD_TYPE=Release \
              -DLLVM_DIR="$GITHUB_WORKSPACE/llvm-build/lib/cmake/llvm" \
              -DENZYME_STATIC_LIB=ON \
              -DCMAKE_CXX_VISIBILITY_PRESET=default

        cmake --build $GITHUB_WORKSPACE/enzyme-build --target EnzymeStatic-22

    - name: Save Enzyme Build
      id: save-enzyme-build
      if: steps.cache-enzyme-build.outputs.cache-hit != 'true'
      uses: actions/cache/save@v4
      with:
        path: ${{ github.workspace }}/enzyme-build
        key: ${{ runner.os }}-${{ runner.arch }}-enzyme-${{ needs.constants.outputs.llvm_version }}-${{ needs.constants.outputs.enzyme_version }}-wheel-build

  catalyst-macos-wheels-arm64:
    needs: [constants, build-dependencies]
    strategy:
      fail-fast: false
      matrix:
        python_version: ${{ fromJson(needs.constants.outputs.python_versions) }}

    name: Build Wheels (Python ${{ matrix.python_version }})
    runs-on: macos-15

    steps:
    - name: Checkout Catalyst repo
      uses: actions/checkout@v4
      with:
        ref: ${{ inputs.branch || github.ref }}

    - name: Setup Python version
      # There are multiple Python versions installed on the GitHub image, 3.12 - 3.14 is already
      # available under /Library/Frameworks/Python.framework/Versions/, but homebrew also provides
      # 3.12 - 3.14. Make sure to consistently use the system versions.
      run: |
        echo /Library/Frameworks/Python.framework/Versions/${{ matrix.python_version }}/bin >> $GITHUB_PATH

    # CMake four has dropped compatibility for CMake 3.5, which is the minimum specified by the
    # LAPACKE reference implementation. TODO: Look into how to upgrade beyond this limit.
    - name: Install Dependencies (Python)
      run: |
        python${{ matrix.python_version }} -m pip install numpy "nanobind<2.13" pybind11 PyYAML ninja delocate
        python${{ matrix.python_version }} -m pip install cmake'<4'

    - name: Get Cached LLVM Source
      id: cache-llvm-source
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/mlir/llvm-project
        key: llvm-${{ needs.constants.outputs.llvm_version }}-default-source
        enableCrossOsArchive: True
        fail-on-cache-miss: True

    - name: Get Cached LLVM Build
      id: cache-llvm-build
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/llvm-build
        key: ${{ runner.os }}-${{ runner.arch }}-llvm-${{ needs.constants.outputs.llvm_version }}-${{ needs.constants.outputs.primary_python_version }}-wheel-build
        fail-on-cache-miss: True

    - name: Get Cached Stablehlo Source
      id: cache-stablehlo-source
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/mlir/stablehlo
        key: stablehlo-${{ needs.constants.outputs.stablehlo_version }}-container-source
        enableCrossOsArchive: True
        fail-on-cache-miss: True

    - name: Get Cached Stablehlo Build
      id: cache-stablehlo-build
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/stablehlo-build
        key: ${{ runner.os }}-${{ runner.arch }}-stablehlo-${{ needs.constants.outputs.stablehlo_version }}-wheel-build
        fail-on-cache-miss: True

    - name: Get Cached Enzyme Source
      id: cache-enzyme-source
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/mlir/Enzyme
        key: enzyme-${{ needs.constants.outputs.enzyme_version }}-default-source
        enableCrossOsArchive: True
        fail-on-cache-miss: True

    - name: Get Cached Enzyme Build
      id: cache-enzyme-build
      uses: actions/cache/restore@v4
      with:
        path: ${{ github.workspace }}/enzyme-build
        key: ${{ runner.os }}-${{ runner.arch }}-enzyme-${{ needs.constants.outputs.llvm_version }}-${{ needs.constants.outputs.enzyme_version }}-wheel-build
        fail-on-cache-miss: True

    # TODO: uncomment the setup xcode action when updating to MacOS 15 in the github runner images
    # - name: Setup Xcode
    #   run:
    #     sudo xcode-select --switch /Library/Developer/CommandLineTools

    # Build Catalyst-Runtime
    - name: Build Catalyst-Runtime
      id: runtime-build
      run: |
        # On GH images, gfortran is only available as a specific version.
        export FC=gfortran-14
        cmake -S runtime -B $GITHUB_WORKSPACE/runtime-build -G Ninja \
              -DCMAKE_BUILD_TYPE=Release \
              -DCMAKE_LIBRARY_OUTPUT_DIRECTORY="$GITHUB_WORKSPACE/runtime-build/lib" \
              -DPython_EXECUTABLE=$(which python${{ matrix.python_version }}) \
              -DENABLE_OPENQASM=ON \
              -DENABLE_OQD=OFF \
              -DMLIR_INCLUDE_DIRS="$GITHUB_WORKSPACE/mlir/llvm-project/mlir/include"

        cmake --build $GITHUB_WORKSPACE/runtime-build --target rt_capi rt_rsdecomp rt_decoder rtd_openqasm rtd_null_qubit

    - name: Error log on failure
      if: failure() && steps.runtime-build.outcome == 'failure'
      run: |
        cat $GITHUB_WORKSPACE/runtime-build/_lapacke-accelerate/src/lapacke-accelerate-stamp/*-err.log 2>/dev/null || True

    - name: Test Catalyst-Runtime
      run: |
        python${{ matrix.python_version }} -m pip install 'amazon-braket-pennylane-plugin>1.27.1'
        cmake --build $GITHUB_WORKSPACE/runtime-build --target runner_tests_openqasm
        $GITHUB_WORKSPACE/runtime-build/tests/runner_tests_openqasm

    # Build OQC-Runtime
    - name: Build OQC-Runtime
      run: |
          OQC_BUILD_DIR="$GITHUB_WORKSPACE/oqc-build" \
          RT_BUILD_DIR="$GITHUB_WORKSPACE/runtime-build" \
          PYTHON=$(which python${{ matrix.python_version }}) \
          make oqc

    # Build Quantum and Gradient Dialects
    - name: Build MLIR Dialects
      run: |
        # xcode builds very slow if we don't turn off spotlight
        sudo mdutil -i off /Users
        cmake -S mlir -B $GITHUB_WORKSPACE/quantum-build -G Ninja \
              -DCMAKE_BUILD_TYPE=Release \
              -DLLVM_ENABLE_ASSERTIONS=ON \
              -DQUANTUM_ENABLE_BINDINGS_PYTHON=ON \
              -DPython_EXECUTABLE=$(which python${{ matrix.python_version }}) \
              -DPython3_EXECUTABLE=$(which python${{ matrix.python_version }}) \
              -DPython3_NumPy_INCLUDE_DIRS=$(python${{ matrix.python_version }} -c "import numpy as np; print(np.get_include())") \
              -DMLIR_DIR="$GITHUB_WORKSPACE/llvm-build/lib/cmake/mlir" \
              -DSTABLEHLO_DIR="$GITHUB_WORKSPACE/mlir/stablehlo" \
              -DSTABLEHLO_BUILD_DIR="$GITHUB_WORKSPACE/stablehlo-build" \
              -DEnzyme_DIR="$GITHUB_WORKSPACE/enzyme-build" \
              -DENZYME_SRC_DIR="$GITHUB_WORKSPACE/mlir/Enzyme" \
              -DLLVM_ENABLE_ZLIB=FORCE_ON \
              -DLLVM_ENABLE_ZSTD=OFF \
              -DLLVM_ENABLE_LLD=OFF \
              -DLLVM_DIR="$GITHUB_WORKSPACE/llvm-build/lib/cmake/llvm"

        # xcode builds significantly slower when multithreaded
        cmake --build $GITHUB_WORKSPACE/quantum-build --target check-dialects catalyst-cli -- -j 1

    # Package the Catalyst MLIR development subsystem (headers, static libs, CMake config).
    # Only build once per platform (primary Python version) since the archive is Python-agnostic.
    - name: Package catalyst-dev (CPack)
      if: inputs.build_dev_package && matrix.python_version == needs.constants.outputs.primary_python_version
      run: |
        cd $GITHUB_WORKSPACE/quantum-build
        cpack

    - name: Upload catalyst-dev Archive
      if: inputs.build_dev_package && matrix.python_version == needs.constants.outputs.primary_python_version
      uses: actions/upload-artifact@v4
      with:
        name: catalyst-dev_macos_arm64
        path: |
          ${{ github.workspace }}/quantum-build/catalyst-dev_Darwin_arm64*.tar.gz
        retention-days: 14
        if-no-files-found: error

    - name: Build Plugin wheel
      # Run only on Thursday at the given time
      if: env.BUILD_STANDALONE_PLUGIN == 'true'
      run: |
        MLIR_DIR="$GITHUB_WORKSPACE/llvm-build/lib/cmake/mlir" \
        LLVM_BUILD_DIR="$GITHUB_WORKSPACE/llvm-build" \
        make plugin-wheel

    - name: Build wheel
      run: |
        PYTHON=python${{ matrix.python_version }} \
        LLVM_BUILD_DIR="$GITHUB_WORKSPACE/llvm-build" \
        STABLEHLO_BUILD_DIR="$GITHUB_WORKSPACE/stablehlo-build" \
        DIALECTS_BUILD_DIR="$GITHUB_WORKSPACE/quantum-build" \
        RT_BUILD_DIR="$GITHUB_WORKSPACE/runtime-build" \
        OQC_BUILD_DIR="$GITHUB_WORKSPACE/oqc-build" \
        ENZYME_BUILD_DIR="$GITHUB_WORKSPACE/enzyme-build" \
        make wheel

    - name: Repair wheel using delocate-wheel
      run: |
        # ignore-missing-dependencies only ignores libopenblas.dylib
        delocate-wheel --require-archs=arm64 -w ./wheel -v dist/*.whl --ignore-missing-dependencies -vv

    - name: Upload Wheel Artifact
      uses: actions/upload-artifact@v4
      with:
        name: catalyst-macos_arm64-wheel-py-${{ matrix.python_version }}.zip
        path: ${{ github.workspace }}/wheel/
        retention-days: 14

    - name: Upload Standalone Plugin Wheel Artifact
      # Run only on Thursday at the given time
      if: env.BUILD_STANDALONE_PLUGIN == 'true'
      uses: actions/upload-artifact@v4
      with:
        name: standalone-plugin-macos_arm64-wheel-py-${{ matrix.python_version }}.zip
        path: ${{ github.workspace }}/standalone_plugin_wheel/dist
        retention-days: 14

  test-wheels:
    needs: [constants, catalyst-macos-wheels-arm64]
    strategy:
      fail-fast: false
      matrix:
        python_version: ${{ fromJson(needs.constants.outputs.python_test_versions) }}

    # To check all wheels for supported python3 versions
    name: Test Wheels (Python ${{ matrix.python_version }}) on Mac arm64
    runs-on: macos-15

    steps:
    - name: Checkout Catalyst repo
      uses: actions/checkout@v4
      with:
        ref: ${{ inputs.branch || github.ref }}

    # choose FORWARD_COMPAT_BASE_VERSION if python version > FORWARD_COMPAT_BASE_VERSION
    - name: Determine which python build version to use
      id: python_build_version
      env:
        FORWARD_COMPAT_BASE_VERSION: ${{ needs.constants.outputs.forward_compat_python_version }}
        IS_VERSION_SUPPORTED: ${{ contains(fromJson(needs.constants.outputs.python_versions), matrix.python_version) }}
      run: |
        if [[ $IS_VERSION_SUPPORTED == "true" ]]; then
          echo "python_build_version=${{ matrix.python_version }}" >> $GITHUB_OUTPUT
        else
          echo "python_build_version=$FORWARD_COMPAT_BASE_VERSION" >> $GITHUB_OUTPUT
        fi

    - name: Download Wheel Artifact
      uses: actions/download-artifact@v4
      with:
        name: catalyst-macos_arm64-wheel-py-${{ steps.python_build_version.outputs.python_build_version }}.zip
        path: ${{ github.workspace }}/dist

    - name: Download Standalone Plugin Wheel Artifact
      # Run only on Thursday at the given time
      if: env.BUILD_STANDALONE_PLUGIN == 'true'
      uses: actions/download-artifact@v4
      with:
        name: standalone-plugin-macos_arm64-wheel-py-${{ steps.python_build_version.outputs.python_build_version }}.zip
        path: ${{ github.workspace }}/standalone_plugin_wheel/wheel

    - name: Setup Python version
      # There are multiple Python versions installed on the GitHub image, 3.12 - 3.14 is already
      # available under /Library/Frameworks/Python.framework/Versions/, but homebrew also provides
      # 3.12 - 3.14. Make sure to consistently use the system versions.
      run: |
        echo /Library/Frameworks/Python.framework/Versions/${{ matrix.python_version }}/bin >> $GITHUB_PATH

    - name: Install Python dependencies
      run: |
        python${{ matrix.python_version }} -m pip install pytest pytest-xdist pytest-mock
        # Install graphviz for testing graph visualization
        brew install graphviz
        python${{ matrix.python_version }} -m pip install graphviz pydot matplotlib

    - name: Install PennyLane Plugins
      run: |
        python${{ matrix.python_version }} -m pip install PennyLane-Lightning-Kokkos
        python${{ matrix.python_version }} -m pip install 'amazon-braket-pennylane-plugin>1.27.1'

    - name: Install OQC client
      run: |
        python_minor=$(echo "${{ matrix.python_version }}" | cut -d. -f2)
        if [ "$python_minor" -lt 13 ]; then
          python${{ matrix.python_version }} -m pip install oqc-qcaas-client
        fi

    - name: Install Catalyst
      run: |
        python${{ matrix.python_version }} -m pip install dist/*.whl --extra-index-url https://test.pypi.org/simple

    - name: Install Standalone Plugin
      # Run only on Thursday at the given time
      if: env.BUILD_STANDALONE_PLUGIN == 'true'
      run: |
        python${{ matrix.python_version }} -m pip install standalone_plugin_wheel/wheel/*.whl --no-deps

    - name: Run Python Pytest Tests
      run: |
        python${{ matrix.python_version }} -m pytest frontend/test/pytest -n auto
        python${{ matrix.python_version }} -m pytest frontend/test/pytest --backend="lightning.kokkos" -n auto -m "not xdsl"
        python${{ matrix.python_version }} -m pytest frontend/test/async_tests
        python${{ matrix.python_version }} -m pytest frontend/test/pytest --runbraket=LOCAL -n auto -m "not xdsl" || true
        python${{ matrix.python_version }} -m pytest frontend/test/test_oqc/oqc -n auto

    - name: Run Standalone Plugin Tests
      # Run only on Thursday at the given time
      if: env.BUILD_STANDALONE_PLUGIN == 'true'
      run: |
        python${{ matrix.python_version }} -m pytest standalone_plugin_wheel/standalone_plugin/test -n auto