extended CI example testing

Now, all standalone C and C++ files in the 'isolated' and 'automated' subdirectories of 'examples' will be executed by the compiler Github Action. The former is to just catch/log interface issues not reflected by the unit tests, while the latter empowers external contributors to include casual test code with their PRs which will be run cross-platform, cross-compiler and cross-precision. This is a much easier alternative to users attempting to include unit tests in their PRs,  and has been setup in preparation for unitaryHACK 2025.

 Also documented each examples subdir

Author: TysonRayJones

.github/workflows/compile.yml

@@ -2,16 +2,21 @@
 # code with (attemptedly) all possible configurations
 # of operating system, precision, multithreading,
 # distribution, GPU-acceleration (via CUDA or HIP),
-# and cuQuantum (else custom kernels). Currently,
-# this wastefully downlaods and installs all needed
-# compilers (like libomp, CUDA, ROCm). Compilation
+# and cuQuantum (else custom kernels). Compilation
 # includes the v4 unit and integration tests, the
 # deprecated v3 tests (when possible), and all the
-# example programs. One example executable is then
-# run (both C and C++ versions) to ensure the build
-# was successful and does not cause link-time errors.
-# Note that ARM compilation is not yet tested here,
-# but in fact Linux ARM is used by a paid test runner.
+# example programs. All 'isolated' example executables
+# are then run (both C and C++ versions) to ensure the 
+# build was successful and does not cause link-time 
+# errors. Then, all 'automated' examples are run which
+# permits contributors to demo or test their changes 
+# across all operation systems and compilers.
+# 
+# Note:
+# - This workflow currently wastefully re-downloads and 
+#   installs all needed compilers (like libomp, CUDA, ROCm)
+# - ARM compilation is not tested here, though it is used
+#   by the paid multithreaded CI tests.
 #
 # @author Tyson Jones
 
@@ -142,12 +147,12 @@ jobs:
 
     # constants
     env:
-      build_dir: "build"
       cuda_arch: 70
       hip_arch: gfx801
       rocm_path: /opt/rocm/bin
-      example_dir: build/examples/isolated
-      example_fn_pref: reporting_quregs
+      build_dir: build
+      isolated_dir: build/examples/isolated
+      automated_dir: build/examples/automated
 
     # perform the job
     steps:
@@ -237,15 +242,43 @@ jobs:
       - name: Compile
         run: cmake --build ${{ env.build_dir }} --config Release --parallel
 
-      # attempt to run the compiled executable, testing for link-time errors,
-      # logging stdout and stderr to file (to verify the executable actually ran)
-      - name: Run (Windows)
+      # run all compiled isolated examples to test for link-time errors,
+      # continuing if any fail (since some deliberately fail)
+      - name: Run isolated examples (Windows)
         if: ${{ matrix.os == 'windows-latest' }}
+        working-directory: ${{ env.isolated_dir }}/Release/
+        shell: pwsh
+        run: |
+          Get-ChildItem -Filter '*.exe' -File |
+          ForEach-Object {
+            Write-Host "`r`n[[[ $($_.Name) ]]]`r`n"
+            & $_.FullName
+          }
+      - name: Run isolated examples (Unix)
+        if: ${{ matrix.os != 'windows-latest' }}
+        working-directory: ${{ env.isolated_dir }}
+        run: |
+          for fn in *_c *_cpp; do
+            printf "\n[[[ $fn ]]]\n"
+            ./$fn || true
+          done
+
+      # run all compiled 'automated' examples
+      - name: Run automated examples (Windows)
+        if: ${{ matrix.os == 'windows-latest' }}
+        working-directory: ${{ env.automated_dir }}/Release/
+        shell: pwsh
         run: |
-          ./${{ env.example_dir }}/Release/${{ env.example_fn_pref }}_c.exe
-          ./${{ env.example_dir }}/Release/${{ env.example_fn_pref }}_cpp.exe
-      - name: Run (non-Windows)
+          Get-ChildItem -Filter '*.exe' -File |
+          ForEach-Object {
+            Write-Host "`r`n[[[ $($_.Name) ]]]`r`n"
+            & $_.FullName
+          }
+      - name: Run automated examples (Unix)
         if: ${{ matrix.os != 'windows-latest' }}
+        working-directory: ${{ env.automated_dir }}
         run: |
-          ./${{ env.example_dir }}/${{ env.example_fn_pref }}_c
-          ./${{ env.example_dir }}/${{ env.example_fn_pref }}_cpp
+          for fn in *_c *_cpp; do
+            printf "\n[[[ $fn ]]]\n"
+            ./$fn || true
+          done

examples/CMakeLists.txt

@@ -59,3 +59,4 @@ endfunction()
 
 add_subdirectory(isolated)
 add_subdirectory(extended)
+add_subdirectory(automated)

examples/README.md

@@ -7,6 +7,8 @@
   @author Tyson Jones
 -->
 
