utilities.hpp File Reference
#include "QuEST.h"
#include "QuEST_complex.h"
#include "catch.hpp"
#include <vector>

Go to the source code of this file.

Macros

#define NUM_QUBITS   5
 The default number of qubits in the registers created for unit testing (both statevectors and density matrices). More...
 

Typedefs

template<class T >
using CatchGen = Catch::Generators::GeneratorWrapper< T >
 
typedef std::vector< std::vector< qcomp > > QMatrix
 A complex square matrix. More...
 
typedef std::vector< qcompQVector
 A complex vector, which can be zero-initialised with QVector(numAmps). More...
 

Functions

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). More...
 
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). More...
 
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). More...
 
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). More...
 
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). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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). More...
 
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). More...
 
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). More...
 
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. More...
 
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. More...
 
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). More...
 
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). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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). More...
 
unsigned int calcLog2 (long unsigned int res)
 Returns log2 of numbers which must be gauranteed to be 2^n. More...
 
qcomp expI (qreal phase)
 Returns the unit-norm complex number exp(i*phase). More...
 
QMatrix getConjugateTranspose (QMatrix a)
 Returns the conjugate transpose of the complex square matrix a. More...
 
QMatrix getExponentialOfDiagonalMatrix (QMatrix a)
 Returns the matrix exponential of a diagonal, square, complex matrix. More...
 
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). More...
 
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. More...
 
QMatrix getIdentityMatrix (size_t dim)
 Returns a dim-by-dim identity matrix. More...
 
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|. More...
 
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. More...
 
QVector getNormalised (QVector vec)
 Returns an L2-normalised copy of vec, using Kahan summation for improved accuracy. More...
 
QMatrix getRandomDensityMatrix (int numQb)
 Returns a random numQb-by-numQb density matrix, from an undisclosed distribution, in a very mixed state. More...
 
int getRandomInt (int min, int max)
 Returns a random integer between min (inclusive) and max (exclusive), from the uniform distribution. More...
 
std::vector< QMatrixgetRandomKrausMap (int numQb, int numOps)
 Returns a random Kraus map of #numOps 2^numQb-by-2^numQb operators, from an undisclosed distribution. More...
 
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). More...
 
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. More...
 
qreal getRandomReal (qreal min, qreal max)
 Returns a random real between min (inclusive) and max (exclusive), from the uniform distribution. More...
 
QVector getRandomStateVector (int numQb)
 Returns a random numQb-length L2-normalised state-vector from an undisclosed distribution. More...
 
QMatrix getRandomUnitary (int numQb)
 Returns a uniformly random (under Haar) 2^numQb-by-2^numQb unitary matrix. More...
 
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. More...
 
QMatrix getZeroMatrix (size_t dim)
 Returns a dim-by-dim square complex matrix, initialised to all zeroes. More...
 
QMatrix operator* (const qcomp &a, const QMatrix &m)
 
QVector operator* (const qcomp &a, const QVector &v)
 
QMatrix operator* (const QMatrix &m, const qcomp &a)
 
QVector operator* (const QMatrix &m, const QVector &v)
 
QMatrix operator* (const QMatrix &m1, const QMatrix &m2)
 
QVector operator* (const QVector &v, const qcomp &a)
 
qcomp operator* (const QVector &v1, const QVector &v2)
 
void operator*= (QMatrix &m1, const QMatrix &m2)
 
void operator*= (QMatrix &m1, const qreal &a)
 
void operator*= (QVector &v1, const qcomp &a)
 
QMatrix operator+ (const QMatrix &m1, const QMatrix &m2)
 
QVector operator+ (const QVector &v1, const QVector &v2)
 
void operator+= (QMatrix &m1, const QMatrix &m2)
 
void operator+= (QVector &v1, const QVector &v2)
 
QMatrix operator- (const QMatrix &m1, const QMatrix &m2)
 
QVector operator- (const QVector &v1, const QVector &v2)
 
void operator-= (QMatrix &m1, const QMatrix &m2)
 
void operator-= (QVector &v1, const QVector &v2)
 
QMatrix operator/ (const QMatrix &m, const qcomp &a)
 
QVector operator/ (const QVector &v, const qcomp &a)
 
void operator/= (QMatrix &m1, const qreal &a)
 
void operator/= (QVector &v1, const qcomp &a)
 
CatchGen< pauliOpType * > pauliseqs (int numPaulis)
 Returns a Catch2 generator of every numPaulis-length set of Pauli-matrix types (or base-4 integers). More...
 
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). More...
 
void setRandomPauliSum (PauliHamil hamil)
 Populates hamil with random coefficients and pauli codes. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
ComplexMatrix2 toComplexMatrix2 (QMatrix qm)
 Returns a ComplexMatrix2 copy of QMatix qm. More...
 
ComplexMatrix4 toComplexMatrix4 (QMatrix qm)
 Returns a ComplexMatrix4 copy of QMatix qm. More...
 
void toComplexMatrixN (QMatrix qm, ComplexMatrixN cm)
 Initialises cm with the values of qm. More...
 
