added (some) operator validation tests

since they arguably constitute the majority of functions interfaced by users, so are worth checking before v4 release! The in-development more-doc branch has removed the corresponding `@nottested` tags from the checked functions.

Additionally:
- added C++-macro guard (to defend from `__cplusplus=0`)
- ensured pre-processor checks are performed first when `quest.h` is included
- removed some defunct validation-related comments
- added post-sample validation to test utility RNG - I'm suspicious of it!

Author: TysonRayJones

quest/include/modes.h

@@ -63,6 +63,16 @@
 
 
 
+// ensure C++ macro is valid (API headers use #ifdef, not #if)
+
+#ifdef __cplusplus
+#if !__cplusplus
+#error "Preprocessor __cplusplus was 0 and should instead be undefined"
+#endif
+#endif
+
+
+
 // define optional-macro defaults (mostly to list them)
 
 #ifndef PERMIT_NODES_TO_SHARE_GPU

quest/include/quest.h

@@ -15,20 +15,27 @@
 #define QUEST_H
 
 
+// include version first so it is accessible to 
+// debuggers in case a subsequent include fails
+#include "quest/include/version.h"
+
+// include before API headers since it validates
+// preprocessor configuration, and affirms macro
+// preconditions assumed by subsequent header
+#include "quest/include/modes.h"
+
+#include "quest/include/precision.h"
+#include "quest/include/types.h"
 #include "quest/include/calculations.h"
 #include "quest/include/debug.h"
 #include "quest/include/decoherence.h"
 #include "quest/include/environment.h"
 #include "quest/include/initialisations.h"
 #include "quest/include/channels.h"
-#include "quest/include/modes.h"
 #include "quest/include/operations.h"
 #include "quest/include/paulis.h"
-#include "quest/include/precision.h"
 #include "quest/include/qureg.h"
 #include "quest/include/matrices.h"
-#include "quest/include/types.h"
-#include "quest/include/version.h"
 #include "quest/include/wrappers.h"
 
 

quest/src/api/operations.cpp

@@ -312,9 +312,9 @@ void applyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matr
     validate_quregFields(qureg, __func__);
     validate_targets(qureg, targets, numTargets, __func__);
     validate_matrixDimMatchesTargets(matrix, numTargets, __func__); // also checks fields and is-synced
-    validate_matrixIsUnitary(matrix, __func__);  // checks abs=1 (so no risk of 0^(-neg exp)) and rechecks fields/synced
-    validate_matrixExpIsNonDiverging(matrix, exponent, __func__); // harmlessly re-validates fields and is-sync
-    validate_unitaryExponentIsReal(exponent, __func__); // checks matrix^exponent is approx unitary (abs=1)
+    validate_matrixIsUnitary(matrix, __func__);
+    validate_matrixExpIsNonDiverging(matrix, exponent, __func__);
+    validate_unitaryExponentIsReal(exponent, __func__);
 
     // notice exponent is a 'qcomp' not a 'qreal' despite validation; see applyMultiStateControlledDiagMatrPower()
 
