Functions for initialising Qureg into physical states. More...

Functions
void	initArbitraryPureState (Qureg qureg, qcomp *amps)

void	initBlankState (Qureg qureg)

void	initClassicalState (Qureg qureg, qindex stateInd)

void	initDebugState (Qureg qureg)

void	initPlusState (Qureg qureg)

void	initPureState (Qureg qureg, Qureg pure)

void	initRandomMixedState (Qureg qureg, qindex numPureStates)

void	initRandomPureState (Qureg qureg)

void	initZeroState (Qureg qureg)

Detailed Description

Functions for initialising Qureg into physical states.

Function Documentation

◆ initArbitraryPureState()

void initArbitraryPureState	(	Qureg	qureg,
		qcomp *	amps )

Initialises qureg from the statevector amplitudes in amps.

Formulae

Let \(N\) be the number of qubits in qureg, and let \(\alpha_i\) be the amplitude amps[i]. Array amps must be length \(2^N\).

If qureg is a statevector, its amplitudes are overwritten by amps, to become
\[ \sum\limits_i \alpha_i \ket{i}. \]
If qureg is a density matrix, it is initialised to the pure state \(\ket{\psi}\) encoded by amps, i.e.
\[ \ket{\psi}\bra{\psi} = \sum\limits_i\sum\limits_j \alpha_i \,\alpha_j^* \, \ket{i}\bra{j} \]

There is no need for amps to be normalised, although qureg will otherwise be left in an unnormalised, non-physical state.

Parameters

[in,out]	qureg	the Qureg to overwrite.
[in]	amps	an array of \(2^N\) pure-state amplitudes.

Exceptions

error	if `qureg` is uninitialised.
seg-fault	if `amps` has fewer than \(2^N\) elements.

Author: Tyson Jones

Definition at line 100 of file initialisations.cpp.

                                                      {
    validate_quregFields(qureg, __func__);
 
    // set qureg = |amps> or |amps><amps|
    (qureg.isDensityMatrix)?
        localiser_densmatr_initArbitraryPureState(qureg, amps):
        localiser_statevec_initArbitraryPureState(qureg, amps);
}

Referenced by TEST_CASE(), and TEST_CASE().

◆ initBlankState()

void initBlankState ( Qureg qureg )

Initialises qureg to the unnormalised all-zero-amplitude state.

Every statevector amplitude, or every density-matrix element, is set to zero. This is not a physical quantum state, but is useful as a blank workspace before manually setting amplitudes.

Attention: When qureg is GPU-accelerated, this function modifies only its GPU amplitudes (Qureg::gpuAmps), leaving its CPU amps (Qureg::cpuAmps) unchanged (like almost all QuEST operations). It is therefore necessary to follow this function with syncQuregFromGpu() in order to make further, manual changes from the host side.

Equivalences

This function is equivalent to (but much faster than) overwriting every amplitude to zero, except that it does not modify Qureg::cpuAmps.
for (int i=0; i<qureg.numAmpsPerNode; i++)

qureg.cpuAmps[i] = 0;

syncQuregToGpu(qureg);

// restore qureg.cpuAmps when !qureg.isGpuAccelerated

syncQuregToGpu
void syncQuregToGpu(Qureg qureg)
Definition qureg.cpp:409

Example

This function is useful for preparing sparse states, noting we must explicitly copy the newly-zeroed amplitudes from GPU memory, when qureg is GPU-accelerated (though such functions are always safe to call).

initBlankState(qureg);
syncQuregFromGpu(qureg);
 
// manually modify qureg.cpuAmps in some manner that wouldn't
// be more sensible to perform with setQuregAmps, such as to a
// uniform superposition of random basis states
for (qindex i=0; i<500; i++) {
    qindex j = rand % qureg.numAmpsPerNode;
    qureg.cpuAmps[j] = 1;
}
 
syncQuregToGpu(qureg);
setQuregToRenormalized();

Parameters

[in,out] qureg the Qureg to overwrite.

Exceptions

error

if qureg is uninitialised.

See also

setQuregAmps()
initZeroState()
initClassicalState()
initPlusState()
initRandomPureState()

Author: Tyson Jones

