Functions for preparing quantum states. More...

Functions
void	cloneQureg (Qureg targetQureg, Qureg copyQureg)
	Overwrite the amplitudes of `targetQureg` with those from `copyQureg`. More...

void	initBlankState (Qureg qureg)
	Initialises a qureg to have all-zero-amplitudes. More...

void	initClassicalState (Qureg qureg, long long int stateInd)
	Initialise `qureg` into the classical state (also known as a "computational basis state") with index `stateInd`. More...

void	initPlusState (Qureg qureg)
	Initialise `qureg` into the plus state. More...

void	initPureState (Qureg qureg, Qureg pure)
	Initialise `qureg` into to a given pure state of an equivalent Hilbert dimension. More...

void	initStateFromAmps (Qureg qureg, qreal reals, qreal imags)
	Initialise `qureg` by specifying all amplitudes. More...

void	initZeroState (Qureg qureg)
	Initialise `qureg` into the zero state. More...

void	setAmps (Qureg qureg, long long int startInd, qreal reals, qreal imags, long long int numAmps)
	Overwrites a subset of the amplitudes in state-vector `qureg`, with those passed in `reals` and `imags`. More...

void	setWeightedQureg (Complex fac1, Qureg qureg1, Complex fac2, Qureg qureg2, Complex facOut, Qureg out)
	Modifies qureg `out` to the result of (`facOut` `out` + `fac1` `qureg1` + `fac2` `qureg2`), imposing no constraints on normalisation. More...

Detailed Description

Functions for preparing quantum states.

Function Documentation

◆ cloneQureg()

void cloneQureg	(	Qureg	targetQureg,
		Qureg	copyQureg
	)

Overwrite the amplitudes of targetQureg with those from copyQureg.

Registers must either both be state-vectors, or both be density matrices, and of equal dimensions. Only the quantum state is cloned, while auxilary info (like recorded QASM) is unchanged. copyQureg is unaffected.

See also

Parameters

[in,out]	targetQureg	the qureg to have its quantum state overwritten
[in]	copyQureg	the qureg to have its quantum state cloned into targetQureg.

Exceptions

invalidQuESTInputError()

if targetQureg is a state-vector while copyQureg is a density matrix (and vice versa)
if targetQureg and copyQureg have different dimensions

Author: Tyson Jones

Definition at line 164 of file QuEST.c.

                                                     {
     validateMatchingQuregTypes(targetQureg, copyQureg, __func__);
     validateMatchingQuregDims(targetQureg, copyQureg, __func__);
     
     statevec_cloneQureg(targetQureg, copyQureg);
 }

References statevec_cloneQureg(), validateMatchingQuregDims(), and validateMatchingQuregTypes().

Referenced by TEST_CASE().

◆ initBlankState()

void initBlankState ( Qureg qureg )

Initialises a qureg to have all-zero-amplitudes.

This is an unphysical state useful for iteratively building a state with functions like setWeightedQureg(), and should not be confused with initZeroState().

Parameters

[in,out] qureg a Qureg of which to clear all amplitudes

Author: Tyson Jones

Definition at line 119 of file QuEST.c.

                                  {
     statevec_initBlankState(qureg);
     
     qasm_recordComment(qureg, "Here, the register was initialised to an unphysical all-zero-amplitudes 'state'.");
 }

References qasm_recordComment(), and statevec_initBlankState().

Referenced by TEST_CASE().

◆ initClassicalState()

void initClassicalState	(	Qureg	qureg,
		long long int	stateInd
	)

Initialise qureg into the classical state (also known as a "computational basis state") with index stateInd.

If qureg is a state-vector, it will become $| \text{stateInd} \rangle$ .
If qureg is a density matrix, it will become $| \text{stateInd} \rangle \langle \text{stateInd} |$ .

Classical states are indexed from zero, so that stateInd = 0 produces $| 00 \dots 00 \rangle$ , and stateInd = 1 produces $| 00 \dots 01 \rangle$ , and stateInd = $ 2^N - 1 $ produces $| 11 \dots 11 \rangle$ .

Subsequent calls to getProbAmp() will yield 0 for all indices except stateInd, and the phase of stateInd's amplitude will be 1 (real).

This function can be used to initialise qureg into a specific binary state (e.g. 11001) using a binary literal (supported by only some compilers):

initClassicalState(qureg, 0b11001);

See also

initPureState()

Parameters

[in,out]	qureg	the Qureg to modify
[in]	stateInd	the index of the basis state to modify `qureg` into

Exceptions

invalidQuESTInputError()

if stateInd is outside [0, qureg.numQubitsRepresented)

Author: Tyson Jones

