Environment

Data structures for managing the QuEST execution environment. More...

Classes
struct	QuESTEnv

Functions
void	finalizeQuESTEnv ()
QuESTEnv	getQuESTEnv ()
void	initCustomQuESTEnv (int useDistrib, int useGpuAccel, int useMultithread)
void	initQuESTEnv ()
int	isQuESTEnvInit ()
void	reportQuESTEnv ()
void	syncQuESTEnv ()

Detailed Description

Data structures for managing the QuEST execution environment.

Function Documentation

finalizeQuESTEnv()

void finalizeQuESTEnv

(

)

Finalises the active QuEST execution environment.

This synchronises outstanding GPU/MPI work, clears QuEST's GPU cache, finalises cuQuantum if active, and finalises MPI if QuEST initialised it. It does not destroy any existing QuEST structs, such as Qureg or CompMatr, which should be prior destroyed to avoid a leak.

Exceptions

error

if the QuEST environment is not initialised.

See also

• initQuESTEnv()

Author

Tyson Jones

Definition at line 457 of file environment.cpp.

                        {
    validate_envIsInit(__func__);
 
    // NOTE:
    // calling this will not automatically
    // free the memory of existing Quregs
 
    if (global_envPtr->isGpuAccelerated)
        gpu_clearCache(); // syncs first
 
    if (global_envPtr->isGpuAccelerated && gpu_isCuQuantumCompiled())
        gpu_finalizeCuQuantum();
 
    if (global_envPtr->isDistributed) {
        comm_sync();
        comm_end();
    }
 
    // free global env's heap memory and flag it as unallocated
    free(global_envPtr);
    global_envPtr = nullptr;
 
    // flag that the environment was finalised, to ensure it is never re-initialised
    global_hasEnvBeenFinalized = true;
}

getQuESTEnv()

QuESTEnv getQuESTEnv

(

)

Returns a copy of the active QuEST execution environment.

The returned QuESTEnv describes the active deployment and MPI rank information. This can be useful for making programmatical decisions based on the environment.

Example

QuESTEnv env = getQuESTEnv();
 
if (env.isDistributed && env.isGpuAccelerated && ! env.isMpiGpuAware)
    printf("What a waste!\n");

Returns

A copy of the active QuESTEnv.

Exceptions

error

if the QuEST environment is not initialised.

Author

Tyson Jones

Definition at line 449 of file environment.cpp.

                       {
    validate_envIsInit(__func__);
 
    // returns a copy, so cheeky users calling memcpy() upon const struct still won't mutate
    return *global_envPtr;
}

