Add manually-triggered debugging workflow

.github/workflows/pytest-debug.yaml

@@ -0,0 +1,153 @@
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Summary: GitHub workflow for manually running pytest with debug flags.
+#
+# This workflow can only be executed manually, e.g., using the "Run workflow"
+# button on https://github.com/quantumlib/Cirq/actions/workflows/debug.yaml
+# Clicking the "Run workflow" button there will present a form interface with
+# various options for the characteristics of the run.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+name: Run pytest with debug options
+
+on:
+  workflow_dispatch:
+    inputs:
+      py-version:
+        description: "Python version:"
+        type: choice
+        default: "3.12"
+        options:
+          - "3.13"
+          - "3.12"
+          - "3.11"
+          - "3.10"
+
+      os:
+        description: "Runner OS:"
+        type: choice
+        default: ubuntu-20.04
+        options:
+          - ubuntu-22.04
+          - ubuntu-20.04
+          - macos-15
+          - macos-14
+          - macos-13
+          - windows-2025
+          - windows-2022
+          - windows-2019
+
+      arch:
+        description: "Hardware architecture:"
+        type: choice
+        default: x64
+        options:
+          - x64
+          - arm64
+
+      single-test:
+        description: "Run specific single test:"
+        type: string
+        default: ""
+
+      repetitions:
+        description: "Number of repetitions:"
+        type: number
+        default: 1
+
+      random-seed:
+        description: "Explicit random seed:"
+        type: number
+
+      multiple-workers:
+        description: "Use multiple pytest workers"
+        type: boolean
+        default: true
+
+      verbose:
+        description: "Turn on verbose tracing"
+        type: boolean
+        default: false
+
+      exit-first:
+        description: "Stop at first error"
+        type: boolean
+        default: true
+
+      include-rigetti:
+        description: "Include rigetti module"
+        type: boolean
+        default: false
+
+run-name: |
+  Pytest ${{inputs.single-test || '(all tests)' }} on ${{inputs.os}}
+  ${{inputs.arch}} with Python ${{inputs.py-version}}
+
+jobs:
+  pytest:
+    name: Run pytest
+    runs-on: ${{github.event.inputs.os}}
+    steps:
+      - name: Do miscellaneous preliminary configuration steps
+        run: |
+          mkdir -p ~/.cache/pip
+
+      - name: Check out a copy of the Cirq git repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{github.event.inputs.py-version}}
+          architecture: ${{github.event.inputs.arch}}
+          cache: pip
+          cache-dependency-path: |
+            dev_tools/requirements/*.txt
+            dev_tools/requirements/deps/*.txt
+
+      - name: Install Python requirements
+        run: |
+          set -e
+          requirements="dev_tools/requirements/dev.env.txt"
+          pip install --upgrade pip setuptools wheel
+          pip install --upgrade --upgrade-strategy eager -r "$requirements"
+
+      - name: Start Quil dependencies if needed
+        if: inputs.include-rigetti == true || inputs.include-rigetti == 'true'
+        run: docker compose -f cirq-rigetti/docker-compose.test.yaml up -d
+
+      - name: Run pytest
+        run: |
+          # Configure flags for pytest.
+          flags="--durations=20 --strict-config --ignore=cirq-core/cirq/contrib"
+          workers="-n auto"
+          if [[ -n "${{github.event.inputs.random-seed}}" ]]; then
+            flags=" --randomly-seed=${{github.event.inputs.random-seed}}"
+          fi
+          if [[ "${{github.event.inputs.multiple-workers}}" == "false" ]]; then
+            workers="-n0"
+          fi
+          if [[ "${{github.event.inputs.verbose}}" == "true" ]]; then
+            flags+="-vv --full-trace --setup-show"
+            # Save Python info to the run log, in case it's useful.
+            which python
+            pip list
+          fi
+          if [[ "${{github.event.inputs.include-rigetti}}" == true ]]; then
+            flags+=" --rigetti-integration"
+          fi
+          if [[ "${{github.event.inputs.exit-first}}" == "true" ]]; then
+            flags+=" --exitfirst"
+            set -e
+          fi
+          # Now finally run pytest, as many times as requested.
+          for i in $(seq 1 ${{github.event.inputs.repetitions}}); do
+            echo ""
+            echo -n "︎▞▚▞ Iteration $i ▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚"
+            echo    "▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞"
+            echo ""
+            check/pytest $workers $flags ${{github.event.inputs.single-test}}
+          done
+
+      - name: Stop Quil dependencies if needed
+        if: inputs.include-rigetti == true || inputs.include-rigetti == 'true'
+        run: docker compose -f cirq-rigetti/docker-compose.test.yaml down