Merge branch 'v4' into new-readmes

.github/scripts/setup_cuda.ps1

@@ -0,0 +1,106 @@
+# - written by thewh1teagle (github.com/thewh1teagle)
+# - taken from Vibe (github.com/thewh1teagle/vibe)
+# - perma: https://github.com/thewh1teagle/vibe/blob/5ee8bf7e74a01429cfd164590fce2e4fcd07fae0/.github/workflows/windows_special.yml#L80
+
+
+
+$CUDA_VERSION_FULL = $env:INPUT_CUDA_VERSION # v12.5.0 or v11.8.0
+
+# Make sure CUDA_VERSION_FULL is set and valid, otherwise error.
+# Validate CUDA version, extracting components via regex
+$cuda_ver_matched = $CUDA_VERSION_FULL -match "^(?<major>[1-9][0-9]*)\.(?<minor>[0-9]+)\.(?<patch>[0-9]+)$"
+if(-not $cuda_ver_matched){
+    Write-Output "Invalid CUDA version specified, <major>.<minor>.<patch> required. '$CUDA_VERSION_FULL'."
+    exit 1
+}
+$CUDA_MAJOR=$Matches.major
+$CUDA_MINOR=$Matches.minor
+$CUDA_PATCH=$Matches.patch
+
+Write-Output "Selected CUDA version: $CUDA_VERSION_FULL"
+
+$src = "cuda"
+$dst = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v$($CUDA_MAJOR).$($CUDA_MINOR)"
+$installer = "cuda.exe"
+
+if ($CUDA_VERSION_FULL -eq "12.5.0") {
+    $downloadUrl = "https://developer.download.nvidia.com/compute/cuda/12.5.0/local_installers/cuda_12.5.0_555.85_windows.exe"
+} elseif ($CUDA_VERSION_FULL -eq "11.8.0") {
+    $downloadUrl = "https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_522.06_windows.exe"
+} else {
+    Write-Output "Unsupported CUDA version specified"
+    exit 1
+}
+
+# Download cuda
+Write-Output "Downloading CUDA from: $downloadUrl"
+if (-not (Test-Path -Path $installer)) {
+    Write-Output "Downloading CUDA installer..."
+    # If the file does not exist, download it
+    & "C:\msys64\usr\bin\wget" $downloadUrl -O $installer -q
+}
+
+# Extract cuda
+if (-not (Test-Path -Path $src -Type Container)) {
+    # Extract CUDA using 7-Zip
+    Write-Output "Extracting CUDA using 7-Zip..."
+    mkdir "$src"
+    & 'C:\Program Files\7-Zip\7z' x $installer -o"$src"
+}
+
+# Create destination directory if it doesn't exist
+if (-Not (Test-Path -Path $dst)) {
+    Write-Output "Creating destination directory: $dst"
+    New-Item -Path $dst -ItemType Directory
+}
+
+# Get directories to process from the source path
+$directories = Get-ChildItem -Directory -Path $src
+$whitelist = @("CUDA_Toolkit_Release_Notes.txt", "DOCS", "EULA.txt", "LICENSE", "README", "version.json")
+
+foreach ($dir in $directories) {
+    # Get all subdirectories and files in the current directory
+    $items = Get-ChildItem -Path (Join-Path $src $dir.Name)
+
+    foreach ($item in $items) {
+        if ($item.PSIsContainer) {
+            # If the item is a directory, copy its contents
+            Write-Output "Copying contents of directory $($item.FullName) to $dst"
+            Copy-Item -Path "$($item.FullName)\*" -Destination $dst -Recurse -Force
+        } else {
+            if ($whitelist -contains $item.Name) {
+                Write-Output "Copying file $($item.FullName) to $dst"
+                Copy-Item -Path $item.FullName -Destination $dst -Force
+            }
+        }
+    }
+}
+
+# Add msbuild cuda extensions
+$msBuildExtensions = (Get-ChildItem  "$src\visual_studio_integration\CUDAVisualStudioIntegration\extras\visual_studio_integration\MSBuildExtensions").fullname
+(Get-ChildItem 'C:\Program Files\Microsoft Visual Studio\2022\*\MSBuild\Microsoft\VC\*\BuildCustomizations').FullName | ForEach-Object { 
+    $destination = $_
+    $msBuildExtensions | ForEach-Object {
+        $extension = $_
+        Copy-Item $extension -Destination $destination -Force
+        Write-Output "Copied $extension to $destination"
+    }
+}
+
+# Add to Github env
+Write-Output "Setting environment variables for GitHub Actions..."
+
+Write-Output "CUDA_PATH=$dst"
+Write-Output "CUDA_PATH_V$($CUDA_MAJOR)_$($CUDA_MINOR)=$dst"
+Write-Output "CUDA_PATH_VX_Y=CUDA_PATH_V$($CUDA_MAJOR)_$($CUDA_MINOR)"
+Write-Output "CUDA_VERSION=$CUDA_VERSION_FULL"
+
+Write-Output "CUDA_PATH=$dst" >> $env:GITHUB_ENV
+Write-Output "CUDA_PATH_V$($CUDA_MAJOR)_$($CUDA_MINOR)=$dst" >> $env:GITHUB_ENV
+Write-Output "CUDA_PATH_VX_Y=CUDA_PATH_V$($CUDA_MAJOR)_$($CUDA_MINOR)" >> $env:GITHUB_ENV
+Write-Output "CudaToolkitDir=$dst" >> $env:GITHUB_ENV
+Write-Output "CMAKE_CUDA_COMPILER=$dst\bin\nvcc.exe" >> $env:GITHUB_ENV
+Write-Output "NVCC_APPEND_FLAGS=-allow-unsupported-compiler" >> $env:GITHUB_ENV
+
+Write-Output "CUDA_VERSION=$CUDA_VERSION_FULL" >> $env:GITHUB_ENV
+Write-Output "Setup completed."