Definition at line 42 of file initialisations.cpp.

                                 {
    validate_quregFields(qureg, __func__);
 
    // |null> = {0, 0, 0, ...}
    qcomp amp = 0;
    localiser_statevec_initUniformState(qureg, amp);
}

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

◆ initClassicalState()

void initClassicalState	(	Qureg	qureg,
		qindex	stateInd )

Initialises qureg to a computational basis state.

Note: Like most of QuEST's API, this function leaves Qureg::cpuAmps unchanged when qureg is GPU-accelerated, overwriting only the relevant GPU buffer Qureg::gpuAmps. See initBlankState() for more information.

Formulae

Let \(N\) be the number of qubits in qureg, and let \(i=\) stateInd.

States are enumerated from \(0\) to \(2^N-1\), such that the bits of the indices match the qubits of the corresponding basis states.

If qureg is a statevector, it is initialised to \(\ket{i}\).
If qureg is a density matrix, it is initialised to \(\ket{i}\bra{i}\).

The bits of \(i\) will match the qubit values of the resulting state in qureg, where the zero-th qubit is the rightmost bit.

Equivalences

The resulting state contains zero for all amplitudes except that at global index \(i\) (when qureg is a statevector) or the \(i\)-th diagonal (when qureg is a density matrix).
initBlankState(qureg);

// determine where the single, global amp to modify is located

qindex numNewAmps = 1;

qindex densityDim = 1 + (1 << qureg.numQubits);

qindex globalAmpInd = stateInd * (qureg.isDensityMatrix? densityDim : 1);

qindex localAmpInd = globalAmpInd % qureg.numAmpsPerNode;

int rankContainingAmp = i / qureg.numAmpsPerNode;

bool isAmpInThisNode = (rankContainingAmp == qureg.rank);

// one node modifies 1 CPU amp

if (isAmpInThisNode)

qureg.cpuAmps[localAmpInd] = 1;

// all nodes sync to GPU but only one node specifies a more than zero amps

syncSubQuregToGpu(qureg, i, numNewAmps * isAmpInThisNode);

syncSubQuregToGpu
void syncSubQuregToGpu(Qureg qureg, qindex localStartInd, qindex numLocalAmps)
Definition qureg.cpp:425
The resulting state can be (pointlessly slowly) produced by qubit flips from the zero state, according to the bits in stateInd.
initZeroState(qureg);

for (int i=0; i<qureg.numQubits; i++)

if ((stateInd >> i) & 1)

applyPauliX(qureg, i);

initZeroState
void initZeroState(Qureg qureg)
Definition initialisations.cpp:51

applyPauliX
void applyPauliX(Qureg qureg, int target)
Definition operations.cpp:785

Parameters

[in,out]	qureg	the Qureg to overwrite.
[in]	stateInd	the computational basis-state index.

Exceptions

error

if qureg is uninitialised.
if stateInd is outside the computational basis of qureg.

Author: Tyson Jones

Definition at line 81 of file initialisations.cpp.

                                                 {
    validate_quregFields(qureg, __func__);
    validate_basisStateIndex(qureg, ind, __func__);
 
    // |ind><ind| = ||ind'>>
    if (qureg.isDensityMatrix)
        ind = util_getGlobalFlatIndex(qureg, ind, ind);
 
    localiser_statevec_initClassicalState(qureg, ind);
}

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

◆ initDebugState()

void initDebugState ( Qureg qureg )

Initialises qureg to the debug state.

This is a non-physical, deterministic pattern useful for debugging. The \(j\)-th local amplitude becomes

\[ 2j/10 + \iu(2j+1)/10, \]

even if qureg is a density matrix, in which case it is enumerated column-major.

Attention: When qureg is GPU-accelerated, this function modifies only its GPU amplitudes (Qureg::gpuAmps), leaving its CPU amps (Qureg::cpuAmps) unchanged (like almost all QuEST operations). It is therefore necessary to follow this function with syncQuregFromGpu() in order to make further, manual changes from the host side. See initBlankState() for more information.

Example

Qureg qureg = createQureg(3);
initDebugState(qureg);
reportQureg(qureg);

