Insert QuEST into debug API names

docs/tutorial.md

@@ -176,24 +176,24 @@ Configuring the environment is ordinarily not necessary, but convenient in certa
 For example, we may wish our simulations to deterministically obtain the same measurement outcomes and random states as a previous or future run, and ergo choose to [override](https://quest-kit.github.io/QuEST/group__debug__seed.html#ga9e3a6de413901afbf50690573add1587) the default seeds.
 ```cpp
 unsigned seeds[] = {123u, 1u << 10};
-setSeeds(seeds, 2);
+setQuESTSeeds(seeds, 2);
 ```
 
 We may wish further to [adjust](https://quest-kit.github.io/QuEST/group__debug__reporting.html) how subsequent functions will display information to the screen
 ```cpp
 int maxRows = 8;
 int maxCols = 4;
-setMaxNumReportedItems(maxRows, maxCols);
-setMaxNumReportedSigFigs(3);
+setQuESTMaxNumReportedItems(maxRows, maxCols);
+setQuESTMaxNumReportedSigFigs(3);
 ```
 or [add](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga29413703d609254244d6b13c663e6e06) extra spacing between QuEST's printed outputs
 ```cpp
-setNumReportedNewlines(3);
+setQuESTNumReportedNewlines(3);
 ```
 
 Perhaps we also wish to relax the [precision](https://quest-kit.github.io/QuEST/group__debug__validation.html#gae395568df6def76045ec1881fcb4e6d1) with which our future inputs will be asserted unitary or Hermitian
 ```cpp
-setValidationEpsilon(0.001);
+setQuESTValidationEpsilon(0.001);
 ```
 but when unitarity _is_ violated, or we otherwise pass an invalid input, we wish to execute a [custom function](https://quest-kit.github.io/QuEST/group__debug__validation.html#ga14b6e7ce08465e36750da3acbc41062f) before exiting.
 ```cpp
@@ -205,7 +205,7 @@ void myErrorHandler(const char *func, const char *msg) {
     exit(1);
 }
 
-setInputErrorHandler(myErrorHandler);
+setQuESTInputErrorHandler(myErrorHandler);
 ```
 
 > [!TIP]
@@ -218,7 +218,7 @@ setInputErrorHandler(myErrorHandler);
 >     std::string msg(errMsg);
 >     throw std::runtime_error(func + ": " + msg);
 > }
-> setInputErrorHandler(myErrorHandler);
+> setQuESTInputErrorHandler(myErrorHandler);
 > ```
 <!-- newlines removed above because doxygen renders them as <br> text, how stupid! -->
 
@@ -253,7 +253,7 @@ Qureg (10 qubit statevector, 1024 qcomps, 16.1 KiB):
     0  |1022⟩
     0  |1023⟩
 ```
-> This printed only `8` amplitudes as per our setting of [`setMaxNumReportedItems()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga093c985b1970a0fd8616c01b9825979a) above.
+> This printed only `8` amplitudes as per our setting of [`setQuESTMaxNumReportedItems()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga093c985b1970a0fd8616c01b9825979a) above.
 
 Behind the scenes, the function `createQureg` did something clever; it consulted the compiled deployments and available hardware to decide whether to distribute `qureg`, or dedicate it persistent GPU memory, and marked whether or not to multithread its subsequent modification. It attempts to choose _optimally_, avoiding gratuitous parallelisation if the overheads outweigh the benefits, or if the hardware devices have insufficient memory.
 
@@ -356,7 +356,7 @@ Qureg:
     globalTotal.......16 MiB
 ```
 
-> The spacing between the outputs of those two consecutive QuEST functions was determined by our earlier call to [`setNumReportedNewlines()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga29413703d609254244d6b13c663e6e06).
+> The spacing between the outputs of those two consecutive QuEST functions was determined by our earlier call to [`setQuESTNumReportedNewlines()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga29413703d609254244d6b13c663e6e06).
 
 
 A density matrix `Qureg` can model classical uncertainty as results from [decoherence](https://quest-kit.github.io/QuEST/group__decoherence.html), and proves useful when simulating quantum operations on a noisy quantum computer.
@@ -415,7 +415,7 @@ Qureg (5 qubit density matrix, 32x32 qcomps, 16.1 KiB):
     -0.00597-0.00615i   -0.00207-0.00451i   …  0.000509-0.00401i   0.0173+(3.12e-19)i
 ```
 
-> The number of printed significant figures above results from our earlier calling of [`setMaxNumReportedSigFigs()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga15d46e5d813f70b587762814964e1994).
+> The number of printed significant figures above results from our earlier calling of [`setQuESTMaxNumReportedSigFigs()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga15d46e5d813f70b587762814964e1994).
 
 
 
@@ -612,7 +612,7 @@ Exiting...
 If we're satisfied our matrix _is_ sufficiently approximately unitary, we can [adjust](https://quest-kit.github.io/QuEST/group__debug__validation.html#gae395568df6def76045ec1881fcb4e6d1) or [disable](https://quest-kit.github.io/QuEST/group__debug__validation.html#ga5999824df0785ea88fb2d5b5582f2b46) the validation.
 ```cpp
 // max(norm(m * dagger(m) - identity)) = 0.9025
-setValidationEpsilon(0.903);
+setQuESTValidationEpsilon(0.903);
 applyCompMatr1(qureg, 0, m);
 ```
 
@@ -783,7 +783,7 @@ reportScalar("entanglement", calcPurity(reduced));
 ## Report the results
 
 
-We've seen above that [scalars](https://quest-kit.github.io/QuEST/group__types.html) can be reported, handling the pretty formatting of real and complex numbers, controlled by settings like [`setMaxNumReportedSigFigs()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga15d46e5d813f70b587762814964e1994). But we can also report every data structure in the QuEST API, such as Pauli strings
+We've seen above that [scalars](https://quest-kit.github.io/QuEST/group__types.html) can be reported, handling the pretty formatting of real and complex numbers, controlled by settings like [`setQuESTMaxNumReportedSigFigs()`](https://quest-kit.github.io/QuEST/group__debug__reporting.html#ga15d46e5d813f70b587762814964e1994). But we can also report every data structure in the QuEST API, such as Pauli strings
 ```cpp
 reportPauliStr(
     getInlinePauliStr("XXYYZZ", {5,50, 10,60, 30,40})
@@ -805,8 +805,8 @@ PauliStrSum (4 terms, 160 bytes):
 ```
 All outputs are affected by the [reporter settings](https://quest-kit.github.io/QuEST/group__debug__reporting.html).
 ```cpp
-setMaxNumReportedItems(4,4);
-setMaxNumReportedSigFigs(1);
+setQuESTMaxNumReportedItems(4,4);
+setQuESTMaxNumReportedSigFigs(1);
 reportCompMatr(bigmatrix);
 ```
 ```

examples/extended/dynamics.c

@@ -103,16 +103,16 @@ PauliStrSum createMyObservable(int numQubits) {
 
 void reportMyStructs(Qureg qureg, PauliStrSum hamil, PauliStrSum observ) {
 
-    setMaxNumReportedSigFigs(6);   // sig-figs in scalars
-    setNumReportedNewlines(2);     // spacing between reports
-    setReportedPauliChars(".XYZ"); // print I as .
-    setReportedPauliStrStyle(0);   // print XYZ (0) or Z3 Y2 X1 (1)
-    setMaxNumReportedItems(8, 8);  // show max 8 qureg amplitudes
+    setQuESTMaxNumReportedSigFigs(6);   // sig-figs in scalars
+    setQuESTNumReportedNewlines(2);     // spacing between reports
+    setQuESTReportedPauliChars(".XYZ"); // print I as .
+    setQuESTReportedPauliStrStyle(0);   // print XYZ (0) or Z3 Y2 X1 (1)
+    setQuESTMaxNumReportedItems(8, 8);  // show max 8 qureg amplitudes
 
     reportStr("[Initial state]");
     reportQureg(qureg);
 
-    setMaxNumReportedItems(0, 0); // show 0=all Pauli operators
+    setQuESTMaxNumReportedItems(0, 0); // show 0=all Pauli operators
 
     reportStr("[Hamiltonian]");
     reportPauliStrSum(hamil);
@@ -144,8 +144,8 @@ int main() {
     reportMyStructs(qureg, hamil, observ);
 
     // tidy reporting of below expectation values
-    setMaxNumReportedSigFigs(3);
-    setNumReportedNewlines(1);
+    setQuESTMaxNumReportedSigFigs(3);
+    setQuESTNumReportedNewlines(1);
 
     // evolve by repeatedly (each is a "step") Trotterising
     // exp(-i dt H) with the specified order and repetitions.
@@ -172,8 +172,8 @@ int main() {
     reportStr("");
 
     // preview the final state...
-    setNumReportedNewlines(2);
-    setMaxNumReportedItems(25, 25);
+    setQuESTNumReportedNewlines(2);
+    setQuESTMaxNumReportedItems(25, 25);
     reportStr("[Final state]");
     reportQureg(qureg);
 

examples/extended/dynamics.cpp

@@ -100,16 +100,16 @@ PauliStrSum createMyObservable(int numQubits) {
 
 void reportMyStructs(Qureg qureg, PauliStrSum hamil, PauliStrSum observ) {
 
-    setMaxNumReportedSigFigs(6);   // sig-figs in scalars
-    setNumReportedNewlines(2);     // spacing between reports
-    setReportedPauliChars(".XYZ"); // print I as .
-    setReportedPauliStrStyle(0);   // print XYZ (0) or Z3 Y2 X1 (1)
-    setMaxNumReportedItems(8, 8);  // show max 8 qureg amplitudes
+    setQuESTMaxNumReportedSigFigs(6);   // sig-figs in scalars
+    setQuESTNumReportedNewlines(2);     // spacing between reports
+    setQuESTReportedPauliChars(".XYZ"); // print I as .
+    setQuESTReportedPauliStrStyle(0);   // print XYZ (0) or Z3 Y2 X1 (1)
+    setQuESTMaxNumReportedItems(8, 8);  // show max 8 qureg amplitudes
 
     reportStr("[Initial state]");
     reportQureg(qureg);
 
-    setMaxNumReportedItems(0, 0); // show 0=all Pauli operators
+    setQuESTMaxNumReportedItems(0, 0); // show 0=all Pauli operators
 
     reportStr("[Hamiltonian]");
     reportPauliStrSum(hamil);
@@ -141,8 +141,8 @@ int main() {
     reportMyStructs(qureg, hamil, observ);
 
     // tidy reporting of below expectation values
-    setMaxNumReportedSigFigs(3);
-    setNumReportedNewlines(1);
+    setQuESTMaxNumReportedSigFigs(3);
+    setQuESTNumReportedNewlines(1);
 
     // evolve by repeatedly (each is a "step") Trotterising
     // exp(-i dt H) with the specified order and repetitions.
@@ -166,8 +166,8 @@ int main() {
     reportStr("");
 
     // preview the final state...
-    setNumReportedNewlines(2);
-    setMaxNumReportedItems(25, 25);
+    setQuESTNumReportedNewlines(2);
+    setQuESTMaxNumReportedItems(25, 25);
     reportStr("[Final state]");
     reportQureg(qureg);
 

examples/isolated/reporting_matrices.c

@@ -49,7 +49,7 @@ void demo_CompMatr() {
     for (int i=0; i<len; i++) {
         qindex num = numReportElems[i];
         rootPrint(num);
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportCompMatr(matr);
     }
 }
@@ -69,7 +69,7 @@ void demo_DiagMatr() {
     for (int i=0; i<len; i++) {
         qindex num = numReportElems[i];
         rootPrint(num);
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportDiagMatr(matr);
     }
 }
@@ -91,7 +91,7 @@ void demo_FullStateDiagMatr() {
     for (int i=0; i<6; i++) {
         qindex num = numReportElems[i];
         rootPrint(num);
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportFullStateDiagMatr(matr);
     }
 }

examples/isolated/reporting_matrices.cpp

@@ -39,7 +39,7 @@ void demo_CompMatr() {
 
     for (int num : {0, 12, 5, 1}) {
         rootPrint(num);
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportCompMatr(matr);
     }
 }
@@ -55,7 +55,7 @@ void demo_DiagMatr() {
 
     for (int num : {0, 10}) {
         rootPrint(num);
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportDiagMatr(matr);
     }
 }
@@ -74,7 +74,7 @@ void demo_FullStateDiagMatr() {
 
     for (int num : {0, 50, 30, 10, 5, 1}) {
         rootPrint(num);
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportFullStateDiagMatr(matr);
     }
 }

examples/isolated/reporting_paulis.c

@@ -93,7 +93,7 @@ void demo_PauliStrSum() {
         qindex num = numReportElems[i];
         rootPrint(num);
 
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportPauliStrSum(sum);
     }
 

examples/isolated/reporting_paulis.cpp

@@ -99,7 +99,7 @@ void demo_PauliStrSum() {
     for (int num : numReportElems) {
         rootPrint(num);
 
-        setMaxNumReportedItems(num, num);
+        setQuESTMaxNumReportedItems(num, num);
         reportPauliStrSum(sum);
     }
 

examples/isolated/setting_errorhandler.c

@@ -19,7 +19,7 @@ void myErrorHandler(const char* errFunc, const char* errMsg) {
 
 int main() {
     initQuESTEnv();
-    setInputErrorHandler(myErrorHandler);
+    setQuESTInputErrorHandler(myErrorHandler);
 
     Qureg qureg = createQureg(-123);
 

examples/isolated/setting_errorhandler.cpp

@@ -48,7 +48,7 @@ void myErrorHandlerB(const char* errFunc, const char* errMsg) {
 int main() {
     initQuESTEnv();
 
-    setInputErrorHandler(myErrorHandlerA);
+    setQuESTInputErrorHandler(myErrorHandlerA);
 
     try {
         Qureg qureg = createQureg(-123);
@@ -59,7 +59,7 @@ int main() {
             << std::endl;
     }
 
-    setInputErrorHandler(myErrorHandlerB);
+    setQuESTInputErrorHandler(myErrorHandlerB);
     initQuESTEnv(); // illegal to recall
 
     std::cout << "this will never be reached, because myErrorHandlerB exits!" << std::endl;

quest/include/calculations.h

@@ -69,7 +69,7 @@ extern "C" {
  * 
  * - Postcondition validation will check that the calculated expectation value is approximately
  *   real (i.e. the imaginary component is smaller in size than the validation epsilon), as admitted
- *   when @p qureg is correctly normalised. This behaviour can be adjusted using setValidationEpsilon(). 
+ *   when @p qureg is correctly normalised. This behaviour can be adjusted using setQuESTValidationEpsilon(). 
  * - Regardless of the validation epsilon, the returned value is always real and the imaginary component
  *   is discarded. The full complex value can be obtained using calcExpecNonHermitianPauliStrSum().
  * 
@@ -129,7 +129,7 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str);
  *   @f[ 
      |\im{c}| \le \valeps
  *   @f]
- *   for all @f$c \in @f$ `sum.coeffs`. Adjust @f$\valeps@f$ using setValidationEpsilon().
+ *   for all @f$c \in @f$ `sum.coeffs`. Adjust @f$\valeps@f$ using setQuESTValidationEpsilon().
  *   The sub-epsilon imaginary components of the coefficients _are_ included in calculation.
  * - Postcondition validation will check that the calculated expectation value is approximately
  *   real (i.e. the imaginary component is smaller in size than the validation epsilon), as should be
@@ -201,7 +201,7 @@ qreal calcExpecPauliStrSum(Qureg qureg, PauliStrSum sum);
  *   @f[ 
      |\im{c}| \le \valeps
  *   @f]
- *   for all @f$c \in @f$ `matr.cpuElems`. Adjust @f$\valeps@f$ using setValidationEpsilon().
+ *   for all @f$c \in @f$ `matr.cpuElems`. Adjust @f$\valeps@f$ using setQuESTValidationEpsilon().
  * - Postcondition validation will check that the calculated expectation value is approximately
  *   real (i.e. the imaginary component is smaller in size than the validation epsilon), as should be
  *   admitted when @p qureg is correctly normalised, and @p matr is Hermitian.
@@ -277,14 +277,14 @@ qreal calcExpecFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr);
  *   @f[ 
      |\im{c}| \le \valeps
  *   @f]
- *   for all @f$c \in @f$ `matr.cpuElems`. Adjust @f$\valeps@f$ using setValidationEpsilon().
+ *   for all @f$c \in @f$ `matr.cpuElems`. Adjust @f$\valeps@f$ using setQuESTValidationEpsilon().
  * 
  *   > [!CAUTION]
  *   > Unlike other functions (including calcExpecFullStateDiagMatr()), this function will _NOT_
  *   > consult the imaginary components of the elements of @p matrix, since a non-complex exponentiation
  *   > function is used. That is, while validation permits the imaginary components to be small, they
  *   > will be internally treated as precisely zero. This is true even when Hermiticity validation
- *   > is disabled using setValidationOff(). To consult the imaginary components of @p matrix, use
+ *   > is disabled using setQuESTValidationOff(). To consult the imaginary components of @p matrix, use
  *   > calcExpecNonHermitianFullStateDiagMatrPower().
  * 
  * - Hermiticity of @p matrix when raised to @p exponent further requires that, when @p exponent is 
@@ -298,7 +298,7 @@ qreal calcExpecFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr);
  *   zero elements which would otherwise create divergences in @f$\hat{D}^x@f$. Validation ergo
  *   checks that when @p exponent is (strictly) negative, @p matrix contains no elements within 
  *   distance @f$\valeps@f$ to zero (regardless of the magnitude of @p exponent). Adjust
- *   @f$\valeps@f$ using setValidationEpsilon().
+ *   @f$\valeps@f$ using setQuESTValidationEpsilon().
  * - The passed @p exponent is always real, but can be relaxed to a general complex scalar via
  *   calcExpecNonHermitianFullStateDiagMatrPower().
  * - The returned value is always real, and the imaginary component is neglected even when 
@@ -890,7 +890,7 @@ qreal calcPurity(Qureg qureg);
  * - The output of this function is always real, which validation will check after computing the
  *   fidelity as a complex scalar. Specifically, validation will assert that the result has an
  *   absolute imaginary component less than the validation epsilon, which can be adjusted with
- *   setValidationEpsilon().
+ *   setQuESTValidationEpsilon().
  * 
  * - This function does not yet support both @p qureg and @p other being density matrices, for
  *   which the fidelity calculation is more substantial.
@@ -1004,7 +1004,7 @@ qreal calcFidelity(Qureg qureg, Qureg other);
          \left| \, \im{ \brapsi \dmrho \svpsi } \, \right| \le \valeps, \\
          \re{ \brapsi \dmrho \svpsi } \le 1 + \valeps,
  *   @f]
- *   where @f$\valeps@f$ is the validation epsilon, adjustable via setValidationEpsilon().
+ *   where @f$\valeps@f$ is the validation epsilon, adjustable via setQuESTValidationEpsilon().
  * 
  * - Even when the above postcondition validation is disabled, the Bures and purified distance
  *   calculations will respectively replace @f$\left| \braket{\phi}{\psi} \right|@f$ and