added (most) v4 repo docs

and API docs, and some patches!

Specifically: 
- added docs/v4.md
- added docs/compile.md (WIP)
- added docs/run.md (WIP)
- added examples/README.md tutorial (WIP)
- expanded docs/compilers.md
- added test-var list to docs/cmake.md
- added API doc latex definitins
- added API doc sub-groups
- added some example API docs:
  - calcExpecPauliStr
  - calcExpecPauliStrSum
  - multiplyCompMatr1
  - applyCompMatr1
- added some example circuit diagrams using Graphviz:
  - applyCompMatr1
  - applyControlledCompMatr1
  - applyMultiControlledCompMatr1
  - applyMultiStateControlledCompMatr1
  - applyCompMatr2
  - applyControlledCompMatr2
  - applyMultiControlledCompMatr2
  - applyMultiStateControlledCompMatr2
  - applySwap
  - applyTwoQubitPhaseFlip
  - applyTwoQubitPhaseShift
- added some TODO comments to source
- patched:
  - syncQuESTEnv (which wasn't syncing GPU)
  - FullStateDiagMatr multithreaded setters (missing OpenMP if clause)

See commit breakdown in #583

Author: TysonRayJones

.github/workflows/doc.yml

@@ -41,10 +41,13 @@ jobs:
       build_dir: "build"
 
     steps:
-      - name: obtain copy of repository
+      - name: Obtain copy of repository
         uses: actions/checkout@v4
 
-      - name: generate doc with doxygen
+      - name: Install Graphviz (for circuit diagrams)
+        uses: tlylt/install-graphviz@v1
+
+      - name: Generate doc with doxygen
         uses: mattnotmitt/[email protected]
         with:
           doxyfile-path: ${{ env.doxy_file }}

README.md

@@ -40,7 +40,7 @@
 <!-- intro -->
 
 > [!NOTE]
-> QuEST `v4` has been released which re-designed QuEST from the ground up. Read about the exciting new features [here](/docs/version4.md).
+> QuEST `v4` has been released which re-designed QuEST from the ground up. Read about the exciting new features [here](/docs/v4.md).
 
 The **Quantum Exact Simulation Toolkit** (QuEST) is a high-performance simulator of quantum statevectors and density matrices.
 It hybridises **multithreading**, **GPU acceleration** and **distribution** to run lightning fast on laptops, desktops and 
@@ -87,7 +87,7 @@ To learn more:
 
 - visit the [website](https://quest.qtechtheory.org/)
 - see some [examples](/examples/)
-- view the [documentation](#book-documentation)
+- view the [documentation](#documentation)
 - browse the [API](https://quest-kit.github.io/QuEST/group__api.html)
 - read the [whitepaper](https://www.nature.com/articles/s41598-019-47174-9), which featured in Scientific Report's [Top 100 in Physics](https://www.nature.com/collections/ecehgdfcba/) :trophy:
 
@@ -187,9 +187,10 @@ QuEST supports:
 > QuEST v4's documentation is still under construction!
 
 Visit the [docs](docs/) to:
-  - [see what's new in v4](docs/version4.md)
-  - [compile with cmake](docs/cmake.md)
+  - [see what's new in v4](docs/v4.md)
+  - [compile with cmake](docs/compile.md)
   - [find compatible compilers](docs/compilers.md)
+  - [launch your simulations](docs/run.md)
   - [view some examples](examples/)
 
 The [API](https://quest-kit.github.io/QuEST/group__api.html) documentation is divided into the following groups:

docs/cmake.md

@@ -2,6 +2,7 @@
   Instructions for compiling QuEST with CMake
 
   @author Oliver Thomson Brown
+  @author Tyson Jones (test variables)
 -->
 
 
@@ -20,27 +21,47 @@ cd build
 make
 ```
 
+> [!NOTE]
 > Windows or MSVC users should additionally supply `--config Release` during compilation to enable optimisations.
 
-## QuEST CMake variables
+
+
+------------------------
+
+## QuEST variables
 
 | Variable | (Default) Values | Notes |
 | -------- | ---------------- | ----- |
 | `LIB_NAME` | (`QuEST`), String | The QuEST library will be named `lib${LIB_NAME}.so`. Can be used to differentiate multiple versions of QuEST which have been compiled. |
 | `VERBOSE_LIB_NAME` | (`OFF`), `ON` | When turned on `LIB_NAME` will be modified according to the other configuration options chosen. For example compiling QuEST with multithreading, distribution, and double precision with `VERBOSE_LIB_NAME` turned on creates `libQuEST-fp2+mt+mpi.so`. |
 | `FLOAT_PRECISION` | (`2`), `1`, `4` | Determines which floating-point precision QuEST will use: double, single, or quad. *Note: Quad precision is not supported when also compiling for GPU.* |
 | `BUILD_EXAMPLES` | (`OFF`), `ON` | Determines whether the example programs will be built alongside QuEST. Note that `min_example` is always built. |
-| `ENABLE_TESTING` | (`ON`), `OFF` | Determines whether Catch2 tests will be built alongisde QuEST. If built, tests can be run from the build directory with `make test`. |
-| `DOWNLOAD_CATCH2` | (`ON`), `OFF` | By default, if you don't have Catch2 installed (or CMake doesn't find it) it will be downloaded from Git and built for you. If you don't want that to happen, for example because you _do_ have Catch2 installed, set this to `OFF`. |
 | `ENABLE_MULTITHREADING` | (`ON`), OFF | Determines whether QuEST will be built with support for parallelisation with OpenMP. |
 | `ENABLE_DISTRIBUTION` | (`OFF`), ON | Determines whether QuEST will be built with support for parallelisation with MPI. |
 | `ENABLE_CUDA` | (`OFF`), `ON` | Determines whether QuEST will be built with support for NVIDIA GPU acceleration. If turned on, `CMAKE_CUDA_ARCHITECTURES` should probably also be set. |
 | `ENABLE_CUQUANTUM` | (`OFF`), `ON` | Determines whether QuEST will make use of the NVIDIA CuQuantum library. Cannot be turned on if `ENABLE_CUDA` is off. |
 | `ENABLE_HIP` | (`OFF`), `ON` | Determines whether QuEST will be built with support for AMD GPU acceleration. If turned on, `CMAKE_HIP_ARCHITECTURES` should probably also be set. |
-| `ENABLE_DEPRECATED_API` | (`OFF`), `ON` | Determines whether QuEST will be built with support for the deprecated (v3) API. *Note: will generate compiler warnings, and not supported by GCC.` |
+| `ENABLE_DEPRECATED_API` | (`OFF`), `ON` | Determines whether QuEST will be built with support for the deprecated (v3) API. ***Note**: this will generate compiler warnings and is not supported by MSVC.* |
 | `USER_SOURCE` | (Undefined), String | The source file for a user program which will be compiled alongside QuEST. `OUTPUT_EXE` *must* also be defined. |
 | `OUTPUT_EXE` | (Undefined), String | The name of the executable which will be created from the provided `USER_SOURCE`. `USER_SOURCE` *must* also be defined. |
 
+
+--------------------------
+
+## Test variables
+
+| Variable | (Default) Values | Notes |
+| -------- | ---------------- | ----- |
+| `ENABLE_TESTING` | (`OFF`), `ON` | Determines whether to additionally build QuEST's unit and integration tests. If built, tests can be run from the `build` directory with `make test`, or `ctest`, or manually launched with `./tests/tests` which enables distribution (i.e. `mpirun -np 8 ./tests/tests`) |
+| `ENABLE_DEPRECATED_API` | (`OFF`), `ON` | As described above. When enabled alongside testing, the `v3 deprecated` unit tests will additionally be compiled and can be run from within `build` via `cd tests/deprecated; ctest`, or manually launched with `./tests/deprecated/dep_tests` (enabling distribution, as above).
+| `DOWNLOAD_CATCH2` | (`ON`), `OFF` | QuEST's tests require Catch2. By default, if you don't have Catch2 installed (or CMake doesn't find it) it will be downloaded from Github and built for you. If you don't want that to happen, for example because you _do_ have Catch2 installed, set this to `OFF`. |
+| `TEST_MAX_NUM_QUBIT_PERMUTATIONS` | (`0`), Integer | Determines the maximum number of control and target qubit permutations with which to test each API function. Set to `0` to test all permutations, or to a positive integer (e.g. `50`) to accelerate the unit tests. |
+| `TEST_MAX_NUM_SUPEROP_TARGETS` | (`4`), Integer | Determines the maximum number of superoperator targets in the unit tests (for functions `mixKrausMap` and `mixSuperOp`). Set to `0` to impose no maximum (which is extraordinarily slow), or a positive integer (e.g. `3`) to accelerate the unit tests. |
+| `TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS` | (`10`), Integer | Determines the number of times (minimum of `1`) to repeat the randomised unit tests of functions which accept multiple distinctly-deployed `Qureg`s. Set to a small, positive integer to accelerate mixed-deployment unit tests. |
+| `TEST_ALL_DEPLOYMENTS` | (`ON`), `OFF` | Determines whether unit tests will be repeatedly run using all possible combinations of available `Qureg` deployments (i.e. `OpenMP` and/or `CUDA` and/or `MPI`), else only once using all available deployments simultaneously. Set to `OFF` to accelerate unit tests. |
+
+---------------------------
+
 ## Standard CMake variables
 
 | Variable | Description | CMake Doc Page |