pnl-ci.yml

name: PsyNeuLink CI

on:
  schedule:
    - cron: "35 5 * * *"
  push:
    branches-ignore:
      - 'dependabot/**'
    paths-ignore:
      - 'docs/**'
      - 'doc_requirements.txt'
    tags-ignore:
      - 'v**'
  pull_request:

# run only the latest instance of this workflow job for the current branch/PR
# cancel older runs
# fall back to run id if not available (run id is unique -> no cancellations)
concurrency:
  group: ci-${{ github.ref || github.run_id }}-${{ github.workflow }}
  cancel-in-progress: true

jobs:
  # The main test job
  build:
    # Explanation of the expression below:
    # line 1: Check if the job environment is listed in repository-scale "SELF_HOSTED" variable
    # line 2: "true" branch. Construct tag array to match one of the self hosted runners. All tags need to match.
    # line 3: "else" branch. Construct GA image description. Generally the {windows,macos,ubuntu}-latest.
    runs-on: ${{ (contains(vars.SELF_HOSTED, format(';{0}_{1}_{2};', matrix.os, matrix.python-version, matrix.extra-args))
                && fromJSON(format('[ "self-hosted","{0}", "X64", "enabled" ]', matrix.os == 'ubuntu' && 'Linux' || matrix.os)))
                || format('{0}-latest', matrix.os) }}
    env:
      # Keep DESCRIPTION in sync with the above
      DESCRIPTION: ${{ format(';{0}_{1}_{2};', matrix.os, matrix.python-version, matrix.extra-args) }}
      SELF_HOSTED: ${{ vars.SELF_HOSTED }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.8', '3.11', '3.12', '3.13', '3.14']
        extra-args: ['']
        os: [ubuntu, macos, windows]
        version-restrict: ['']
        torch: ['']
        include:
          # --forked run of python only tests
          # Python tests are enough to test potential naming issues
          - python-version: '3.9'
            os: ubuntu
            extra-args: '--forked -m "not llvm"'

          # --benchmark-enable run on macos python 3.9
          - python-version: '3.9'
            os: macos
            # pytest needs both '--benchmark-only' and '-m benchmark'
            # The former fails the test if benchmarks cannot be enabled
            # (e.g. due to --dist setting)
            # The latter works around a crash in pytest when collecting tests:
            # https://github.com/ionelmc/pytest-benchmark/issues/243
            extra-args: '-m benchmark --benchmark-enable --benchmark-only --benchmark-min-rounds=2 --benchmark-max-time=0.001 --benchmark-warmup=off -n0 --dist=no'

          # fp32 run on linux python 3.10
          - python-version: '3.10'
            os: ubuntu
            extra-args: '--fp-precision=fp32'

          # code-coverage run on macos python 3.10
          - python-version: '3.10'
            os: macos
            extra-args: '--cov=psyneulink'

          # run without pytorch on windows python 3.10
          - python-version: '3.10'
            os: windows
            torch: 'notorch'

          # add python 3.8 with deps restricted to min supported package versions
          - python-version: '3.8'
            os: macos
            version-restrict: 'min'

        exclude:
          - python-version: '3.8'
            os: macos

    steps:
    # increased fetch-depth and tag checkout needed to get correct
    # version string from versioneer (must have history to a prior tag);
    # otherwise install fails due to circular dependency with modeci_mdf
    - name: Checkout sources
      uses: actions/checkout@v6
      with:
        fetch-depth: 200

    # fetch only master to avoid getting unneeded branches with
    # characters invalid on windows
    - name: Checkout tags
      run: git fetch --tags origin master

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v6
      with:
        python-version: ${{ matrix.python-version }}

    - name: Restrict version of direct dependencies
      if: ${{ matrix.version-restrict == 'min' }}
      shell: bash
      run: |
        # macos/bsd sed requires backup suffix argument to -i
        sed -i=.bak -e '/^[^#]/s/>=/==/' *requirements.txt
        git config user.name "github actions"
        git config user.email "none"
        git commit -a -m "Restrict version of direct dependencies to min"

    - name: Get pip cache location
      shell: bash
      id: pip_cache
      run: |
        python -m pip install -U pip
        python -m pip --version
        echo "pip_cache_dir=$(python -m pip cache dir)" | tee -a $GITHUB_OUTPUT

    - name: Restore wheels cache
      uses: actions/cache/restore@v5
      with:
        path: ${{ steps.pip_cache.outputs.pip_cache_dir }}/wheels
        key: ${{ runner.os }}-python-${{ matrix.python-version }}-pip-wheels-${{ hashFiles('requirements.txt', 'dev_requirements.txt') }}-${{ github.sha }}
        restore-keys: ${{ runner.os }}-python-${{ matrix.python-version }}-pip-wheels-${{ hashFiles('requirements.txt', 'dev_requirements.txt') }}

    - name: Drop PyTorch requirement
      if: ${{ matrix.torch == 'notorch' }}
      shell: bash
      run: |
        # macos/bsd sed requires backup suffix argument to -i
        sed -i=.bak -e '/torch/d' requirements.txt
        sed -i=.bak -e '/modeci_mdf/d' requirements.txt

    - name: Install PNL package
      uses: ./.github/actions/install-pnl
      id: install
      with:
        features: 'dev'

    - name: Save wheels cache
      uses: actions/cache/save@v5
      if: always()
      with:
        path: ${{ steps.pip_cache.outputs.pip_cache_dir }}/wheels
        key: ${{ runner.os }}-python-${{ matrix.python-version }}-pip-wheels-${{ hashFiles('requirements.txt', 'dev_requirements.txt') }}-${{ github.sha }}

    - name: Lint with flake8
      shell: bash
      run: |
        pip install flake8 flake8-unused-arguments

        # stop build if there are unused arguments in tests (these might be fixtures)
        flake8 tests/ --select=U100 --unused-arguments-ignore-stub-functions --unused-arguments-ignore-lambdas --unused-arguments-ignore-nested-functions --unused-arguments-ignore-variadic-names --extend-exclude tests/functions/test_user_defined_func.py

        # stop the build if there are Python syntax errors or undefined names
        # exclude F821 "unknown names" as there are quite a few of them around PNL
        flake8 . --count --select=E9,F63,F7,F82 --extend-ignore=F821 --show-source  --extend-exclude Scripts/

        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics

    - name: Print numpy info
      shell: bash
      run: |
        python -c "import numpy; numpy.show_config()"

    - name: Print machine info
      shell: bash
      run: |
        case "$RUNNER_OS" in
          Linux*) lscpu; lsmem;;
          macOS*) sysctl -a | grep '^hw' ;;
          Windows*)
            powershell -c "Get-CimInstance -ClassName Win32_Processor | Select-Object Description,CurrentClockSpeed,NumberOfCores,NumberOfEnabledCore,NumberOfLogicalProcessors"
            powershell -c "Get-CimInstance -ClassName Win32_PhysicalMemory | Select-Object Capacity,Speed,Status,Manufacturer"
            ;;
        esac

    # Windows runners use MS Edge as the default pdf viewer.
    # This causes issues if any of the tests calls show_graph()
    # or any other routine that by default produces a .pdf file
    # and opens is in the default application.
    # The problem with MS Edge is that it intermittently fails
    # to exit and hangs the entire CI job in the last step.
    # see: https://github.com/actions/runner/issues/3383
    # Removing the default .pdf file association on windows is
    # quite difficult because it needs to check multiple places
    # and elevated privileges.
    # Installing an alternative pdf viewer works around the issue
    # as it prevents MS Edge from running when .pdf is displayed.
    - name: Install windows pdf viewer
      shell: bash
      if: ${{ matrix.os == 'windows' }}
      run: |
          choco install --no-progress -y sumatrapdf.install

    - name: Test with pytest
      timeout-minutes: 180
      run: pytest --junit-xml=tests_out.xml --verbosity=0 -n logical --capture=sys -o console_output_style=count ${{ matrix.extra-args }}

    - name: Upload test results
      uses: actions/upload-artifact@v6
      with:
        name: test-results-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.version-restrict }}
        path: tests_out.xml
        retention-days: 5
      if: (success() || failure()) && ! contains(matrix.extra-args, 'forked')

    - name: Check that PyTorch wasn't transitively included
      if: ${{ matrix.torch == 'notorch' }}
      shell: bash
      run: |
        ! pip show torch

    - name: Upload coveralls code coverage
      if: contains(matrix.extra-args, '--cov=psyneulink')
      shell: bash
      env:
        COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
      run: |
        if [ -n "$COVERALLS_REPO_TOKEN" ]; then
          pip install coveralls
          coveralls
        else
          echo "::warning::Not uploading to coveralls.io, token not available!"
        fi

    - name: Upload dist packages
      uses: actions/upload-artifact@v6
      if: matrix.version-restrict == ''
      with:
        name: dist-${{ matrix.os }}-${{ matrix.python-version }}
        path: |
          ${{ steps.install.outputs.wheel }}
          ${{ steps.install.outputs.sdist }}
        retention-days: 2

    # this step is kept for debugging hangs at the end of runner execution.
    - name: List running processes
      shell: pwsh
      if: ${{ matrix.os == 'windows' }}
      run: |
        Get-Process;