Functions to control how QuEST's reporters display and truncate information. More...

Functions
void	setQuESTMaxNumReportedItems (qindex numRows, qindex numCols)

void	setQuESTMaxNumReportedSigFigs (int numSigFigs)

void	setQuESTNumReportedNewlines (int numNewlines)

void	setQuESTReportedPauliChars (const char *paulis)

void	setQuESTReportedPauliStrStyle (int style)

Detailed Description

Functions to control how QuEST's reporters display and truncate information.

Function Documentation

◆ setQuESTMaxNumReportedItems()

void setQuESTMaxNumReportedItems	(	qindex	numRows,
		qindex	numCols )

Sets the maximum number of rows and columns of data structures subsequently printed by QuEST's report functions, with remaining elements ellipted.

This function is useful for keeping stdout concise and readable when reporting large data structures, such as matrices and Qureg. The ellipted elements are in the center of the reported data structure. The specified maximums persist until changed again with this function.

Remarks: Specifying numRows=0 or numCols=0 respectively disables ellipsis across rows and columns respectively. Beware this means that functions like reportQureg() will display the entirety of their data, which can be very large.

This function presently affects the output of functions:

In contrast, it has no effect on the output of functions:

‍When this function is not called, the QuEST defaults are adopted, which are presently:

numRows=32

numCols=4

Example

Qureg qureg = createDensityQureg(6);
initRandomPureState(qureg);
setQuESTMaxNumReportedItems(7,4);
reportQureg(qureg);

will report 7 rows and 4 columns of qureg.

Qureg (6 qubit density matrix, 64x64 qcomps, 64.1 KiB):
    0.012273+(3.2329e-19)i  -0.0056906+0.0072884i   …  -0.0052104-0.0070839i    0.00092891-0.0086299i    
    -0.0056906-0.0072884i   0.0069669-(1.363e-20)i  …  -0.0017909+0.0063788i    -0.0055556+0.0034498i    
    0.014757-0.0083751i     -0.0018689+0.012647i    …  -0.011099-0.0049622i     -0.0047721-0.011011i     
    0.00078401+0.0014319i   -0.0012139-0.00019834i  …  0.00049365-0.0010604i    0.0010662-0.00044291i    
              ⋮
    -0.010456+0.012047i     -0.0023056-0.011795i    …  0.011393+0.00092115i     0.0076794+0.0082644i     
    -0.0052104+0.0070839i   -0.0017909-0.0063788i   …  0.0063009-(3.3799e-20)i  0.0045868+0.0041999i     
    0.00092891+0.0086299i   -0.0055556-0.0034498i   …  0.0045868-0.0041999i     0.0061386-(1.4941e-19)i  

Parameters

[in]	numRows	the max number of rows to report (all if `=0`).
[in]	numCols	the max number of columns to report (all if `=0`).

Exceptions

error

if the QuEST environment has not been initialised via initQuESTEnv().
if either numRows or numCols is negative.

See also

C and C++ examples
setQuESTMaxNumReportedSigFigs()
setQuESTNumReportedNewlines()

Definition at line 128 of file debug.cpp.

                                                                 {
    validate_envIsInit(__func__);
    validate_newMaxNumReportedScalars(numRows, numCols, __func__);
 
    // replace 0 values (indicating no truncation) with max-val,
    // since there can never be max(qindex)-many amps
    qindex max = std::numeric_limits<qindex>::max();
    numRows = (numRows == 0)? max : numRows;
    numCols = (numCols == 0)? max : numCols;
 
    printer_setMaxNumPrintedScalars(numRows, numCols);
}

◆ setQuESTMaxNumReportedSigFigs()

void setQuESTMaxNumReportedSigFigs ( int numSigFigs )

Sets the maximum number of significant figures in floating-point numbers printed by QuEST's reporter functions.