QMatrix toQMatrix (Complex alpha, Complex beta)
 Returns the matrix (where a=alpha, b=beta) {{a, -conj(b)}, {b, conj(a)}} using the qcomp complex type. More...
 
QMatrix toQMatrix (ComplexMatrix2 src)
 Returns a copy of the given 2-by-2 matrix. More...
 
QMatrix toQMatrix (ComplexMatrix4 src)
 Returns a copy of the given 4-by-4 matrix. More...
 
QMatrix toQMatrix (ComplexMatrixN src)
 Returns a copy of the given 2^N-by-2^N matrix. More...
 
QMatrix toQMatrix (DiagonalOp op)
 Returns a 2^N-by-2^N complex diagonal matrix form of the DiagonalOp. More...
 
QMatrix toQMatrix (PauliHamil hamil)
 Returns a 2^N-by-2^N Hermitian matrix form of the PauliHamil. More...
 
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. More...
 
QMatrix toQMatrix (Qureg qureg)
 Returns an equal-size copy of the given density matrix qureg. More...
 
void toQureg (Qureg qureg, QMatrix mat)
 Initialises the density matrix qureg to have the same amplitudes as mat. More...
 
void toQureg (Qureg qureg, QVector vec)
 Initialises the state-vector qureg to have the same amplitudes as vec. More...
 
QVector toQVector (DiagonalOp op)
 Returns a vector with the same of the full diagonal operator, populated with op's elements. More...
 
QVector toQVector (Qureg qureg)
 Returns an equal-size copy of the given state-vector qureg. More...
 

Variables

QuESTEnv QUEST_ENV
 The single QuESTEnv environment created before the Catch tests begin, and destroyed thereafter. More...
 

Detailed Description

Unoptimised, analytic implementations of matrix operations used by QuEST's unit tests

Definition in file utilities.hpp.

Macro Definition Documentation

◆ NUM_QUBITS

#define NUM_QUBITS   5

The default number of qubits in the registers created for unit testing (both statevectors and density matrices).

Creation of non-NUM_QUBITS sized Quregs should be justified in a comment. Note that the smaller this number is, the fewer nodes can be employed in distribution testing, since each node must contain at least one amplitude. Furthermore, the larger this number is, the greater the deviation of correct results from their expected value, due to numerical error; this is especially apparent for density matrices.

Definition at line 36 of file utilities.hpp.

Typedef Documentation

◆ CatchGen

template<class T >
using CatchGen = Catch::Generators::GeneratorWrapper<T>

Definition at line 864 of file utilities.hpp.

Function Documentation

◆ expI()

qcomp expI ( qreal  phase)

Returns the unit-norm complex number exp(i*phase).

This function uses the Euler formula, and avoids problems with calling exp(complex) in a platform agnostic way

Definition at line 406 of file utilities.cpp.

406  {
407  return cos(phase) + 1i*sin(phase);
408 }

Referenced by TEST_CASE().

◆ operator*() [1/7]

QMatrix operator* ( const qcomp a,
const QMatrix m 
)

Definition at line 92 of file utilities.cpp.

92  {
93  QMatrix out = m;
94  for (size_t r=0; r<m.size(); r++)
95  for (size_t c=0; c<m.size(); c++)
96  out[r][c] *= a;
97  return out;
98 }

◆ operator*() [2/7]

QVector operator* ( const qcomp a,
const QVector v 
)

Definition at line 40 of file utilities.cpp.

40  {
41  QVector out = v;
42  for (size_t i=0; i<v.size(); i++)
43  out[i] *= a;
44  return out;
45 }

◆ operator*() [3/7]

QMatrix operator* ( const QMatrix m,
const qcomp a 
)

Definition at line 99 of file utilities.cpp.

99  {
100  return a * m;
101 }

◆ operator*() [4/7]

QVector operator* ( const QMatrix m,
const QVector v 
)

Definition at line 134 of file utilities.cpp.

134  {
135  DEMAND( m.size() == v.size() );
136  QVector prod = QVector(v.size());
137  for (size_t r=0; r<v.size(); r++)
138  for (size_t c=0; c<v.size(); c++)
139  prod[r] += m[r][c] * v[c];
140  return prod;
141 }

References DEMAND.

◆ operator*() [5/7]

QMatrix operator* ( const QMatrix m1,
const QMatrix m2 
)

Definition at line 109 of file utilities.cpp.

109  {
110  QMatrix prod = m1; // will be completely overwritten
111  for (size_t r=0; r<m1.size(); r++)
112  for (size_t c=0; c<m1.size(); c++) {
113  prod[r][c] = 0;
114  for (size_t k=0; k<m1.size(); k++)
115  prod[r][c] += m1[r][k] * m2[k][c];
116  }
117  return prod;
118 }

◆ operator*() [6/7]

QVector operator* ( const QVector v,
const qcomp a 
)

Definition at line 46 of file utilities.cpp.

46  {
47  return a * v;
48 }

◆ operator*() [7/7]

qcomp operator* ( const QVector v1,
const QVector v2 
)

Definition at line 56 of file utilities.cpp.

56  {
57  // this is sum_i v1_i conj(v2_i)
58  DEMAND( v1.size() == v2.size() );
59  qcomp out = 0;
60  for (size_t i=0; i<v1.size(); i++)
61  out += v1[i] * conj(v2[i]);
62  return out;
63 }

