Precision-agnostic types and data structures for representing numbers, quantum states, and operators. More...

Data Structures
struct	Complex
	Represents one complex number. More...

struct	ComplexMatrix2
	Represents a 2x2 matrix of complex numbers. More...

struct	ComplexMatrix4
	Represents a 4x4 matrix of complex numbers. More...

struct	ComplexMatrixN
	Represents a general 2^N by 2^N matrix of complex numbers. More...

struct	QuESTEnv
	Information about the environment the program is running in. More...

struct	Qureg
	Represents a system of qubits. More...

struct	Vector
	Represents a 3-vector of real numbers. More...

Macros
#define	fromComplex(comp) qcomp(comp.real, comp.imag)

#define	getStaticComplexMatrixN(numQubits, re, im)
	Creates a ComplexMatrixN struct which lives in the stack and so does not need freeing, but cannot be returned beyond the calling scope. More...

#define	qcomp

#define	qreal double

#define	QuEST_PREC 2

#define	toComplex(scalar) ((Complex) {.real = creal(scalar), .imag = cimag(scalar)})

Enumerations
enum	pauliOpType { PAULI_I =0, PAULI_X =1, PAULI_Y =2, PAULI_Z =3 }
	Codes for specifying Pauli operators. More...

Functions
Qureg	createCloneQureg (Qureg qureg, QuESTEnv env)
	Create a new Qureg which is an exact clone of the passed qureg, which can be either a statevector or a density matrix. More...

ComplexMatrixN	createComplexMatrixN (int numQubits)
	Create (dynamically) a square complex matrix which can be passed to the multi-qubit general unitary functions. More...

Qureg	createDensityQureg (int numQubits, QuESTEnv env)
	Create a Qureg for qubits which are represented by a density matrix, and can be in mixed states. More...

QuESTEnv	createQuESTEnv (void)
	Create the QuEST execution environment. More...

Qureg	createQureg (int numQubits, QuESTEnv env)
	Create a Qureg object representing a set of qubits which will remain in a pure state. More...

void	destroyComplexMatrixN (ComplexMatrixN matr)
	Destroy a ComplexMatrixN instance created with createComplexMatrixN() More...

void	destroyQuESTEnv (QuESTEnv env)
	Destroy the QuEST environment. More...

void	destroyQureg (Qureg qureg, QuESTEnv env)
	Deallocate a Qureg object representing a set of qubits. More...

void	initComplexMatrixN (ComplexMatrixN m, qreal real[][1<< m.numQubits], qreal imag[][1<< m.numQubits])
	Initialises a ComplexMatrixN instance to have the passed `real` and `imag` values. More...

Detailed Description

Precision-agnostic types and data structures for representing numbers, quantum states, and operators.

Macro Definition Documentation

◆ fromComplex

#define fromComplex ( comp ) qcomp(comp.real, comp.imag)

Converts a Complex struct to a qcomp native type

Author: Tyson Jones

◆ getStaticComplexMatrixN

#define getStaticComplexMatrixN	(	numQubits,
		re,
		im
	)

Value:

    bindArraysToStackComplexMatrixN( \
        numQubits, \
        (qreal[1<<numQubits][1<<numQubits]) UNPACK_ARR re, \
        (qreal[1<<numQubits][1<<numQubits]) UNPACK_ARR im, \
        (double*[1<<numQubits]) {NULL}, (double*[1<<numQubits]) {NULL} \
    )

Creates a ComplexMatrixN struct which lives in the stack and so does not need freeing, but cannot be returned beyond the calling scope.

That is, the .real and .imag arrays of the returned ComplexMatrixN live in the stack as opposed to that returned by createComplexMatrixN() (which live in the heap). Note the real and imag components must be wrapped in paranthesis, e.g.

ComplexMatrixN u = getStaticComplexMatrixN(1, ({{1,2},{3,4}}), ({{0}}));

