Modes

Constants and environment variables for controlling QuEST execution. More...

Variables
const qreal	QUEST_DEFAULT_NUM_GPU_THREADS_PER_BLOCK = 0
const qreal	QUEST_DEFAULT_VALIDATION_EPSILON = 0
const int	QUEST_PERMIT_NODES_TO_SHARE_GPU = 0

Detailed Description

Constants and environment variables for controlling QuEST execution.

Variable Documentation

QUEST_DEFAULT_NUM_GPU_THREADS_PER_BLOCK

const qreal QUEST_DEFAULT_NUM_GPU_THREADS_PER_BLOCK = 0

Note

This entity is actually an environment variable.

Specifies the default number of threads per block (or "block dimension") used by GPU acceleration.

The number of dispatched CUDA threads per block controls the parallelisation granularity of QuEST's GPU backend, affecting performance. Specifying QUEST_DEFAULT_NUM_GPU_THREADS_PER_BLOCK to a valid, positive integer overrides QuEST's default otherwise set during compilation via a CMake option of the same name. If that CMake option was not set, the default is assumed to be 128.

The number specified by this environment variable will be used as the block dimension by all of QuEST's GPU backend functions, unless overridden at runtime via setQuESTNumGpuThreadsPerBlock(). The actual number of threads per block used at any time can be queried via getQuESTNumGpuThreadsPerBlock(), or reported by reportQuESTEnv().

Values

• use internal default of 128: '', , (unspecified)
• use number x: x, 'x', '+x'

Constraints

The function initQuESTEnv() will throw a validation error if any of the below are not satisfied.

• The specified number must be a positive integer.
• The specified number must not exceed the minimum or maximum value which can be stored in an int.
• The specified number must be divisible by the GPU warp size, which is 32 or 64, depending on whether deployed to an NVIDIA or AMD GPU. This restriction is imposed even when QuEST is not deployed with GPU-acceleration.
• The specified number exceeds the maximum imposed by the available GPU hardware.

Author

Oliver Brown

Tyson Jones

Definition at line 116 of file modes.h.

QUEST_DEFAULT_VALIDATION_EPSILON

const qreal QUEST_DEFAULT_VALIDATION_EPSILON = 0

Note

This entity is actually an environment variable.

Specifies the default validation epsilon.

Specifying QUEST_DEFAULT_VALIDATION_EPSILON to a positive, real number overrides the precision-specific default (1E-5, 1E-12, 1E-13 for single, double and quadruple precision respectively). The specified epsilon is used by QuEST for numerical validation unless overriden at runtime via setQuESTValidationEpsilon(), in which case it can be restored to that specified by this environment variable using setQuESTValidationEpsilonToDefault().

Values

• setting QUEST_DEFAULT_VALIDATION_EPSILON=0 disables numerical validation, as if the value were instead infinity.
• setting QUEST_DEFAULT_VALIDATION_EPSILON='' is equivalent to not specifying the variable, adopting instead the precision-specific default above.
• setting QUEST_DEFAULT_VALIDATION_EPSILON=x where x is a positive, valid qreal in any format accepted by C or C++ (e.g. 0.01, 1E-2, +1e-2) will use x as the default validation epsilon.

Constraints

The function initQuESTEnv() will throw a validation error if any of the below are not satisfied.

• The specified epsilon must be 0 or positive.
• The specified epsilon must not exceed that maximum or minimum value which can be stored in a qreal, which is specific to its precision.

Author

Tyson Jones

Definition at line 82 of file modes.h.

QUEST_PERMIT_NODES_TO_SHARE_GPU

const int QUEST_PERMIT_NODES_TO_SHARE_GPU = 0

Note

This entity is actually an environment variable.

Specifies whether to permit multiple MPI processes to deploy to the same GPU.

Attention

This environment variable has no effect when either (or both) of distribution or GPU-acceleration are disabled.

In multi-GPU execution, which combines distribution with GPU-acceleration, it is prudent to assign each GPU to at most one MPI process in order to avoid superfluous slowdown. Hence by default, initQuESTEnv() will forbid assigning multiple MPI processes to the same GPU. This environment variable can be set to 1 to disable this validation, permitting sharing of a single GPU, as is often useful for debugging or unit testing (for example, testing multi-GPU execution when only a single GPU is available).

Warning

Permitting GPU sharing may cause unintended behaviour when additionally using cuQuantum.

Values

• forbid sharing: 0, '0', '', , (unspecified)
• permit sharing: 1, '1'

Constraints

The function initQuESTEnv() will throw a validation error if any of the below are not satisfied.

• The specified string does not evaluate to an integer 0 or 1.

Author

Tyson Jones

Definition at line 52 of file modes.h.