QuEST.h

// 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"
 
 
 
// ensure custatevecHandle_t is defined, even if no GPU
# ifdef USE_CUQUANTUM
# include <custatevec.h>
typedef struct CuQuantumConfig {
    cudaMemPool_t cuMemPool;
    cudaStream_t cuStream;
    custatevecHandle_t cuQuantumHandle;
    custatevecDeviceMemHandler_t cuMemHandler;
} CuQuantumConfig;
# else
# define CuQuantumConfig void*
# endif
 
 
 
// 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;
 
enum phaseFunc {
    NORM=0,     SCALED_NORM=1,      INVERSE_NORM=2,      SCALED_INVERSE_NORM=3,      SCALED_INVERSE_SHIFTED_NORM=4,
    PRODUCT=5,  SCALED_PRODUCT=6,   INVERSE_PRODUCT=7,   SCALED_INVERSE_PRODUCT=8,
    DISTANCE=9, SCALED_DISTANCE=10, INVERSE_DISTANCE=11, SCALED_INVERSE_DISTANCE=12, SCALED_INVERSE_SHIFTED_DISTANCE=13, SCALED_INVERSE_SHIFTED_WEIGHTED_DISTANCE=14
};
    
enum bitEncoding {UNSIGNED=0, TWOS_COMPLEMENT=1};
 
typedef struct PauliHamil 
{
    enum pauliOpType* pauliCodes;
    qreal* termCoeffs;
    int numSumTerms;
    int numQubits;
} PauliHamil;
 
typedef struct DiagonalOp
{
    int numQubits;
    long long int numElemsPerChunk;
    int numChunks;
    int chunkId;
    qreal *real;
    qreal *imag;
    ComplexArray deviceOperator;
} DiagonalOp;
 
typedef struct SubDiagonalOp
{
    int numQubits;
    long long int numElems;
    qreal *real;
    qreal *imag;
    
} SubDiagonalOp;
 
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;
 
    cuAmp* cuStateVec;
    cuAmp* deviceCuStateVec;
    CuQuantumConfig* cuConfig;
 
    QASMLogger* qasmLog;
    
} Qureg;
 
typedef struct QuESTEnv
{
    int rank;
    int numRanks;
    unsigned long int* seeds;
    int numSeeds;
 
    // a copy of the QuESTEnv's config, used only in cuQuantum deployment
    CuQuantumConfig* cuConfig;
    
} 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
#ifndef _WIN32
void initComplexMatrixN(ComplexMatrixN m, qreal real[][1<<m.numQubits], qreal imag[][1<<m.numQubits]);
#endif
#endif
 
PauliHamil createPauliHamil(int numQubits, int numSumTerms);
 
void destroyPauliHamil(PauliHamil hamil);
 
PauliHamil createPauliHamilFromFile(char* fn);
 
void initPauliHamil(PauliHamil hamil, qreal* coeffs, enum pauliOpType* codes);
 
DiagonalOp createDiagonalOp(int numQubits, QuESTEnv env);
 
void destroyDiagonalOp(DiagonalOp op, QuESTEnv env);
 
void syncDiagonalOp(DiagonalOp op);
 
void initDiagonalOp(DiagonalOp op, qreal* real, qreal* imag);
 
void initDiagonalOpFromPauliHamil(DiagonalOp op, PauliHamil hamil);
 
DiagonalOp createDiagonalOpFromPauliHamilFile(char* fn, QuESTEnv env);
 
void setDiagonalOpElems(DiagonalOp op, long long int startInd, qreal* real, qreal* imag, long long int numElems);
 
void applyDiagonalOp(Qureg qureg, DiagonalOp op);
 
Complex calcExpecDiagonalOp(Qureg qureg, DiagonalOp op);
 
SubDiagonalOp createSubDiagonalOp(int numQubits);
 
void destroySubDiagonalOp(SubDiagonalOp op);
 
void diagonalUnitary(Qureg qureg, int* targets, int numTargets, SubDiagonalOp op);
 
void applyGateSubDiagonalOp(Qureg qureg, int* targets, int numTargets, SubDiagonalOp op);
 
void applySubDiagonalOp(Qureg qureg, int* targets, int numTargets, SubDiagonalOp op);
 
void reportState(Qureg qureg);
 
void reportStateToScreen(Qureg qureg, QuESTEnv env, int reportRank);
 
void reportQuregParams(Qureg qureg);
 
void reportPauliHamil(PauliHamil hamil);
 
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 setDensityAmps(Qureg qureg, long long int startRow, long long int startCol, qreal* reals, qreal* imags, long long int numAmps);
 