Here is an example of an incorrect usage, since a 'local' ComplexMatrixN cannot leave the calling scope (otherwise inducing dangling pointers):

ComplexMatrixN getMyMatrix(void) {
    return getStaticComplexMatrixN(1, ({{1,2},{3,4}}), ({{0}}));
}

This function is actually a single-line anonymous macro, so can be safely invoked within arguments to other functions, e.g.

 multiQubitUnitary(
     qureg, (int[]) {0}, 1, 
     getStaticComplexMatrixN(1, ({{1,0},{0,1}}), ({{0}}))
 );

The returned ComplexMatrixN can be accessed and modified in the same way as that returned by createComplexMatrixN(), e.g.

 ComplexMatrixN u = getStaticComplexMatrixN(3, ({{0}}), ({{0}}));
 for (int i=0; i<8; i++)
     for (int j=0; j<8; j++)
         u.real[i][j] = .1;

Note that the first argument numQubits must be a literal.

This macro is only callable in C, since it invokes the function bindArraysToStackComplexMatrixN() which is only callable in C.

Author: Tyson Jones

Definition at line 3284 of file QuEST.h.

◆ qcomp

#define qcomp

A precision-agnostic operator-overloaded complex number type.
This is a complex analog of qreal and is of single, double or quad precision depending on the value of QuEST_PREC. It resolves to the native complex type provided by <complex.h> for both C99 and C++11, so can be used with operators. It can be constructed with qcomp(real, imag).

For example, in C,

qcomp x = 2 + 3i;

x -= 3.2*x;

and in C++,

qcomp x = qcomp(2, 3);

x -= 3*x;

Assuming QuEST_PREC=4, qcomp will be 'complex long double' in C and 'complex<long double>' in C++.

Can be converted to/from Complex, the struct accepted by the QuEST interface, using toComplex and fromComplex.

Authors: Randy Meyers and Dr. Thomas Plum (created C & C++ agnosticism)

Author: Tyson Jones (created precision agnosticism)

◆ qreal

#define qreal double

A precision-agnostic floating point number, as determined by QuEST_PREC. Is a single, double or quad precision float when QuEST_PREC is 1, 2 or 4 respectively.

Author: Ania Brown; Tyson Jones (doc)

◆ QuEST_PREC

#define QuEST_PREC 2

Sets the precision of qreal and qcomp, and generally that of the state-vectors stored by QuEST. QuEST_PREC can be 1, 2 or 4 for single, double and quad precision - requires 4, 8 and 16 bytes per real & imag component per amplitude of the statevector respectively. This should be passed as a macro to the preprocessor during compilation, which overwrites the value explicitly defined in QuEST_precision.h. Note that quad precision is not compatible with most GPUs.

Author: Ania Brown; Tyson Jones (doc)

◆ toComplex

#define toComplex ( scalar ) ((Complex) {.real = creal(scalar), .imag = cimag(scalar)})

Creates a Complex struct, which can be passed to the QuEST API, from a qcomp

Author: Tyson Jones

Enumeration Type Documentation

◆ pauliOpType

enum pauliOpType

Codes for specifying Pauli operators.

Author: Tyson Jones

Enumerator
PAULI_I
PAULI_X
PAULI_Y
PAULI_Z

Definition at line 96 of file QuEST.h.

96 {PAULI_I=0, PAULI_X=1, PAULI_Y=2, PAULI_Z=3};

Function Documentation

◆ createCloneQureg()

Qureg createCloneQureg	(	Qureg	qureg,
		QuESTEnv	env
	)

Create a new Qureg which is an exact clone of the passed qureg, which can be either a statevector or a density matrix.

That is, it will have the same dimensions as the passed qureg and begin in an identical quantum state. This must be destroyed by the user later with destroyQureg()

Returns: an object representing the set of qubits

Parameters

[in]	qureg	an existing qureg to be cloned
[in]	env	object representing the execution environment (local, multinode etc)

