QuEST.h

Go to the documentation of this file.

// Distributed under MIT licence. See https://github.com/QuEST-Kit/QuEST/blob/master/LICENCE.txt for details 
 
# ifndef QUEST_H
# define QUEST_H
 
# include "QuEST_precision.h"
 
// prevent C++ name mangling
#ifdef __cplusplus
extern "C" {
#endif
 
 
/*
 * private structures
 */
    
// hide these from doxygen
 
enum phaseGateType {SIGMA_Z=0, S_GATE=1, T_GATE=2};    
    
typedef struct {
    
    char* buffer;       // generated QASM string
    int bufferSize;     // maximum number of chars before overflow
    int bufferFill;     // number of chars currently in buffer
    int isLogging;      // whether gates are being added to buffer
    
} QASMLogger;
 
typedef struct ComplexArray
{
    qreal *real; 
    qreal *imag;
} ComplexArray;
 
 
    
 
/*
 * public structures
 */
 
 enum pauliOpType {PAULI_I=0, PAULI_X=1, PAULI_Y=2, PAULI_Z=3};
 
typedef struct Complex
{
    qreal real;
    qreal imag;
} Complex;
 
typedef struct ComplexMatrix2
{
    qreal real[2][2];
    qreal imag[2][2];
} ComplexMatrix2;
 
typedef struct ComplexMatrix4
{
    qreal real[4][4];
    qreal imag[4][4];
} ComplexMatrix4;
 
typedef struct ComplexMatrixN
{
  int numQubits;
  qreal **real;
  qreal **imag;
} ComplexMatrixN;
 
typedef struct Vector
{
    qreal x, y, z;
} Vector;
 
typedef struct Qureg
{
    int isDensityMatrix;
    int numQubitsRepresented;
    int numQubitsInStateVec;
    long long int numAmpsPerChunk;
    long long int numAmpsTotal;
    int chunkId;
    int numChunks;
    
    ComplexArray stateVec; 
    ComplexArray pairStateVec;
    
    ComplexArray deviceStateVec;
    qreal *firstLevelReduction, *secondLevelReduction;
 
    QASMLogger* qasmLog;
    
} Qureg;
 
typedef struct QuESTEnv
{
    int rank;
    int numRanks;
} QuESTEnv;
 
 
 
/*
 * public functions
 */
 
Qureg createQureg(int numQubits, QuESTEnv env);
 
Qureg createDensityQureg(int numQubits, QuESTEnv env);
 
Qureg createCloneQureg(Qureg qureg, QuESTEnv env);
 
void destroyQureg(Qureg qureg, QuESTEnv env);
 
ComplexMatrixN createComplexMatrixN(int numQubits);
 
void destroyComplexMatrixN(ComplexMatrixN matr);
 
#ifndef __cplusplus
 
void initComplexMatrixN(ComplexMatrixN m, qreal real[][1<<m.numQubits], qreal imag[][1<<m.numQubits]);
#endif 
 
void reportState(Qureg qureg);
 
void reportStateToScreen(Qureg qureg, QuESTEnv env, int reportRank);
 
void reportQuregParams(Qureg qureg);
 
int getNumQubits(Qureg qureg);
 
long long int getNumAmps(Qureg qureg);
 
void initBlankState(Qureg qureg);
 
void initZeroState(Qureg qureg);
 
void initPlusState(Qureg qureg);
 
void initClassicalState(Qureg qureg, long long int stateInd);
 
void initPureState(Qureg qureg, Qureg pure);
 
void initDebugState(Qureg qureg);
 
void initStateFromAmps(Qureg qureg, qreal* reals, qreal* imags);
 
void setAmps(Qureg qureg, long long int startInd, qreal* reals, qreal* imags, long long int numAmps);
 
void cloneQureg(Qureg targetQureg, Qureg copyQureg);
 
void phaseShift(Qureg qureg, const int targetQubit, qreal angle);
 
void controlledPhaseShift(Qureg qureg, const int idQubit1, const int idQubit2, qreal angle);
 
void multiControlledPhaseShift(Qureg qureg, int *controlQubits, int numControlQubits, qreal angle);
 
void controlledPhaseFlip (Qureg qureg, const int idQubit1, const int idQubit2);
 
void multiControlledPhaseFlip(Qureg qureg, int *controlQubits, int numControlQubits);
 
void sGate(Qureg qureg, const int targetQubit);
 
void tGate(Qureg qureg, const int targetQubit);
 
QuESTEnv createQuESTEnv(void);
 
void destroyQuESTEnv(QuESTEnv env);
 
void syncQuESTEnv(QuESTEnv env);
 
int syncQuESTSuccess(int successCode);
 
void reportQuESTEnv(QuESTEnv env);
 
void getEnvironmentString(QuESTEnv env, Qureg qureg, char str[200]);
 
void copyStateToGPU(Qureg qureg);
 
void copyStateFromGPU(Qureg qureg);
 
Complex getAmp(Qureg qureg, long long int index);
 
qreal getRealAmp(Qureg qureg, long long int index);
 
qreal getImagAmp(Qureg qureg, long long int index);
 
qreal getProbAmp(Qureg qureg, long long int index);
 
Complex getDensityAmp(Qureg qureg, long long int row, long long int col);
 
qreal calcTotalProb(Qureg qureg);
 
void compactUnitary(Qureg qureg, const int targetQubit, Complex alpha, Complex beta);
 
void unitary(Qureg qureg, const int targetQubit, ComplexMatrix2 u);
 
void rotateX(Qureg qureg, const int rotQubit, qreal angle);
 
void rotateY(Qureg qureg, const int rotQubit, qreal angle);
 
void rotateZ(Qureg qureg, const int rotQubit, qreal angle);
 
void rotateAroundAxis(Qureg qureg, const int rotQubit, qreal angle, Vector axis);
 
 
void controlledRotateX(Qureg qureg, const int controlQubit, const int targetQubit, qreal angle);
 
void controlledRotateY(Qureg qureg, const int controlQubit, const int targetQubit, qreal angle);
 
void controlledRotateZ(Qureg qureg, const int controlQubit, const int targetQubit, qreal angle);
 
void controlledRotateAroundAxis(Qureg qureg, const int controlQubit, const int targetQubit, qreal angle, Vector axis);
 
void controlledCompactUnitary(Qureg qureg, const int controlQubit, const int targetQubit, Complex alpha, Complex beta);
 
void controlledUnitary(Qureg qureg, const int controlQubit, const int targetQubit, ComplexMatrix2 u);
 
void multiControlledUnitary(Qureg qureg, int* controlQubits, const int numControlQubits, const int targetQubit, ComplexMatrix2 u);
 
void pauliX(Qureg qureg, const int targetQubit);
 
void pauliY(Qureg qureg, const int targetQubit);
 
void pauliZ(Qureg qureg, const int targetQubit);
 
void hadamard(Qureg qureg, const int targetQubit);
 
void controlledNot(Qureg qureg, const int controlQubit, const int targetQubit);
 
void controlledPauliY(Qureg qureg, const int controlQubit, const int targetQubit);
 
qreal calcProbOfOutcome(Qureg qureg, const int measureQubit, int outcome);
 
qreal collapseToOutcome(Qureg qureg, const int measureQubit, int outcome);
 
int measure(Qureg qureg, int measureQubit);
 
int measureWithStats(Qureg qureg, int measureQubit, qreal *outcomeProb);
 
Complex calcInnerProduct(Qureg bra, Qureg ket);
 
qreal calcDensityInnerProduct(Qureg rho1, Qureg rho2);
 
void seedQuESTDefault(void);
 
void seedQuEST(unsigned long int *seedArray, int numSeeds);
 
void startRecordingQASM(Qureg qureg);
 
void stopRecordingQASM(Qureg qureg);
 
void clearRecordedQASM(Qureg qureg);
 
void printRecordedQASM(Qureg qureg);
 
void writeRecordedQASMToFile(Qureg qureg, char* filename);
 
void mixDephasing(Qureg qureg, const int targetQubit, qreal prob);
 
void mixTwoQubitDephasing(Qureg qureg, int qubit1, int qubit2, qreal prob);
 
void mixDepolarising(Qureg qureg, const int targetQubit, qreal prob);
 
void mixDamping(Qureg qureg, const int targetQubit, qreal prob);
 
void mixTwoQubitDepolarising(Qureg qureg, int qubit1, int qubit2, qreal prob);
 
void mixPauli(Qureg qureg, int targetQubit, qreal probX, qreal probY, qreal probZ);
 
void mixDensityMatrix(Qureg combineQureg, qreal prob, Qureg otherQureg);
 
qreal calcPurity(Qureg qureg);
 
qreal calcFidelity(Qureg qureg, Qureg pureState);
 
void swapGate(Qureg qureg, int qubit1, int qubit2);
 
 
void sqrtSwapGate(Qureg qureg, int qb1, int qb2);
 
void multiStateControlledUnitary(
    Qureg qureg, int* controlQubits, int* controlState, const int numControlQubits, 
    const int targetQubit, ComplexMatrix2 u
);
 
void multiRotateZ(Qureg qureg, int* qubits, int numQubits, qreal angle);
 
void multiRotatePauli(Qureg qureg, int* targetQubits, enum pauliOpType* targetPaulis, int numTargets, qreal angle);
 
qreal calcExpecPauliProd(Qureg qureg, int* targetQubits, enum pauliOpType* pauliCodes, int numTargets, Qureg workspace);
 
qreal calcExpecPauliSum(Qureg qureg, enum pauliOpType* allPauliCodes, qreal* termCoeffs, int numSumTerms, Qureg workspace);
 
void twoQubitUnitary(Qureg qureg, const int targetQubit1, const int targetQubit2, ComplexMatrix4 u);
 
void controlledTwoQubitUnitary(Qureg qureg, const int controlQubit, const int targetQubit1, const int targetQubit2, ComplexMatrix4 u);
 
void multiControlledTwoQubitUnitary(Qureg qureg, int* controlQubits, const int numControlQubits, const int targetQubit1, const int targetQubit2, ComplexMatrix4 u);
 
void multiQubitUnitary(Qureg qureg, int* targs, const int numTargs, ComplexMatrixN u);
 
void controlledMultiQubitUnitary(Qureg qureg, int ctrl, int* targs, const int numTargs, ComplexMatrixN u);
 
void multiControlledMultiQubitUnitary(Qureg qureg, int* ctrls, const int numCtrls, int* targs, const int numTargs, ComplexMatrixN u);
 
void mixKrausMap(Qureg qureg, int target, ComplexMatrix2 *ops, int numOps);
 
void mixTwoQubitKrausMap(Qureg qureg, int target1, int target2, ComplexMatrix4 *ops, int numOps);
 
void mixMultiQubitKrausMap(Qureg qureg, int* targets, int numTargets, ComplexMatrixN* ops, int numOps);
 
qreal calcHilbertSchmidtDistance(Qureg a, Qureg b);
 
void setWeightedQureg(Complex fac1, Qureg qureg1, Complex fac2, Qureg qureg2, Complex facOut, Qureg out);
 
void applyPauliSum(Qureg inQureg, enum pauliOpType* allPauliCodes, qreal* termCoeffs, int numSumTerms, Qureg outQureg);
 
void invalidQuESTInputError(const char* errMsg, const char* errFunc);
 
#ifndef __cplusplus
 // hide this function from doxygen
 
ComplexMatrixN bindArraysToStackComplexMatrixN(
    int numQubits, qreal re[][1<<numQubits], qreal im[][1<<numQubits], 
    qreal** reStorage, qreal** imStorage);
#endif
 
// hide this function from doxygen
#define UNPACK_ARR(...) __VA_ARGS__
 
#ifndef __cplusplus
 
#define getStaticComplexMatrixN(numQubits, re, im) \
    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} \
    )
#endif
 
 
// end prevention of C++ name mangling
#ifdef __cplusplus
}
#endif
 
#endif // QUEST_H