updated doc (#621)

including
- removing references to defunct `invalidQuESTInputError`
- essential doc needed to disambiguate function conventions (like relationship between function parameters and effected operation phases)
- renamed Doxygen keyword `@equivalent` to `@equivalences`
- ... `@notvalidated` to `@notyetvalidated`
- ... `@notdoced` to `@notyetdoced`
- ... `@nottested` to `@notyettested`
- changed some `@cpponly` functions into new `@cppvectoroverload`, and then hid the latter
- added links from doc to the example PR
- linked `C++`-overload doc to corresponding `C` function (using `@see`)

Author: TysonRayJones

docs/architecture.md

@@ -7,6 +7,10 @@
   @author Tyson Jones
 -->
 
+> [!TIP]
+> See [PR #615](https://github.com/QuEST-Kit/QuEST/pull/615) for an illustration of integrating 
+> new functions into the QuEST software architecture.
+
 All user-visible API signatures are contained in `include/`, divided into semantic submodules (like `calculations.h` and `qureg.h`), but all exposed by `quest.h`. They are all strictly `C` _and_ `C++` compatible, hence their `.h` file extension.
 
 The source code within `src/` is divided between five subdirectories, listed below in order of increasing control flow depth. All code is parsed strictly by `C++`, hence all files have `.cpp` and `.hpp` extensions.

docs/contributing.md

@@ -13,3 +13,7 @@
 <!--- @todo -->
 
 In the meantime, feel free to open an issue, a discussion or a pull request, or reach out to `[email protected]`.
+
+> [!TIP]
+> See [PR #615](https://github.com/QuEST-Kit/QuEST/pull/615) for an illustration of integrating 
+> new functions into the QuEST software architecture.

docs/launch.md

@@ -595,7 +595,7 @@ For convenience however, we offer some example [SLURM](https://slurm.schedmd.com
 #SBATCH --nodes=4
 #SBATCH --ntasks-per-node=1
 #SBATCH --cpus-per-task=8
-OMP_NUM_THREADS=8 mpirun ./myexec
+OMP_NUM_THREADS=8 srun ./myexec
 ```
 
 1 machine with 4 local GPUs:

quest/include/calculations.h

@@ -69,15 +69,17 @@ extern "C" {
  *   which case the imaginary component of the above expression is neglected.
  *   The full complex value can be obtained using calcExpecNonHermitianPauliStrSum().
  * 
- * @equivalence
+ * @equivalences
  * - When @p str is general, this function is equivalent to calling calcExpecPauliStrSum() with a 
  *   PauliStrSum composed of only a single PauliStr term and a unity coefficient.
  * - When @p str @f$ = \id^\otimes @f$, the output is equivalent to that of calcTotalProb().
  * 
  * @myexample
  * ```
-    Qureg qureg = createQureg(4);
-    PauliStr str = getPauliStr("XYZ");
+    Qureg qureg = createQureg(10);
+    initRandomPureState(qureg);
+
+    PauliStr str = getInlinePauliStr("XYZ", {0,2,3});
 
     qreal expec = calcExpecPauliStr(qureg, str);
     reportScalar("expec", expec);  
@@ -89,11 +91,11 @@ extern "C" {
  * @param[in] qureg the reference state.
  * @param[in] str   the observable operator.
  * @returns The real component of the expectation value.
- * @throws invalidQuESTInputError()
+ * @throws @validationerror
  * - if @p qureg is uninitialised.
  * - if @p str contains a (non-identity) Pauli upon a higher-index qubit than exists in @p qureg.
  * - if the output (with unreturned imaginary component) is not approximately real.
- * @notvalidated
+ * @notyetvalidated
  * @author Tyson Jones
  */
 qreal calcExpecPauliStr(Qureg qureg, PauliStr str);
@@ -125,7 +127,7 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str);
  *   Hermiticity validation is relaxed and/or @p qureg is an unnormalised density matrix. 
  *   The full complex value can be obtained using calcExpecNonHermitianPauliStrSum().
  * 
- * @equivalence
+ * @equivalences
  * - This function is mathematically equivalent to (albeit faster than) calling calcExpecPauliStr() upon
  *   each constituent @p PauliStr within @p sum, weighting each by its corresponding coefficient, and
  *   summing the outputs.
@@ -145,15 +147,16 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str);
     qreal expec = calcExpecPauliStrSum(qureg, sum);
     reportScalar("expec", expec);  
  * ```
+ *
  * @param[in] qureg the reference state.
  * @param[in] sum   the observable operator.
  * @returns The real component of the expectation value.
- * @throws invalidQuESTInputError()
+ * @throws @validationerror
  * - if @p qureg or @p sum are uninitialised.
  * - if any PauliStr in @p sum targets a higher-index qubit than exists in @p qureg.
  * - if @p sum is not approximately Hermitian.
  * - if the output (with unreturned imaginary component) is not approximately real.
-* @notvalidated
+* @notyetvalidated
  * @see
  * - calcExpecNonHermitianPauliStrSum()
  * - calcExpecFullStateDiagMatr()
@@ -162,13 +165,13 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str);
 qreal calcExpecPauliStrSum(Qureg qureg, PauliStrSum sum);
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcExpecFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr);
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcExpecFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matr, qreal exponent);
 
 
@@ -183,23 +186,23 @@ qreal calcExpecFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matr, qreal
  */
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcProbOfBasisState(Qureg qureg, qindex index);
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcProbOfQubitOutcome(Qureg qureg, int qubit, int outcome);
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcProbOfMultiQubitOutcome(Qureg qureg, int* qubits, int* outcomes, int numQubits);
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 void calcProbsOfAllMultiQubitOutcomes(qreal* outcomeProbs, Qureg qureg, int* qubits, int numQubits);
 
 
@@ -214,13 +217,13 @@ void calcProbsOfAllMultiQubitOutcomes(qreal* outcomeProbs, Qureg qureg, int* qub
  */
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcTotalProb(Qureg qureg);
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcPurity(Qureg qureg);
 
 
@@ -235,12 +238,12 @@ qreal calcPurity(Qureg qureg);
  */
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcFidelity(Qureg qureg, Qureg other);
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qreal calcDistance(Qureg qureg1, Qureg qureg2);
 
 
@@ -255,13 +258,13 @@ qreal calcDistance(Qureg qureg1, Qureg qureg2);
  */
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 Qureg calcPartialTrace(Qureg qureg, int* traceOutQubits, int numTraceQubits);
 
 
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 Qureg calcReducedDensityMatrix(Qureg qureg, int* retainQubits, int numRetainQubits);
 
 
@@ -292,26 +295,26 @@ Qureg calcReducedDensityMatrix(Qureg qureg, int* retainQubits, int numRetainQubi
 
 
 /// @ingroup calc_comparisons
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qcomp calcInnerProduct(Qureg qureg1, Qureg qureg2);
 
 
 /// @ingroup calc_expec
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qcomp calcExpecNonHermitianPauliStrSum(Qureg qureg, PauliStrSum sum); 
 
 
 /// @ingroup calc_expec
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qcomp calcExpecNonHermitianFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr);
 
 
 /// @ingroup calc_expec
-/// @notdoced
-/// @notvalidated
+/// @notyetdoced
+/// @notyetvalidated
 qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent);
 
 
@@ -330,34 +333,38 @@ qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr
 
 
 /// @ingroup calc_prob
-/// @nottested
-/// @notdoced
-/// @notvalidated
-/// @cpponly
+/// @notyettested
+/// @notyetdoced
+/// @notyetvalidated
+/// @cppoverload
+/// @see calcProbOfMultiQubitOutcome()
 qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector<int> qubits, std::vector<int> outcomes);
 
 
 /// @ingroup calc_prob
-/// @nottested
-/// @notdoced
-/// @notvalidated
+/// @notyettested
+/// @notyetdoced
+/// @notyetvalidated
 /// @cpponly
+/// @see calcProbsOfAllMultiQubitOutcomes()
 std::vector<qreal> calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector<int> qubits);
 
 
 /// @ingroup calc_partialtrace
-/// @nottested
-/// @notdoced
-/// @notvalidated
-/// @cpponly
+/// @notyettested
+/// @notyetdoced
+/// @notyetvalidated
+/// @cppoverload
+/// @see calcPartialTrace()
 Qureg calcPartialTrace(Qureg qureg, std::vector<int> traceOutQubits);
 
 
 /// @ingroup calc_partialtrace
-/// @nottested
-/// @notdoced
-/// @notvalidated
-/// @cpponly
+/// @notyettested
+/// @notyetdoced
+/// @notyetvalidated
+/// @cppoverload
+/// @see calcReducedDensityMatrix()
 Qureg calcReducedDensityMatrix(Qureg qureg, std::vector<int> retainQubits);