Utilities for testing QuEST's deprecated v3 API functions. More...

Typedefs
typedef vector< vector< qcomp > >	QMatrix

typedef vector< qcomp >	QVector

Functions
void	applyReferenceMatrix (QMatrix &state, int ctrls, int numCtrls, int targs, int numTargs, QMatrix op)

void	applyReferenceMatrix (QMatrix &state, int *targs, int numTargs, QMatrix op)

void	applyReferenceMatrix (QVector &state, int ctrls, int numCtrls, int targs, int numTargs, QMatrix op)

void	applyReferenceMatrix (QVector &state, int *targs, int numTargs, QMatrix op)

void	applyReferenceOp (QMatrix &state, int ctrls, int numCtrls, int targs, int numTargs, QMatrix op)

void	applyReferenceOp (QMatrix &state, int *ctrls, int numCtrls, int targ1, int targ2, QMatrix op)

void	applyReferenceOp (QMatrix &state, int *ctrls, int numCtrls, int target, QMatrix op)

void	applyReferenceOp (QMatrix &state, int *targs, int numTargs, QMatrix op)

void	applyReferenceOp (QMatrix &state, int ctrl, int *targs, int numTargs, QMatrix op)

void	applyReferenceOp (QMatrix &state, int ctrl, int targ, QMatrix op)

void	applyReferenceOp (QMatrix &state, int ctrl, int targ1, int targ2, QMatrix op)

void	applyReferenceOp (QMatrix &state, int targ, QMatrix op)

void	applyReferenceOp (QVector &state, int ctrls, int numCtrls, int targs, int numTargs, QMatrix op)

void	applyReferenceOp (QVector &state, int *ctrls, int numCtrls, int targ1, int targ2, QMatrix op)

void	applyReferenceOp (QVector &state, int *ctrls, int numCtrls, int target, QMatrix op)

void	applyReferenceOp (QVector &state, int *targs, int numTargs, QMatrix op)

void	applyReferenceOp (QVector &state, int ctrl, int *targs, int numTargs, QMatrix op)

void	applyReferenceOp (QVector &state, int ctrl, int targ, QMatrix op)

void	applyReferenceOp (QVector &state, int ctrl, int targ1, int targ2, QMatrix op)

void	applyReferenceOp (QVector &state, int targ, QMatrix op)

bool	areEqual (QMatrix a, QMatrix b)

bool	areEqual (Qureg qureg, QMatrix matr)

bool	areEqual (Qureg qureg, QMatrix matr, qreal precision)

bool	areEqual (Qureg qureg, QVector vec)

bool	areEqual (Qureg qureg, QVector vec, qreal precision)

bool	areEqual (Qureg qureg1, Qureg qureg2)

bool	areEqual (Qureg qureg1, Qureg qureg2, qreal precision)

bool	areEqual (QVector a, QVector b)

bool	areEqual (QVector vec, qreal *reals)

bool	areEqual (QVector vec, qreal reals, qreal imags)

void	assertQuregAndRefInDebugState (Qureg qureg, QMatrix ref)

void	assertQuregAndRefInDebugState (Qureg qureg, QVector ref)

CatchGen< int * >	bitsets (int numBits)

unsigned int	calcLog2 (long unsigned int res)

void	deleteFilesWithPrefixSynch (char *prefix)

QMatrix	getConjugateTranspose (QMatrix a)

QVector	getDFT (QVector in)

QVector	getDFT (QVector in, int *targs, int numTargs)

QMatrix	getExponentialOfDiagonalMatrix (QMatrix a)

QMatrix	getExponentialOfPauliMatrix (qreal angle, QMatrix a)

QMatrix	getFullOperatorMatrix (int ctrls, int numCtrls, int targs, int numTargs, QMatrix op, int numQubits)

QMatrix	getIdentityMatrix (size_t dim)

QMatrix	getKetBra (QVector ket, QVector bra)

QMatrix	getKroneckerProduct (QMatrix a, QMatrix b)

QVector	getKroneckerProduct (QVector b, QVector a)

QVector	getMatrixDiagonal (QMatrix matr)

QMatrix	getMixedDensityMatrix (vector< qreal > probs, vector< QVector > states)

QVector	getNormalised (QVector vec)

QMatrix	getPureDensityMatrix (QVector state)

qcomp	getRandomComplex ()

QMatrix	getRandomDensityMatrix (int numQb)

int	getRandomInt (int min, int max)

vector< QMatrix >	getRandomKrausMap (int numQb, int numOps)

vector< QVector >	getRandomOrthonormalVectors (int numQb, int numStates)

vector< qreal >	getRandomProbabilities (int numProbs)

QMatrix	getRandomPureDensityMatrix (int numQb)

QMatrix	getRandomQMatrix (int dim)

QVector	getRandomQVector (int dim)

qreal	getRandomReal (qreal min, qreal max)

QVector	getRandomStateVector (int numQb)

QMatrix	getRandomUnitary (int numQb)

QMatrix	getSwapMatrix (int qb1, int qb2, int numQb)

long long int	getTwosComplement (long long int decimal, int numBits)

long long int	getUnsigned (long long int twosComp, int numBits)

long long int	getValueOfTargets (long long int ind, int *targs, int numTargs)

QMatrix	getZeroMatrix (size_t dim)

CatchGen< pauliOpType * >	pauliseqs (int numPaulis)

CatchGen< int * >	sequences (int base, int numDigits)

void	setRandomDiagPauliHamil (PauliHamil hamil, int numQubits)

void	setRandomPauliSum (PauliHamil hamil, int numQubits)

void	setRandomPauliSum (qreal coeffs, pauliOpType codes, int numQubits, int numTerms)

void	setRandomTargets (int *targs, int numTargs, int numQb)

void	setRandomTargets (vector< int > &targs, int numQb)

void	setRandomTestStateSeeds ()

void	setSubMatrix (QMatrix &dest, QMatrix sub, size_t r, size_t c)

void	setUniqueFilename (char outFn, int maxlen, char prefix)

CatchGen< int * >	sublists (CatchGen< int > &&gen, int numSamps, const int *exclude, int numExclude)

CatchGen< int * >	sublists (CatchGen< int > &&gen, int numSamps, int excluded)

CatchGen< int * >	sublists (CatchGen< int > &&gen, int sublen)

CatchGen< int * >	sublists (int *list, int len, int sublen)

ComplexMatrix2	toComplexMatrix2 (QMatrix qm)

ComplexMatrix4	toComplexMatrix4 (QMatrix qm)

void	toComplexMatrixN (QMatrix qm, ComplexMatrixN cm)

QMatrix	toDiagonalQMatrix (QVector vec)

QMatrix	toQMatrix (CompMatr src)

QMatrix	toQMatrix (CompMatr1 src)

QMatrix	toQMatrix (CompMatr2 src)

QMatrix	toQMatrix (DiagMatr matr)

QMatrix	toQMatrix (FullStateDiagMatr matr)

QMatrix	toQMatrix (PauliHamil hamil)

QMatrix	toQMatrix (PauliStrSum sum)

QMatrix	toQMatrix (qreal coeffs, pauliOpType paulis, int numQubits, int numTerms)

QMatrix	toQMatrix (Qureg qureg)

void	toQureg (Qureg qureg, QMatrix mat)

void	toQureg (Qureg qureg, QVector vec)

QVector	toQVector (DiagMatr op)

QVector	toQVector (FullStateDiagMatr op)

QVector	toQVector (Qureg qureg)

void	writeToFileSynch (char *fn, const string &contents)

Detailed Description

Utilities for testing QuEST's deprecated v3 API functions.

Typedef Documentation

◆ QMatrix

typedef vector<vector<qcomp> > QMatrix

A complex square matrix. Should be initialised with getZeroMatrix(). These have all the natural linear-algebra operator overloads, including left-multiplication onto a vector.

This data-structure is not partitioned between nodes in distributed mode. That is, every node has a complete copy, allowing for safe comparisons.

Author: Tyson Jones

Definition at line 60 of file test_utilities.hpp.

◆ QVector

typedef vector<qcomp> QVector

A complex vector, which can be zero-initialised with QVector(numAmps). These have all the natural linear-algebra operator overloads.

This data-structure is not partitioned between nodes in distributed mode. That is, every node has a complete copy, allowing for safe comparisons.

Author: Tyson Jones

Definition at line 71 of file test_utilities.hpp.

Function Documentation

◆ applyReferenceMatrix() [1/4]

