Functions for creating statevectors and density matrices. More...

Functions
Qureg	createCloneQureg (Qureg qureg)

Qureg	createCustomQureg (int numQubits, int isDensMatr, int useDistrib, int useGpuAccel, int useMultithread)

Qureg	createDensityQureg (int numQubits)

Qureg	createForcedDensityQureg (int numQubits)

Qureg	createForcedQureg (int numQubits)

Qureg	createQureg (int numQubits)

Detailed Description

Functions for creating statevectors and density matrices.

Function Documentation

◆ createCloneQureg()

Qureg createCloneQureg ( Qureg qureg )

Note: Documentation for this function or struct is under construction!

Definition at line 315 of file qureg.cpp.

                                    {
    validate_quregFields(qureg, __func__);
 
    // create a new Qureg with identical fields, but zero'd memory
    Qureg clone = validateAndCreateCustomQureg(
        qureg.numQubits, qureg.isDensityMatrix, qureg.isDistributed, 
        qureg.isGpuAccelerated, qureg.isMultithreaded, __func__);
 
    setQuregToClone(clone, qureg); // harmlessly re-validates
 
    // if GPU-accelerated, clone's CPU amps are NOT updated
    return clone;
}

Referenced by TEST_CASE(), and TEST_CASE().

◆ createCustomQureg()

Qureg createCustomQureg	(	int	numQubits,
		int	isDensMatr,
		int	useDistrib,
		int	useGpuAccel,
		int	useMultithread )

Creates a statevector or density matrix with the specified deployments, initialised in the zero state. This function is an alternative to createQureg() and createDensityQureg() which permits explicitly forcing, disabling, or automating particular deployments.

State: Parameters numQubits and isDensMatr respectively inform the dimension of the Qureg, and whether the Qureg is a density matrix or statevector.

Let \( N = \) numQubits.

When isDensMatr=0, the returned statevector contains \( 2^N \) amplitudes, initialised to state
\[ \ket{0}^{\otimes N} \;\; = \;\; \{ 1, \, 0, \, 0, \, \dots, \, 0 \}. \]
When isDensMatr=1, the returned density matrix contains \( 2^{N}\times 2^{N} \) amplitudes, initialised to state
\[ \ket{0}\bra{0}^{\otimes N} \;\; = \;\; \begin{pmatrix} 1 & 0 & \dots \\ 0 & 0 & \\ \vdots & & \ddots \end{pmatrix}. \]

Deployments

The remaining parameters decide the deployments used to accelerate the Qureg in subsequent simulation, and the associated additional memory allocations.

useDistrib indicates whether (=1) or not (=0) to distribute the Qureg's amplitudes across all available MPI nodes. This is suitable for Qureg which are too large to fit into a single node, and requires allocating an additional communication buffer per-node. When useDistrib=0 but the QuEST executable is launched in distributed settings, the Qureg amplitudes will be duplicated upon every node.
useGpuAccel indicates whether (=1) or not (=0) to GPU-accelerate the Qureg, and requires allocating additional persistent memory in the GPU VRAM. When combined with useDistrib=1, every node will allocate both communication buffers and persistent GPU memory, and an additional persistent GPU-memory communication buffer.
useMultithread indicates whether (=1) or not (=0) to use multithreading when subsequently modifying the Qureg with a CPU routine. This requires no additional allocations, and typically has no effect when GPU acceleration is also enabled.

The deployment parameters can also be -1 to let QuEST choose that parameter, taking into account the other forced deployments. While it is always safe to disable a deployment, forcing a deployment which is invalid (e.g. because the device has insufficient free memory) will throw a validation error.

Memory: The total allocated memory depends on all parameters (except useMultithread), and the size of the variable-precision qcomp used to represent each amplitude. This is determined by preprocessor FLOAT_PRECISION via

`FLOAT_PRECISION`	`qcomp` size (bytes)
1	8
2	16
4	16, 20, 32

where the quad-precision size is platform specific, and is often the size of two long double primitives.

Let:

\( N = \) numQubits
\( D=2^N \) or \( =2^{2N} \) (the total number of amplitudes in the state)
\( B = \) sizeof(qcomp) (the size in bytes)
\( W \) be the total number of distributed nodes (the "world size").

The allocated CPU memory (RAM) and GPU memory (VRAM) is

`useDistrib`	`useGpuAccel`	RAM per node	RAM total	VRAM per node	VRAM total	memory total
0	0	\( B \, D \)	\( W B \, D \)	0	0	\( W B \, D \)
0	1	\( B \, D \)	\( W B \, D \)	\( B \, D \)	\( W B \, D \)	\( 2 \, W B \, D \)
1	0	\( 2 \, B \, D \, / \, W \)	\( 2 \, B \, D \)	0	0	\( 2 \, B \, D \)
1	1	\( 2 \, B \, D \, / \, W \)	\( 2 \, B \, D \)	\( 2 \, B \, D \, / \, W \)	\( 2 \, B \, D \)	\( 4 \, B \, D \)

For illustration, using the default FLOAT_PRECISION=2 whereby \( B = 16 \) bytes, the RAM per node over varying distributions is:

