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 ![]() stateInd . More... | |
void | initPlusState (Qureg qureg) |
Initialise a set of ![]() ![]() ![]() | |
void | initPureState (Qureg qureg, Qureg pure) |
Initialise a set of ![]() | |
void | initStateFromAmps (Qureg qureg, qreal *reals, qreal *imags) |
Initialise qureg by specifying the complete statevector. More... | |
void | initZeroState (Qureg qureg) |
Initialise a set of ![]() ![]() | |
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()
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.
Definition at line 165 of file QuEST.c.
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
Definition at line 119 of file QuEST.c.
References qasm_recordComment(), and statevec_initBlankState().
Referenced by TEST_CASE().
◆ initClassicalState()
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
.
State-vectors will be initialised to , and density-matrices to
Classical states are indexed from zero, so that stateInd
= 0 produces , and
stateInd
= 1 produces , and
stateInd
= produces
. 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].
Definition at line 134 of file QuEST.c.
References densmatr_initClassicalState(), Qureg::isDensityMatrix, qasm_recordInitClassical(), statevec_initClassicalState(), and validateStateIndex().
Referenced by TEST_CASE().
◆ initPlusState()
void initPlusState | ( | Qureg | qureg | ) |
Initialise a set of qubits to the plus state
(and similarly
for density matrices).
This is the product state of qubits where every classical state is uniformly populated (with real coefficient
in the state-vector and
in the density-matrix). This is equivalent to applying a Hadamard to every qubit in the zero state:
- Parameters
-
[in,out] qureg the object representing the set of qubits to be initialised
Definition at line 125 of file QuEST.c.
References densmatr_initPlusState(), Qureg::isDensityMatrix, qasm_recordInitPlus(), and statevec_initPlusState().
Referenced by TEST_CASE().
◆ initPureState()
Initialise a set of 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
andpure
have mismatching dimensions, or ifpure
is a density matrix.
Definition at line 145 of file QuEST.c.
References densmatr_initPureState(), Qureg::isDensityMatrix, qasm_recordComment(), statevec_cloneQureg(), validateMatchingQuregDims(), and validateSecondQuregStateVec().
Referenced by TEST_CASE().
◆ initStateFromAmps()
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)
Definition at line 157 of file QuEST.c.
References Qureg::numAmpsTotal, qasm_recordComment(), statevec_setAmps(), and validateStateVecQureg().
Referenced by TEST_CASE().
◆ initZeroState()
void initZeroState | ( | Qureg | qureg | ) |
Initialise a set of qubits to the classical zero state
.
- Parameters
-
[in,out] qureg the object representing the set of all qubits to initialise
Definition at line 113 of file QuEST.c.
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 ifstartInd
is outside [0,qureg.numAmpsTotal
], or ifnumAmps
is outside [0,qureg.numAmpsTotal
], or ifnumAmps
+startInd
is >= qureg.numAmpsTotal.
Definition at line 781 of file QuEST.c.
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 iffacOut
is set to (Complex) {.real=0,.imag=0}[in,out] out the qureg to be modified, to be scaled by facOut
then havefac1
qureg1
andfac2
qureg2
added to it.
- Exceptions
-
invalidQuESTInputError if qureg1
,qureg2
andaren't
all state-vectors or all density matrices, or if the dimensions ofqureg1
,qureg2
andaren't
equal
Definition at line 797 of file QuEST.c.
References qasm_recordComment(), statevec_setWeightedQureg(), validateMatchingQuregDims(), and validateMatchingQuregTypes().
Referenced by TEST_CASE().