This function is useful for keeping stdout concise and readable when reporting numerical quantites, such as matrices and Qureg amplitudes. The specified number of significant figures persists until changed again with this function.

Remarks: Numbers with fewer non-zero significant figures will not be padded with zeros, and so will print fewer digits than numSigFigs, keeping the output concise.

Note: Complex quantities will have their real and imaginary components separately printed, each with the specified number of significant figures.

Important: This function does not affect the significant figures in printed memory sizes (e.g. 5.32 KiB) which is always shown with three significant figures (or four when in bytes, e.g. 1023 bytes).

Example

Qureg qureg = createQureg(3);
initRandomPureState(qureg);
 
setQuESTMaxNumReportedSigFigs(2);
reportQureg(qureg);
 
setQuESTMaxNumReportedSigFigs(10);
reportQureg(qureg);

may output

Qureg (3 qubit statevector, 8 qcomps, 232 bytes):
    0.49+0.35i    |0⟩
    -0.085+0.17i  |1⟩
    0.37+0.099i   |2⟩
    -0.14+0.088i  |3⟩
    -0.29+0.078i  |4⟩
    0.19+0.019i   |5⟩
    0.02-0.5i     |6⟩
    -0.032+0.22i  |7⟩
 
Qureg (3 qubit statevector, 8 qcomps, 232 bytes):
    0.4915502074+0.3471270204i    |0⟩
    -0.08473589829+0.1685819182i  |1⟩
    0.3702183582+0.0991921232i    |2⟩
    -0.142193399+0.08829704821i   |3⟩
    -0.2881909331+0.07795511511i  |4⟩
    0.1868915394+0.01946703883i   |5⟩
    0.01956017542-0.5029788111i   |6⟩
    -0.03171267079+0.220342331i   |7⟩

Meanwhile,

CompMatr1 matr = getInlineCompMatr1({{1,2},{3,4.123456789}});
setQuESTMaxNumReportedSigFigs(3);
reportCompMatr1(matr);

will output

CompMatr1 (1 qubit, 2x2 qcomps, 80 bytes):
    1  2     
    3  4.12

Parameters

[in] numSigFigs the max number of significant figures to print in subsequent report functions.

Exceptions

error

if the QuEST environment has not been initialised via initQuESTEnv().
if numSigFigs is negative.

See also

setQuESTMaxNumReportedItems()
setQuESTNumReportedNewlines()

Author: Tyson Jones

Definition at line 142 of file debug.cpp.

                                                   {
    validate_envIsInit(__func__);
    validate_newMaxNumReportedSigFigs(numSigFigs, __func__);
 
    printer_setMaxNumPrintedSigFig(numSigFigs);
}

◆ setQuESTNumReportedNewlines()

void setQuESTNumReportedNewlines ( int numNewlines )

Sets the number of trailing newlines printed at the end of QuEST's report functions.

These newlines are merely a convenience so that users do not have to manually intersperse newlines in stdout between functions like reportScalar() and reportPauliStr(), which becomes a greater pain in distributed settings when avoiding duplicated output across processes. The specified number of newlines persists until changed again with this function.

Example

By default, the sequence

reportCompMatr1(getInlineCompMatr1({{1,2},{3,4}}));
reportPauliStr(getInlinePauliStr("XYZ", {0,2,4}));
reportScalar("x", 5);
reportStr("hello world!");

will print with the internal default of numNewLines=2

CompMatr1 (1 qubit, 2x2 qcomps, 80 bytes):
    1  2  
    3  4  
 
ZIYIX
 
x: 5
 
hello world!

but if called after setQuESTNumReportedNewlines(1), will output

CompMatr1 (1 qubit, 2x2 qcomps, 80 bytes):
    1  2  
    3  4  
ZIYIX
x: 5
hello world!

It is possible to forego all trailing newlines, and also to write to stdout between report functions.