`isDensMatr`	`numQubits`	\( W=1 \)	\( W=2 \)	\( W=4 \)	\( W=8 \)	\( W=16 \)	\( W=1024 \)
0	20	16 MiB	16 MiB	8 MiB	4 MiB	2 MiB	32 KiB
0	30	16 GiB	16 GiB	8 GiB	4 GiB	2 GiB	32 MiB
0	35	512 GiB	512 GiB	256 GiB	128 GiB	64 GiB	1 GiB
0	40	16 TiB	16 TiB	8 TiB	4 TiB	2 TiB	32 GiB
0	45	512 TiB	512 TiB	256 TiB	128 TiB	64 TiB	1 TiB
0	50	16 PiB	16 PiB	8 PiB	4 PiB	2 PiB	32 TiB
1	10	16 MiB	16 MiB	8 MiB	4 MiB	2 MiB	32 KiB
1	15	16 GiB	16 GiB	8 GiB	4 GiB	2 GiB	32 MiB
1	20	16 TiB	16 TiB	8 TiB	4 TiB	2 TiB	32 GiB
1	25	16 PiB	16 PiB	8 PiB	4 PiB	2 PiB	32 TiB

Constraints

Cannot use any deployment which has not been prior enabled during compilation, or disabled by createCustomQuESTEnv().
Cannot distribute \( N \) qubits over more than \( 2^N \) nodes (regardless of isDensMatr).
Cannot distribute when the executable was not launched using MPI (e.g. via mpirun).
Cannot GPU-accelerate when a GPU is not available at runtime, or has insufficient memory.

Example: int numQubits = 30;

int isDensMatr = 0;

int useDistrib = 1; // use distribution

int useMultithread = 0; // don't use multithreading

int useGpuAccel = -1; // automate whether to GPU-accelerate

Qureg qureg = createCustomQureg(

numQubits, isDensMatr,

useDistrib, useGpuAccel, useMultithread);

reportQuregParams(qureg);

createCustomQureg
Qureg createCustomQureg(int numQubits, int isDensMatr, int useDistrib, int useGpuAccel, int useMultithread)
Definition qureg.cpp:273

reportQuregParams
void reportQuregParams(Qureg qureg)
Definition qureg.cpp:353

Parameters

