added setReportedPauli(Chars|StrStyle)

Author: TysonRayJones

quest/include/debug.h

@@ -121,6 +121,38 @@ void setMaxNumReportedSigFigs(int numSigFigs);
 void setNumReportedNewlines(int numNewlines);
 
 
+/** 
+ * @notdoced
+ * @nottested
+ * @myexample
+ * ```
+   PauliStr str = getInlinePauliStr("XYZ", {0,10,20});
+   reportPauliStr(str);
+
+   setReportedPauliChars(".xyz");
+   reportPauliStr(str);
+ * ```
+ */
+void setReportedPauliChars(const char* paulis);
+
+
+/** 
+ * @notdoced
+ * @nottested
+ * @myexample
+ * ```
+   PauliStr str = getInlinePauliStr("XYZ", {0,10,20});
+
+   setReportedPauliStrStyle(0);
+   reportPauliStr(str);
+
+   setReportedPauliStrStyle(1);
+   reportPauliStr(str);
+ * ```
+ */
+void setReportedPauliStrStyle(int style);
+
+
 /** @} */
 
 

quest/src/api/debug.cpp

@@ -155,6 +155,22 @@ void setNumReportedNewlines(int numNewlines) {
 }
 
 
+void setReportedPauliChars(const char* paulis) {
+    validate_envIsInit(__func__);
+    validate_numPauliChars(paulis, __func__);
+
+    printer_setPauliChars(paulis);
+}
+
+
+void setReportedPauliStrStyle(int flag) {
+    validate_envIsInit(__func__);
+    validate_reportedPauliStrStyleFlag(flag, __func__);
+
+    printer_setPauliStrFormat(flag);
+}
+
+
 
 /*
  * GPU CACHE

quest/src/api/paulis.cpp

@@ -327,7 +327,8 @@ PauliStr getPauliStr(int* paulis, int* indices, int numPaulis) {
     // validation ensures never causes stack overflow
     char pauliChars[MAX_NUM_PAULIS_PER_STR + 1]; // +1 for null-terminal
 
-    // made a char array from the pauli codes
+    // make a char array from the pauli codes, using an arbitrary 
+    // choice of the Pauli characters accepted by the API (like IXYZ)
     for (int i=0; i<numPaulis; i++)
         pauliChars[i] = "IXYZ"[paulis[i]];
 

quest/src/core/printer.cpp

@@ -63,6 +63,7 @@ const int SET_SPACE_BETWEEN_KET_AND_RANK = 2;
 // must be kept as single char; use numbers above to change spacing
 const char TABLE_SPACE_CHAR = '.';
 const char MATRIX_SPACE_CHAR = ' ';
+const char PAULI_SPACE_CHAR = ' ';
 
 // should not contain newline
 const string LABEL_SUFFIX = ":";
@@ -137,6 +138,32 @@ int printer_getNumTrailingNewlines() {
 }
 
 
+// user specified characters to represent Pauli operators
+
+string global_pauliChars = "IXYZ";
+
+void printer_setPauliChars(string newChars) {
+
+    global_pauliChars = newChars;
+}
+
+
+// user specified Pauli string format
+
+int global_pauliStrFormatFlag = 0;
+
+void printer_setPauliStrFormat(int flag) {
+
+    /// @todo
+    /// this could be changed to an enum, even though the
+    /// API will likely always receive an int (for C and
+    /// C++ agnosticism and simplicity - I hate polluting
+    /// an API with custom types and constants!).
+
+    global_pauliStrFormatFlag = flag;
+}
+
+
 
 /*
  * TYPE NAME STRINGS
@@ -1236,27 +1263,85 @@ extern int paulis_getIndOfLefmostNonIdentityPauli(PauliStr str);
 extern int paulis_getIndOfLefmostNonIdentityPauli(PauliStr* strings, qindex numStrings);
 
 
-string getPauliStrAsString(PauliStr str, int maxNumQubits) {
+string getPauliStrAsAllQubitsString(PauliStr str, int numPaulis) {
 
-    string labels = "IXYZ";
+    // avoid repeated allocations in below string concatenation
+    string out = "";
+    out.reserve(numPaulis);
 
     // ugly but adequate - like me (call me)
-    string out = "";
-    for (int i=maxNumQubits-1; i>=0; i--)
-        out += labels[paulis_getPauliAt(str, i)];
+    for (int i=numPaulis-1; i>=0; i--) {
+        int code = paulis_getPauliAt(str, i); // 0123
+        out += global_pauliChars[code];       // IXYZ unless user-overriden
+    }
 
     return out;
 }
 
 
+string getPauliStrAsIndexString(PauliStr str, int numPaulis) {
+
+    string out = "";
+
+    // prematurely optimise (hehe) by avoiding repeated allocations
+    // induced by below string concatenation, since we can bound the
+    // string length; each Pauli is 1 char, each index is max 2 digits
+    // (<64) and each inter-Pauli space is 1 char, so <=4 chars per Pauli.
+    int maxLen = numPaulis * 4; // <= 256 always
+    out.reserve(maxLen);
+
+    for (int i=0; i<numPaulis; i++) {
+        int code = paulis_getPauliAt(str, i);
+
+        // don't report identities
+        if (code == 0)
+            continue;
+
+        // e.g. X12 
+        out += global_pauliChars[code] + toStr(i) + PAULI_SPACE_CHAR;
+    }
+
+    // out includes a trailing PAULI_SPACE_CHAR which is fine,
+    // since nothing else is ever post-printed on the same line
+    return out;
+}
+
+
+string getPauliStrAsString(PauliStr str, int numPauliChars=0) {
+
+    // numPauliChars (only used by all-qubits reporting format)
+    // allows the caller to pad the printed PauliStr with left I,
+    // useful when reporting a truncated PauliStrSum to ensure
+    // the top and bottom partitions are aligned and equal width.
+    // When not passed, it defaults to minimum padding
+    if (numPauliChars == 0)
+        numPauliChars = 1 + paulis_getIndOfLefmostNonIdentityPauli(str);
+
+    /// @todo
+    /// to be absolutely pedantic/defensively-designed, we should
+    /// assert numPauliChars >= 1+paulis_getIndOfLefmostNonIdentityPauli
+    /// to ensure a bug never occludes a PauliStr. Very low priority!
+
+    switch(global_pauliStrFormatFlag) {
+        case 0: return getPauliStrAsAllQubitsString(str, numPauliChars);
+        case 1: return getPauliStrAsIndexString(str, numPauliChars);
+    }
+
+    /// @todo
+    /// to be defensively-designed, we should throw a runtime error
+    /// here because global_pauliStrFormatFlag was mutilated. This is
+    /// a very low priority; so we just return a suspicious string!
+    return "(PauliStr stringifying failed - please alert the QuEST devs)";
+}
+
+
 void print_elemsWithoutNewline(PauliStr str, string indent) {
 
     // only root node ever prints
     if (!comm_isRootNode())
         return;
 
-    int numPaulis = 1 + paulis_getIndOfLefmostNonIdentityPauli(str);
-    cout << indent << getPauliStrAsString(str, numPaulis);
+    cout << indent << getPauliStrAsString(str);
 
     // beware that NO trailing newlines are printed so subsequent
     // calls (without calling print_newlines()) will run-on

quest/src/core/printer.hpp

@@ -42,6 +42,10 @@ void printer_setNumTrailingNewlines(int numNewlines);
 
 int printer_getNumTrailingNewlines();
 
+void printer_setPauliChars(string newChars);
+
+void printer_setPauliStrFormat(int flag);
+
 
 
 /*

quest/src/core/validation.cpp

@@ -134,6 +134,12 @@ namespace report {
     string INSUFFICIENT_NUM_REPORTED_NEWLINES =
         "The number of trailing newlines (set by setNumReportedNewlines()) is zero which is not permitted when calling multi-line reporters.";
 
+    string INVALID_NUM_NEW_PAULI_CHARS =
+        "Given an invalid number of Pauli characters. Must specify precisely four to respectively replace IXYZ.";
+
+    string INVALID_REPORTED_PAULI_STR_STYLE_FLAG =
+        "Given an unrecognised style flag (${FLAG}). Legal flags are 0 and 1.";
+
 
     /*
      * QUREG CREATION
@@ -1433,6 +1439,21 @@ void validate_numReportedNewlinesAboveZero(const char* caller) {
     assertThat(printer_getNumTrailingNewlines() > 0, report::INSUFFICIENT_NUM_REPORTED_NEWLINES, caller);
 }
 
+void validate_numPauliChars(const char* paulis, const char* caller) {
+
+    // check position of terminal char, else default to numChars=5 (illegal)
+    int numChars = 0;
+    for (int i=0; i<5 && paulis[i] != '\0'; i++)
+        numChars++;
+    
+    assertThat(numChars==4, report::INVALID_NUM_NEW_PAULI_CHARS, caller);
+}
+
+void validate_reportedPauliStrStyleFlag(int flag, const char* caller) {
+
+    assertThat(flag==0 || flag==1, report::INVALID_REPORTED_PAULI_STR_STYLE_FLAG, {{"${FLAG}",flag}}, caller);
+}
+
 
 
 /*

quest/src/core/validation.hpp

@@ -103,6 +103,10 @@ void validate_newNumReportedNewlines(int numNewlines, const char* caller);
 
 void validate_numReportedNewlinesAboveZero(const char* caller);
 
+void validate_numPauliChars(const char* paulis, const char* caller);
+
+void validate_reportedPauliStrStyleFlag(int flag, const char* caller);
+
 
 
 /*

tests/unit/debug.cpp

@@ -750,3 +750,6 @@ void setMaxNumReportedItems(qindex numRows, qindex numCols);
 
 void getEnvironmentString(char str[200]);
 
+void setReportedPauliChars(const char* paulis);
+
+void setReportedPauliStrStyle(int style);