setQuESTNumReportedNewlines(0);
reportPauliStr(getInlinePauliStr("XYZ", {0,2,4}));
printf(" * ");
reportPauliStr(getInlinePauliStr("ZZZ", {0,1,2}));
printf(" = ");
reportPauliStr(getInlinePauliStr("YZXZ", {0,1,2,4}));
printf("\n");

ZIYIX * ZZZ = ZIXZY

Parameters

[in] numNewlines the new number of trailing newlines.

Exceptions

error

if the QuEST environment has not been initialised via initQuESTEnv().
if numNewlines is negative.

Author: Tyson Jones

Definition at line 150 of file debug.cpp.

                                                  {
    validate_envIsInit(__func__);
    validate_newNumReportedNewlines(numNewlines, __func__);
 
    printer_setNumTrailingNewlines(numNewlines);
}

◆ setQuESTReportedPauliChars()

void setQuESTReportedPauliChars ( const char * paulis )

Sets the characters used by reportPauliStr() and reportPauliStrSum() to indicate the I, X, Y and Z Pauli operators.

Example: PauliStr str = getInlinePauliStr("XYZZ", {0,10,13,20});

reportPauliStr(str);

setQuESTReportedPauliChars(".xyz");

reportPauliStr(str);

setQuESTReportedPauliChars(" !!!");

reportPauliStr(str);

setQuESTReportedPauliChars
void setQuESTReportedPauliChars(const char *paulis)
Definition debug.cpp:158

PauliStr
Definition paulis.h:53

ZIIIIIIZIIYIIIIIIIIIX

z......z..y.........x

! ! ! !

These symbols are used across all styles accepted by setQuESTReportedPauliStrStyle().
setQuESTReportedPauliStrStyle(1); // style=1

setQuESTReportedPauliChars(".XyS");

reportPauliStr(str);

setQuESTReportedPauliStrStyle
void setQuESTReportedPauliStrStyle(int style)
Definition debug.cpp:166

X0 y10 S13 S20

Parameters

[in] paulis four characters to indicate I, X, Y and Z respectively.

Exceptions

error	if the QuEST environment has not been initialised via initQuESTEnv(). if `paulis` is not length `4`.
seg-fault	if `paulis` is a null pointer. if `paulis` does not contain a terminal character and is smaller than 4 bytes in size.

See also

setQuESTReportedPauliStrStyle()

Author: Tyson Jones

Definition at line 158 of file debug.cpp.

                                                    {
    validate_envIsInit(__func__);
    validate_numPauliChars(paulis, __func__);
 
    printer_setPauliChars(paulis);
}

◆ setQuESTReportedPauliStrStyle()

void setQuESTReportedPauliStrStyle ( int style )

Sets the visual style of Pauli strings printed by reportPauliStr() and reportPauliStrSum().

When style=0 (default), every Pauli operator in the string is printed, until the largest-index non-identity operator. The rightmost printed operator is the least significant (i.e. of qubit index 0).

For example:
setQuESTReportedPauliStrStyle(0); // default

reportPauliStr(getInlinePauliStr("XYZZ", {0,10,13,20}));

ZIIIIIIZIIYIIIIIIIIIX
When style=1, only non-identity Pauli operators are printed, followed by their indices.

For example:
setQuESTReportedPauliStrStyle(1);

reportPauliStr(getInlinePauliStr("XYZZ", {0,10,13,20}));

X0 Y10 Z13 Z20

The symbols for I, X, Y and Z can be overridden with setQuESTReportedPauliChars().

Parameters

[in] style either 0 or 1 to respectively indicate the above styles.

Exceptions

error

if the QuEST environment has not been initialised via initQuESTEnv().
if style is not 0 or 1.

See also

setQuESTReportedPauliChars()

Author: Tyson Jones

Definition at line 166 of file debug.cpp.

                                             {
    validate_envIsInit(__func__);
    validate_reportedPauliStrStyleFlag(flag, __func__);
 
    printer_setPauliStrFormat(flag);
}