[in]	numQubits	the number of qubits in the output Qureg.
[in]	isDensMatr	whether the Qureg is a density matrix (`=1`) or statevector (`=0`).
[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.

Returns: A new Qureg instance of the specified dimension and deployments.

Exceptions

error

if numQubits < 1
if isDensMatr is not 0 or 1
if any of useDistrib, useGpuAccel, useMultithread is not 0, 1 or -1.
if any of useDistrib, useGpuAccel, useMultithread is forced (=1) but is unsupported by the active QuESTEnv. This can happen because:
- the particular deployment was disabled by initCustomQuESTEnv().
- the deployment was not enabled during compilation.
- useDistrib=1 but QuEST was not launched by MPI (e.g. via mpirun).
- useGpuAccel=1 but a GPU is not accessible at runtime.
if useDistrib=1 but the Qureg is too small to distribute over the running nodes.
if the Qureg dimensions would overflow the qindex type.
if the total Qureg memory would overflow the size_t type.
if the system contains insufficient RAM (or VRAM) to store the Qureg.
if any memory allocation unexpectedly fails.

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

See also

createQureg() to automate deployments (equivalent to passing -1).
createForcedQureg() to use all available deployments.

Author: Tyson Jones

Definition at line 273 of file qureg.cpp.

                                                                                                            {
 
    return validateAndCreateCustomQureg(numQubits, isDensMatr, useDistrib, useGpuAccel, useMultithread, __func__);
}

Referenced by TEST_CASE().

◆ createDensityQureg()

Qureg createDensityQureg ( int numQubits )

Creates a density matrix containing numQubits qubits, with automatically chosen deployments, initialised in the zero state.

The chosen deployments (multithreading, GPU-acceleration and distribution) are informed by which facilities are compiled, available at runtime, beneficial for the specified Qureg size, and whether the necessary additional memory structures can fit in accelerators and buffers.

State: Let \( N = \) numQubits. The returned Qureg contains \( 2^N \times 2^N \) amplitudes, each represented by a qcomp, initialised to state
\[ \ket{0}\bra{0}^{\otimes N} \;\; = \;\; \begin{pmatrix} 1 & 0 & \dots \\ 0 & 0 & \\ \vdots & & \ddots \end{pmatrix}. \]

Memory: A density matrix contains square as many amplitudes as the equal-dimension statevector. The total allocated memory will depend upon the automatically chosen deployments, since use of GPU-acceleration requires persistent device memory and distribution necessitates allocating communication buffers. See createCustomQureg() for more information.

Equivalences

This function is equivalent to calling createCustomQureg(), passing isDensMatr=1 and -1 for all deployments to automate them.
Qureg qureg = createCustomQureg(numQubits, 1, -1, -1, -1);

Example: Qureg qureg = createDensityQureg(15);

reportQuregParams(qureg);

createDensityQureg
Qureg createDensityQureg(int numQubits)
Definition qureg.cpp:287

Parameters

[in] numQubits the number of qubits in the output Qureg.

Returns: A new Qureg instance.

Exceptions

error

if numQubits < 1
if the Qureg dimensions would overflow the qindex type.
if the total Qureg memory would overflow the size_t type.
if the system contains insufficient RAM (or VRAM) to store the Qureg in any deployment.
if any memory allocation unexpectedly fails.

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

See also

createQureg() to create a quadratically-smaller statevector Qureg which cannot undergo Decoherence.
createForcedDensityQureg() to create a density matrix which is forced to make use of all available deployments.
createCustomQureg() to explicitly set the used deployments.

Author: Tyson Jones

Definition at line 287 of file qureg.cpp.

                                        {
 
    int isDensMatr = 1;
    int autoMode = modeflag::USE_AUTO;
    return validateAndCreateCustomQureg(numQubits, isDensMatr, autoMode, autoMode, autoMode, __func__);
}

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ createForcedDensityQureg()

Qureg createForcedDensityQureg ( int numQubits )

Note: Documentation for this function or struct is under construction!

Equivalences

This function is equivalent to calling createCustomQureg(), passing isDensMatr=1 and all deployments enabled by the QuEST environment.
QuESTEnv env = getQuESTEnv();

Qureg qureg = createCustomQureg(

numQubits, 1,

env.isDistributed,

env.isGpuAccelerated,

env.isMultithreaded);

getQuESTEnv
QuESTEnv getQuESTEnv()
Definition environment.cpp:408

QuESTEnv
Definition environment.h:33

Definition at line 305 of file qureg.cpp.

                                              {
    validate_envIsInit(__func__);
 
    QuESTEnv env = getQuESTEnv();
 
    int isDensMatr = 1;
    return validateAndCreateCustomQureg(numQubits, isDensMatr, env.isDistributed, env.isGpuAccelerated, env.isMultithreaded, __func__);
}

Referenced by 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(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ createForcedQureg()

Qureg createForcedQureg ( int numQubits )

Note: Documentation for this function or struct is under construction!

Equivalences

This function is equivalent to calling createCustomQureg(), passing isDensMatr=0 and all deployments enabled by the QuEST environment.
QuESTEnv env = getQuESTEnv();

Qureg qureg = createCustomQureg(

numQubits, 0,

env.isDistributed,

env.isGpuAccelerated,

env.isMultithreaded);

Definition at line 295 of file qureg.cpp.

                                       {
    validate_envIsInit(__func__);
 
    QuESTEnv env = getQuESTEnv();
 
    int isDensMatr = 0;
    return validateAndCreateCustomQureg(numQubits, isDensMatr, env.isDistributed, env.isGpuAccelerated, env.isMultithreaded, __func__);
}

Referenced by 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(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ createQureg()

Qureg createQureg ( int numQubits )

Creates a statevector containing numQubits qubits, with automatically chosen deployments, initialised in the zero state.

The chosen deployments (multithreading, GPU-acceleration and distribution) are informed by which facilities are compiled, available at runtime, beneficial for the specified Qureg size, and whether the necessary additional memory structures can fit in accelerators and buffers.

State: Let \( N = \) numQubits. The returned Qureg contains \( 2^N \) amplitudes, each represented by a qcomp, initialised to state
\[ \ket{0}^{\otimes N} \;\; = \;\; \{ 1, \, 0, \, 0, \, \dots, \, 0 \}. \]

Memory: The total allocated memory will depend upon the automatically chosen deployments, since use of GPU-acceleration requires persistent device memory and distribution necessitates allocating communication buffers. See createCustomQureg() for more information.

Equivalences

This function is equivalent to calling createCustomQureg(), passing isDensMatr=0 and -1 for all deployments to automate them.
Qureg qureg = createCustomQureg(numQubits, 0, -1, -1, -1);

Example: Qureg qureg = createQureg(30);

reportQuregParams(qureg);

createQureg
Qureg createQureg(int numQubits)
Definition qureg.cpp:279

Parameters

[in] numQubits the number of qubits in the output Qureg.

Returns: A new Qureg instance.

Exceptions

error

if numQubits < 1
if the Qureg dimensions would overflow the qindex type.
if the total Qureg memory would overflow the size_t type.
if the system contains insufficient RAM (or VRAM) to store the Qureg in any deployment.
if any memory allocation unexpectedly fails.

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

See also

createDensityQureg() to create a density matrix which can additionally undergo Decoherence.
createForcedQureg() to create a statevector which is forced to make use of all available deployments.
createCustomQureg() to explicitly set the used deployments.

Author: Tyson Jones

Definition at line 279 of file qureg.cpp.

                                 {
 
    int isDensMatr = 0;
    int autoMode = modeflag::USE_AUTO;
    return validateAndCreateCustomQureg(numQubits, isDensMatr, autoMode, autoMode, autoMode, __func__);
}

Referenced by 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 TEST_CASE().