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 contiguous subset of the amplitudes in state-vector `qureg`, with those passed in `reals` and `imags`. More...

void	setDensityAmps (Qureg qureg, long long int startRow, long long int startCol, qreal reals, qreal imags, long long int numAmps)
	Overwrites a contiguous subset of the amplitudes in density-matrix `qureg`, with those passed in `reals` and `imags`, intrepreted column-wise. More...

void	setQuregToPauliHamil (Qureg qureg, PauliHamil hamil)
	Overwrites the density-matrix `qureg` with the Z-basis matrix representation of the given real-weighted sum of Pauli tensors `hamil`. 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

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

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);

initClassicalState

void initClassicalState(Qureg qureg, long long int stateInd)

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

Definition: QuEST.c:134

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

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)

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

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

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)

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 contiguous 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

Referenced by TEST_CASE().

◆ setDensityAmps()

void setDensityAmps	(	Qureg	qureg,
		long long int	startRow,
		long long int	startCol,
		qreal *	reals,
		qreal *	imags,
		long long int	numAmps
	)

Overwrites a contiguous subset of the amplitudes in density-matrix qureg, with those passed in reals and imags, intrepreted column-wise.

Only the first numAmp amplitudes starting from row-column index (startRow, startCol), and proceeding down the column (wrapping around between rows) will be modified. The resulting qureg may not necessarily be a valid density matrix normalisation.

In distributed mode, this function assumes the subset reals and imags exist (at least) on the node(s) containing the ultimately updated elements.

See also

Parameters

[in,out]	qureg	the density-matrix to modify
[in]	startRow	the row-index of the first amplitude in `qureg` to modify
[in]	startCol	the column-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 density matrix (i.e. is a state-vector)
if startRow is outside [0, 1 << qureg.numQubitsRepresented]
if startCol is outside [0, 1 << qureg.numQubitsRepresented]
if numAmps is outside [0, qureg.numAmpsTotal]
if numAmps is larger than the remaining number of amplitudes from (startRow, startCol), column-wise

Author: Tyson Jones

Referenced by TEST_CASE().

◆ setQuregToPauliHamil()

void setQuregToPauliHamil	(	Qureg	qureg,
		PauliHamil	hamil
	)

Overwrites the density-matrix qureg with the Z-basis matrix representation of the given real-weighted sum of Pauli tensors hamil.

This leaves qureg in a non-physical state - as a matrix form of hamil - and is useful for establishing a persistent-backend dense representation of the Hamiltonian. For example, qureg can be subsequently passed to functions like calcDensityInnerProduct() which would effectively in-place compute calcExpecPauliHamil().

See also

Parameters

[in,out]	qureg	the density-matrix to overwrite
[in]	hamil	the PauliHamil to expand into a matrix representation

Exceptions

invalidQuESTInputError()

if qureg is not a density matrix (i.e. is a state-vector)
if the dimensions of qureg and hamil do not match
if hamil is an invalid PauliHamil

Author: Tyson Jones

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

Referenced by TEST_CASE().