Functions for preparing quantum states. More...

Functions
void	cloneQureg (Qureg targetQureg, Qureg copyQureg)
	Set targetQureg to be a clone of copyQureg. More...

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

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

void	initPlusState (Qureg qureg)
	Initialise a set of qubits to the plus state ${\| + \rangle}^{\otimes N} = \frac{1}{\sqrt{2^N}} (\| 0 \rangle + \| 1 \rangle)^{\otimes N}$ (and similarly $\|+\rangle \langle+\|$ for density matrices). More...

void	initPureState (Qureg qureg, Qureg pure)
	Initialise a set of qubits, which can be a state vector or density matrix, to a given pure state. More...

void	initStateFromAmps (Qureg qureg, qreal reals, qreal imags)
	Initialise qureg by specifying the complete statevector. More...

void	initZeroState (Qureg qureg)
	Initialise a set of qubits to the classical zero state ${\| 0 \rangle}^{\otimes N}$ . More...

void	setAmps (Qureg qureg, long long int startInd, qreal reals, qreal imags, long long int numAmps)
	Overwrites a subset of the amplitudes in `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
	)

Set targetQureg to be a clone of copyQureg.

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

Parameters

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

Author: Tyson Jones

Definition at line 165 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 e.g. setWeightedQureg, and should not be confused with the zero state |0...0>

Parameters

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

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 a set of $ N $ qubits to the classical state (also known as a "computational basis state") with index stateInd.

State-vectors will be initialised to $| \text{stateInd} \rangle$ , and density-matrices to $| \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 a Qureg in a specific binary state (e.g. 11001) using a binary literal (supported by only some compilers):

 initClassicalState(qureg, 0b11001);

Parameters

[in,out]	qureg	the object representing the set of qubits to be initialised
[in]	stateInd	the index (0 to the number of amplitudes, exclusive) of the state to give probability 1

Exceptions

invalidQuESTInputError if stateInd is outside [0, 2^N-1].

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 a set of $ N $ qubits to the plus state ${| + \rangle}^{\otimes N} = \frac{1}{\sqrt{2^N}} (| 0 \rangle + | 1 \rangle)^{\otimes N}$ (and similarly $|+\rangle \langle+|$ for density matrices).

This is the product state of $N$ qubits where every classical state is uniformly populated (with real coefficient $\frac{1}{\sqrt{2^N}}$ in the state-vector and $\frac{1}{{2^N}}$ in the density-matrix). This is equivalent to applying a Hadamard to every qubit in the zero state: $\hat{H}^{\otimes N} {|0\rangle}^{\otimes N}$

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 a set of $ N $ qubits, which can be a state vector or density matrix, to a given pure state.

If qureg is a state-vector, this merely makes qureg an identical copy of pure. If qureg is a density matrix, this makes qureg 100% likely to be in the pure state.

Parameters

[in,out]	qureg	the object representing the set of qubits to be initialised
[in]	pure	the pure state to be copied or to give probability 1 in qureg

Exceptions

invalidQuESTInputError if qureg and pure have mismatching dimensions, or 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 the complete statevector.

The real and imaginary components of the amplitudes are passed in separate arrays, 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 statevector to fit in every node. To manually prepare a statevector which cannot fit in every node, use setAmps()

Parameters

[in,out]	qureg	the object representing the set of qubits to be initialised
[in]	reals	array of the real components of the new amplitudes
[in]	imags	array of the imaginary components of the new amplitudes

Exceptions

invalidQuESTInputError if qureg is not a statevector (i.e. is a density matrix)

Author: Tyson Jones

Definition at line 157 of file QuEST.c.

                                                                 {
     validateStateVecQureg(qureg, __func__);
     
     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(), statevec_setAmps(), and validateStateVecQureg().

Referenced by TEST_CASE().

◆ initZeroState()

void initZeroState ( Qureg qureg )

Initialise a set of $ N $ qubits to the classical zero state ${| 0 \rangle}^{\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 qureg, with those passed in reals and imags.

Only amplitudes with indices in [startInd, startInd + numAmps] will be changed, which means the new state may not be L2 normalised. This allows the user to initialise a custom state by setting batches of amplitudes.

Parameters

[in,out]	qureg	the statevector to modify
[in]	startInd	the index of the first amplitude in `qureg's` statevector 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 statevector (i.e. is a density matrix), or if startInd is outside [0, qureg.numAmpsTotal], or if numAmps is outside [0, qureg.numAmpsTotal], or if numAmps + startInd is >= qureg.numAmpsTotal.

Author: Tyson Jones

Definition at line 781 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 statevectors and density matrices. Note that afterward, out may not longer be normalised and ergo no longer a valid statevector 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, or if the dimensions of qureg1, qureg2 and aren't equal

Author: Tyson Jones

Definition at line 797 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().