Author: Tyson Jones

Definition at line 62 of file QuEST.c.

                                                   {
  
     Qureg newQureg;
     statevec_createQureg(&newQureg, qureg.numQubitsInStateVec, env);
     newQureg.isDensityMatrix = qureg.isDensityMatrix;
     newQureg.numQubitsRepresented = qureg.numQubitsRepresented;
     newQureg.numQubitsInStateVec = qureg.numQubitsInStateVec;
     
     qasm_setup(&newQureg);
     statevec_cloneQureg(newQureg, qureg);
     return newQureg;
 }

References Qureg::isDensityMatrix, Qureg::numQubitsInStateVec, Qureg::numQubitsRepresented, qasm_setup(), statevec_cloneQureg(), and statevec_createQureg().

Referenced by TEST_CASE().

◆ createComplexMatrixN()

ComplexMatrixN createComplexMatrixN ( int numQubits )

Create (dynamically) a square complex matrix which can be passed to the multi-qubit general unitary functions.

The matrix will have dimensions (2^numQubits) by (2^numQubits), and all elements of .real and .imag are initialised to zero. The ComplexMatrixN must eventually be freed using destroyComplexMatrixN(). Like ComplexMatrix2 and ComplexMatrix4, the returned ComplexMatrixN is safe to return from functions.