Qureg (3 qubit statevector, 8 qcomps, 232 bytes):
1i      |0⟩
2+0.3i  |1⟩
4+0.5i  |2⟩
6+0.7i  |3⟩
8+0.9i  |4⟩
    1+1.1i    |5⟩
2+1.3i  |6⟩
4+1.5i  |7⟩

Parameters

[in,out] qureg the Qureg to overwrite.

Exceptions

error

if qureg is uninitialised.

Author: Tyson Jones

Definition at line 93 of file initialisations.cpp.

                                 {
    validate_quregFields(qureg, __func__);
 
    localiser_statevec_initDebugState(qureg);
}

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

◆ initPlusState()

void initPlusState ( Qureg qureg )

Initialises qureg to the uniform plus state.

Note: Like most of QuEST's API, this function leaves Qureg::cpuAmps unchanged when qureg is GPU-accelerated, overwriting only the relevant GPU buffer Qureg::gpuAmps. See initBlankState() for more information.

Formulae

Let \(N\) be the number of qubits in qureg.

If qureg is a statevector, it is initialised to
\[ \begin{aligned} \ket{+}^{\otimes N} &= \left( \frac{1}{\sqrt{2}} \ket{0} + \frac{1}{\sqrt{2}} \ket{1} \right)^{\otimes N} \\ &= \frac{1}{\sqrt{2^N}} \{ 1, 1, \dots, 1 \} \end{aligned} \]
If qureg is a density matrix, it is initialised to
\[ \ket{+}\bra{+}^{\otimes N} = \frac{1}{2^N} \begin{pmatrix} 1 & 1 & \dots \\ 1 & \ddots \\ \vdots \end{pmatrix} \]

Equivalences

The plus state can also be produced by applying a Hadamard gate upon every zero-state qubit.
initZeroState(qureg);

for (int i=0; i<qureg.numQubits; i++)

applyHadamard(qureg, i);

applyHadamard
void applyHadamard(Qureg qureg, int target)
Definition operations.cpp:597

Parameters

[in,out] qureg the Qureg to overwrite.

Exceptions

error

if qureg is uninitialised.

Author: Tyson Jones

Definition at line 60 of file initialisations.cpp.

                                {
    validate_quregFields(qureg, __func__);
 
    // |+>    = sum_i 1/sqrt(2^N) |i>  where 2^N = numAmps
    // |+><+| = sum_ij 1/2^N |i><j|    where 2^N = sqrt(numAmps)
    qcomp amp = 1.0 / std::sqrt(qureg.numAmps);
    localiser_statevec_initUniformState(qureg, amp);
}

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

◆ initPureState()

void initPureState	(	Qureg	qureg,
		Qureg	pure )

Initialises qureg to the state in statevector pure.

Note: Like most of QuEST's API, this function leaves Qureg::cpuAmps unchanged when qureg is GPU-accelerated, overwriting only the relevant GPU buffer Qureg::gpuAmps. See initBlankState() for more information.

Formulae

Let \(N\) be the number of qubits in qureg or pure, and let \(\ket{\psi} = \) pure, with amplitudes \(\ket{\psi} = \sum_i \alpha_i \ket{i}\).

If qureg is a statevector, it is overwritten by the state in pure.
If qureg is a density matrix, it is initialised to
\[ \ket{\psi}\bra{\psi} = \sum\limits_i\sum\limits_j \alpha_i \,\alpha_j^* \, \ket{i}\bra{j} \]

Equivalences

When qureg is a statevector, this function is entirely equivalent to
setQuregToClone(qureg, pure);

setQuregToClone
void setQuregToClone(Qureg outQureg, Qureg inQureg)
Definition initialisations.cpp:175
When qureg is a density matrix, this function is equivalent to
double prob = 1;

setQuregToMixture(qureg, &prob, &pure, 1);

setQuregToMixture
void setQuregToMixture(Qureg out, qreal *probs, Qureg *in, int numIn)
Definition initialisations.cpp:253

Parameters

[in,out]	qureg	the Qureg to overwrite.
[in]	pure	the statevector pure state to copy.

Exceptions

error

if qureg or pure are uninitialised.
if pure is not a statevector.
if qureg and pure have incompatible dimensions or deployments.

Author: Tyson Jones