void setQuregToPauliHamil(Qureg qureg, PauliHamil hamil);
 
void cloneQureg(Qureg targetQureg, Qureg copyQureg);
 
void phaseShift(Qureg qureg, int targetQubit, qreal angle);
 
void controlledPhaseShift(Qureg qureg, int idQubit1, int idQubit2, qreal angle);
 
void multiControlledPhaseShift(Qureg qureg, int *controlQubits, int numControlQubits, qreal angle);
 
void controlledPhaseFlip (Qureg qureg, int idQubit1, int idQubit2);
 
void multiControlledPhaseFlip(Qureg qureg, int *controlQubits, int numControlQubits);
 
void sGate(Qureg qureg, int targetQubit);
 
void tGate(Qureg qureg, 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, char str[200]);
 
void copyStateToGPU(Qureg qureg);
 
void copyStateFromGPU(Qureg qureg);
 
void copySubstateToGPU(Qureg qureg, long long int startInd, long long int numAmps);
 
void copySubstateFromGPU(Qureg qureg, long long int startInd, long long int numAmps);
 
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, int targetQubit, Complex alpha, Complex beta);
 
void unitary(Qureg qureg, int targetQubit, ComplexMatrix2 u);
 
void rotateX(Qureg qureg, int rotQubit, qreal angle);
 
void rotateY(Qureg qureg, int rotQubit, qreal angle);
 
void rotateZ(Qureg qureg, int rotQubit, qreal angle);
 
void rotateAroundAxis(Qureg qureg, int rotQubit, qreal angle, Vector axis);
 
void controlledRotateX(Qureg qureg, int controlQubit, int targetQubit, qreal angle);
 
void controlledRotateY(Qureg qureg, int controlQubit, int targetQubit, qreal angle);
 
void controlledRotateZ(Qureg qureg, int controlQubit, int targetQubit, qreal angle);
 
void controlledRotateAroundAxis(Qureg qureg, int controlQubit, int targetQubit, qreal angle, Vector axis);
 
void controlledCompactUnitary(Qureg qureg, int controlQubit, int targetQubit, Complex alpha, Complex beta);
 
void controlledUnitary(Qureg qureg, int controlQubit, int targetQubit, ComplexMatrix2 u);
 
void multiControlledUnitary(Qureg qureg, int* controlQubits, int numControlQubits, int targetQubit, ComplexMatrix2 u);
 
void pauliX(Qureg qureg, int targetQubit);
 
void pauliY(Qureg qureg, int targetQubit);
 
void pauliZ(Qureg qureg, int targetQubit);
 
void hadamard(Qureg qureg, int targetQubit);
 
void controlledNot(Qureg qureg, int controlQubit, int targetQubit);
 
void multiControlledMultiQubitNot(Qureg qureg, int* ctrls, int numCtrls, int* targs, int numTargs);
 
void multiQubitNot(Qureg qureg, int* targs, int numTargs);
 
void controlledPauliY(Qureg qureg, int controlQubit, int targetQubit);
 
qreal calcProbOfOutcome(Qureg qureg, int measureQubit, int outcome);
 
void calcProbOfAllOutcomes(qreal* outcomeProbs, Qureg qureg, int* qubits, int numQubits);
 