void applyReferenceMatrix	(	QMatrix &	state,
		int *	ctrls,
		int	numCtrls,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the density matrix state to be the result of left-multiplying the multi-target operator matrix op, with the specified control and target qubits (in ctrls and targs respectively). Here, op is treated like a simple matrix and is hence left-multiplied onto the state once.

Author: Tyson Jones

Definition at line 997 of file test_utilities.cpp.

  {
    // for density matrices, op is left-multiplied only
    int numQubits = calcLog2(state.size());
    QMatrix leftOp = getFullOperatorMatrix(ctrls, numCtrls, targs, numTargs, op, numQubits);
    state = leftOp * state;
}

◆ applyReferenceMatrix() [2/4]

void applyReferenceMatrix	(	QMatrix &	state,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the density matrix state to be the result of left-multiplying the multi-target operator matrix op, with the target qubits (assuming no control qubits). Here, op is treated like a simple matrix and is hence left-multiplied onto the state once.

Author: Tyson Jones

Definition at line 1005 of file test_utilities.cpp.

  {
    applyReferenceMatrix(state, NULL, 0, targs, numTargs, op);
}

◆ applyReferenceMatrix() [3/4]

void applyReferenceMatrix	(	QVector &	state,
		int *	ctrls,
		int	numCtrls,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the state-vector state to be the result of left-multiplying the multi-target operator matrix op, with the specified control and target qubits (in ctrls and targs respectively). This is an alias of applyReferenceOp(), since operators are always left-multiplied as matrices onto state-vectors.

Author: Tyson Jones

Definition at line 985 of file test_utilities.cpp.

  {
    // for state-vectors, the op is always just left-multiplied
    applyReferenceOp(state, ctrls, numCtrls, targs, numTargs, op);
}

Referenced by applyReferenceMatrix(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ applyReferenceMatrix() [4/4]

void applyReferenceMatrix	(	QVector &	state,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the state-vector state to be the result of left-multiplying the multi-target operator matrix op, with the specified target qubits (assuming no control qubits). T

Author: Tyson Jones

Definition at line 991 of file test_utilities.cpp.

  {
    // for state-vectors, the op is always just left-multiplied
    applyReferenceOp(state, targs, numTargs, op);
}

◆ applyReferenceOp() [1/16]

void applyReferenceOp	(	QMatrix &	state,
		int *	ctrls,
		int	numCtrls,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the multi-target operator matrix op, with the specified control and target qubits (in ctrls and targs respectively). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 2^numTargs-by-2^numTargs matrix. Furthermore, every element of targs must not appear in ctrls (and vice-versa), though this is not explicitly checked. Elements of targs and ctrls should be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 928 of file test_utilities.cpp.

  {
    int numQubits = calcLog2(state.size());
    QMatrix leftOp = getFullOperatorMatrix(ctrls, numCtrls, targs, numTargs, op, numQubits);
    QMatrix rightOp = getConjugateTranspose(leftOp);
    state = leftOp * state * rightOp;
}

◆ applyReferenceOp() [2/16]

void applyReferenceOp	(	QMatrix &	state,
		int *	ctrls,
		int	numCtrls,
		int	targ1,
		int	targ2,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the two-target operator matrix op, with the specified control qubits (in ctrls). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 4-by-4 matrix. Both targ1 and targ2 must not appear in ctrls, though this is not explicitly checked. Elements of ctrls, and targ1 and targ2, should be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 936 of file test_utilities.cpp.

  {
    int targs[2] = {targ1, targ2};
    applyReferenceOp(state, ctrls, numCtrls, targs, 2, op);
}

◆ applyReferenceOp() [3/16]

void applyReferenceOp	(	QMatrix &	state,
		int *	ctrls,
		int	numCtrls,
		int	target,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the single-target operator matrix op, with the specified control qubits (in ctrls). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 2-by-2 matrix. target must not appear in ctrls, though this is not explicitly checked.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 942 of file test_utilities.cpp.

  {
    int targs[1] = {target};
    applyReferenceOp(state, ctrls, numCtrls, targs, 1, op);
}

◆ applyReferenceOp() [4/16]

void applyReferenceOp	(	QMatrix &	state,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the multi-target operator matrix op, with no control qubits. This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 2^numTargs-by-2^numTargs matrix. Every element in targs should be unique, though this is not explicitly checked.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 948 of file test_utilities.cpp.

  {
    applyReferenceOp(state, NULL, 0, targs, numTargs, op);
}

◆ applyReferenceOp() [5/16]

void applyReferenceOp	(	QMatrix &	state,
		int	ctrl,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the multi-target operator matrix op, with a single control qubit ctrl. This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 2^numTargs-by-2^numTargs matrix, and ctrl must not appear in targs (though this is not explicitly checked).

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 960 of file test_utilities.cpp.

  {
    int ctrls[1] = {ctrl};
    applyReferenceOp(state, ctrls, 1, targs, numTargs, op);
}

◆ applyReferenceOp() [6/16]

void applyReferenceOp	(	QMatrix &	state,
		int	ctrl,
		int	targ,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the single-control single-target operator matrix op. This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 2-by-2 matrix, and ctrl and targ should be different.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 953 of file test_utilities.cpp.

  {
    int ctrls[1] = {ctrl};
    int targs[1] = {targ};
    applyReferenceOp(state, ctrls, 1, targs, 1, op);
}

◆ applyReferenceOp() [7/16]

void applyReferenceOp	(	QMatrix &	state,
		int	ctrl,
		int	targ1,
		int	targ2,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the two-target operator matrix op, with a single control qubit ctrl. This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 4-by-4 matrix, and ctrl, targ1 and targ2 must be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 966 of file test_utilities.cpp.

  {
    int ctrls[1] = {ctrl};
    int targs[2] = {targ1, targ2};
    applyReferenceOp(state, ctrls, 1, targs, 2, op);
}

◆ applyReferenceOp() [8/16]

void applyReferenceOp	(	QMatrix &	state,
		int	targ,
		QMatrix	op )

Modifies the density matrix state to be the result of applying the single-target operator matrix op, with no control qubit. This updates state under

\[ \text{state} \to \text{op} \, \text{state} \, \text{op}^\dagger \]

even if op is not unitary (which is useful for applying Kraus operators).

op must be a 2-by-2 matrix.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multipling it to state, then right-multiplying its conjugate transpose onto the result.

Author: Tyson Jones

Definition at line 973 of file test_utilities.cpp.

  {
    int targs[1] = {targ};
    applyReferenceOp(state, NULL, 0, targs, 1, op);
}

◆ applyReferenceOp() [9/16]

void applyReferenceOp	(	QVector &	state,
		int *	ctrls,
		int	numCtrls,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the multi-target operator matrix op, with the specified control and target qubits (in ctrls and targs respectively). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 2^numTargs-by-2^numTargs matrix. Furthermore, every element of targs must not appear in ctrls (and vice-versa), though this is not explicitly checked. Elements of targs and ctrls should be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 872 of file test_utilities.cpp.

  {
    int numQubits = calcLog2(state.size());
    QMatrix fullOp = getFullOperatorMatrix(ctrls, numCtrls, targs, numTargs, op, numQubits);
    state = fullOp * state;
}

◆ applyReferenceOp() [10/16]

void applyReferenceOp	(	QVector &	state,
		int *	ctrls,
		int	numCtrls,
		int	targ1,
		int	targ2,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the two-target operator matrix op, with the specified control qubits (in ctrls). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 4-by-4 matrix. Furthermore, ctrls, targ1 and targ2 should all be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 879 of file test_utilities.cpp.

  {
    int targs[2] = {targ1, targ2};
    applyReferenceOp(state, ctrls, numCtrls, targs, 2, op);
}

◆ applyReferenceOp() [11/16]

void applyReferenceOp	(	QVector &	state,
		int *	ctrls,
		int	numCtrls,
		int	target,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the single-target operator matrix op, with the specified control qubits (in ctrls). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 2-by-2 matrix. Furthermore, elements in ctrls and target should all be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 885 of file test_utilities.cpp.

  {
    int targs[1] = {target};
    applyReferenceOp(state, ctrls, numCtrls, targs, 1, op);
}

◆ applyReferenceOp() [12/16]

void applyReferenceOp	(	QVector &	state,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the multi-target operator matrix op, with no contorl qubits. This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 2^numTargs-by-2^numTargs matrix. Furthermore, elements in targs should be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 891 of file test_utilities.cpp.

  {
    applyReferenceOp(state, NULL, 0, targs, numTargs, op);
}

◆ applyReferenceOp() [13/16]

void applyReferenceOp	(	QVector &	state,
		int	ctrl,
		int *	targs,
		int	numTargs,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the multi-target operator matrix op, with a single control qubit (ctrl) This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 2^numTargs-by-2^numTargs matrix. Furthermore, elements in targs and ctrl should be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 903 of file test_utilities.cpp.

  {
    int ctrls[1] = {ctrl};
    applyReferenceOp(state, ctrls, 1, targs, numTargs, op);
}

◆ applyReferenceOp() [14/16]

void applyReferenceOp	(	QVector &	state,
		int	ctrl,
		int	targ,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the single-target operator matrix op, with a single control qubit (ctrl). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 2-by-2 matrix. Furthermore, ctrl and targ must be different.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 896 of file test_utilities.cpp.

  {
    int ctrls[1] = {ctrl};
    int targs[1] = {targ};
    applyReferenceOp(state, ctrls, 1, targs, 1, op);
}

◆ applyReferenceOp() [15/16]

void applyReferenceOp	(	QVector &	state,
		int	ctrl,
		int	targ1,
		int	targ2,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the two-target operator matrix op, with a single control qubit (ctrl). This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 4-by-4 matrix. Furthermore, ctrl, targ1 and targ2 should all be unique.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 909 of file test_utilities.cpp.

  {
    int ctrls[1] = {ctrl};
    int targs[2] = {targ1, targ2};
    applyReferenceOp(state, ctrls, 1, targs, 2, op);
}

◆ applyReferenceOp() [16/16]

void applyReferenceOp	(	QVector &	state,
		int	targ,
		QMatrix	op )

Modifies the state-vector state to be the result of applying the single-target operator matrix op, with no contorl qubits. This updates state under

\[ \text{state} \to \text{op} \, \text{state} \]

even if op is not unitary.

op must be a 2-by-2 matrix.

This function works by computing getFullOperatorMatrix() from the given arguments, and left-multiplying it onto state.

Author: Tyson Jones

Definition at line 916 of file test_utilities.cpp.

  {
    int targs[1] = {targ};
    applyReferenceOp(state, NULL, 0, targs, 1, op);
}

◆ areEqual() [1/10]

bool areEqual	(	QMatrix	a,
		QMatrix	b )

Returns true if the absolute value of the difference between every amplitude in matrices a and b is less than REAL_EPS.

Author: Tyson Jones

Definition at line 524 of file test_utilities.cpp.

                                    {
    DEMAND( a.size() == b.size() );
    
    for (size_t i=0; i<a.size(); i++)
        for (size_t j=0; j<b.size(); j++)
            if (abs(a[i][j] - b[i][j]) > REAL_EPS)
                return false;
    return true;
}

◆ areEqual() [2/10]

bool areEqual	(	Qureg	qureg,
		QMatrix	matr )

Performs a hardware-agnostic comparison of density-matrix qureg to matr, checking whether the difference between the real and imaginary components of every amplitude is smaller than the QuEST_PREC-specific REAL_EPS (defined in QuEST_precision) precision. This function demands qureg is a density matrix, and that qureg and matr have equal dimensions.

In GPU mode, this function involves a GPU to CPU memory copy overhead. In distributed mode, it involves a all-to-all single-int broadcast.

Author: Tyson Jones

Definition at line 1139 of file test_utilities.cpp.

                                         {
    return areEqual(qureg, matr, REAL_EPS);
}

◆ areEqual() [3/10]

bool areEqual	(	Qureg	qureg,
		QMatrix	matr,
		qreal	precision )

Performs a hardware-agnostic comparison of density-matrix qureg to matr, checking whether the difference between the real and imaginary components of every amplitude is smaller than precision. This function demands qureg is a density matrix, and that qureg and matr have equal dimensions.

In GPU mode, this function involves a GPU to CPU memory copy overhead. In distributed mode, it involves a all-to-all single-int broadcast.

Author: Tyson Jones

Definition at line 1080 of file test_utilities.cpp.

                                                          {
    DEMAND( qureg.isDensityMatrix );
    DEMAND( (long long int) (matr.size()*matr.size()) == qureg.numAmps );
    
    // ensure local qureg amps is up to date
    copyStateFromGPU(qureg);
    syncQuESTEnv();
    
    // the starting index in vec of this node's qureg partition.
    long long int startInd = qureg.rank * qureg.numAmpsPerNode;
    long long int globalInd, row, col, i;
    int ampsAgree;
    
    // compare each of this node's amplitude to the corresponding matr sub-matrix
    for (i=0; i<qureg.numAmpsPerNode; i++) {
        globalInd = startInd + i;
        row = globalInd % matr.size();
        col = globalInd / matr.size();
 
        qreal realDif = absReal(real(qureg.cpuAmps[i]) - real(matr[row][col]));
        qreal imagDif = absReal(imag(qureg.cpuAmps[i]) - imag(matr[row][col]));
        ampsAgree = (realDif < precision && imagDif < precision);
        
        // DEBUG
        if (!ampsAgree) {
            char buff[200];
            snprintf(buff, 200, "[msg from utilities.cpp] node %d has a disagreement at %lld of (%s) + i(%s):\n\t[qureg] %s + i(%s) VS [ref] %s + i(%s)\n",
                qureg.rank, startInd+i,
                QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER, 
                QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER);
            printf(buff,
                realDif, imagDif,
                real(qureg.cpuAmps[i]), imag(qureg.cpuAmps[i]),
                real(matr[row][col]),   imag(matr[row][col]));
        }
 
        // break loop as soon as amplitudes disagree
        if (!ampsAgree)
            break;
            
        /* TODO:
         * of the nodes which disagree, the lowest-rank should send its 
         * disagreeing (i, row, col, stateVec[i]) to rank 0 which should 
         * report it immediately (before the impending DEMAND failure)
         * using FAIL_CHECK, so users can determine nature of disagreement 
         * (e.g. numerical precision).
         * Note FAIL_CHECK accepts << like cout, e.g.
         * FAIL_CHECK( "Amp at (" << row << ", " << col ") disagreed" );
         */
    }
    
    // if one node's partition wasn't equal, all-nodes must report not-equal
    int allAmpsAgree = ampsAgree;
#if COMPILE_MPI
    MPI_Allreduce(&ampsAgree, &allAmpsAgree, 1, MPI_INT, MPI_LAND, MPI_COMM_WORLD);
#endif
        
    return allAmpsAgree;
}

◆ areEqual() [4/10]

bool areEqual	(	Qureg	qureg,
		QVector	vec )

Performs a hardware-agnostic comparison of state-vector qureg to vec, checking whether the difference between the real and imaginary components of every amplitude is smaller than the QuEST_PREC-specific REAL_EPS (defined in QuEST_precision) precision. This function demands qureg is a state-vector, and that qureg and vec have the same number of amplitudes.

In GPU mode, this function involves a GPU to CPU memory copy overhead. In distributed mode, it involves a all-to-all single-int broadcast.

Author: Tyson Jones

Definition at line 1076 of file test_utilities.cpp.

                                        {
    return areEqual(qureg, vec, REAL_EPS);
}

◆ areEqual() [5/10]

bool areEqual	(	Qureg	qureg,
		QVector	vec,
		qreal	precision )

Performs a hardware-agnostic comparison of state-vector qureg to vec, checking whether the difference between the real and imaginary components of every amplitude is smaller than precision. This function demands qureg is a state-vector, and that qureg and vec have the same number of amplitudes.

In GPU mode, this function involves a GPU to CPU memory copy overhead. In distributed mode, it involves a all-to-all single-int broadcast.

Author: Tyson Jones

Definition at line 1036 of file test_utilities.cpp.

                                                         {
    DEMAND( !qureg.isDensityMatrix );
    DEMAND( (int) vec.size() == qureg.numAmps );
    
    copyStateFromGPU(qureg);
    syncQuESTEnv();
    
    // the starting index in vec of this node's qureg partition.
    long long int startInd = qureg.rank * qureg.numAmpsPerNode;
            
    int ampsAgree = 1;
    for (long long int i=0; i<qureg.numAmpsPerNode; i++) {
        qcomp dif = (qureg.cpuAmps[i] - vec[startInd+i]);
 
        if (absComp(dif) > precision) {
            ampsAgree = 0;
 
            // debug
            char buff[200];
            snprintf(buff, 200, "Disagreement at %lld of (%s) + i(%s):\n\t%s + i(%s) VS %s + i(%s)\n",
                startInd+i,
                QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER, 
                QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER, QREAL_FORMAT_SPECIFIER);
            printf(buff,
                real(dif), imag(dif),
                real(qureg.cpuAmps[i]), imag(qureg.cpuAmps[i]),
                real(vec[startInd+i]), imag(vec[startInd+i]));
            
            break;
        }
    }
            
    // if one node's partition wasn't equal, all-nodes must report not-equal
    int allAmpsAgree = ampsAgree;
#if COMPILE_MPI
    MPI_Allreduce(&ampsAgree, &allAmpsAgree, 1, MPI_INT, MPI_LAND, MPI_COMM_WORLD);
#endif
    
    return allAmpsAgree;
}

◆ areEqual() [6/10]

bool areEqual	(	Qureg	qureg1,
		Qureg	qureg2 )

Performs a hardware-agnostic comparison of the given quregs, checking whether the difference between the real and imaginary components of every amplitude is smaller than the QuEST_PREC-specific REAL_EPS (defined in QuEST_precision) precision. This function demands that qureg1 and qureg2 are of the same type (i.e. both state-vectors or both density matrices), and of an equal number of qubits.

In GPU mode, this function involves a GPU to CPU memory copy overhead. In distributed mode, it involves a all-to-all single-int broadcast.

Author: Tyson Jones

Definition at line 1032 of file test_utilities.cpp.

                                          {
    return areEqual(qureg1, qureg2, REAL_EPS);
}

◆ areEqual() [7/10]

bool areEqual	(	Qureg	qureg1,
		Qureg	qureg2,
		qreal	precision )

Performs a hardware-agnostic comparison of the given quregs, checking whether the difference between the real and imaginary components of every amplitude is smaller than precision. This function demands that qureg1 and qureg2 are of the same type (i.e. both state-vectors or both density matrices), and of an equal number of qubits.

In GPU mode, this function involves a GPU to CPU memory copy overhead. In distributed mode, it involves a all-to-all single-int broadcast.

Author: Tyson Jones

Definition at line 1011 of file test_utilities.cpp.

                                                           {
    DEMAND( qureg1.isDensityMatrix == qureg2.isDensityMatrix );
    DEMAND( qureg1.numAmps == qureg2.numAmps );
        
    copyStateFromGPU(qureg1);
    copyStateFromGPU(qureg2);
    syncQuESTEnv();
    
    // loop terminates when areEqual = 0
    int ampsAgree = 1;
    for (long long int i=0; ampsAgree && i<qureg1.numAmpsPerNode; i++)
        ampsAgree = absComp(qureg1.cpuAmps[i] - qureg2.cpuAmps[i]) < precision;
            
    // if one node's partition wasn't equal, all-nodes must report not-equal
    int allAmpsAgree = ampsAgree;
#if COMPILE_MPI
    MPI_Allreduce(&ampsAgree, &allAmpsAgree, 1, MPI_INT, MPI_LAND, MPI_COMM_WORLD);
#endif
 
    return allAmpsAgree;
}

◆ areEqual() [8/10]

bool areEqual	(	QVector	a,
		QVector	b )

Returns true if the absolute value of the difference between every amplitude in vectors a and b is less than REAL_EPS.

Author: Tyson Jones

Definition at line 515 of file test_utilities.cpp.

                                    {
    DEMAND( a.size() == b.size() );
    
    for (size_t i=0; i<a.size(); i++)
        if (abs(a[i] - b[i]) > REAL_EPS)
            return false;
    return true;
}

◆ areEqual() [9/10]

bool areEqual	(	QVector	vec,
		qreal *	reals )

Returns true if the absolute value of the difference between every element in vec (which must be strictly real) and those implied by reals, is less than REAL_EPS.

Author: Tyson Jones

Definition at line 1157 of file test_utilities.cpp.

                                         {
    for (size_t i=0; i<vec.size(); i++) {
        DEMAND( imag(vec[i]) == 0. );
        
        qreal dif = abs(real(vec[i]) - reals[i]);
        if (dif > REAL_EPS)
            return false;
    }
    return true;
}

◆ areEqual() [10/10]

bool areEqual	(	QVector	vec,
		qreal *	reals,
		qreal *	imags )

Returns true if the absolute value of the difference between every element in vec and those implied by reals and imags, is less than REAL_EPS.

Author: Tyson Jones

Definition at line 1143 of file test_utilities.cpp.

                                                       {
    
    qreal dif;
    for (size_t i=0; i<vec.size(); i++) {
        dif = absReal(real(vec[i]) - reals[i]);
        if (dif > REAL_EPS)
            return false;
        dif = absReal(imag(vec[i]) - imags[i]);
        if (dif > REAL_EPS)
            return false;
    }
    return true;
}

◆ assertQuregAndRefInDebugState() [1/2]

void assertQuregAndRefInDebugState	(	Qureg	qureg,
		QMatrix	ref )

Asserts the given density qureg and reference agree, and are properly initialised in the debug state. Assertion uses the DEMAND() macro, calling Catch2's FAIL() if unsatisfied, so does not contribute toward unit test statistics. This should be called within every PREPARE_TEST macro, to ensure that the test states themselves are initially correct, and do not accidentally agree by (e.g.) being all-zero.

Author: Tyson Jones

Definition at line 233 of file test_utilities.cpp.

                                                             {
    DEMAND( qureg.isDensityMatrix == 1 );
    DEMAND( (1LL << qureg.numQubits) == (long long int) ref.size() );
 
    // assert ref is in the (column-wise) debug state (else initDebugState failed)
    size_t i = 0;
    for (size_t c=0; c<ref.size(); c++) {
        for (size_t r=0; r<ref.size(); r++) {
            qcomp val = qcomp(.2*i, .2*i+.1);
            DEMAND( abs(ref[r][c] - val) < REAL_EPS );
            i++;
        }
    }
 
    // check qureg and ref agree
    DEMAND( areEqual(qureg, ref) );
}

◆ assertQuregAndRefInDebugState() [2/2]

void assertQuregAndRefInDebugState	(	Qureg	qureg,
		QVector	ref )

Asserts the given statevector qureg and reference agree, and are properly initialised in the debug state. Assertion uses the DEMAND() macro, calling Catch2's FAIL() if unsatisfied, so does not contribute toward unit test statistics. This should be called within every PREPARE_TEST macro, to ensure that the test states themselves are initially correct, and do not accidentally agree by (e.g.) being all-zero.

Author: Tyson Jones

Definition at line 219 of file test_utilities.cpp.

                                                             {
    DEMAND( qureg.isDensityMatrix == 0 );
    DEMAND( qureg.numAmps == (long long int) ref.size() );
 
    // assert ref is in the debug state (else initDebugState failed)
    for (size_t i=0; i<ref.size(); i++) {
        qcomp val = qcomp(.2*i, .2*i+.1);
        DEMAND( abs(ref[i] - val) < REAL_EPS );
    }
 
    // check qureg and ref agree
    DEMAND( areEqual(qureg, ref) );
}

◆ bitsets()

CatchGen< int * > bitsets ( int numBits )

Returns a Catch2 generator of every numBits-length bit-set, in increasing lexographic order, where left-most (zero index) bit is treated as LEAST significant (opposite typical convention). Note that the produced bitset must not be modified during generation.

This function can be used like

int* bits = GENERATE( bitsets(3) );

to produce {0,0,0}, {1,0,0}, {0,1,0}, {1,1,0}, {0,0,1}, {1,0,1}, {0,1,1}, {1,1,1}.

Author: Tyson Jones

Definition at line 1723 of file test_utilities.cpp.

                                                           {    
    return Catch::Generators::GeneratorWrapper<int*>(
        Catch::Detail::make_unique<SequenceGenerator<int>>(1, numBits));
}

Referenced by TEST_CASE().

◆ calcLog2()

unsigned int calcLog2 ( long unsigned int res )

Returns log2 of numbers which must be gauranteed to be 2^n

Author: Tyson Jones

Definition at line 488 of file test_utilities.cpp.

                                             {
    unsigned int n = 0;
    while (res >>= 1)
        n++;
    return n;
}

Referenced by applyReferenceMatrix(), applyReferenceOp(), applyReferenceOp(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ deleteFilesWithPrefixSynch()

void deleteFilesWithPrefixSynch ( char * prefix )

Deletes all files with filename starting with prefix. In distributed mode, the master node deletes while the other nodes wait until complete.

Author: Tyson Jones

Definition at line 1543 of file test_utilities.cpp.

                                              {
    
    // master node deletes all files
    if (getQuESTEnv().rank == 0) {
        char cmd[200];
        snprintf(cmd, 200, "exec rm %s*", prefix);
        system(cmd);
    }
    
    // other nodes wait 
    syncQuESTEnv();
}

◆ getConjugateTranspose()

QMatrix getConjugateTranspose ( QMatrix a )

Returns the conjugate transpose of the complex square matrix a

Author: Tyson Jones

Definition at line 291 of file linalg.cpp.

                                         {
    DEMAND( m.size() > 0 );
 
    // unlike most functions which assume qmatrix
    // is square, this one cheekily handles when
    // 'm' is non-square, since necessary for
    // computing partial traces
 
    qmatrix out(m[0].size(), qvector(m.size()));
 
    for (size_t r=0; r<out.size(); r++)
        for (size_t c=0; c<out[0].size(); c++)
            out[r][c] = std::conj(m[c][r]);
 
    return out;
}

Referenced by applyReferenceOp(), getRandomKrausMap(), getRandomUnitary(), TEST_CASE(), and TEST_CASE().

◆ getDFT() [1/2]

QVector getDFT ( QVector in )

Returns the discrete fourier transform of vector in

Author: Tyson Jones

Definition at line 795 of file test_utilities.cpp.

                           {
    REQUIRE( in.size() > 0 );
    
    size_t dim = in.size();
    qreal ampFac = 1 / sqrt( dim );
    qreal phaseFac = 2 * M_PI / dim;
    
    QVector dftVec = QVector(dim);
    
    for (size_t x=0; x<dim; x++) {
        dftVec[x] = 0;
        for (size_t y=0; y<dim; y++)
            dftVec[x] += expI(phaseFac * x * y) * in[y];
        dftVec[x] *= ampFac;
    }
    return dftVec;
}

Referenced by TEST_CASE(), and TEST_CASE().

◆ getDFT() [2/2]

QVector getDFT	(	QVector	in,
		int *	targs,
		int	numTargs )

Returns the discrete fourier transform of a sub-partition of the vector in.

Author: Tyson Jones

Definition at line 843 of file test_utilities.cpp.

                                                     {
    
    QVector out = QVector(in.size());
    long long int inDim = (long long int) in.size();
    long long int targDim = (1LL << numTargs);
    
    for (long long int j=0; j<inDim; j++) {
        
        // |j> = |x> (x) |...>, but mixed (not separated)
        long long int x = getValueOfTargets(j, targs, numTargs);
        
        for (long long int y=0; y<targDim; y++) {
            
            // modifies sum_y |y> (x) ...
            long long int outInd = getIndexOfTargetValues(j, targs, numTargs, y);
            
            qcomp elem = (in[j] / sqrt(pow(2,numTargs))) * expI(2*M_PI * x * y / pow(2,numTargs));
            out[outInd] += elem;
        }
    }
    
    return out;
}

◆ getExponentialOfDiagonalMatrix()

QMatrix getExponentialOfDiagonalMatrix ( QMatrix a )

Returns the matrix exponential of a diagonal, square, complex matrix. This method explicitly checks that the passed matrix a is diagonal.

Author: Tyson Jones

Definition at line 336 of file linalg.cpp.

                                                  {
    DEMAND( isDiagonal(m) );
 
    qmatrix out = getZeroMatrix(m.size());
 
    for (size_t i=0; i<m.size(); i++)
        out[i][i] = std::exp(m[i][i]);
 
    return out;
}

Referenced by TEST_CASE(), and TEST_CASE().

◆ getExponentialOfPauliMatrix()

QMatrix getExponentialOfPauliMatrix	(	qreal	angle,
		QMatrix	a )

Returns the matrix exponential of a kronecker product of pauli matrices (or of any involutory matrices), with exponent factor (-i angle / 2). This method will not explicitly check that the passed matrix a is kronecker product of involutory matrices, but will otherwise return an incorrect exponential.

Author: Tyson Jones

Definition at line 348 of file linalg.cpp.

                                                          {
    
    // exp(-i arg/2 m) where m = prod(paulis)
    qmatrix id = getIdentityMatrix(m.size());
    qmatrix out = std::cos(arg/2)*id - 1_i*std::sin(arg/2)*m;
    return out;
}

Referenced by TEST_CASE(), and TEST_CASE().

◆ getFullOperatorMatrix()

QMatrix getFullOperatorMatrix	(	int *	ctrls,
		int	numCtrls,
		int *	targs,
		int	numTargs,
		QMatrix	op,
		int	numQubits )

Takes a 2^numTargs-by-2^numTargs matrix op and a returns a 2^numQubits-by-2^numQubits matrix where op is controlled on the given ctrls qubits. The union of {ctrls} and {targs} must be unique (though this is not explicitly checked), and every element must be >= 0 (not checked). The passed {ctrls} and {targs} arrays are unmodified.

This funciton works by first swapping {targs} and {ctrls} (via swap unitaries) to be strictly increasing {0,1,...}, building controlled(op), tensoring it to the full Hilbert space, and then 'unswapping'. The returned matrix has form: swap1 ... swapN . controlled(op) . swapN ... swap1

Author: Tyson Jones

Definition at line 420 of file test_utilities.cpp.

  {        
    DEMAND( numCtrls >= 0 );
    DEMAND( numTargs >= 0 );
    DEMAND( numQubits >= (numCtrls+numTargs) );
    DEMAND( op.size() == (1u << numTargs) );
    
    // copy {ctrls} and {targs}to restore at end
    vector<int> ctrlsCopy(ctrls, ctrls+numCtrls);
    vector<int> targsCopy(targs, targs+numTargs);
    
    // full-state matrix of qubit swaps
    QMatrix swaps = getIdentityMatrix(1 << numQubits);
    QMatrix unswaps = getIdentityMatrix(1 << numQubits);
    QMatrix matr;
    
    // swap targs to {0, ..., numTargs-1}
    for (int i=0; i<numTargs; i++) {
        if (i != targs[i]) {
            matr = getSwapMatrix(i, targs[i], numQubits);
            swaps = matr * swaps;
            unswaps = unswaps * matr;
            
            // even if this is the last targ, ctrls might still need updating
            updateIndices(
                i, targs[i], (i < numTargs-1)? &targs[i+1] : NULL, 
                numTargs-i-1, ctrls, numCtrls);
        }
    }
 
    // swap ctrls to {numTargs, ..., numTargs+numCtrls-1}
    for (int i=0; i<numCtrls; i++) {
        int newInd = numTargs+i;
        if (newInd != ctrls[i]) {
            matr = getSwapMatrix(newInd, ctrls[i], numQubits);
            swaps = matr * swaps;
            unswaps = unswaps * matr;
            
            // update remaining ctrls (if any exist)
            if (i < numCtrls-1)
                updateIndices(newInd, ctrls[i], NULL, 0, &ctrls[i+1], numCtrls-i-1);
        }
    }
    
    // construct controlled-op matrix for qubits {0, ..., numCtrls+numTargs-1}
    size_t dim = 1 << (numCtrls+numTargs);
    QMatrix fullOp = getIdentityMatrix(dim);
    setSubMatrix(fullOp, op, dim-op.size(), dim-op.size());
    
    // create full-state controlled-op matrix (left-pad identities)
    if (numQubits > numCtrls+numTargs) {
        size_t pad = 1 << (numQubits - numCtrls - numTargs);
        fullOp = getKroneckerProduct(getIdentityMatrix(pad), fullOp);
    }
    
    // apply swap to either side (to swap qubits back and forth)
    fullOp = unswaps * fullOp * swaps;
    
    // restore {ctrls and targs}
    for (int i=0; i<numCtrls; i++)
        ctrls[i] = ctrlsCopy[i];
    for (int i=0; i<numTargs; i++)
        targs[i] = targsCopy[i];
 
    return fullOp;
}

Referenced by applyReferenceMatrix(), applyReferenceOp(), applyReferenceOp(), TEST_CASE(), and TEST_CASE().

◆ getIdentityMatrix()

QMatrix getIdentityMatrix ( size_t dim )

Returns a dim-by-dim identity matrix

Author: Tyson Jones

Definition at line 30 of file qmatrix.cpp.

                                      {
    DEMAND( dim >= 1 );
 
    qmatrix out = getZeroMatrix(dim);
 
    for (size_t i=0; i<dim; i++)
        out[i][i] = 1;
    
    return out;
}

Referenced by getExponentialOfPauliMatrix(), getExponentialOfPauliMatrix(), getFullOperatorMatrix(), getRandomKrausMap(), getRandomUnitary(), getSwapMatrix(), and TEST_CASE().

◆ getKetBra()

QMatrix getKetBra	(	QVector	ket,
		QVector	bra )

Returns the matrix |ket><bra|, with ith-jth element ket(i) conj(bra(j)), since |ket><bra| = sum_i a_i|i> sum_j b_j* <j| = sum_{ij} a_i b_j* |i><j|. The dimensions of bra and ket must agree, and the returned square complex matrix has dimensions size(bra) x size(bra).

Author: Tyson Jones

Definition at line 277 of file test_utilities.cpp.

                                            {
    DEMAND( ket.size() == bra.size() );
    QMatrix mat = getZeroMatrix(ket.size());
    
    for (size_t r=0; r<ket.size(); r++)
        for (size_t c=0; c<ket.size(); c++)
            mat[r][c] = ket[r] * conj(bra[c]);
    return mat;
}

Referenced by getPureDensityMatrix(), getRandomDensityMatrix(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getKroneckerProduct() [1/2]

QMatrix getKroneckerProduct	(	QMatrix	a,
		QMatrix	b )

Returns the kronecker product of a and b, where a and b are square but possibly differently-sized complex matrices.

Author: Tyson Jones

Definition at line 523 of file linalg.cpp.

                                                  {
 
    // we permit the matrices to be non-square which is
    // pretty cheeky (since qmatrix is assumed square with
    // a 2^N dimension by most other functions), but is
    // necessary for us to compute partial traces
 
    size_t aRows = a.size();
    size_t bRows = b.size();
    size_t aCols = a[0].size();
    size_t bCols = b[0].size();
 
    qmatrix out(aRows * bRows, qvector(aCols * bCols));
    
    for (size_t r=0; r<bRows; r++)
        for (size_t c=0; c<bCols; c++)
            for (size_t i=0; i<aRows; i++)
                for (size_t j=0; j<aCols; j++)
                    out[r+bRows*i][c+bCols*j] = a[i][j] * b[r][c];
 
    return out;
}

Referenced by getSwapMatrix(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getKroneckerProduct() [2/2]

QVector getKroneckerProduct	(	QVector	b,
		QVector	a )

Returns b (otimes) a. If b and a are state-vectors, the resulting kronecker product is the seperable state formed by joining the qubits in the state-vectors, producing |b>|a> (a is least significant)

Author: Tyson Jones

Definition at line 251 of file test_utilities.cpp.

                                                  {
 
    QVector prod = QVector(a.size() * b.size());
    
    for (size_t i=0; i<prod.size(); i++)
        prod[i] = b[i / a.size()] * a[i % a.size()];
    
    return prod;
}

Referenced by getFullOperatorMatrix(), getSwapMatrix(), and toQMatrix().

◆ getMatrixDiagonal()

QVector getMatrixDiagonal ( QMatrix matr )

Returns the diagonal vector of the given matrix

Author: Tyson Jones

Definition at line 633 of file test_utilities.cpp.

                                        {
    
    QVector vec = QVector(matr.size());
    for (size_t i=0; i<vec.size(); i++)
        vec[i] = matr[i][i];
    
    return vec;
}

◆ getMixedDensityMatrix()

QMatrix getMixedDensityMatrix	(	vector< qreal >	probs,
		vector< QVector >	states )

Returns a mixed density matrix formed from mixing the given pure states, which are assumed normalised, but not necessarily orthogonal.

Author: Tyson Jones

Definition at line 783 of file test_utilities.cpp.

                                                                           {
    DEMAND( probs.size() == states.size() );
    DEMAND( probs.size() >= 1 );
    
    QMatrix matr = getZeroMatrix(states[0].size());
    
    for (size_t i=0; i<probs.size(); i++)
        matr += probs[i] * getPureDensityMatrix(states[i]);
        
    return matr;
}

Referenced by TEST_CASE(), and TEST_CASE().

◆ getNormalised()

QVector getNormalised ( QVector vec )

Returns an L2-normalised copy of vec, using Kahan summation for improved accuracy.

Author: Tyson Jones

Definition at line 560 of file test_utilities.cpp.

                                   {
 
    // compute the vec norm via Kahan summation to suppress numerical error
    qreal norm = 0;
    qreal y, t, c;
    c = 0;
    
    for (size_t i=0; i<vec.size(); i++) {
        y = real(vec[i])*real(vec[i]) - c;
        t = norm + y;
        c = ( t - norm ) - y;
        norm = t;
        
        y = imag(vec[i])*imag(vec[i]) - c;
        t = norm + y;
        c = ( t - norm ) - y;
        norm = t;
    }
    
    for (size_t i=0; i<vec.size(); i++)
        vec[i] /= sqrt(norm);
    return vec;
}

Referenced by getRandomOrthonormalVectors(), and getRandomStateVector().

◆ getPureDensityMatrix()

QMatrix getPureDensityMatrix ( QVector state )

Returns a density matrix initialised into the given pure state

Author: Tyson Jones

Definition at line 623 of file test_utilities.cpp.

                                            {
    return getKetBra(state, state);
}

Referenced by getMixedDensityMatrix(), getRandomPureDensityMatrix(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomComplex()

qcomp getRandomComplex ( )

Returns a random complex number within the square closing (-1-i) and (1+i), from a distribution uniformly randomising the individual real and imaginary components in their domains.

Author: Tyson Jones

Definition at line 107 of file random.cpp.

                         {
    qreal re = getRandomReal(-1,1);
    qreal im = getRandomReal(-1,1);
    return qcomp(re, im);
}

Referenced by getRandomQVector(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomDensityMatrix()

QMatrix getRandomDensityMatrix ( int numQb )

Returns a random numQb-by-numQb density matrix, from an undisclosed distribution, in a very mixed state. This function works by generating 2^numQb random pure states, and mixing them with random probabilities.

Author: Tyson Jones

Definition at line 308 of file random.cpp.

                                          {
    DEMAND( numQb > 0 );
    
    // generate random probabilities to weight random pure states
    int dim = getPow2(numQb);
    vector<qreal> probs = getRandomProbabilities(dim);
    
    // add random pure states
    qmatrix dens = getZeroMatrix(dim);
    for (int i=0; i<dim; i++) {
        qvector pure = getRandomStateVector(numQb);
        dens += probs[i] * getOuterProduct(pure, pure);
    }
    
    return dens;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomInt()

int getRandomInt	(	int	min,
		int	max )

Returns a random integer between min (inclusive) and max (exclusive), from the uniform distribution. Demands that max > min.

Author: Tyson Jones

Definition at line 90 of file random.cpp.

                                       {
    DEMAND( maxExcl >= min );
 
    // permit this out of convenience
    // for some test generators
    if (min == maxExcl)
        return min;
 
    qreal r = std::floor(getRandomReal(min, maxExcl));
    int out = static_cast<int>(r);
 
    DEMAND( out >= min );
    DEMAND( out < maxExcl );
    return out;
}

Referenced by setRandomPauliSum(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomKrausMap()

vector< QMatrix > getRandomKrausMap	(	int	numQb,
		int	numOps )

Returns a random Kraus map of #numOps 2^numQb-by-2^numQb operators, from an undisclosed distribution. Note this method is very simple and cannot generate all possible Kraus maps. It works by generating numOps random unitary matrices, and randomly re-normalising them, such that the sum of ops[j]^dagger ops[j] = 1

Author: Tyson Jones

Definition at line 405 of file random.cpp.

                                                         {
    DEMAND( numOps >= 1 );
 
    // generate random unitaries
    vector<qmatrix> ops(numOps);
    for (auto& u : ops)
        u = getRandomUnitary(numQb);
 
    // generate random weights
    vector<qreal> weights(numOps);
    for (auto& w : weights)
        w = getRandomReal(0, 1);
        
    // normalise random weights
    qreal sum = 0;
    for (auto& w : weights)
        sum += w;
    for (auto& w : weights)
        w = std::sqrt(w/sum);
        
    // normalise unitaries according to weights
    for (int i=0; i<numOps; i++)
        ops[i] *= weights[i];
 
    DEMAND( isApproxCPTP(ops) );
    return ops;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomOrthonormalVectors()

vector< QVector > getRandomOrthonormalVectors	(	int	numQb,
		int	numStates )

Returns a list of random orthonormal complex vectors, from an undisclosed distribution.

Author: Tyson Jones

Definition at line 756 of file test_utilities.cpp.

                                                                      {
    DEMAND( numQb >= 1 );
    DEMAND( numStates >= 1);
    
    // set of orthonormal vectors
    vector<QVector> vecs;
    
    for (int n=0; n<numStates; n++) {
        
        QVector vec = getRandomStateVector(numQb);
        
        // orthogonalise by substracting projections of existing vectors
        for (int m=0; m<n; m++) {
            qcomp prod = vec * vecs[m];
            vec -= (prod * vecs[m]);
        }
        
        // renormalise
        vec = getNormalised(vec);
        
        // add to orthonormal set
        vecs.push_back(vec);
    }
 
    return vecs;
}

◆ getRandomProbabilities()

vector< qreal > getRandomProbabilities ( int numProbs )

Returns a list of random real scalars, each in [0, 1], which sum to unity.

Author: Tyson Jones

Definition at line 160 of file random.cpp.

                                                   {
    
    vector<qreal> probs(numProbs, 0);
 
    // generate random unnormalised scalars
    for (auto& p : probs)
        p = getRandomReal(0, 1);
 
    // normalise
    qreal total = 0;
    for (auto& p : probs)
        total += p;
 
    for (auto& p : probs)
        p /= total;
 
    return probs;
}

Referenced by getRandomDensityMatrix(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomPureDensityMatrix()

QMatrix getRandomPureDensityMatrix ( int numQb )

Returns a random numQb-by-numQb density matrix, from an undisclosed distribution, which is pure (corresponds to a random state-vector)

Author: Tyson Jones

Definition at line 326 of file random.cpp.

                                              {
 
    qvector vec = getRandomStateVector(numQb);
    qmatrix mat = getOuterProduct(vec, vec);
    return mat;
}

◆ getRandomQMatrix()

QMatrix getRandomQMatrix ( int dim )

Returns a dim-by-dim complex matrix, where the real and imaginary value of each element are independently random, under the standard normal distribution (mean 0, standard deviation 1).

Author: Tyson Jones

Definition at line 495 of file test_utilities.cpp.

                                  {
    DEMAND( dim > 1 );
    
    QMatrix matr = getZeroMatrix(dim);
    for (int i=0; i<dim; i++) {
        for (int j=0; j<dim; j++) {
            
            // generate 2 normally-distributed random numbers via Box-Muller
            qreal a = rand()/(qreal) RAND_MAX;
            qreal b = rand()/(qreal) RAND_MAX;
            if (a == 0) a = REAL_EPS; // prevent rand()=0 creation of NaN
            qreal r1 = sqrt(-2 * log(a)) * cos(2 * 3.14159265 * b);
            qreal r2 = sqrt(-2 * log(a)) * sin(2 * 3.14159265 * b);
            
            matr[i][j] = r1 + r2 * (qcomp) 1i;
        }
    }
    return matr;
}

Referenced by getRandomUnitary(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomQVector()

QVector getRandomQVector ( int dim )

Returns a dim-length vector with random complex amplitudes in the square joining {-1-i, 1+i}, of an undisclosed distribution. The resulting vector is NOT L2-normalised.

Author: Tyson Jones

Definition at line 552 of file test_utilities.cpp.

                                  { 
    QVector vec = QVector(dim);
    for (int i=0; i<dim; i++)
        vec[i] = getRandomComplex();
    
    return vec;
}

Referenced by getRandomStateVector(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomReal()

qreal getRandomReal	(	qreal	min,
		qreal	max )

Returns a random real between min (inclusive) and max (exclusive), from the uniform distribution. Demands that max > min.

Author: Tyson Jones

Definition at line 63 of file random.cpp.

                                              {
    DEMAND( min < maxExcl );
 
    // advance RNG on every node, identically
    std::uniform_real_distribution<qreal> dist(min,maxExcl);
    qreal out = dist(RNG);
 
    // note despite the doc asserting maxExcl is exclusive, 
    // uniform_real_distribution() can indeed return it! In that
    // case, we substract machine-eps for caller integrity
    if (out >= maxExcl)
        out = std::nextafter(maxExcl, min);
 
    DEMAND( out >= min );
    DEMAND( out < maxExcl );
    return out;
}

◆ getRandomStateVector()

QVector getRandomStateVector ( int numQb )

Returns a random numQb-length L2-normalised state-vector from an undisclosed distribution. This function works by randomly generating each complex amplitude, then L2-normalising.

Author: Tyson Jones

Definition at line 296 of file random.cpp.

                                        {
 
    return getNormalised(getRandomVector(getPow2(numQb)));
}

Referenced by getRandomDensityMatrix(), getRandomOrthonormalVectors(), getRandomPureDensityMatrix(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getRandomUnitary()

QMatrix getRandomUnitary ( int numQb )

Returns a uniformly random (under Haar) 2^numQb-by-2^numQb unitary matrix. This function works by first generating a complex matrix where each element is independently random; the real and imaginary component thereof are independent standard normally-distributed (mean 0, standard-dev 1). Then, the matrix is orthonormalised via the Gram Schmidt algorithm. The resulting unitary matrix MAY be uniformly distributed under the Haar measure, but we make no assurance. This routine may return an identity matrix if it was unable to sufficiently precisely produce a unitary of the given size.

Author: Tyson Jones

Definition at line 348 of file random.cpp.

                                    {
    DEMAND( numQb >= 1 );
 
    // create Z ~ random complex matrix (distribution not too important)
    size_t dim = getPow2(numQb);
    qmatrix matrZ = getRandomMatrix(dim);
    qmatrix matrZT = getTranspose(matrZ);
 
    // create Z = Q R (via QR decomposition) ...
    qmatrix matrQT = getOrthonormalisedRows(matrZ);
    qmatrix matrQ = getTranspose(matrQT);
    qmatrix matrR = getZeroMatrix(dim);
 
    // ... where R_rc = (columm c of Z) . (column r of Q) = (row c of ZT) . (row r of QT) = <r|c>
    for (size_t r=0; r<dim; r++)
        for (size_t c=r; c<dim; c++)
            matrR[r][c] = getInnerProduct(matrQT[r], matrZT[c]);
 
    // create D = normalised diagonal of R
    qmatrix matrD = getZeroMatrix(dim);
    for (size_t i=0; i<dim; i++)
        matrD[i][i] = matrR[i][i] / std::abs(matrR[i][i]);
 
    // create U = Q D
    qmatrix matrU = matrQ * matrD;
 
    DEMAND( isApproxUnitary(matrU) );
    return matrU;
}

Referenced by getRandomKrausMap(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ getSwapMatrix()

QMatrix getSwapMatrix	(	int	qb1,
		int	qb2,
		int	numQb )

Returns the 2^numQb-by-2^numQb unitary matrix which swaps qubits qb1 and qb2; the SWAP gate of not-necessarily-adjacent qubits. If qb1 == qb2, returns the identity matrix.

Author: Tyson Jones

Definition at line 28 of file evolve.cpp.

                                                   {
    DEMAND( numQb > 1 );
    DEMAND( (qb1 >= 0 && qb1 < numQb) );
    DEMAND( (qb2 >= 0 && qb2 < numQb) );
 
    if (qb1 == qb2)
        return getIdentityMatrix(getPow2(numQb));
        
    if (qb1 > qb2)
        std::swap(qb1, qb2);
 
    qmatrix out;
    
    // qubits are either adjacent
    if (qb2 == qb1 + 1) {
        out = qmatrix{{1,0,0,0},{0,0,1,0},{0,1,0,0},{0,0,0,1}};
    
    // or distant
    } else {
        int block = getPow2(qb2 - qb1);
        out = getZeroMatrix(block*2);
        qmatrix iden = getIdentityMatrix(block/2);
        
        // Lemma 3.1 of arxiv.org/pdf/1711.09765.pdf
        qmatrix p0{{1,0},{0,0}};
        qmatrix l0{{0,1},{0,0}};
        qmatrix l1{{0,0},{1,0}};
        qmatrix p1{{0,0},{0,1}};
        
        // notating a^(n+1) = identity(getPow2(n)) (otimes) a, we construct the matrix
        // [ p0^(N) l1^N ]
        // [ l0^(N) p1^N ]
        // where N = qb2 - qb1 */
        setSubMatrix(out, getKroneckerProduct(iden, p0), 0, 0);
        setSubMatrix(out, getKroneckerProduct(iden, l0), block, 0);
        setSubMatrix(out, getKroneckerProduct(iden, l1), 0, block);
        setSubMatrix(out, getKroneckerProduct(iden, p1), block, block);
    }
    
    // pad swap with outer identities
    if (qb1 > 0)
        out = getKroneckerProduct(out, getIdentityMatrix(getPow2(qb1)));
 
    if (qb2 < numQb-1)
        out = getKroneckerProduct(getIdentityMatrix(getPow2(numQb-qb2-1)), out);
        
    return out;
}

Referenced by getFullOperatorMatrix().

◆ getTwosComplement()

long long int getTwosComplement	(	long long int	decimal,
		int	numBits )

Returns the two's complement signed encoding of the unsigned number decimal, which must be a number between 0 and 2^numBits (exclusive). The returned number lies in [-2^(numBits-1), 2^(numBits-1)-1]

Author: Tyson Jones

Definition at line 1454 of file test_utilities.cpp.

                                                                    {
    DEMAND( decimal >= 0 );
    DEMAND( numBits >= 2 );
    DEMAND( decimal < (1LL << numBits) );
    
    long long int maxMag = 1LL << (numBits-1);
    if (decimal >= maxMag)
        return -maxMag + (decimal - maxMag);
    else
        return decimal;
}

◆ getUnsigned()

long long int getUnsigned	(	long long int	twosComp,
		int	numBits )

Return the unsigned value of a number, made of #numBits bits, which under two's complement, encodes the signed number twosComp. The returned number lies in [0, 2^(numBits)-1]

Author: Tyson Jones

Definition at line 1466 of file test_utilities.cpp.

                                                               {
    DEMAND( numBits >= 2 );
    DEMAND( twosComp < (1LL << (numBits-1)) );
    DEMAND( twosComp >= - (1LL << (numBits-1)) );
    
    if (twosComp >= 0)
        return twosComp;
    else
        return (1<<numBits) + twosComp;
}

◆ getValueOfTargets()

long long int getValueOfTargets	(	long long int	ind,
		int *	targs,
		int	numTargs )

Returns the integer value of the targeted sub-register for the given full state index ind.

Author: Tyson Jones

Definition at line 813 of file test_utilities.cpp.

                                                                             {
    DEMAND( ind >= 0 );
    
    long long int val = 0;
    
    for (int t=0; t<numTargs; t++)
        val += ((ind >> targs[t]) & 1) * (1LL << t);
        
    return val;
}

Referenced by getDFT().

◆ getZeroMatrix()

QMatrix getZeroMatrix ( size_t dim )

Returns a dim-by-dim square complex matrix, initialised to all zeroes.

Author: Tyson Jones

Definition at line 18 of file qmatrix.cpp.

                                  {
    DEMAND( dim >= 1 );
 
    return qmatrix(dim, qvector(dim, 0));
}

◆ pauliseqs()

CatchGen< pauliOpType * > pauliseqs ( int numPaulis )

Returns a Catch2 generator of every numPaulis-length set of Pauli-matrix types (or base-4 integers). Generates in increasing lexographic order, where the left-most (zero index) pauli is treated as LEAST significant. Note that the sequence must not be modified during generation.

This function can be used like

pauliOpType* set = GENERATE( pauliseqs(2) );

to produce {I,I}, {X,I}, {Y,I}, {Z,I}, {I,X}, {X,X}, {Y,X}, {Z,X}, {I,Y}, {X,Y}, {Y,Y}, {Z,Y}, {I,Z}, {X,Z}, {Y,Z}, {Z,Z}/

Author: Tyson Jones

Definition at line 1731 of file test_utilities.cpp.

                                                                       {    
    return Catch::Generators::GeneratorWrapper<pauliOpType*>(
        Catch::Detail::make_unique<SequenceGenerator<pauliOpType>>(PAULI_Z, numPaulis));
}

◆ sequences()

CatchGen< int * > sequences	(	int	base,
		int	numDigits )

Returns a Catch2 generator of every numDigits-length sequence in the given base, in increasing lexographic order, where left-most (zero index) bit is treated as LEAST significant (opposite typical convention). Note that the sequence must not be modified during generation.

This function can be used like

int base = 3;
int numDigits = 2;
int* seq = GENERATE_COPY( sequences(base, numDigits) );

to produce {0,0}, {1,0}, {2,0}, {0,1}, {1,1}, {2,1}, {0,2}, {1,2}, {2,2}.

Author: Tyson Jones

Definition at line 1727 of file test_utilities.cpp.

                                                                         {    
    return Catch::Generators::GeneratorWrapper<int*>(
        Catch::Detail::make_unique<SequenceGenerator<int>>(base-1, numDigits));
}

◆ setRandomDiagPauliHamil()

void setRandomDiagPauliHamil	(	PauliHamil	hamil,
		int	numQubits )

Populates hamil with random coefficients and a random amount number of PAULI_I and PAULI_Z operators.

Author: Tyson Jones

Definition at line 1390 of file test_utilities.cpp.

                                                              {
    for (int n=0; n<hamil.numTerms; n++) {
        hamil.coeffs[n] = getRandomReal(-5, 5);
        hamil.strings[n] = getRandomDiagPauliStr(numQubits);
    }
}

◆ setRandomPauliSum() [1/2]

void setRandomPauliSum	(	PauliHamil	hamil,
		int	numQubits )

Populates hamil with random coefficients and pauli codes

Author: Tyson Jones

Definition at line 1382 of file test_utilities.cpp.

                                                        {
 
    for (int n=0; n<hamil.numTerms; n++) {
        hamil.coeffs[n] = getRandomReal(-5, 5);
        hamil.strings[n] = getRandomPauliStr(numQubits);
    }
}

◆ setRandomPauliSum() [2/2]

void setRandomPauliSum	(	qreal *	coeffs,
		pauliOpType *	codes,
		int	numQubits,
		int	numTerms )

Populates the coeffs array with random qreals in (-5, 5), and populates codes with random Pauli codes

Author: Tyson Jones

Definition at line 1373 of file test_utilities.cpp.

                                                                                       {
    int i=0;
    for (int n=0; n<numTerms; n++) {
        coeffs[n] = getRandomReal(-5, 5);
        for (int q=0; q<numQubits; q++)
            codes[i++] = (pauliOpType) getRandomInt(0,4);
    }
}

Referenced by TEST_CASE().

◆ setRandomTargets() [1/2]

void setRandomTargets	(	int *	targs,
		int	numTargs,
		int	numQb )

Populates targs with a random selection of numTargs elements from [0,numQb-1]. List targs does not need to be initialised and its elements are overwritten.

Author: Tyson Jones

Definition at line 1397 of file test_utilities.cpp.

                                                           {
    DEMAND( numQb >= 1 );
    DEMAND( numTargs >= 1);
    DEMAND( numTargs <= numQb );
 
    // create an ordered list of all possible qubits
    vector<int> allQb(numQb);
    for (int q=0; q<numQb; q++)
        allQb[q] = q;
 
    // shuffle all qubits (must be consistent on each node)
    std::shuffle(&allQb[0], &allQb[numQb], randomGenerator);
 
    // select numTargs of all qubits
    for (int i=0; i<numTargs; i++)
        targs[i] = allQb[i];
}

Referenced by setRandomTargets(), TEST_CASE(), and TEST_CASE().

◆ setRandomTargets() [2/2]

void setRandomTargets	(	vector< int > &	targs,
		int	numQb )

Populates targs with a random selection of elements from [0,numQb-1]. List targs does not need to be initialised and its elements are overwritten.

Author: Tyson Jones

Definition at line 1414 of file test_utilities.cpp.

                                                     {
 
    setRandomTargets(targs.data(), targs.size(), numQb);
}

◆ setRandomTestStateSeeds()

void setRandomTestStateSeeds ( )

Seed the C and C++ RNGs using hardware CSPRNG

Author: Tyson Jones

Definition at line 39 of file random.cpp.

                               {
    DEMAND( isQuESTEnvInit() );
 
    // generate a random seed from hardware rng
    std::random_device cspnrg;
    unsigned seed = cspnrg();
    
    // seed QuEST, which uses only the root node's seed
    setSeeds(&seed, 1);
 
    // broadcast root node seed to all nodes
    getSeeds(&seed);
 
    // seed RNG
    RNG.seed(seed);
}

◆ setSubMatrix()

void setSubMatrix	(	QMatrix &	dest,
		QMatrix	sub,
		size_t	r,
		size_t	c )

Modifies dest by overwriting its submatrix (from top-left corner (r, c) to bottom-right corner (r + dest.size(), c + dest.size()) with the complete elements of sub. This demands that dest.size() >= sub.size() + max(r,c).

Author: Tyson Jones

Definition at line 203 of file qmatrix.cpp.

                                                                  {
    DEMAND( sub.size() > 0 );
    DEMAND( sub   .size() + r <= dest.size() );
    DEMAND( sub[0].size() + c <= dest.size() );
 
    // this function cheekily supports when 'sub' is non-square,
    // which is inconsistent with the preconditions of most of
    // the qmatrix functions, but is needed by setDensityQuregAmps()
 
    for (size_t i=0; i<sub.size(); i++)
        for (size_t j=0; j<sub[i].size(); j++)
            dest[r+i][c+j] = sub[i][j];
}

Referenced by getFullOperatorMatrix(), getSwapMatrix(), TEST_CASE(), and TEST_CASE().

◆ setUniqueFilename()

void setUniqueFilename	(	char *	outFn,
		int	maxlen,
		char *	prefix )

Modifies the given diagonal matrix such that the diagonal elements which correspond to the coordinates in overrideInds are replaced with exp(i phase), as prescribed by overridePhases. This function assumes that the given registers are contiguous, are in order of increasing significance, and that the matrix is proportionately sized and structured to act on the space of all registers combined. Overrides can be repeated, and only the first encountered for a given index will be effected (much like applyMultiVarPhaseFuncOverrides()).

Author: Tyson Jones Modifies outFn to be a filename of format prefix_NUM.txt where NUM is a new unique integer so far. This is useful for getting unique filenames for independent test cases of functions requiring reading/writing to file, to avoid IO locks (especially common in distributed mode).; Tyson Jones

Definition at line 1526 of file test_utilities.cpp.

                                                              {
    snprintf(outFn, maxlen, "%s_%d.txt", prefix, fn_unique_suffix_id++);
}

◆ sublists() [1/4]

CatchGen< int * > sublists	(	CatchGen< int > &&	gen,
		int	numSamps,
		const int *	exclude,
		int	numExclude )

Returns a Catch2 generator of every length-sublen sublist of the elements generated by gen, which exclude all elements in exclude, in increasing lexographic order. This generates every fixed-length combination of gen's elements the nominated exclusions, and every permutation of each.

There is on need for the elements of exclude to actually appear in those of gen. sublen must less than or equal to the number of elements in gen, after the nominated exclusions.

Note that the sublist must not be modified, else further generation may break (QuEST's internal functions will indeed modify but restore the qubit index lists given to them, which is ok). Assumes list contains no duplicates, otherwise the generated sublists may be duplicated.

This function can be used like

int sublen = 2;
int exclude[2] = {3,4};
int* sublist = GENERATE_COPY( sublists(range(1,6), sublen, exclude, 2) );

to generate {1,2}, {1,5}, {2,1}, {2,5}, {5,1}, {5,2}

Author: Tyson Jones

◆ sublists() [2/4]

CatchGen< int * > sublists	(	CatchGen< int > &&	gen,
		int	numSamps,
		int	excluded )

Returns a Catch2 generator of every length-sublen sublist of the elements generated by gen which exclude element excluded, in increasing lexographic order. This generates every fixed-length combination of gen's elements the nominated exclusions, and every permutation of each.

sublen must less than or equal to the number of elements in gen, after the nominated exclusion. There is no need for excluded to actually appear in the elements of gen.

Note that the sublist must not be modified, else further generation may break (QuEST's internal functions will indeed modify but restore the qubit index lists given to them, which is ok). Assumes list contains no duplicates, otherwise the generated sublists may be duplicated.

This function can be used like

int sublen = 2;
int excluded = 1;
int* sublist = GENERATE_COPY( sublists(range(1,4), sublen, excluded) );

to generate {2,3}, {3,2}.

Author: Tyson Jones

◆ sublists() [3/4]

CatchGen< int * > sublists	(	CatchGen< int > &&	gen,
		int	sublen )

Returns a Catch2 generator of every length-sublen sublist of the elements generated by gen, in increasing lexographic order. This generates every fixed-length combination of gen's elements, and every permutation of each. Note that the produced sublist must not be modified, else further generation may break (QuEST's internal functions will indeed modify but restore the qubit index lists given to them, which is ok). Assumes list contains no duplicates, otherwise the generated sublists may be duplicated.

This function can be used like

int sublen = 2;
int* sublist = GENERATE_COPY( sublists(list, 4, sublen) );

to generate {1,2}, {1,3}, {1,4}, {2,1}, {2,3}, {2,4}, {3,1}, {3,2}, {3, 4}, {4,1}, {4,2}, {4, 3}.

Author: Tyson Jones

◆ sublists() [4/4]

CatchGen< int * > sublists	(	int *	list,
		int	len,
		int	sublen )

Returns a Catch2 generator of every length-sublen sublist of length-len list, in increasing lexographic order. This generates every fixed-length combination of the given list and every permutation of each. & If the sublist length is the full list length, this generator produces every permutation correctly. Note that the sublist must not be modified, else further & generation may break (QuEST's internal functions will indeed modify but restore the qubit index lists given to them, which is ok). Assumes list contains no duplicates, otherwise the generated sublists may be duplicated.

This function can be used like

int list[4] = {1,2,3,4};
int sublen = 2;
int* sublist = GENERATE_COPY( sublists(list, 4, sublen) );

to generate {1,2}, {1,3}, {1,4}, {2,1}, {2,3}, {2,4}, {3,1}, {3,2}, {3, 4}, {4,1}, {4,2}, {4, 3}.

Author: Tyson Jones

Definition at line 1657 of file test_utilities.cpp.

  {    
    return Catch::Generators::GeneratorWrapper<int*>(
            Catch::Detail::make_unique<SubListGenerator>(list, len, sublen));
}

◆ toComplexMatrix2()

ComplexMatrix2 toComplexMatrix2 ( QMatrix qm )

Returns a ComplexMatrix2 copy of QMatix qm. Demands that qm is a 2-by-2 matrix.

Author: Tyson Jones

Definition at line 1177 of file test_utilities.cpp.

                                            {
    DEMAND( qm.size() == 2 );
    ComplexMatrix2 cm;
    macro_copyQMatrixToDeprecatedComplexMatrix(cm, qm);
    return cm;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ toComplexMatrix4()

ComplexMatrix4 toComplexMatrix4 ( QMatrix qm )

Returns a ComplexMatrix4 copy of QMatix qm. Demands that qm is a 4-by-4 matrix.

Author: Tyson Jones

Definition at line 1183 of file test_utilities.cpp.

                                            {
    DEMAND( qm.size() == 4 );
    ComplexMatrix4 cm;
    macro_copyQMatrixToDeprecatedComplexMatrix(cm, qm);
    return cm;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ toComplexMatrixN()

void toComplexMatrixN	(	QMatrix	qm,
		ComplexMatrixN	cm )

Populates the ComplexMatrixN with the contents of a QMatrix. In GPU-mode, this will then sync the elements ot the matrix's persistent GPU memory

Author: Tyson Jones

Definition at line 1196 of file test_utilities.cpp.

                                                     {
    DEMAND( qm.size() == (1u<<cm.numQubits) );
    macro_copyComplexMatrix(cm.cpuElems, qm, qm.size());
    syncCompMatr(cm);
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ toDiagonalQMatrix()

QMatrix toDiagonalQMatrix ( QVector vec )

Returns a diagonal complex matrix formed by the given vector

Author: Tyson Jones

Definition at line 1477 of file test_utilities.cpp.

                                       {
    QMatrix mat = getZeroMatrix(vec.size());
    for (size_t i=0; i<vec.size(); i++)
        mat[i][i] = vec[i];
    return mat;
}

◆ toQMatrix() [1/9]

QMatrix toQMatrix ( CompMatr src )

Returns a copy of the given matrix

Author: Tyson Jones

Definition at line 1212 of file test_utilities.cpp.

                                {
    QMatrix dest = getZeroMatrix(1 << src.numQubits);
    macro_copyComplexMatrix(dest, src.cpuElems, dest.size());
    return dest;
}

◆ toQMatrix() [2/9]

QMatrix toQMatrix ( CompMatr1 src )

Returns a copy of the given 2-by-2 matrix.

Author: Tyson Jones

Definition at line 1202 of file test_utilities.cpp.

                                 {
    QMatrix dest = getZeroMatrix(2);
    macro_copyComplexMatrix(dest, src.elems, dest.size());
    return dest;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ toQMatrix() [3/9]

QMatrix toQMatrix ( CompMatr2 src )

Returns a copy of the given 4-by-4 matrix.

Author: Tyson Jones

Definition at line 1207 of file test_utilities.cpp.

                                 {
    QMatrix dest = getZeroMatrix(4);
    macro_copyComplexMatrix(dest, src.elems, dest.size());
    return dest;
}

◆ toQMatrix() [4/9]

QMatrix toQMatrix ( DiagMatr matr )

Returns a dense matrix equivalent to the given diagonal

Author: Tyson Jones

Definition at line 1323 of file test_utilities.cpp.

                               {
    QMatrix mat = getZeroMatrix(in.numElems);
    for (size_t i=0; i<mat.size(); i++)
        mat[i][i] = in.cpuElems[i];
    return mat;
}

◆ toQMatrix() [5/9]

QMatrix toQMatrix ( FullStateDiagMatr matr )

Returns a dense matrix equivalent to the given diagonal

Author: Tyson Jones

Definition at line 1315 of file test_utilities.cpp.

                                        {
    QVector vec = toQVector(in);
    QMatrix mat = getZeroMatrix(in.numElems);
    for (size_t i=0; i<mat.size(); i++)
        mat[i][i] = vec[i];
    return mat;
}

◆ toQMatrix() [6/9]

QMatrix toQMatrix ( PauliHamil hamil )

Returns a 2^N-by-2^N Hermitian matrix form of the PauliHamil

Author: Tyson Jones

◆ toQMatrix() [7/9]

QMatrix toQMatrix ( PauliStrSum sum )

Returns a 2^N-by-2^N Hermitian Z-basis matrix of the given complex-weighted sum of Pauli strings, where N is the number of non-Identity operators.

Author: Tyson Jones

◆ toQMatrix() [8/9]

QMatrix toQMatrix	(	qreal *	coeffs,
		pauliOpType *	paulis,
		int	numQubits,
		int	numTerms )

Returns a 2^N-by-2^N Hermitian matrix form of the specified weighted sum of Pauli products

Author: Tyson Jones

Definition at line 1419 of file test_utilities.cpp.

                                                                                   {
    
    // produce a numTargs-big matrix 'pauliSum' by pauli-matrix tensoring and summing
    QMatrix iMatr{{1,0},{0,1}};
    QMatrix xMatr{{0,1},{1,0}};
    QMatrix yMatr{{0,-qcomp(0,1)},{qcomp(0,1),0}};
    QMatrix zMatr{{1,0},{0,-1}};
    QMatrix pauliSum = getZeroMatrix(1<<numQubits);
    
    for (int t=0; t<numTerms; t++) {
        QMatrix pauliProd = QMatrix{{1}};
        
        for (int q=0; q<numQubits; q++) {
            int i = q + t*numQubits;
            
            QMatrix fac;
            pauliOpType code = paulis[i];
            if (code == PAULI_I) fac = iMatr;
            if (code == PAULI_X) fac = xMatr;
            if (code == PAULI_Y) fac = yMatr;
            if (code == PAULI_Z) fac = zMatr;
            pauliProd = getKroneckerProduct(fac, pauliProd);
        }
        pauliSum += coeffs[t] * pauliProd;
    }
    
    // a now 2^numQubits by 2^numQubits Hermitian matrix
    return pauliSum;
}

◆ toQMatrix() [9/9]

QMatrix toQMatrix ( Qureg qureg )

Returns an equal-size copy of the given density matrix qureg. In GPU mode, this function involves a copy of qureg from GPU memory to RAM. In distributed mode, this involves an all-to-all broadcast of qureg.

Author: Tyson Jones

Definition at line 1218 of file test_utilities.cpp.

                               {
    DEMAND( qureg.isDensityMatrix );
#if COMPILE_MPI
    DEMAND( qureg.numAmps < MPI_MAX_AMPS_IN_MSG );
#endif
    
    // ensure local qureg amps are up to date
    copyStateFromGPU(qureg);
    syncQuESTEnv();
 
    // collect all amps between all nodes
    qcomp* allAmps = qureg.cpuAmps;
    
    // in distributed mode, give every node the full state vector
#if COMPILE_MPI
    if (qureg.isDistributed) {
        allAmps = (qcomp*) malloc(qureg.numAmps * sizeof *allAmps);
        MPI_Allgather(
            qureg.cpuAmps, qureg.numAmpsPerNode, MPI_QCOMP,
            allAmps, qureg.numAmpsPerNode, MPI_QCOMP, MPI_COMM_WORLD);
    }
#endif
        
    // copy full state vector into a QVector
    long long int dim = (1LL << qureg.numQubits);
    QMatrix matr = getZeroMatrix(dim);
    for (long long int n=0; n<qureg.numAmps; n++)
        matr[n%dim][n/dim] = allAmps[n];
    
    // clean up if we malloc'd the distributed array
    if (qureg.isDistributed)
        free(allAmps);
    return matr;
}

◆ toQureg() [1/2]

void toQureg	(	Qureg	qureg,
		QMatrix	mat )

Initialises the density matrix qureg to have the same amplitudes as mat. Demands qureg is a density matrix of equal dimensions to mat. In GPU mode, this function involves a copy from RAM to GPU memory. This function has no communication cost in distributed mode.

Author: Tyson Jones

Definition at line 1342 of file test_utilities.cpp.

                                       {
    DEMAND( qureg.isDensityMatrix );
    DEMAND( (1LL << qureg.numQubits) == (long long int) mat.size() );
    
    syncQuESTEnv();
    
    int len = (1 << qureg.numQubits);
    for (int i=0; i<qureg.numAmpsPerNode; i++) {
        int ind = qureg.rank*qureg.numAmpsPerNode + i;
        qureg.cpuAmps[i] = mat[ind%len][ind/len];
    }
    copyStateToGPU(qureg);
}

◆ toQureg() [2/2]

void toQureg	(	Qureg	qureg,
		QVector	vec )

Initialises the state-vector qureg to have the same amplitudes as vec. Demands qureg is a state-vector of an equal size to vec. In GPU mode, this function involves a copy from RAM to GPU memory. This function has no communication cost in distributed mode.

Author: Tyson Jones

Definition at line 1330 of file test_utilities.cpp.

                                       {
    DEMAND( !qureg.isDensityMatrix );
    DEMAND( qureg.numAmps == (long long int) vec.size() );
    
    syncQuESTEnv();
    
    for (int i=0; i<qureg.numAmpsPerNode; i++) {
        int ind = qureg.rank*qureg.numAmpsPerNode + i;
        qureg.cpuAmps[i] = vec[ind];
    }
    copyStateToGPU(qureg);
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ toQVector() [1/3]

QVector toQVector ( DiagMatr op )

Returns a vector with the given diagonal's elements. In distributed mode, this involves an all-to-all broadcast of op.

Author: Tyson Jones

Definition at line 1288 of file test_utilities.cpp.

                                 {
 
    return vector<qcomp>(matr.cpuElems, matr.cpuElems + matr.numElems);
}

◆ toQVector() [2/3]

QVector toQVector ( FullStateDiagMatr op )

Returns a vector with the given diagonal's elements. In distributed mode, this involves an all-to-all broadcast of op.

Author: Tyson Jones

Definition at line 1293 of file test_utilities.cpp.

                                          {
 
#if COMPILE_MPI
    DEMAND( matr.numElems < MPI_MAX_AMPS_IN_MSG );
#endif
 
    vector<qcomp> vec(matr.numElems);
 
    // in distributed mode, give every node the full diagonal operator
    if (matr.isDistributed) {
        #if COMPILE_MPI
            MPI_Allgather(
                matr.cpuElems, matr.numElemsPerNode, MPI_QCOMP,
                vec.data(),    matr.numElemsPerNode, MPI_QCOMP, MPI_COMM_WORLD);
        #endif
    } else {
        vec.assign(matr.cpuElems, matr.cpuElems + matr.numElems);
    }
 
    return vec;
}

◆ toQVector() [3/3]

QVector toQVector ( Qureg qureg )

Returns an equal-size copy of the given state-vector qureg. In GPU mode, this function involves a copy of qureg from GPU memory to RAM. In distributed mode, this involves an all-to-all broadcast of qureg.

Author: Tyson Jones

Definition at line 1253 of file test_utilities.cpp.

                               {
    DEMAND( !qureg.isDensityMatrix );
#if COMPILE_MPI
    DEMAND( qureg.numAmps < MPI_MAX_AMPS_IN_MSG );
#endif
    
    // ensure local qureg amps are up to date
    copyStateFromGPU(qureg);
    syncQuESTEnv();
    
    qcomp* allAmps = qureg.cpuAmps;
    
    // in distributed mode, give every node the full state vector
#if COMPILE_MPI
    if (qureg.isDistributed) {
        allAmps = (qcomp*) malloc(qureg.numAmps * sizeof *allAmps);
 
        MPI_Allgather(
            qureg.cpuAmps, qureg.numAmpsPerNode, MPI_QCOMP,
            allAmps, qureg.numAmpsPerNode, MPI_QCOMP, MPI_COMM_WORLD);
    }
#endif
    
    // copy full state vector into a QVector
    QVector vec = QVector(qureg.numAmps);
    for (long long int i=0; i<qureg.numAmps; i++)
        vec[i] = allAmps[i];
            
    // clean up if we malloc'd distrib array
    if (qureg.isDistributed)
        free(allAmps);
 
    return vec;
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and toQMatrix().

◆ writeToFileSynch()

void writeToFileSynch	(	char *	fn,
		const string &	contents )

Writes contents to the file with filename fn, which is created and/or overwritten. In distributed mode, the master node writes while the other nodes wait until complete.

Author: Tyson Jones

Definition at line 1530 of file test_utilities.cpp.

                                                        {
    
    // master node writes
    if (getQuESTEnv().rank == 0) {
        FILE* file = fopen(fn, "w");
        fputs(contents.c_str(), file);
        fclose(file);
    }
    
    // other nodes wait
    syncQuESTEnv();
}

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ QMatrix

◆ QVector

Function Documentation

◆ applyReferenceMatrix() [1/4]

◆ applyReferenceMatrix() [2/4]

◆ applyReferenceMatrix() [3/4]

◆ applyReferenceMatrix() [4/4]

◆ applyReferenceOp() [1/16]

◆ applyReferenceOp() [2/16]

◆ applyReferenceOp() [3/16]

◆ applyReferenceOp() [4/16]

◆ applyReferenceOp() [5/16]

◆ applyReferenceOp() [6/16]

◆ applyReferenceOp() [7/16]

◆ applyReferenceOp() [8/16]

◆ applyReferenceOp() [9/16]

◆ applyReferenceOp() [10/16]

◆ applyReferenceOp() [11/16]

◆ applyReferenceOp() [12/16]

◆ applyReferenceOp() [13/16]

◆ applyReferenceOp() [14/16]

◆ applyReferenceOp() [15/16]

◆ applyReferenceOp() [16/16]

◆ areEqual() [1/10]

◆ areEqual() [2/10]

◆ areEqual() [3/10]

◆ areEqual() [4/10]

◆ areEqual() [5/10]

◆ areEqual() [6/10]

◆ areEqual() [7/10]

◆ areEqual() [8/10]

◆ areEqual() [9/10]

◆ areEqual() [10/10]

◆ assertQuregAndRefInDebugState() [1/2]

◆ assertQuregAndRefInDebugState() [2/2]

◆ bitsets()

◆ calcLog2()

◆ deleteFilesWithPrefixSynch()

◆ getConjugateTranspose()

◆ getDFT() [1/2]

◆ getDFT() [2/2]

◆ getExponentialOfDiagonalMatrix()

◆ getExponentialOfPauliMatrix()

◆ getFullOperatorMatrix()

◆ getIdentityMatrix()

◆ getKetBra()

◆ getKroneckerProduct() [1/2]

◆ getKroneckerProduct() [2/2]

◆ getMatrixDiagonal()

◆ getMixedDensityMatrix()

◆ getNormalised()

◆ getPureDensityMatrix()

◆ getRandomComplex()

◆ getRandomDensityMatrix()

◆ getRandomInt()

◆ getRandomKrausMap()

◆ getRandomOrthonormalVectors()

◆ getRandomProbabilities()

◆ getRandomPureDensityMatrix()

◆ getRandomQMatrix()

◆ getRandomQVector()

◆ getRandomReal()

◆ getRandomStateVector()

◆ getRandomUnitary()

◆ getSwapMatrix()

◆ getTwosComplement()

◆ getUnsigned()

◆ getValueOfTargets()

◆ getZeroMatrix()

◆ pauliseqs()

◆ sequences()

◆ setRandomDiagPauliHamil()

◆ setRandomPauliSum() [1/2]

◆ setRandomPauliSum() [2/2]

◆ setRandomTargets() [1/2]

◆ setRandomTargets() [2/2]