References DEMAND, and qcomp.

◆ operator*=() [1/3]

void operator*= ( QMatrix m1,
const QMatrix m2 
)

Definition at line 131 of file utilities.cpp.

131  {
132  m1 = m1 * m2;
133 }

◆ operator*=() [2/3]

void operator*= ( QMatrix m1,
const qreal a 
)

Definition at line 125 of file utilities.cpp.

125  {
126  m1 = m1 * a;
127 }

◆ operator*=() [3/3]

void operator*= ( QVector v1,
const qcomp a 
)

Definition at line 70 of file utilities.cpp.

70  {
71  v1 = v1 * a;
72 }

◆ operator+() [1/2]

QMatrix operator+ ( const QMatrix m1,
const QMatrix m2 
)

Definition at line 76 of file utilities.cpp.

76  {
77  DEMAND( m1.size() == m2.size() );
78  QMatrix out = m1;
79  for (size_t r=0; r<m1.size(); r++)
80  for (size_t c=0; c<m1.size(); c++)
81  out[r][c] += m2[r][c];
82  return out;
83 }

References DEMAND.

◆ operator+() [2/2]

QVector operator+ ( const QVector v1,
const QVector v2 
)

Definition at line 26 of file utilities.cpp.

26  {
27  DEMAND( v1.size() == v2.size() );
28  QVector out = v1;
29  for (size_t i=0; i<v2.size(); i++)
30  out[i] += v2[i];
31  return out;
32 }

References DEMAND.

◆ operator+=() [1/2]

void operator+= ( QMatrix m1,
const QMatrix m2 
)

Definition at line 119 of file utilities.cpp.

119  {
120  m1 = m1 + m2;
121 }

◆ operator+=() [2/2]

void operator+= ( QVector v1,
const QVector v2 
)

Definition at line 64 of file utilities.cpp.

64  { // these violate += returns (fine)
65  v1 = v1 + v2;
66 }

◆ operator-() [1/2]

QMatrix operator- ( const QMatrix m1,
const QMatrix m2 
)

Definition at line 84 of file utilities.cpp.

84  {
85  DEMAND( m1.size() == m2.size() );
86  QMatrix out = m1;
87  for (size_t r=0; r<m1.size(); r++)
88  for (size_t c=0; c<m1.size(); c++)
89  out[r][c] -= m2[r][c];
90  return out;
91 }

References DEMAND.

◆ operator-() [2/2]

QVector operator- ( const QVector v1,
const QVector v2 
)

Definition at line 33 of file utilities.cpp.

33  {
34  DEMAND( v1.size() == v2.size() );
35  QVector out = v1;
36  for (size_t i=0; i<v2.size(); i++)
37  out[i] -= v2[i];
38  return out;
39 }

References DEMAND.

◆ operator-=() [1/2]

void operator-= ( QMatrix m1,
const QMatrix m2 
)

Definition at line 122 of file utilities.cpp.

122  {
123  m1 = m1 - m2;
124 }

◆ operator-=() [2/2]

void operator-= ( QVector v1,
const QVector v2 
)

Definition at line 67 of file utilities.cpp.

67  {
68  v1 = v1 - v2;
69 }

◆ operator/() [1/2]

QMatrix operator/ ( const QMatrix m,
const qcomp a 
)

Definition at line 102 of file utilities.cpp.

102  {
103  QMatrix out = m;
104  for (size_t r=0; r<m.size(); r++)
105  for (size_t c=0; c<m.size(); c++)
106  out[r][c] /= a;
107  return out;
108 }

◆ operator/() [2/2]

QVector operator/ ( const QVector v,
const qcomp a 
)

Definition at line 49 of file utilities.cpp.

49  {
50  DEMAND( abs(a) != 0 );
51  QVector out = v;
52  for (size_t i=0; i<v.size(); i++)
53  out[i] /= a;
54  return out;
55 }

References DEMAND.

◆ operator/=() [1/2]

void operator/= ( QMatrix m1,
const qreal a 
)

Definition at line 128 of file utilities.cpp.

128  {
129  m1 = m1 / a;
130 }

◆ operator/=() [2/2]

void operator/= ( QVector v1,
const qcomp a 
)

Definition at line 73 of file utilities.cpp.

73  {
74  v1 = v1 / a;
75 }

Variable Documentation

◆ QUEST_ENV

QuESTEnv QUEST_ENV

The single QuESTEnv environment created before the Catch tests begin, and destroyed thereafter.

The single QuESTEnv environment created before the Catch tests begin, and destroyed thereafter.

Definition at line 20 of file main.cpp.

Referenced by areEqual(), main(), TEST_CASE(), toQMatrix(), toQureg(), and toQVector().

std::vector< qcomp > QVector
A complex vector, which can be zero-initialised with QVector(numAmps).
Definition: utilities.hpp:60
#define qcomp
std::vector< std::vector< qcomp > > QMatrix
A complex square matrix.
Definition: utilities.hpp:49
#define DEMAND(cond)
Definition: utilities.cpp:24