Definition at line 70 of file initialisations.cpp.

                                            {
    validate_quregFields(qureg, __func__);
    validate_quregFields(pure, __func__);
    validate_quregCanBeInitialisedToPureState(qureg, pure, __func__);
 
    (qureg.isDensityMatrix)?
        localiser_densmatr_initPureState(qureg, pure):
        localiser_statevec_setQuregToClone(qureg, pure);
}

Referenced by TEST_CASE().

◆ initRandomMixedState()

void initRandomMixedState	(	Qureg	qureg,
		qindex	numPureStates )

Initialises a density matrix to a mixture of uniformly random pure states.

The resulting density matrix is the equally weighted mixture of numPureStates independently sampled random pure states, each sampled as per initRandomPureState().

Formulae

Let \(n=\) numPureStates, and let \(\ket{\psi_i}\) be a random pure state with number of qubits as qureg.

This function overwrites qureg to

\[ \sum\limits_i^n \frac{1}{n} \ket{\psi_i}\bra{\psi_i}. \]

Parameters

[in,out]	qureg	the density matrix to overwrite.
[in]	numPureStates	the number of random pure states in the mixture.

Exceptions

error

if qureg is uninitialised.
if qureg is not a density matrix.
if numPureStates is invalid.

See also

initRandomPureState()

Author: Tyson Jones

Definition at line 133 of file initialisations.cpp.

                                                             {
    validate_quregFields(qureg, __func__);
    validate_quregIsDensityMatrix(qureg, __func__);
    validate_numInitRandomPureStates(numPureStates, __func__);
 
    localiser_densmatr_initMixtureOfUniformlyRandomPureStates(qureg, numPureStates);
}

Referenced by TEST_CASE().

◆ initRandomPureState()

void initRandomPureState ( Qureg qureg )

Initialises qureg (a statevector or density matrix) to a pure state with uniformly random amplitudes.

The resulting state is normalised, with basis state probabilities sampled from a chi-squared variate, as described here.

Parameters

[in,out] qureg the Qureg to overwrite.

Exceptions

error

if qureg is uninitialised.

See also

initRandomMixedState()

Author: Tyson Jones

Definition at line 118 of file initialisations.cpp.

                                      {
    validate_quregFields(qureg, __func__);
 
    // these invoked localiser functions may harmlessly 
    // re-call the API and re-perform input validation
 
    if (qureg.isDensityMatrix)
        localiser_densmatr_initUniformlyRandomPureStateAmps(qureg); 
    else {
        localiser_statevec_initUnnormalisedUniformlyRandomPureStateAmps(qureg);
        setQuregToRenormalized(qureg);
    }
}

Referenced by TEST_CASE().

◆ initZeroState()

void initZeroState ( Qureg qureg )

Initialises qureg to the zero computational basis state.

Note: Like most of QuEST's API, this function leaves Qureg::cpuAmps unchanged when qureg is GPU-accelerated, overwriting only the relevant GPU buffer Qureg::gpuAmps. See initBlankState() for more information.

Formulae

Let \(N\) be the number of qubits in qureg.

If qureg is a statevector, it is initialised to \(\ket{0}^{\otimes N}\).
If qureg is a density matrix, it is initialised to \(\ket{0}\bra{0}^{\otimes N}\).'

Equivalences

The zero state is the first enumerated classical state.
initClassicalState(qureg, 0);

initClassicalState
void initClassicalState(Qureg qureg, qindex stateInd)
Definition initialisations.cpp:81
The zero state has a zero amplitude everywhere except at the first index, which has one. The code below is equivalent to this function, except Qureg::cpuAmps are also modified below, whereas initZeroState() leaves them unchanged when qureg is GPU-accelerated.
initBlankState(qureg);

if (qureg.rank == 0)

qureg.cpuAmps[0] = 1;

syncQureg(qureg);

// restore qureg.cpuAmps when !qureg.isGpuAccelerated

Parameters

[in,out] qureg the Qureg to overwrite.

Exceptions

error

if qureg is uninitialised.

Author: Tyson Jones

Definition at line 51 of file initialisations.cpp.

                                {
    validate_quregFields(qureg, __func__);
 
    // |0> = |0><0|
    qindex ind = 0;
    localiser_statevec_initClassicalState(qureg, ind);
}

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