tidied heap flags

- renamed KrausMap.isCPTP to KrausMap.isApproxCPTP to reflect its epsilon-dependence, for consistency with isApproxUnitarity, isApproxHermitian and isApproxNonZero
- defined util_setFlagToUnknown() so that constant validate_STRUCT_PROPERTY_UNKNOWN_FLAG need not be exposed beyond validation.cpp and utilities.cpp
- renamed util_setEpsilonSensitiveStructFieldsToUnknown() to util_setEpsilonSensitiveHeapFlagsToUnknown() to be consistent with related utility functions util_(de)allocEpsilonSensitiveHeapFlag()
- made util_allocEpsilonSensitiveHeapFlag() update the ptr to validate_STRUCT_PROPERTY_UNKNOWN_FLAG by default, in case caller forgets to
- removed redundant logic from validation.cpp which checked whether KrausMap.isCPTP and PauliStrSum.isApproxHermitian were pre-set
- added tests to check that sync() functions (syncKrausMap, syncCompMatr, syncDiagMatr, syncFullStateDiagMatr) clear all property fields (isApproxUnitary, isApproxHermitian, isApproxNonZero, isStrictlyNonNegative)
- added tests to check that validation-changes (setValidationEpsilon, setValidationEpsilonToDefault()) clear all epsilon-dependent struct fields
- hid "struct not initialised" tests from address sanitizer (which erm disliked them)

Author: TysonRayJones

quest/include/channels.h

@@ -102,7 +102,7 @@ typedef struct {
 
     // CPTP-ness is determined at validation; 0 or 1, or -1 to indicate unknown. The flag is 
     // stored in heap so even copies of structs are mutable, but pointer itself is immutable.
-    int* isCPTP;
+    int* isApproxCPTP;
 
 } KrausMap;
 

quest/src/api/channels.cpp

