State initialisations

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 $ N $ qubits to the classical state (also known as a "computational basis state") with index stateInd. More...
 
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). More...
 
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. 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 $ N $ 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]targetQuregthe qureg to have its quantum state overwritten
[in]copyQuregthe qureg to have its quantum state cloned in targetQureg.
Author
Tyson Jones

Definition at line 165 of file QuEST.c.

165  {
166  validateMatchingQuregTypes(targetQureg, copyQureg, __func__);
167  validateMatchingQuregDims(targetQureg, copyQureg, __func__);
168 
169  statevec_cloneQureg(targetQureg, copyQureg);
170 }

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]quregthe object representing the set of all qubits to initialise
Author
Tyson Jones

Definition at line 119 of file QuEST.c.

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

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]quregthe object representing the set of qubits to be initialised
[in]stateIndthe index (0 to the number of amplitudes, exclusive) of the state to give probability 1
Exceptions
invalidQuESTInputErrorif stateInd is outside [0, 2^N-1].
Author
Tyson Jones

Definition at line 134 of file QuEST.c.

134  {
135  validateStateIndex(qureg, stateInd, __func__);
136 
137  if (qureg.isDensityMatrix)
138  densmatr_initClassicalState(qureg, stateInd);
139  else
140  statevec_initClassicalState(qureg, stateInd);
141 
142  qasm_recordInitClassical(qureg, stateInd);
143 }

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]quregthe 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.

125  {
126  if (qureg.isDensityMatrix)
127  densmatr_initPlusState(qureg);
128  else
129  statevec_initPlusState(qureg);
130 
131  qasm_recordInitPlus(qureg);
132 }

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]quregthe object representing the set of qubits to be initialised
[in]purethe pure state to be copied or to give probability 1 in qureg
Exceptions
invalidQuESTInputErrorif qureg and pure have mismatching dimensions, or if pure is a density matrix.
Author
Tyson Jones

Definition at line 145 of file QuEST.c.

145  {
146  validateSecondQuregStateVec(pure, __func__);
147  validateMatchingQuregDims(qureg, pure, __func__);
148 
149  if (qureg.isDensityMatrix)
150  densmatr_initPureState(qureg, pure);
151  else
152  statevec_cloneQureg(qureg, pure);
153 
154  qasm_recordComment(qureg, "Here, the register was initialised to an undisclosed given pure state.");
155 }

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]quregthe object representing the set of qubits to be initialised
[in]realsarray of the real components of the new amplitudes
[in]imagsarray of the imaginary components of the new amplitudes
Exceptions
invalidQuESTInputErrorif qureg is not a statevector (i.e. is a density matrix)
Author
Tyson Jones

Definition at line 157 of file QuEST.c.

157  {
158  validateStateVecQureg(qureg, __func__);
159 
160  statevec_setAmps(qureg, 0, reals, imags, qureg.numAmpsTotal);
161 
162  qasm_recordComment(qureg, "Here, the register was initialised to an undisclosed given pure state.");
163 }

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]quregthe 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.

113  {
114  statevec_initZeroState(qureg); // valid for both statevec and density matrices
115 
116  qasm_recordInitZero(qureg);
117 }

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]quregthe statevector to modify
[in]startIndthe index of the first amplitude in qureg's statevector to modify
[in]realsarray of the real components of the new amplitudes
[in]imagsarray of the imaginary components of the new amplitudes
[in]numAmpsthe length of each of the reals and imags arrays.
Exceptions
invalidQuESTInputErrorif 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.

781  {
782  validateStateVecQureg(qureg, __func__);
783  validateNumAmps(qureg, startInd, numAmps, __func__);
784 
785  statevec_setAmps(qureg, startInd, reals, imags, numAmps);
786 
787  qasm_recordComment(qureg, "Here, some amplitudes in the statevector were manually edited.");
788 }

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]fac1the complex number by which to scale qureg1 in the output state
[in]qureg1the first qureg to add to out, which is itself unmodified
[in]fac2the complex number by which to scale qureg2 in the output state
[in]qureg2the second qureg to add to out, which is itself unmodified
[in]facOutthe 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]outthe qureg to be modified, to be scaled by facOut then have fac1 qureg1 and fac2 qureg2 added to it.
Exceptions
invalidQuESTInputErrorif 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.

797  {
798  validateMatchingQuregTypes(qureg1, qureg2, __func__);
799  validateMatchingQuregTypes(qureg1, out, __func__);
800  validateMatchingQuregDims(qureg1, qureg2, __func__);
801  validateMatchingQuregDims(qureg1, out, __func__);
802 
803  statevec_setWeightedQureg(fac1, qureg1, fac2, qureg2, facOut, out);
804 
805  qasm_recordComment(out, "Here, the register was modified to an undisclosed and possibly unphysical state (setWeightedQureg).");
806 }

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

Referenced by TEST_CASE().

void validateStateIndex(Qureg qureg, long long int stateInd, const char *caller)
void densmatr_initPlusState(Qureg targetQureg)
Definition: QuEST_cpu.c:1154
void validateStateVecQureg(Qureg qureg, const char *caller)
void qasm_recordInitZero(Qureg qureg)
Definition: QuEST_qasm.c:415
void validateNumAmps(Qureg qureg, long long int startInd, long long int numAmps, const char *caller)
void qasm_recordInitPlus(Qureg qureg)
Definition: QuEST_qasm.c:430
void densmatr_initClassicalState(Qureg qureg, long long int stateInd)
Definition: QuEST_cpu.c:1115
void statevec_initZeroState(Qureg qureg)
Definition: QuEST_cpu.c:1428
void statevec_initBlankState(Qureg qureg)
Definition: QuEST_cpu.c:1398
void qasm_recordInitClassical(Qureg qureg, long long int stateInd)
Definition: QuEST_qasm.c:458
void statevec_setAmps(Qureg qureg, long long int startInd, qreal *reals, qreal *imags, long long int numAmps)
Definition: QuEST_cpu.c:1237
void statevec_cloneQureg(Qureg targetQureg, Qureg copyQureg)
works for both statevectors and density matrices
Definition: QuEST_cpu.c:1506
void validateMatchingQuregDims(Qureg qureg1, Qureg qureg2, const char *caller)
void statevec_initPlusState(Qureg qureg)
Definition: QuEST_cpu.c:1438
void qasm_recordComment(Qureg qureg, char *comment,...)
Definition: QuEST_qasm.c:120
void statevec_setWeightedQureg(Complex fac1, Qureg qureg1, Complex fac2, Qureg qureg2, Complex facOut, Qureg out)
Definition: QuEST_cpu.c:3619
void statevec_initClassicalState(Qureg qureg, long long int stateInd)
Definition: QuEST_cpu.c:1470
int isDensityMatrix
Whether this instance is a density-state representation.
Definition: QuEST.h:206
void validateMatchingQuregTypes(Qureg qureg1, Qureg qureg2, const char *caller)
void validateSecondQuregStateVec(Qureg qureg2, const char *caller)
long long int numAmpsTotal
Total number of amplitudes, which are possibly distributed among machines.
Definition: QuEST.h:215
void densmatr_initPureState(Qureg targetQureg, Qureg copyQureg)