qreal collapseToOutcome(Qureg qureg, 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(QuESTEnv *env);
 
void seedQuEST(QuESTEnv *env, unsigned long int *seedArray, int numSeeds);
 
void getQuESTSeeds(QuESTEnv env, unsigned long int** seeds, 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, int targetQubit, qreal prob);
 
void mixTwoQubitDephasing(Qureg qureg, int qubit1, int qubit2, qreal prob);
 
void mixDepolarising(Qureg qureg, int targetQubit, qreal prob);
 
void mixDamping(Qureg qureg, 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, int numControlQubits, 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);
 
void multiControlledMultiRotateZ(Qureg qureg, int* controlQubits, int numControls, int* targetQubits, int numTargets, qreal angle);
 
void multiControlledMultiRotatePauli(Qureg qureg, int* controlQubits, int numControls, 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);
 
qreal calcExpecPauliHamil(Qureg qureg, PauliHamil hamil, Qureg workspace);
 
void twoQubitUnitary(Qureg qureg, int targetQubit1, int targetQubit2, ComplexMatrix4 u);
 
void controlledTwoQubitUnitary(Qureg qureg, int controlQubit, int targetQubit1, int targetQubit2, ComplexMatrix4 u);
 
void multiControlledTwoQubitUnitary(Qureg qureg, int* controlQubits, int numControlQubits, int targetQubit1, int targetQubit2, ComplexMatrix4 u);
 
void multiQubitUnitary(Qureg qureg, int* targs, int numTargs, ComplexMatrixN u);
 
void controlledMultiQubitUnitary(Qureg qureg, int ctrl, int* targs, int numTargs, ComplexMatrixN u);
 
void multiControlledMultiQubitUnitary(Qureg qureg, int* ctrls, int numCtrls, int* targs, 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);
 
void mixNonTPKrausMap(Qureg qureg, int target, ComplexMatrix2 *ops, int numOps);
 
void mixNonTPTwoQubitKrausMap(Qureg qureg, int target1, int target2, ComplexMatrix4 *ops, int numOps);
 
void mixNonTPMultiQubitKrausMap(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 applyPauliHamil(Qureg inQureg, PauliHamil hamil, Qureg outQureg);
 
void applyTrotterCircuit(Qureg qureg, PauliHamil hamil, qreal time, int order, int reps);
 
void applyMatrix2(Qureg qureg, int targetQubit, ComplexMatrix2 u);
 
void applyMatrix4(Qureg qureg, int targetQubit1, int targetQubit2, ComplexMatrix4 u);
 
void applyMatrixN(Qureg qureg, int* targs, int numTargs, ComplexMatrixN u);
 
void applyGateMatrixN(Qureg qureg, int* targs, int numTargs, ComplexMatrixN u);
 
void applyMultiControlledGateMatrixN(Qureg qureg, int* ctrls, int numCtrls, int* targs, int numTargs, ComplexMatrixN m);
 
void applyMultiControlledMatrixN(Qureg qureg, int* ctrls, int numCtrls, int* targs, int numTargs, ComplexMatrixN u);
 
void invalidQuESTInputError(const char* errMsg, const char* errFunc);
 
#ifndef __cplusplus
#ifndef _WIN32
 // hide this function from doxygen
 
ComplexMatrixN bindArraysToStackComplexMatrixN(
    int numQubits, qreal re[][1<<numQubits], qreal im[][1<<numQubits], 
    qreal** reStorage, qreal** imStorage);
#endif
#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
 
void applyPhaseFunc(Qureg qureg, int* qubits, int numQubits, enum bitEncoding encoding, qreal* coeffs, qreal* exponents, int numTerms);
 
void applyPhaseFuncOverrides(Qureg qureg, int* qubits, int numQubits, enum bitEncoding encoding, qreal* coeffs, qreal* exponents, int numTerms, long long int* overrideInds, qreal* overridePhases, int numOverrides);
 
void applyMultiVarPhaseFunc(Qureg qureg, int* qubits, int* numQubitsPerReg, int numRegs, enum bitEncoding encoding, qreal* coeffs, qreal* exponents, int* numTermsPerReg);
 
void applyMultiVarPhaseFuncOverrides(Qureg qureg, int* qubits, int* numQubitsPerReg, int numRegs, enum bitEncoding encoding, qreal* coeffs, qreal* exponents, int* numTermsPerReg, long long int* overrideInds, qreal* overridePhases, int numOverrides);
 
void applyNamedPhaseFunc(Qureg qureg, int* qubits, int* numQubitsPerReg, int numRegs, enum bitEncoding encoding, enum phaseFunc functionNameCode);
 
void applyNamedPhaseFuncOverrides(Qureg qureg, int* qubits, int* numQubitsPerReg, int numRegs, enum bitEncoding encoding, enum phaseFunc functionNameCode, long long int* overrideInds, qreal* overridePhases, int numOverrides);
 
void applyParamNamedPhaseFunc(Qureg qureg, int* qubits, int* numQubitsPerReg, int numRegs, enum bitEncoding encoding, enum phaseFunc functionNameCode, qreal* params, int numParams);
 
void applyParamNamedPhaseFuncOverrides(Qureg qureg, int* qubits, int* numQubitsPerReg, int numRegs, enum bitEncoding encoding, enum phaseFunc functionNameCode, qreal* params, int numParams, long long int* overrideInds, qreal* overridePhases, int numOverrides);
 
void applyFullQFT(Qureg qureg);
 
void applyQFT(Qureg qureg, int* qubits, int numQubits);
 
void applyProjector(Qureg qureg, int qubit, int outcome);
 
// end prevention of C++ name mangling
#ifdef __cplusplus
}
#endif
 
#endif // QUEST_H