@@ -54,7 +54,7 @@ void freeKrausMap(KrausMap map) {
     cpu_deallocMatrixList(map.matrices, map.numRows, map.numMatrices);
 
     // free teeny-tiny heap flag
-    util_deallocEpsilonSensitiveHeapFlag(map.isCPTP);
+    util_deallocEpsilonSensitiveHeapFlag(map.isApproxCPTP);
 
     // free superoperator (which may include freeing GPU memory)
     freeSuperOp(map.superop);
@@ -88,7 +88,7 @@ bool didAnyLocalAllocsFail(SuperOp op) {
 
 bool didAnyLocalAllocsFail(KrausMap map) {
 
-    if (!mem_isAllocated(map.isCPTP))
+    if (!mem_isAllocated(map.isApproxCPTP))
         return true;
 
     if (!mem_isAllocated(map.matrices, map.numRows, map.numMatrices))
@@ -184,15 +184,15 @@ extern "C" KrausMap createKrausMap(int numQubits, int numOperators) {
         .matrices = cpu_allocMatrixList(numRows, numOperators), // is or contains nullptr if failed
         .superop = allocSuperOp(numQubits), // heap fields are or contain nullptr if failed
 
-        .isCPTP = util_allocEpsilonSensitiveHeapFlag(), // nullptr if failed
+        .isApproxCPTP = util_allocEpsilonSensitiveHeapFlag(), // nullptr if failed
     };
 
     // free memory before throwing validation error to avoid memory leaks
     freeAllMemoryIfAnyAllocsFailed(out); // sets out.matrices=nullptr if failed
     validate_newKrausMapAllocs(out, __func__);
 
     // mark CPTP as unknown; it will be lazily evaluated whene a function asserts CPTP-ness
-    *(out.isCPTP) = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+    util_setFlagToUnknown(out.isApproxCPTP);
 
     return out;
 }
@@ -240,7 +240,7 @@ extern "C" void syncKrausMap(KrausMap map) {
 
     // indicate that we do not know whether the revised map is
     // is CPTP; we defer establishing that until a CPTP check
-    *(map.isCPTP) = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+    util_setFlagToUnknown(map.isApproxCPTP);
 }
 
 
@@ -299,7 +299,7 @@ void setAndSyncKrausMapElems(KrausMap map, T matrices) {
     for (int n=0; n<map.numMatrices; n++)
         cpu_copyMatrix(map.matrices[n], matrices[n], map.numRows);
 
-    // update the superoperator, including its GPU memory, and its isCPTP flag
+    // update the superoperator, including its GPU memory, and its isApproxCPTP flag
     syncKrausMap(map);
 }
 

quest/src/api/debug.cpp

@@ -90,14 +90,14 @@ void setValidationEpsilon(qreal eps) {
     validate_newEpsilonValue(eps, __func__);
 
     validateconfig_setEpsilon(eps);
-    util_setEpsilonSensitiveStructFieldsToUnknown();
+    util_setEpsilonSensitiveHeapFlagsToUnknown();
 }
 
 void setValidationEpsilonToDefault() {
     validate_envIsInit(__func__);
 
     validateconfig_setEpsilonToDefault();
-    util_setEpsilonSensitiveStructFieldsToUnknown();
+    util_setEpsilonSensitiveHeapFlagsToUnknown();
 }
 
 qreal getValidationEpsilon() {

quest/src/api/matrices.cpp

@@ -187,14 +187,14 @@ template <class T>
 void setInitialHeapFlags(T matr) {
 
     // set initial propreties of the newly created matrix to unknown
-    *(matr.isApproxUnitary)     = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
-    *(matr.isApproxHermitian)   = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+    util_setFlagToUnknown(matr.isApproxUnitary);
+    util_setFlagToUnknown(matr.isApproxHermitian);
 
     // only diagonal matrices (which can be exponentiated)
     // have these additional fields
     if constexpr (!util_isDenseMatrixType<T>()) {
-        *(matr.isApproxNonZero)       = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
-        *(matr.isStrictlyNonNegative) = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+        util_setFlagToUnknown(matr.isApproxNonZero);
+        util_setFlagToUnknown(matr.isStrictlyNonNegative);
     }
 
     // indicate that GPU memory has not yet been synchronised
@@ -228,8 +228,9 @@ extern "C" CompMatr createCompMatr(int numQubits) {
 
         // allocate flags in the heap so that struct copies are mutable
         .isApproxUnitary    = util_allocEpsilonSensitiveHeapFlag(), // nullptr if failed
-        .isApproxHermitian  = util_allocEpsilonSensitiveHeapFlag(), // nullptr if failed
-        .wasGpuSynced = cpu_allocHeapFlag(),                        // nullptr if failed
+        .isApproxHermitian  = util_allocEpsilonSensitiveHeapFlag(),
+
+        .wasGpuSynced = cpu_allocHeapFlag(), // nullptr if failed
 
         .cpuElems = cpu_allocAndInitMatrixWrapper(cpuMem, numRows), // nullptr if failed
         .cpuElemsFlat = cpuMem,
@@ -345,14 +346,14 @@ void markMatrixAsSynced(T matr) {
 
     // indicate that we do not know the revised matrix properties;
     // we defer establishing that until validation needs to check them
-    *(matr.isApproxUnitary)     = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
-    *(matr.isApproxHermitian)   = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+    util_setFlagToUnknown(matr.isApproxUnitary);
+    util_setFlagToUnknown(matr.isApproxHermitian);
 
     // only diagonal matrices (which can be exponentiated)
     // have these additional fields
     if constexpr (!util_isDenseMatrixType<T>()) {
-        *(matr.isApproxNonZero)       = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
-        *(matr.isStrictlyNonNegative) = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+        util_setFlagToUnknown(matr.isApproxNonZero);
+        util_setFlagToUnknown(matr.isStrictlyNonNegative);
     }
 }
 

quest/src/api/paulis.cpp

@@ -401,7 +401,7 @@ extern "C" PauliStrSum createPauliStrSum(PauliStr* strings, qcomp* coeffs, qinde
 
     // otherwise copy given data into new heap structure, and set initial flags
     cpu_copyPauliStrSum(out, strings, coeffs);
-    *(out.isApproxHermitian) = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+    util_setFlagToUnknown(out.isApproxHermitian);
 
     return out;
 }

quest/src/core/utilities.cpp

@@ -729,16 +729,16 @@ bool util_isCPTP(KrausMap map, qreal eps) {
     assert_utilsGivenNonZeroEpsilon(eps);
 
     // use pre-computed CPTP if it exists
-    if (*(map.isCPTP) != validate_STRUCT_PROPERTY_UNKNOWN_FLAG)
-        return *(map.isCPTP);
+    if (*(map.isApproxCPTP) != validate_STRUCT_PROPERTY_UNKNOWN_FLAG)
+        return *(map.isApproxCPTP);
 
     /// @todo
     /// if KrausMap is GPU-accelerated, we should maybe
     /// instead perform this calculation using the GPU.
     /// otherwise, if matrix is large, we should potentially
     /// use a multithreaded routine
 
-    *(map.isCPTP) = true;
+    *(map.isApproxCPTP) = 1;
 
     // check whether each element satisfies Identity = sum dagger(m)*m
     for (qindex r=0; r<map.numRows; r++) {
@@ -755,14 +755,14 @@ bool util_isCPTP(KrausMap map, qreal eps) {
             if (distSquared > eps) {
 
                 // by recording the result and returning immediately
-                *(map.isCPTP) = false;
-                return *(map.isCPTP);
+                *(map.isApproxCPTP) = 0;
+                return *(map.isApproxCPTP);
             }
         }
     }
 
     // always true by this point
-    return *(map.isCPTP);
+    return *(map.isApproxCPTP);
 }
 
 // T can be qcomp*** or vector<vector<vector<qcomp>>>
@@ -813,16 +813,27 @@ void util_setSuperoperator(qcomp** superop, qcomp*** matrices, int numMatrices,
 
 std::list<int*> globalStructFieldPtrs(0);
 
+void util_setFlagToUnknown(int* ptr) {
+
+    *ptr = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+}
+
 int* util_allocEpsilonSensitiveHeapFlag() {
 
     int* ptr = cpu_allocHeapFlag(); // may be nullptr
 
-    // if allocated successfully, record the ptr, so that
-    // we can set it to -1 when user changes epsilon
-    if (mem_isAllocated(ptr))
-        globalStructFieldPtrs.push_back(ptr);
+    // if failed to alloc, do not add to global list;
+    // caller will handle validation/error messaging
+    if (!mem_isAllocated(ptr))
+        return ptr;
+
+    // caller should set ptr to the default "unknown"
+    // value, but we do so here too just to be safe
+    util_setFlagToUnknown(ptr);
 
-    // caller will handle nullptr
+    // store the pointer so that we can reset the
+    // value to "unknown" when epsilon is changed
+    globalStructFieldPtrs.push_back(ptr);
     return ptr;
 }
 
@@ -837,10 +848,10 @@ void util_deallocEpsilonSensitiveHeapFlag(int* ptr) {
     cpu_deallocHeapFlag(ptr);
 }
 
-void util_setEpsilonSensitiveStructFieldsToUnknown() {
+void util_setEpsilonSensitiveHeapFlagsToUnknown() {
 
     for (auto ptr : globalStructFieldPtrs)
-        *ptr = validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
+        util_setFlagToUnknown(ptr);
 }
 
 

quest/src/core/utilities.hpp

@@ -315,7 +315,9 @@ int* util_allocEpsilonSensitiveHeapFlag();
 
 void util_deallocEpsilonSensitiveHeapFlag(int* ptr);
 
-void util_setEpsilonSensitiveStructFieldsToUnknown();
+void util_setEpsilonSensitiveHeapFlagsToUnknown();
+
+void util_setFlagToUnknown(int* ptr);
 
 
 

quest/src/core/validation.cpp

@@ -598,10 +598,10 @@ namespace report {
 
 
     string INVALID_KRAUS_MAP_IS_CPTP_PTR = 
-        "The 'isCPTP' field of the given KrausMap was a NULL pointer, instead of the expected pointer to persistent heap memory. This suggests the KrausMap was already destroyed and had its fields overwritten by the user.";
+        "The 'isApproxCPTP' field of the given KrausMap was a NULL pointer, instead of the expected pointer to persistent heap memory. This suggests the KrausMap was already destroyed and had its fields overwritten by the user.";
 
     string INVALID_KRAUS_MAP_IS_CPTP_FLAG = 
-        "The 'isCPTP' field of the given Kraus map had invalid value ${BAD_FLAG}, suggesting it was manually modified. Valid values are 0, 1 and ${UNKNOWN_FLAG} (to indicate that unitarity is not yet known, deferring evaluation) although this need never be modified by the user.";
+        "The 'isApproxCPTP' field of the given Kraus map had invalid value ${BAD_FLAG}, suggesting it was manually modified. Valid values are 0, 1 and ${UNKNOWN_FLAG} (to indicate that unitarity is not yet known, deferring evaluation) although this need never be modified by the user.";
 
 
     string INVALID_KRAUS_MAPS_SUPER_OP_CPU_MEM_PTR =
@@ -1122,7 +1122,7 @@ qreal REDUCTION_EPSILON_FACTOR = 100;
  * e.g. checking unitarity/hermiticity/CPTP-ness. This is only
  * consulted when global_isValidationEnabled=true, and can be
  * separately disabled by setting epsilon=0, in which case 
- * permanent properties of structs (like .isCPTP) will not be 
+ * permanent properties of structs (like .isApproxCPTP) will not be 
  * overwritten (so will stay validate_STRUCT_PROPERTY_UNKNOWN_FLAG)
  */
 
@@ -2809,7 +2809,7 @@ void validate_newKrausMapAllocs(KrausMap map, const char* caller) {
         {"${NUM_QUBITS}",   map.numQubits}};
 
     // assert the teeny-tiny heap flag was alloc'd
-    assertAllNodesAgreeThat(mem_isAllocated(map.isCPTP), report::NEW_HEAP_FLAG_ALLOC_FAILED, {{"${NUM_BYTES}", sizeof(*(map.isCPTP))}}, caller);
+    assertAllNodesAgreeThat(mem_isAllocated(map.isApproxCPTP), report::NEW_HEAP_FLAG_ALLOC_FAILED, {{"${NUM_BYTES}", sizeof(*(map.isApproxCPTP))}}, caller);
 
     // assert that the superoperator itself was allocated (along with its own heap fields)
     bool isInKrausMap = true;
@@ -2909,11 +2909,11 @@ void validate_krausMapFields(KrausMap map, const char* caller) {
     // check only outer CPU matrix list is allocated, to avoid expensive enumerating of matrices/rows
     assertThat(mem_isOuterAllocated(map.matrices), report::INVALID_KRAUS_MAP_MATRIX_LIST_MEM_PTR, caller);
 
-    // assert isCPTP heap flag allocated, and that is has a valid value
-    assertThat(mem_isAllocated(map.isCPTP), report::INVALID_HEAP_FLAG_PTR, caller);
+    // assert isApproxCPTP heap flag allocated, and that is has a valid value
+    assertThat(mem_isAllocated(map.isApproxCPTP), report::INVALID_HEAP_FLAG_PTR, caller);
 
     // and that its value is a boolean
-    int flag = *map.isCPTP;
+    int flag = *map.isApproxCPTP;
     bool valid = flag == 0 || flag == 1 || flag == validate_STRUCT_PROPERTY_UNKNOWN_FLAG;
     tokenSubs moreVars = {{"${BAD_FLAG}", flag}, {"${UNKNOWN_FLAG}", validate_STRUCT_PROPERTY_UNKNOWN_FLAG}};
     assertThat(valid, report::INVALID_HEAP_FLAG_VALUE, moreVars, caller);
@@ -2941,15 +2941,12 @@ void validate_krausMapIsCPTP(KrausMap map, const char* caller) {
     validate_krausMapFields(map, caller);
     validate_krausMapIsSynced(map, caller);
 
-    // avoid expensive CPTP check (and do not overwrite .isCPTP) if validation is anyway disabled
+    // avoid expensive CPTP check (and do not overwrite .isApproxCPTP) if validation is anyway disabled
     if (isNumericalValidationDisabled())
         return;
 
-    // evaluate CPTPness if it isn't already known 
-    if (*(map.isCPTP) == validate_STRUCT_PROPERTY_UNKNOWN_FLAG)
-        *(map.isCPTP) = util_isCPTP(map, global_validationEpsilon);
-
-    assertThat(*(map.isCPTP), report::KRAUS_MAP_NOT_CPTP, caller);
+    // use existing CPTPness or calculate afresh
+    assertThat(util_isCPTP(map, global_validationEpsilon), report::KRAUS_MAP_NOT_CPTP, caller);
 }
 
 void validate_krausMapMatchesTargets(KrausMap map, int numTargets, const char* caller) {
@@ -3203,11 +3200,8 @@ void validate_pauliStrSumIsHermitian(PauliStrSum sum, const char* caller) {
     if (isNumericalValidationDisabled())
         return;
 
-    // ensure hermiticity is known (if not; compute it)
-    if (*(sum.isApproxHermitian) == validate_STRUCT_PROPERTY_UNKNOWN_FLAG)
-        *(sum.isApproxHermitian) = util_isHermitian(sum, global_validationEpsilon);
-
-    assertThat(*(sum.isApproxHermitian), report::PAULI_STR_SUM_NOT_HERMITIAN, caller);
+    // consult existing Hermiticity or compute it afresh
+    assertThat(util_isHermitian(sum, global_validationEpsilon), report::PAULI_STR_SUM_NOT_HERMITIAN, caller);
 }
 
 void validate_pauliStrSumTargets(PauliStrSum sum, Qureg qureg, const char* caller) {