-The above folders contain example `C` and `C++` files which use QuEST's [API](https://quest-kit.github.io/QuEST/group__api.html), helping illustrate how to use specific functions. Instructions for compiling and running them are given in [`compile.md`](/docs/compile.md#tests) and [`launch.md`](/docs/launch.md#tests) respectively.
+These folders contain example `C` and `C++` files which use QuEST's [API](https://quest-kit.github.io/QuEST/group__api.html), helping illustrate how to use specific functions. Instructions for compiling and running them are given in [`compile.md`](/docs/compile.md#tests) and [`launch.md`](/docs/launch.md#tests) respectively, though some are automatically run by Github Actions.
 <!-- @todo the above links would fail Doxygen, which does not recognise the #section syntax.
      no problem here however because doxygen fails to render this page all together -->
+
+A description of each folder is given within.

examples/automated/CMakeLists.txt

@@ -0,0 +1,3 @@
+# @author Tyson Jones
+
+add_all_local_examples()

examples/automated/README.md

@@ -0,0 +1,25 @@
+# 🔖🤖  Automated examples
+
+<!--
+  CI-triggered examples
+  (this comment must be under the title for valid doxygen rendering)
+  
+  @author Tyson Jones
+-->
+
+This folder contains examples which are compiled and executed by QuEST's `compile` Github Action, on [free runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners).
+Contributors can include rudimentary testing or demo code in this folder (as standalone `.c` or `.cpp` files)
+in their pull requests and preview its output on Github, where it is run with every combination of operating system, compiler and precision. 
+This is intended for debugging and/or logging purposes, rather than for presenting example codes for users.
+
+> [!IMPORTANT] 
+> Beware that the configurations include use of multithreading, distribution and GPU-acceleration (as `OMP`, `MPI` and `CUDA` respectively) though this reflects only their _compilation_. All files are executed serially and locally on the CPU.
+
+The output can be viewed at the `compile.yml`
+[workflow tab](https://github.com/QuEST-Kit/QuEST/actions/workflows/compile.yml), clicking on the PR name, selecting a configuration (such as `Windows [1] OMP`) and expanding the `run automated examples` section. All files within `automated/` will be run in-turn and their outputs sequentially presented.
+
+> [!IMPORTANT] 
+> Since these examples are executed at every invocation of the CI, they should _not_ perform intensive, long computations. Such examples are better suited for the [`extended/`](../extended/) folder.
+
+> [!TIP] 
+> Files with extensions `.c` or `.cpp` will be respectively compiled in `C11` and `C++17`. An example which uses a facility sensitive to the language can be duplicated as both `file.c` and `file.cpp` so that both versions are tested.

examples/automated/report_quest_env.c

@@ -0,0 +1,14 @@
+/** @file
+ * Shows the output of reportQuESTEnv() on
+ * Github Action runners
+ * 
+ * @author Tyson Jones
+*/
+
+#include "quest.h"
+
+int main() {
+    initQuESTEnv();
+    reportQuESTEnv();
+    finalizeQuESTEnv();
+}

examples/extended/README.md

@@ -0,0 +1,11 @@
+# 🔖📚  Extended examples
+
+<!--
+  Extended examples
+  (this comment must be under the title for valid doxygen rendering)
+  
+  @author Tyson Jones
+-->
+
+This folder contains _extended_ examples which demonstrate the use of QuEST in standalone applications, such as the emulation of canonical quantum algorithms. We provide both `C` and `C++` versions (compiled against standards `C11` and `C++17`) of each example. All fines herein are _compiled_ (but not executed) by the [compile](https://github.com/QuEST-Kit/QuEST/actions/workflows/compile.yml) Github Action.
+

examples/extended/dynamics.c

@@ -1,3 +1,12 @@
+/** @file
+ * An example of using QuEST (primarily function
+ * applyTrotterizedPauliStrSumGadget()) to perform
+ * dynamical simulation via Trotterisation of the
+ * unitary-time evolution operator.
+ * 
+ * @author Tyson Jones
+*/
+
 #include "quest.h"
 #include <stdio.h>
 #include <stdlib.h>

examples/extended/dynamics.cpp

@@ -1,3 +1,12 @@
+/** @file
+ * An example of using QuEST (primarily function
+ * applyTrotterizedPauliStrSumGadget()) to perform
+ * dynamical simulation via Trotterisation of the
+ * unitary-time evolution operator.
+ * 
+ * @author Tyson Jones
+*/
+
 #include "quest.h"
 #include <vector>
 #include <string>

examples/isolated/README.md

@@ -0,0 +1,12 @@
+# 🔖🔍  Isolated examples
+
+<!--
+  Isolated examples
+  (this comment must be under the title for valid doxygen rendering)
+  
+  @author Tyson Jones
+-->
+
+This folder contains _isolated_ examples which demonstrate the possible uses of a specific QuEST function or facility. They mostly serve to illustrate the various ways that a single task (such as initialising a `KrausMap`) can be performed with the QuEST API. We provide both `C` and `C++` versions (compiled against standards `C11` and `C++17`) of each example to highlight the interfaces available to the respective languages.
+
+Every `.c` and `.cpp` in this folder is compiled _and_ executed by the [compile](https://github.com/QuEST-Kit/QuEST/actions/workflows/compile.yml) Github Action, to automatically check for compilation and link-time issues.