Definition at line 134 of file QuEST.c.

                                                              {
     validateStateIndex(qureg, stateInd, __func__);
     
     if (qureg.isDensityMatrix)
         densmatr_initClassicalState(qureg, stateInd);
     else
         statevec_initClassicalState(qureg, stateInd);
     
     qasm_recordInitClassical(qureg, stateInd);
 }

References densmatr_initClassicalState(), Qureg::isDensityMatrix, qasm_recordInitClassical(), statevec_initClassicalState(), and validateStateIndex().

Referenced by TEST_CASE().

◆ initPlusState()

void initPlusState ( Qureg qureg )

Initialise qureg into the plus state.

If qureg is a state-vector of $N$ qubits, it is modified to state

${| + \rangle}^{\otimes N} = \frac{1}{\sqrt{2^N}} (| 0 \rangle + | 1 \rangle)^{\otimes N}\,.$

If qureg is a density matrix of $N$ qubits, it is modified to state

${| + \rangle\langle+|}^{\otimes N} = \frac{1}{{2^N}} \sum_i\sum_j |i\rangle\langle j|\,.$

Parameters

[in,out] qureg the object representing the set of qubits to be initialised

Author: Ania Brown (state-vector); Tyson Jones (density matrix, doc)

Definition at line 125 of file QuEST.c.

                                 {
     if (qureg.isDensityMatrix)
         densmatr_initPlusState(qureg);
     else
         statevec_initPlusState(qureg);
     
     qasm_recordInitPlus(qureg);
 }

References densmatr_initPlusState(), Qureg::isDensityMatrix, qasm_recordInitPlus(), and statevec_initPlusState().

Referenced by TEST_CASE().

◆ initPureState()

void initPureState	(	Qureg	qureg,
		Qureg	pure
	)

Initialise qureg into to a given pure state of an equivalent Hilbert dimension.

If qureg is a state-vector, this merely clones pure into qureg.
If qureg is a density matrix, this makes qureg 100% likely to be in the pure state.

Qureg pure is not modified.

See also

initClassicalState()

Parameters

[in,out]	qureg	the Qureg to modify
[in]	pure	a state-vector containing the pure state into which to initialise `qureg`

Exceptions

invalidQuESTInputError()

if qureg and pure have mismatching dimensions
if pure is a density matrix

Author: Tyson Jones

Definition at line 145 of file QuEST.c.

                                             {
     validateSecondQuregStateVec(pure, __func__);
     validateMatchingQuregDims(qureg, pure, __func__);
  
     if (qureg.isDensityMatrix)
         densmatr_initPureState(qureg, pure);
     else
         statevec_cloneQureg(qureg, pure);
     
     qasm_recordComment(qureg, "Here, the register was initialised to an undisclosed given pure state.");
 }

References densmatr_initPureState(), Qureg::isDensityMatrix, qasm_recordComment(), statevec_cloneQureg(), validateMatchingQuregDims(), and validateSecondQuregStateVec().

Referenced by TEST_CASE().

◆ initStateFromAmps()

void initStateFromAmps	(	Qureg	qureg,
		qreal *	reals,
		qreal *	imags
	)

Initialise qureg by specifying all amplitudes.

For density matrices, it is assumed the amplitudes have been flattened column-wise into the given arrays.

The real and imaginary components of the amplitudes are passed in separate arrays, reals and imags, each of which must have length qureg.numAmpsTotal. There is no automatic checking that the passed arrays are L2 normalised, so this can be used to prepare qureg in a non-physical state.

In distributed mode, this would require the complete state to fit in every node. To manually prepare a state for which all amplitudes cannot fit into a single node, use setAmps()

See also

setAmps()

Parameters

[in,out]	qureg	the Qureg to overwrite
[in]	reals	array of the real components of the new amplitudes
[in]	imags	array of the imaginary components of the new amplitudes

Exceptions

segmentation-fault

if either reals or imags have fewer than qureg.numAmpsTotal elements

Author: Tyson Jones

Definition at line 157 of file QuEST.c.

                                                                 {
     
     statevec_setAmps(qureg, 0, reals, imags, qureg.numAmpsTotal);
     
     qasm_recordComment(qureg, "Here, the register was initialised to an undisclosed given pure state.");
 }

References Qureg::numAmpsTotal, qasm_recordComment(), and statevec_setAmps().

Referenced by TEST_CASE().

◆ initZeroState()

void initZeroState ( Qureg qureg )

Initialise qureg into the zero state.

If qureg is a state-vector of $N$ qubits, it is modified to state ${| 0 \rangle}^{\otimes N}$ .
If qureg is a density matrix of $ N $ qubits, it is modified to state ${| 0 \rangle\langle 0 |}^{\otimes N}$

Parameters

[in,out] qureg the object representing the set of all qubits to initialise

Author: Ania Brown (state-vector); Tyson Jones (density matrix, doc)