@@ -326,9 +326,9 @@ void applyControlledDiagMatrPower(Qureg qureg, int control, int* targets, int nu
     validate_quregFields(qureg, __func__);
     validate_controlAndTargets(qureg, control, targets, numTargets, __func__);
     validate_matrixDimMatchesTargets(matrix, numTargets, __func__); // also checks fields and is-synced
-    validate_matrixIsUnitary(matrix, __func__);  // checks abs=1 (so no risk of 0^(-neg exp)) and rechecks fields/synced
-    validate_matrixExpIsNonDiverging(matrix, exponent, __func__); // harmlessly re-validates fields and is-sync
-    validate_unitaryExponentIsReal(exponent, __func__); // checks matrix^exponent is approx unitary (abs=1)
+    validate_matrixIsUnitary(matrix, __func__);
+    validate_matrixExpIsNonDiverging(matrix, exponent, __func__);
+    validate_unitaryExponentIsReal(exponent, __func__);
 
     // notice exponent is a 'qcomp' not a 'qreal' despite validation; see applyMultiStateControlledDiagMatrPower()
 
@@ -340,9 +340,9 @@ void applyMultiControlledDiagMatrPower(Qureg qureg, int* controls, int numContro
     validate_quregFields(qureg, __func__);
     validate_controlsAndTargets(qureg, controls, numControls, targets, numTargets, __func__);
     validate_matrixDimMatchesTargets(matrix, numTargets, __func__); // also checks fields and is-synced
-    validate_matrixIsUnitary(matrix, __func__);  // checks abs=1 (so no risk of 0^(-neg exp)) and rechecks fields/synced
-    validate_matrixExpIsNonDiverging(matrix, exponent, __func__); // harmlessly re-validates fields and is-sync
-    validate_unitaryExponentIsReal(exponent, __func__); // checks matrix^exponent is approx unitary (abs=1)
+    validate_matrixIsUnitary(matrix, __func__);
+    validate_matrixExpIsNonDiverging(matrix, exponent, __func__);
+    validate_unitaryExponentIsReal(exponent, __func__);
 
     // notice exponent is a 'qcomp' not a 'qreal' despite validation; see applyMultiStateControlledDiagMatrPower()
 
@@ -354,10 +354,10 @@ void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* sta
     validate_quregFields(qureg, __func__);
     validate_controlsAndTargets(qureg, controls, numControls, targets, numTargets, __func__);
     validate_controlStates(states, numControls, __func__); // can be nullptr, ignoring numControls
-    validate_matrixDimMatchesTargets(matrix, numTargets, __func__); // also checks fields and is-synced
-    validate_matrixIsUnitary(matrix, __func__);  // checks abs=1 (so no risk of 0^(-neg exp)) and rechecks fields/synced
-    validate_matrixExpIsNonDiverging(matrix, exponent, __func__); // harmlessly re-validates fields and is-sync
-    validate_unitaryExponentIsReal(exponent, __func__); // checks matrix^exponent is approx unitary (abs=1)
+    validate_matrixDimMatchesTargets(matrix, numTargets, __func__);
+    validate_matrixIsUnitary(matrix, __func__); 
+    validate_matrixExpIsNonDiverging(matrix, exponent, __func__);
+    validate_unitaryExponentIsReal(exponent, __func__);
 
     // unlike calcExpecDiagMatrPower which accepts a 'qreal' exponent,
     // this function accepts a 'qcomp'. This is because it always
@@ -422,8 +422,8 @@ void applyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp ex
     validate_quregFields(qureg, __func__);
     validate_matrixFields(matrix, __func__);
     validate_matrixAndQuregAreCompatible(matrix, qureg, false, __func__);
-    validate_matrixIsUnitary(matrix, __func__);  // checks abs=1 (so no risk of 0^(-neg exp))
-    validate_unitaryExponentIsReal(exponent, __func__); // checks matrix^exponent is approx unitary (abs=1)
+    validate_matrixIsUnitary(matrix, __func__);
+    validate_unitaryExponentIsReal(exponent, __func__);
     validate_matrixExpIsNonDiverging(matrix, exponent, __func__);
 
     bool onlyMultiply = false;

quest/src/core/validation.cpp

@@ -2272,7 +2272,9 @@ void assertMatrixIsSynced(T matr, string errMsg, const char* caller) {
     if (!mem_isAllocated(util_getGpuMemPtr(matr)))
         return;
 
-    // check if GPU amps have EVER been overwritten; we sadly cannot check the LATEST changes were pushed though
+    // check if GPU amps have EVER been overwritten; we sadly cannot check the LATEST changes were pushed though.
+    // note we check this whenever the matrix has GPU memory, even if it is being applied upon a Qureg which is
+    // NOT GPU-accelerated and ergo the GPU memory is not consulted. It's best to build the habit in the user!
     assertThat(*(matr.wasGpuSynced) == 1, errMsg, caller);
 }
 void validate_matrixIsSynced(CompMatr matr, const char* caller) { assertMatrixIsSynced(matr, report::COMP_MATR_NOT_SYNCED_TO_GPU, caller);}