.github/workflows/audit.yml

@@ -0,0 +1,177 @@
+name: audit
+
+
+on:
+  push:
+    branches:
+      - v4
+  pull_request:
+    branches:
+      - v4
+
+
+jobs:
+
+
+  # run LLVM address sanitiser
+  sanitisation-test:
+    name: address sanitisation [${{ matrix.precision }}]
+    runs-on: macos-latest
+
+    # try all precisions without aborting
+    strategy:
+      fail-fast: false
+      matrix:
+        precision: [1, 2, 4]
+
+    # constants (which I cannot split overlines, GRR)
+    env:
+      build_dir: "build"
+      sanitiser_flags: -g -fno-omit-frame-pointer -fno-optimize-sibling-calls -fsanitize=address -fsanitize-address-use-after-scope
+
+    # perform the job
+    steps:
+      - name: Get QuEST
+        uses: actions/checkout@v4
+
+      # compile QuEST using clang address sanitiser, foregoing all parallelisations
+      - name: Configure CMake to use sanitiser
+        run: >
+          cmake -B ${{ env.build_dir }}
+          -DCMAKE_CXX_COMPILER=clang++
+          -DENABLE_TESTING=ON
+          -DENABLE_MULTITHREADING=OFF
+          -DFLOAT_PRECISION=${{ matrix.precision }}
+          -DCMAKE_CXX_FLAGS="${{ env.sanitiser_flags }}"
+          -DCMAKE_EXE_LINKER_FLAGS="${{ env.sanitiser_flags }}"
+
+      - name: Compile with sanitiser
+        run: cmake --build ${{ env.build_dir }}
+
+      # run unit tests in random order, excluding the integration tests
+      # TODO:
+      # ctest currently doesn't know of our Catch2 tags, so we
+      # are manually excluding each integration test by name
+      - name: Run unit tests with active sanitiser
+        run: ctest -j2 --output-on-failure --schedule-random -E "density evolution"
+        working-directory: ${{ env.build_dir }}
+
+
+  # run valgrind
+  memory-leak-test:
+    name: memory checks [${{ matrix.precision }}]
+    runs-on: ubuntu-latest
+
+    # try all precisions without aborting
+    strategy:
+      fail-fast: false
+      matrix:
+        precision: [1, 2, 4]
+
+    # constants (which I cannot split overlines, GRR)
+    env:
+      build_dir: "build"
+
+    # perform the job
+    steps:
+      - name: Get QuEST
+        uses: actions/checkout@v4
+
+      # compile QuEST like normal albeit without parallelisations
+      - name: Configure CMake
+        run: >
+          cmake -B ${{ env.build_dir }}
+          -DENABLE_TESTING=ON
+          -DENABLE_MULTITHREADING=OFF
+          -DFLOAT_PRECISION=${{ matrix.precision }}
+
+      - name: Compile QuEST
+        run: cmake --build ${{ env.build_dir }}
+
+      - name: Install valgrind
+        run: sudo apt install -y valgrind
+
+      # make valgrind fail CI if detecting issue when running unit tests in a randomised order
+      # TODO:
+      # ctest currently doesn't know of our Catch2 tags, so we are 
+      # manually excluding each integration test by name
+      - name: Run unit tests under valgrind
+        run: >
+          valgrind --leak-check=full --error-exitcode=1 
+          ctest -j2 --output-on-failure --schedule-random -E "density evolution"
+        working-directory: ${{ env.build_dir }}
+
+
+  # run lcov
+  coverage-test:
+    name: code coverage
+
+    # test only serial double-precision QuEST on Ubuntu
+    runs-on: ubuntu-latest
+
+    # constants: CI will fail if coverage less than below percent
+    # TODO: this is currently so low (1%) because we really need
+    # to run in MPI + GPU mode for reliable coverage statistics
+    env:
+      min_coverage: 1 # %
+      tracefile: "coverage.info"
+
+    # perform the job
+    steps:
+      - name: Get QuEST
+        uses: actions/checkout@v4
+
+      # work in a build directory to reduce verbosity below
+      - run: > 
+          mkdir build;
+          cd build
+
+      # compile QuEST and unit tests in coverage mode. We opt to use
+      # Release mode (rather than Debug) and permit e.g. inlining for
+      # performance (else the runner times out), though this could
+      # corrupt the statistics in the future (it doesn't now, strangely)
+      - name: Configure CMake
+        run: >
+          cmake -B .
+          -DCMAKE_BUILD_TYPE=Release
+          -DENABLE_TESTING=ON
+          -DENABLE_MULTITHREADING=OFF
+          -DCMAKE_CXX_FLAGS="--coverage"
+          -DCMAKE_EXE_LINKER_FLAGS="--coverage"
+
+      - name: Compile unit tests
+        run: make
+
+      # run the unit tests, saving coverage data to file
+      - name: Run unit tests
+        run: ctest -j2 --output-on-failure
+
+      # analyse the unit test coverage
+      - name: Setup LCOV
+        uses: hrishikesh-kadam/setup-lcov@v1
+
+      - name: Run LCOV
+        run: lcov --directory . --capture --output-file ${{ env.tracefile }} --ignore-errors source
+
+      # remove standard-library and testing and code from coverage data
+      - name: Filter LCOV results
+        run: lcov --remove ${{ env.tracefile }} '/usr/*' '*/tests/*' '*/_deps/*' --output-file ${{ env.tracefile }}
+
+      # TODO: temporarily remove MPI and GPU files from coverage stats, since unused
+      - name: Remove MPI and GPU coverage
+        run: lcov --remove ${{ env.tracefile }} '*/comm/*' '*/gpu/*' --output-file ${{ env.tracefile }}
+
+      # touched files are correct but percentages are strangely reported wrong in preview,
+      # even though the subsequent reporting below is correct - weird! 
+      - name: Preview LCOV results (percentages are wrong)
+        run: lcov --list ${{ env.tracefile }}
+
+      # report coverage of remaining files in the triggering PR
+      - name: Report code coverage
+        uses: zgosalvez/github-actions-report-lcov@v4
+        with:
+          artifact-name: code-coverage-report
+          update-comment: true
+          coverage-files: ./${{ env.tracefile }}
+          minimum-coverage: ${{ env.min_coverage }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}