Definition at line 113 of file QuEST.c.

                                 {
     statevec_initZeroState(qureg); // valid for both statevec and density matrices
     
     qasm_recordInitZero(qureg);
 }

References qasm_recordInitZero(), and statevec_initZeroState().

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

◆ setAmps()

void setAmps	(	Qureg	qureg,
		long long int	startInd,
		qreal *	reals,
		qreal *	imags,
		long long int	numAmps
	)

Overwrites a subset of the amplitudes in state-vector qureg, with those passed in reals and imags.

Only amplitudes with indices in [startInd, startInd + numAmps] will be changed. The resulting qureg may not necessarily be in an L2 normalised state.

In distributed mode, this function assumes the subset reals and imags exist (at least) on the node containing the ultimately updated elements.
For example, below is the correct way to modify the full 8 elements of qureg when split between 2 nodes.

Qureg qureg = createQureg(3, env);
 
long long int numAmps = 4;
qreal re[] = {1,2,3,4};
qreal im[] = {1,2,3,4};
setAmps(qureg, 0, re, im, numAmps);
 
// modify re and im to the next set of elements 
for (int i=0; i<4; i++) {
  re[i] += 4;
  im[i] += 4;
}
setAmps(qureg, 4, re, im, numAmps);

See also

Parameters

[in,out]	qureg	the state-vector to modify
[in]	startInd	the index of the first amplitude in `qureg` to modify
[in]	reals	array of the real components of the new amplitudes
[in]	imags	array of the imaginary components of the new amplitudes
[in]	numAmps	the length of each of the reals and imags arrays.

Exceptions

invalidQuESTInputError()

if qureg is not a state-vector (i.e. is a density matrix)
if startInd is outside [0, qureg.numAmpsTotal]
if numAmps is outside [0, qureg.numAmpsTotal]
if numAmps + startInd >= qureg.numAmpsTotal

Author: Tyson Jones

Definition at line 1021 of file QuEST.c.

                                                                                                      {
     validateStateVecQureg(qureg, __func__);
     validateNumAmps(qureg, startInd, numAmps, __func__);
     
     statevec_setAmps(qureg, startInd, reals, imags, numAmps);
     
     qasm_recordComment(qureg, "Here, some amplitudes in the statevector were manually edited.");
 }

References qasm_recordComment(), statevec_setAmps(), validateNumAmps(), and validateStateVecQureg().

Referenced by TEST_CASE().

◆ setWeightedQureg()

void setWeightedQureg	(	Complex	fac1,
		Qureg	qureg1,
		Complex	fac2,
		Qureg	qureg2,
		Complex	facOut,
		Qureg	out
	)

Modifies qureg out to the result of (facOut out + fac1 qureg1 + fac2 qureg2), imposing no constraints on normalisation.

Works for both state-vectors and density matrices. Note that afterward, out may not longer be normalised and ergo no longer a valid state-vector or density matrix. Users must therefore be careful passing out to other QuEST functions which assume normalisation in order to function correctly.

qureg1, qureg2 and out must be all state-vectors, or all density matrices, of equal dimensions. out can be one (or both) of qureg1 and qureg2.

Parameters

[in]	fac1	the complex number by which to scale `qureg1` in the output state
[in]	qureg1	the first qureg to add to `out`, which is itself unmodified
[in]	fac2	the complex number by which to scale `qureg2` in the output state
[in]	qureg2	the second qureg to add to `out`, which is itself unmodified
[in]	facOut	the complex factor by which to multiply the current elements of `out`. `out` is completely overwritten if `facOut` is set to (Complex) {.real=0,.imag=0}
[in,out]	out	the qureg to be modified, to be scaled by `facOut` then have `fac1` `qureg1` and `fac2` `qureg2` added to it.

Exceptions

invalidQuESTInputError()

if qureg1, qureg2 and aren't all state-vectors or all density matrices
if the dimensions of qureg1, qureg2 and aren't equal

Author: Tyson Jones

Definition at line 1037 of file QuEST.c.

                                                                                                          {
     validateMatchingQuregTypes(qureg1, qureg2, __func__);
     validateMatchingQuregTypes(qureg1, out, __func__);
     validateMatchingQuregDims(qureg1, qureg2,  __func__);
     validateMatchingQuregDims(qureg1, out, __func__);
  
     statevec_setWeightedQureg(fac1, qureg1, fac2, qureg2, facOut, out);
  
     qasm_recordComment(out, "Here, the register was modified to an undisclosed and possibly unphysical state (setWeightedQureg).");
 } 

References qasm_recordComment(), statevec_setWeightedQureg(), validateMatchingQuregDims(), and validateMatchingQuregTypes().

Referenced by TEST_CASE().