One can instead use getStaticComplexMatrixN() to create a ComplexMatrixN struct in the stack (which doesn't need to be later destroyed).

Parameters

[in] numQubits the number of qubits of which the returned ComplexMatrixN will correspond

Returns: a dynamic ComplexMatrixN struct, that is one where the .real and .imag fields are arrays kept in the heap and must be later destroyed.

Author: Tyson Jones

Definition at line 1000 of file QuEST.c.

                                                     {
      validateNumQubitsInMatrix(numQubits, __func__);
  
      int numRows = 1 << numQubits;
  
      ComplexMatrixN m = {
          .numQubits = numQubits,
          .real = malloc(numRows * sizeof *m.real),
          .imag = malloc(numRows * sizeof *m.imag)};
  
      for (int n=0; n < 1<<numQubits; n++) {
          m.real[n] = calloc(numRows, sizeof **m.real);
          m.imag[n] = calloc(numRows, sizeof **m.imag);
      }
      
      // error if the ComplexMatrixN was not successfully malloc'ds
      validateMatrixInit(m, __func__);
      
      return m;
  }

References ComplexMatrixN::imag, ComplexMatrixN::numQubits, ComplexMatrixN::real, validateMatrixInit(), and validateNumQubitsInMatrix().

Referenced by densmatr_mixMultiQubitKrausMap(), and TEST_CASE().

◆ createDensityQureg()

Qureg createDensityQureg	(	int	numQubits,
		QuESTEnv	env
	)

Create a Qureg for qubits which are represented by a density matrix, and can be in mixed states.

Allocates space for a density matrix of probability amplitudes, including space for temporary values to be copied from one other chunk if running the distributed version. Define properties related to the size of the set of qubits. initZeroState is automatically called allocation, so that the density qureg begins in the zero state |0><0|.

Returns: an object representing the set of qubits

Parameters

[in]	numQubits	number of qubits in the system
[in]	env	object representing the execution environment (local, multinode etc)

Exceptions

exitWithError if numQubits <= 0

Author: Tyson Jones

Definition at line 48 of file QuEST.c.

                                                       {
     validateNumQubitsInQureg(2*numQubits, env.numRanks, __func__);
     
     Qureg qureg;
     statevec_createQureg(&qureg, 2*numQubits, env);
     qureg.isDensityMatrix = 1;
     qureg.numQubitsRepresented = numQubits;
     qureg.numQubitsInStateVec = 2*numQubits;
     
     qasm_setup(&qureg);
     initZeroState(qureg); // safe call to public function
     return qureg;
 }

References initZeroState(), Qureg::isDensityMatrix, Qureg::numQubitsInStateVec, Qureg::numQubitsRepresented, QuESTEnv::numRanks, qasm_setup(), statevec_createQureg(), and validateNumQubitsInQureg().

Referenced by TEST_CASE().

◆ createQuESTEnv()

QuESTEnv createQuESTEnv ( void )

Create the QuEST execution environment.

This should be called only once, and the environment should be freed with destroyQuESTEnv at the end of the user's code. If something needs to be done to set up the execution environment, such as initializing MPI when running in distributed mode, it is handled here.

Returns: object representing the execution environment. A single instance is used for each program

Author: Ania Brown

Definition at line 129 of file QuEST_cpu_distributed.c.

                               {
     
     QuESTEnv env;
     
     // init MPI environment
     int rank, numRanks, initialized;
     MPI_Initialized(&initialized);
     if (!initialized){
         MPI_Init(NULL, NULL);
         MPI_Comm_size(MPI_COMM_WORLD, &numRanks);
         MPI_Comm_rank(MPI_COMM_WORLD, &rank);
  
         env.rank=rank;
         env.numRanks=numRanks;
  
     } else {
         
         printf("ERROR: Trying to initialize QuESTEnv multiple times. Ignoring...\n");
         
         // ensure env is initialised anyway, so the compiler is happy
         MPI_Comm_size(MPI_COMM_WORLD, &numRanks);
         MPI_Comm_rank(MPI_COMM_WORLD, &rank);
         env.rank=rank;
         env.numRanks=numRanks;
         }
     
     validateNumRanks(env.numRanks, __func__);
     
         seedQuESTDefault();
     
     return env;
 }

References GPUExists(), QuESTEnv::numRanks, QuESTEnv::rank, seedQuESTDefault(), and validateNumRanks().

Referenced by main().

◆ createQureg()

Qureg createQureg	(	int	numQubits,
		QuESTEnv	env
	)

Create a Qureg object representing a set of qubits which will remain in a pure state.

Allocate space for state vector of probability amplitudes, including space for temporary values to be copied from one other chunk if running the distributed version. Define properties related to the size of the set of qubits. The qubits are initialised in the zero state (i.e. initZeroState is automatically called)

Returns: an object representing the set of qubits

Parameters

[in]	numQubits	number of qubits in the system
[in]	env	object representing the execution environment (local, multinode etc)

Exceptions

exitWithError if numQubits <= 0

Author: Ania Brown

Definition at line 34 of file QuEST.c.

                                                {
     validateNumQubitsInQureg(numQubits, env.numRanks, __func__);
     
     Qureg qureg;
     statevec_createQureg(&qureg, numQubits, env);
     qureg.isDensityMatrix = 0;
     qureg.numQubitsRepresented = numQubits;
     qureg.numQubitsInStateVec = numQubits;
     
     qasm_setup(&qureg);
     initZeroState(qureg); // safe call to public function
     return qureg;
 }

References initZeroState(), Qureg::isDensityMatrix, Qureg::numQubitsInStateVec, Qureg::numQubitsRepresented, QuESTEnv::numRanks, qasm_setup(), statevec_createQureg(), and validateNumQubitsInQureg().

Referenced by TEST_CASE().

◆ destroyComplexMatrixN()

void destroyComplexMatrixN ( ComplexMatrixN matr )

Destroy a ComplexMatrixN instance created with createComplexMatrixN()

It is invalid to attempt to destroy a matrix created with getStaticComplexMatrixN().

Parameters

[in] matr the dynamic matrix (created with createComplexMatrixN()) to deallocate

Exceptions

exitWithError	if `matr` was not yet allocated.
malloc_error	if `matr` was static (created with getStaticComplexMatrixN())

Author: Tyson Jones

Definition at line 1021 of file QuEST.c.

                                              {
     /* this checks m.real/imag != NULL, which is only ever set when the mallocs 
      * in createComplexMatrixN fail, which already prompts an error. Hence 
      * this check if useless 
      */
     validateMatrixInit(m, __func__);
     
     int numRows = 1 << m.numQubits;
     for (int r=0; r < numRows; r++) {
         free(m.real[r]);
         free(m.imag[r]);
     }
     free(m.real);
     free(m.imag);
 }

References ComplexMatrixN::imag, ComplexMatrixN::numQubits, ComplexMatrixN::real, and validateMatrixInit().

Referenced by densmatr_mixMultiQubitKrausMap(), and TEST_CASE().

◆ destroyQuESTEnv()

void destroyQuESTEnv ( QuESTEnv env )

Destroy the QuEST environment.

If something needs to be done to clean up the execution environment, such as finalizing MPI when running in distributed mode, it is handled here

Parameters

[in] env object representing the execution environment. A single instance is used for each program

Author: Ania Brown

Definition at line 172 of file QuEST_cpu_distributed.c.

                                   {
     int finalized;
     MPI_Finalized(&finalized);
     if (!finalized) MPI_Finalize();
     else printf("ERROR: Trying to close QuESTEnv multiple times. Ignoring\n");
 }

Referenced by main().

◆ destroyQureg()

void destroyQureg	(	Qureg	qureg,
		QuESTEnv	env
	)

Deallocate a Qureg object representing a set of qubits.

Free memory allocated to state vector of probability amplitudes, including temporary vector for values copied from another chunk if running the distributed version.

Parameters

[in,out]	qureg	object to be deallocated
[in]	env	object representing the execution environment (local, multinode etc)

Author: Ania Brown

Definition at line 75 of file QuEST.c.

                                              {
     statevec_destroyQureg(qureg, env);
     qasm_free(qureg);
 }

References qasm_free(), and statevec_destroyQureg().

Referenced by TEST_CASE().

◆ initComplexMatrixN()

void initComplexMatrixN	(	ComplexMatrixN	m,
		qreal	real[][1<< m.numQubits],
		qreal	imag[][1<< m.numQubits]
	)

Initialises a ComplexMatrixN instance to have the passed real and imag values.

This allows succint population of any-sized ComplexMatrixN, e.g. through 2D arrays:

ComplexMatrixN m = createComplexMatrixN(3);
initComplexMatrixN(m, 
    (qreal[8][8]) {{1,2,3,4,5,6,7,8}, {0}},
    (qreal[8][8]) {{0}});

m can be created by either createComplexMatrixN() or getStaticComplexMatrixN().

This function is only callable in C, since C++ signatures cannot contain variable-length 2D arrays

Parameters

[in]	m	the matrix to initialise
[in]	real	matrix of real values; can be 2D array of array of pointers
[in]	imag	matrix of imaginary values; can be 2D array of array of pointers

Exceptions

exitWithError if m has not been allocated (e.g. with createComplexMatrixN())

Author: Tyson Jones

Definition at line 1037 of file QuEST.c.

                                                                                                   {
     validateMatrixInit(m, __func__);
     
     int dim = 1 << m.numQubits;
     for (int i=0; i<dim; i++)
         for (int j=0; j<dim; j++) {
             m.real[i][j] = re[i][j];
             m.imag[i][j] = im[i][j];
         }
 }

References ComplexMatrixN::imag, ComplexMatrixN::numQubits, ComplexMatrixN::real, and validateMatrixInit().

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ fromComplex

◆ getStaticComplexMatrixN

◆ qcomp

◆ qreal

◆ QuEST_PREC

◆ toComplex

Enumeration Type Documentation

◆ pauliOpType

Function Documentation

◆ createCloneQureg()

◆ createComplexMatrixN()

◆ createDensityQureg()

◆ createQuESTEnv()

◆ createQureg()

◆ destroyComplexMatrixN()

◆ destroyQuESTEnv()

◆ destroyQureg()

◆ initComplexMatrixN()