Referenced by clearQuESTGpuCache(), createCompMatr(), createDiagMatr(), createForcedDensityQureg(), createForcedQureg(), deleteFilesWithPrefixSynch(), getQuESTGpuCacheSize(), setQuESTNumGpuThreadsPerBlock(), 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(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and writeToFileSynch().

initCustomQuESTEnv()

void initCustomQuESTEnv	(	int	useDistrib,
		int	useGpuAccel,
		int	useMultithread )

Initialises the QuEST execution environment with the specified deployments.

Each deployment flag may be 1 to force the deployment, 0 to disable it, or -1 to let QuEST choose automatically. The environment must be initialised exactly once, and cannot be re-initialised after finalizeQuESTEnv().

Parameters

[in]	useDistrib	whether to force (=1), disable (=0), or automate (=-1) distribution.
[in]	useGpuAccel	whether to force (=1), disable (=0), or automate (=-1) GPU acceleration.
[in]	useMultithread	whether to force (=1), disable (=0), or automate (=-1) multithreading.

Exceptions

error

if any deployment flag is not 0, 1 or -1. if the QuEST environment was already initialised, or has already been finalised. if any environment variable has an invalid value. if distribution is enabled but MPI was already initialised. if distribution is enabled but QuEST is launched with a non-power-of-2 number of MPI processes. if distribution and GPU are enabled, and a GPU is used by more than one process, unless explicitly enabled through environment variable QUEST_PERMIT_NODES_TO_SHARE_GPU. if GPU is enabled and cuQuantum was compiled, but the GPU is not compatible with cuQuantum.

See also

• initQuESTEnv()
• initCustomMpiQuESTEnv()
• C and C++ examples

Author

Tyson Jones

Definition at line 429 of file environment.cpp.

                                                                             {
 
    const bool userOwnsMpi = false;
    validateAndInitCustomQuESTEnv(useDistrib, userOwnsMpi, useGpuAccel, useMultithread, __func__);
}

initQuESTEnv()

void initQuESTEnv

(

)

Initialises the QuEST execution environment.

This must be called before any other QuEST function, and performs tasks like validating the environment, reading environment variables, initialising external libraries like MPI or cuQuantum (when available), and seeding random number generators.

This function prepares usage of all of QuEST's parallelisation facilities, such as multithreading, GPU-acceleration and distribution, provided they are compiled and appropriate hardware is available. The used facilities can be controlled with initCustomQuESTEnv().

Remarks

The utilised facilities can be conveniently viewed with reportQuESTEnv().

When distributed execution is initialised with this function, QuEST takes control of MPI, including its initialisation and finalization. User-owned MPI is possible through initCustomMpiQuESTEnv().

Note that when cuQuantum was compiled, and a GPU is available at runtime, the cuQuantum backend is always used over the custom GPU backend (which, infact, was not compiled!). This means the GPU must be compatible with cuQuantum.

Note

Before exiting, the initialised QuEST environment should be finalized with finalizeQuESTEnv(). This is especially important in a distributed environment to avoid MPI errors.

Example

int main() {
    initQuESTEnv();
    reportQuESTEnv();
    finalizeQuESTEnv();
    return 0;
}

Exceptions

error

if the QuEST environment was already initialised, or has already been finalised. if any environment variable has an invalid value. if distribution is enabled but MPI was already initialised. if distribution is enabled but QuEST is launched with a non-power-of-2 number of MPI processes. if distribution and GPU are enabled, and a GPU is used by more than one process, unless explicitly enabled through environment variable QUEST_PERMIT_NODES_TO_SHARE_GPU. if GPU is enabled and cuQuantum was compiled, but the GPU is not compatible with cuQuantum.

See also

• initCustomQuESTEnv()
• initCustomMpiQuESTEnv()
• initCustomMpiCommQuESTEnv()
• finalizeQuESTEnv()
• reportQuESTEnv()

Author

Tyson Jones

Definition at line 436 of file environment.cpp.

                    {
 
    const bool userOwnsMpi = false;
    validateAndInitCustomQuESTEnv(modeflag::USE_AUTO, userOwnsMpi, modeflag::USE_AUTO, modeflag::USE_AUTO, __func__);
}

Referenced by TEST_CASE().

isQuESTEnvInit()

int isQuESTEnvInit

(

)

Indicates whether the QuEST execution environment is currently initialised.

Unlike other QuEST functions, this can be called at any time, including before QuEST initialisation, and after finalisation.

Returns

1 if the environment is initialised, otherwise 0.

Author

Tyson Jones

Definition at line 443 of file environment.cpp.

                     {
 
    return (int) (global_envPtr != nullptr);
}

Referenced by setRandomTestStateSeeds().

reportQuESTEnv()

void reportQuESTEnv

(

)

Prints a summary of the active QuEST execution environment.

The report includes precision, compilation, deployment, CPU, GPU, distribution, Qureg size-limit and automatic-deployment information.

Example

An example output:

QuEST execution environment:
[precision]
    qreal.................double (8 bytes)
    qcomp.................std::__1::complex<double> (16 bytes)
    qindex................long long int (8 bytes)
    validationEpsilon.....1e-12
[compilation]
    isOmpCompiled...............1
    isMpiCompiled...............1
    isMpiSubCommCompiled........0
    isGpuCompiled...............0
    isHipCompiled...............0
    isCuQuantumCompiled.........0
    isCheckpointingCompiled.....0
[deployment]
    isOmpEnabled...........1
    isMpiEnabled...........1
    isGpuEnabled...........0
    isCuQuantumEnabled.....0
[cpu]
    numCpuCores.......14 per machine
    numOmpProcs.......14 per machine
    numOmpThrds.......14 per node
    cpuMemory.........36 GiB per machine
    cpuMemoryFree.....unknown
[gpu]
    numGpus................N/A
    gpuDirect..............N/A
    gpuMemPools............N/A
    gpuMemory..............N/A
    gpuMemoryFree..........N/A
    gpuCache...............N/A
    numThreadsPerBlock.....N/A
[distribution]
    isMpiUserOwned..........0
    isMpiGpuAware...........0
    isGpuSharingEnabled.....N/A
    numMpiNodes.............16
[statevector limits]
    minQubitsForMpi.............4
    maxQubitsForCpu.............31
    maxQubitsForGpu.............N/A
    maxQubitsForMpiCpu..........34
    maxQubitsForMpiGpu..........N/A
    maxQubitsForMemOverflow.....58
    maxQubitsForIndOverflow.....63
[density matrix limits]
    minQubitsForMpi.............4
    maxQubitsForCpu.............15
    maxQubitsForGpu.............N/A
    maxQubitsForMpiCpu..........19
    maxQubitsForMpiGpu..........N/A
    maxQubitsForMemOverflow.....28
    maxQubitsForIndOverflow.....31
[statevector autodeployment]
    8 qubits......[omp] 
    30 qubits.....[omp] [mpi] 
[density matrix autodeployment]
    4 qubits......[omp] 
    15 qubits.....[omp] [mpi]

Exceptions

error

if the QuEST environment is not initialised.

See also

• C and C++ examples

Author

Tyson Jones

Definition at line 495 of file environment.cpp.

                      {
    validate_envIsInit(__func__);
    validate_numReportedNewlinesAboveZero(__func__); // because trailing newline mandatory
 
    /// @todo add function to write this output to file (useful for HPC debugging)
 
    printer_sync();
 
    print_label("QuEST execution environment");
 
    bool statevec = false;
    bool densmatr = true;
 
    // we attempt to report properties of available hardware facilities
    // (e.g. number of CPU cores, number of GPUs) even if the environment is not
    // making use of them, to inform the user how they might change deployment.
    printPrecisionInfo();
    printCompilationInfo();
    printDeploymentInfo();
    printCpuInfo();
    printGpuInfo();
    printDistributionInfo();
    printQuregSizeLimits(statevec);
    printQuregSizeLimits(densmatr);
    printQuregAutoDeployments(statevec);
    printQuregAutoDeployments(densmatr);
 
    // exclude mandatory newline above
    print_oneFewerNewlines();
 
    printer_sync();
}

syncQuESTEnv()

void syncQuESTEnv

(

)

Synchronises QuEST across all processes and machines, waiting for outstanding work to complete.

• When GPU acceleration is active, this function blocks until all outstanding GPU work is complete.
• When distribution is active, this function blocks until all MPI ranks are synchronised.

Exceptions

error

if the QuEST environment is not initialised.

Author

Tyson Jones

Definition at line 484 of file environment.cpp.

                    {
    validate_envIsInit(__func__);
 
    if (global_envPtr->isGpuAccelerated)
        gpu_sync();
 
    if (global_envPtr->isDistributed)
        comm_sync();
}

Referenced by areEqual(), areEqual(), areEqual(), deleteFilesWithPrefixSynch(), toQMatrix(), toQureg(), toQureg(), toQVector(), and writeToFileSynch().