Calculations and property-getters which do not modify the studied quantum state. More...

Functions
qreal	calcDensityInnerProduct (Qureg rho1, Qureg rho2)
	Computes the Hilbert-Schmidt scalar product (which is equivalent to the Frobenius inner product of matrices) of two density matrices `rho1` and `rho2` of equivalent size. More...

Complex	calcExpecDiagonalOp (Qureg qureg, DiagonalOp op)
	Computes the expected value of the diagonal operator `op` for state `qureg`. More...

qreal	calcExpecPauliHamil (Qureg qureg, PauliHamil hamil, Qureg workspace)
	Computes the expected value of `qureg` under Hermitian operator `hamil`. More...

qreal	calcExpecPauliProd (Qureg qureg, int targetQubits, enum pauliOpType pauliCodes, int numTargets, Qureg workspace)
	Computes the expected value of a product of Pauli operators. More...

qreal	calcExpecPauliSum (Qureg qureg, enum pauliOpType allPauliCodes, qreal termCoeffs, int numSumTerms, Qureg workspace)
	Computes the expected value of a sum of products of Pauli operators. More...

qreal	calcFidelity (Qureg qureg, Qureg pureState)
	Calculates the fidelity of `qureg` (a statevector or density matrix) against a reference pure state (necessarily a statevector). More...

qreal	calcHilbertSchmidtDistance (Qureg a, Qureg b)
	Computes the Hilbert Schmidt distance between two density matrices `a` and `b`, defined as the Frobenius norm of the difference between them. More...

Complex	calcInnerProduct (Qureg bra, Qureg ket)
	Computes the inner product $\langle \text{bra} \| \text{ket} \rangle$ of two equal-size state vectors, given by. More...

qreal	calcProbOfOutcome (Qureg qureg, int measureQubit, int outcome)
	Gives the probability of a specified qubit being measured in the given outcome (0 or 1). More...

qreal	calcPurity (Qureg qureg)
	Calculates the purity of a density matrix, by the trace of the density matrix squared. More...

qreal	calcTotalProb (Qureg qureg)
	A debugging function which calculates the probability of the qubits in `qureg` being in any state, which should always be 1 for correctly normalised states (hence returning a real number). More...

Complex	getAmp (Qureg qureg, long long int index)
	Get the complex amplitude at a given index in the state vector. More...

Complex	getDensityAmp (Qureg qureg, long long int row, long long int col)
	Get an amplitude from a density matrix at a given row and column. More...

qreal	getImagAmp (Qureg qureg, long long int index)
	Get the imaginary component of the complex probability amplitude at an index in the state vector. More...

long long int	getNumAmps (Qureg qureg)
	Get the number of probability amplitudes in a qureg object, given by 2^numQubits. More...

int	getNumQubits (Qureg qureg)
	Get the number of qubits in a qureg object. More...

qreal	getProbAmp (Qureg qureg, long long int index)
	Get the probability of a state-vector at an index in the full state vector. More...

qreal	getRealAmp (Qureg qureg, long long int index)
	Get the real component of the complex probability amplitude at an index in the state vector. More...

Detailed Description

Calculations and property-getters which do not modify the studied quantum state.

Function Documentation

◆ calcDensityInnerProduct()

qreal calcDensityInnerProduct	(	Qureg	rho1,
		Qureg	rho2
	)

Computes the Hilbert-Schmidt scalar product (which is equivalent to the Frobenius inner product of matrices) of two density matrices rho1 and rho2 of equivalent size.

That is, we define the Hilbert-Schmidt scalar product

$((\rho_1, \rho_2))_{HS} := \text{Tr}[ \rho_1^\dagger \rho_2 ],$

which is equivalent to the sum of products of matrix elemets, i.e.,

$((\rho_1, \rho_2))_{HS} = \sum\limits_i \sum\limits_j (\rho_1)_{ij}^* (\rho_2)_{ij}$

Assuming that both density matrices are Hermitian, the resulting scalar product is real and invariant under reordering its arguments as

$((\rho_1, \rho_2))_{HS} = ((\rho_2, \rho_1))_{HS} = \text{Tr}[\rho_1 \rho_2]$

If both rho1 and rho2 are density matrices of pure states bra and ket, then the equality holds

$((\rho_1, \rho_2))_{HS} = |\langle \text{bra} | \text{ket} \rangle|^2.$

If either or both of rho1 and rho2 are non Hermitian (i.e. invalid density matrices), then this function returns the real component of the scalar product, and discards the imaginary component. That is, it returns

$\text{Re}\{ \text{Tr}[ \rho_1^\dagger \rho_2 ] \} = \text{Re}\{ \text{Tr}[ \rho_2^\dagger \rho_1 ] \}.$

This is still sometimes useful, e.g. in calculating the inner product with an anti-commutator, e.g. (for Hermitian $\sigma$ , $\rho$ , $ H $ )

$((\sigma, H \rho + \rho H))_{HS} = 2 \; \text{Re} \{ ((\sigma, H \rho))_{HS} \}$

where $H \rho$ could be a weighted sum of Pauli products applied to $\rho$ through applyPauliSum().

Parameters

[in]	rho1	qureg as a density matrix (to have its values conjugate transposed)
[in]	rho2	qureg as a density matrix

Returns: the real Hilbert-Schmidt scalar product of density matrices rho1 and rho2 (assuming Hermiticity)

Exceptions

invalidQuESTInputError if rho1 and rho2 are not density matrices or have mismatching dimensions.

Author: Balint Koczor (CPU); Tyson Jones (GPU)

Definition at line 918 of file QuEST.c.

                                                       {
     validateDensityMatrQureg(rho1, __func__);
     validateDensityMatrQureg(rho2, __func__);
     validateMatchingQuregDims(rho1, rho2, __func__);
     
     return densmatr_calcInnerProduct(rho1, rho2);
 }

References densmatr_calcInnerProduct(), validateDensityMatrQureg(), and validateMatchingQuregDims().

Referenced by TEST_CASE().

◆ calcExpecDiagonalOp()

Complex calcExpecDiagonalOp	(	Qureg	qureg,
		DiagonalOp	op
	)

Computes the expected value of the diagonal operator op for state qureg.

Since op is not necessarily Hermitian, the expected value may be a complex number.

Let $ D $ be the diagonal operator op, with diagonal elements $ d_i $ . Then if qureg is a state-vector $|\psi\rangle$ , this function computes

$\langle \psi | D | \psi \rangle = \sum_i |\psi_i|^2 \, d_i$

If qureg is a density matrix $\rho$ , this function computes

$\text{Trace}( D \rho ) = \sum_i \rho_{ii} \, d_i$

Parameters

[in]	qureg	a state-vector or density matrix
[in]	op	the diagonal operator to compute the expected value of

Returns: the expected vaulue of the operator

Exceptions

invalidQuESTInputError if op was not created, or if op acts on a different number of qubits than qureg represents.

Author: Tyson Jones

Definition at line 979 of file QuEST.c.

                                                         {
     validateDiagonalOp(qureg, op, __func__);
     
     if (qureg.isDensityMatrix)
         return densmatr_calcExpecDiagonalOp(qureg, op);
     else
         return statevec_calcExpecDiagonalOp(qureg, op);
 }

References densmatr_calcExpecDiagonalOp(), Qureg::isDensityMatrix, statevec_calcExpecDiagonalOp(), and validateDiagonalOp().

Referenced by TEST_CASE().

◆ calcExpecPauliHamil()

qreal calcExpecPauliHamil	(	Qureg	qureg,
		PauliHamil	hamil,
		Qureg	workspace
	)

Computes the expected value of qureg under Hermitian operator hamil.

Represent hamil as $H = \sum_i c_i \otimes_j^{N} \hat{\sigma}_{i,j}$ (where $c_i \in$ hamil.termCoeffs and $ N = $ hamil.numQubits). This function computes $\langle \psi | H | \psi \rangle$ if qureg = $\psi$ is a statevector, and computes $\text{Trace}(H \rho) =\text{Trace}(\rho H)$ if qureg = $\rho$ is a density matrix.

This function is merely an encapsulation of calcExpecPauliSum() - refer to the doc there for an elaboration.

workspace must be a register with the same type (statevector vs density matrix) and dimensions (number of represented qubits) as qureg and hamil, and is used as working space. When this function returns, qureg will be unchanged and workspace will be set to qureg pre-multiplied with the final Pauli product in hamil. NOTE that if qureg is a density matrix, workspace will become $\hat{\sigma} \rho$ which is itself not a density matrix (it is distinct from $\hat{\sigma} \rho \hat{\sigma}^\dagger$ ).

This function works by cloning the qureg state into workspace, applying each of the specified Pauli products in hamil to workspace (one Pauli operation at a time), then computing its inner product with qureg (for statevectors) or its trace (for density matrices) multiplied with the corresponding coefficient, and summing these contributions. It therefore should scale linearly in time with the total number of non-identity specified Pauli operators.

Parameters

[in]	qureg	the register of which to find the expected value, which is unchanged by this function
[in]	hamil	a `PauliHamil` created with createPauliHamil() or createPauliHamilFromFile()
[in,out]	workspace	a working-space qureg with the same dimensions as `qureg`, which is modified to be the result of multiplying the state with the final specified Pauli product

Exceptions

invalidQuESTInputError if any code in hamil.pauliCodes is not a valid Pauli code, or if hamil.numSumTerms <= 0, or if workspace is not of the same type and dimensions as qureg and hamil

Author: Tyson Jones

Definition at line 970 of file QuEST.c.

                                                                           {
     validateMatchingQuregTypes(qureg, workspace, __func__);
     validateMatchingQuregDims(qureg, workspace, __func__);
     validatePauliHamil(hamil, __func__);
     validateMatchingQuregPauliHamilDims(qureg, hamil, __func__);
     
     return statevec_calcExpecPauliSum(qureg, hamil.pauliCodes, hamil.termCoeffs, hamil.numSumTerms, workspace);
 }

References PauliHamil::numSumTerms, PauliHamil::pauliCodes, statevec_calcExpecPauliSum(), PauliHamil::termCoeffs, validateMatchingQuregDims(), validateMatchingQuregPauliHamilDims(), validateMatchingQuregTypes(), and validatePauliHamil().

Referenced by TEST_CASE().

◆ calcExpecPauliProd()

qreal calcExpecPauliProd	(	Qureg	qureg,
		int *	targetQubits,
		enum pauliOpType *	pauliCodes,
		int	numTargets,
		Qureg	workspace
	)

Computes the expected value of a product of Pauli operators.

Letting $\sigma = \otimes_j \hat{\sigma}_j$ be the operators indicated by pauliCodes and acting on qubits targetQubits, this function computes $\langle \psi | \sigma | \psi \rangle$ if qureg = $\psi$ is a statevector, and computes $\text{Trace}(\sigma \rho)$ if qureg = $\rho$ is a density matrix.

pauliCodes is an array of length numTargets which specifies which Pauli operators to enact on the corresponding qubits in targetQubits, where 0 = PAULI_I, 1 = PAULI_X, 2 = PAULI_Y, 3 = PAULI_Z. The target qubits must be unique, and at most qureg.numQubitsRepresented may be specified. For example, on a 7-qubit statevector,

calcExpecPauliProd(qureg, {4,5,6}, {PAULI_X, PAULI_I, PAULI_Z}, 3, workspace);

will compute $\langle \psi | I I I I X I Z | \psi \rangle$ (where in this notation, the left-most operator applies to the least-significant qubit, i.e. that with index 0).

workspace must be a register with the same type (statevector vs density matrix) and dimensions (number of represented qubits) as qureg, and is used as working space. When this function returns, qureg will be unchanged and workspace will be set to $\sigma | \psi \rangle$ (if qureg is a statevector) or $\sigma \rho$ (if qureg is a density matrix). NOTE that this last quantity is NOT the result of applying the paulis as unitaries, $\sigma^\dagger \rho \sigma$ , but is instead the result of their direct multiplication with the density matrix. It is therefore itself not a valid density matrix.

This function works by cloning the qureg state into workspace, applying the specified Pauli operators to workspace then computing its inner product with qureg (for statevectors) or its trace (for density matrices). It therefore should scale linearly in time with the number of specified non-identity Pauli operators, which is bounded by the number of represented qubits.

Parameters

[in]	qureg	the register of which to find the expected value, which is unchanged by this function
[in]	targetQubits	a list of the indices of the target qubits
[in]	pauliCodes	a list of the Pauli codes (0=PAULI_I, 1=PAULI_X, 2=PAULI_Y, 3=PAULI_Z) to apply to the corresponding qubits in `targetQubits`
[in]	numTargets	number of target qubits, i.e. the length of `targetQubits` and `pauliCodes`
[in,out]	workspace	a working-space qureg with the same dimensions as `qureg`, which is modified to be the result of multiplying the state with the pauli operators

Exceptions

invalidQuESTInputError if numTargets is outside [1, qureg.numQubitsRepresented]), or if any qubit in targetQubits is outside [0, qureg.numQubitsRepresented)) or if any qubit in targetQubits is repeated, or if any code in pauliCodes is not in {0,1,2,3}, or if workspace is not of the same type and dimensions as qureg

Author: Tyson Jones

Definition at line 952 of file QuEST.c.

                                                                                                                         {
     validateMultiTargets(qureg, targetQubits, numTargets, __func__);
     validatePauliCodes(pauliCodes, numTargets, __func__);
     validateMatchingQuregTypes(qureg, workspace, __func__);
     validateMatchingQuregDims(qureg, workspace, __func__);
     
     return statevec_calcExpecPauliProd(qureg, targetQubits, pauliCodes, numTargets, workspace);
 }

References statevec_calcExpecPauliProd(), validateMatchingQuregDims(), validateMatchingQuregTypes(), validateMultiTargets(), and validatePauliCodes().

Referenced by TEST_CASE().

◆ calcExpecPauliSum()

qreal calcExpecPauliSum	(	Qureg	qureg,
		enum pauliOpType *	allPauliCodes,
		qreal *	termCoeffs,
		int	numSumTerms,
		Qureg	workspace
	)

Computes the expected value of a sum of products of Pauli operators.

Let $H = \sum_i c_i \otimes_j^{N} \hat{\sigma}_{i,j}$ be the operators indicated by allPauliCodes (where $c_i \in$ termCoeffs and $ N = $ qureg.numQubitsRepresented). This function computes $\langle \psi | H | \psi \rangle$ if qureg = $\psi$ is a statevector, and computes $\text{Trace}(H \rho) =\text{Trace}(\rho H)$ if qureg = $\rho$ is a density matrix.

allPauliCodes is an array of length numSumTerms*qureg.numQubitsRepresented which specifies which Pauli operators to apply, where 0 = PAULI_I, 1 = PAULI_X, 2 = PAULI_Y, 3 = PAULI_Z. For each sum term, a Pauli operator must be specified for EVERY qubit in qureg; each set of numSumTerms operators will be grouped into a product. termCoeffs is an arrray of length numSumTerms containing the term coefficients. For example, on a 3-qubit statevector,

int paulis[6] = {PAULI_X, PAULI_I, PAULI_I,  PAULI_X, PAULI_Y, PAULI_Z};
qreal coeffs[2] = {1.5, -3.6};
calcExpecPauliSum(qureg, paulis, coeffs, 2, workspace);

will compute $\langle \psi | (1.5 X I I - 3.6 X Y Z) | \psi \rangle$ (where in this notation, the left-most operator applies to the least-significant qubit, i.e. that with index 0).

workspace must be a register with the same type (statevector vs density matrix) and dimensions (number of represented qubits) as qureg, and is used as working space. When this function returns, qureg will be unchanged and workspace will be set to qureg pre-multiplied with the final Pauli product. NOTE that if qureg is a density matrix, workspace will become $\hat{\sigma} \rho$ which is itself not a density matrix (it is distinct from $\hat{\sigma} \rho \hat{\sigma}^\dagger$ ).

This function works by cloning the qureg state into workspace, applying each of the specified Pauli products to workspace (one Pauli operation at a time), then computing its inner product with qureg (for statevectors) or its trace (for density matrices) multiplied with the corresponding coefficient, and summing these contributions. It therefore should scale linearly in time with the total number of non-identity specified Pauli operators.

Parameters

[in]	qureg	the register of which to find the expected value, which is unchanged by this function
[in]	allPauliCodes	a list of the Pauli codes (0=PAULI_I, 1=PAULI_X, 2=PAULI_Y, 3=PAULI_Z) of all Paulis involved in the products of terms. A Pauli must be specified for each qubit in the register, in every term of the sum.
[in]	termCoeffs	The coefficients of each term in the sum of Pauli products
[in]	numSumTerms	The total number of Pauli products specified
[in,out]	workspace	a working-space qureg with the same dimensions as `qureg`, which is modified to be the result of multiplying the state with the final specified Pauli product

Exceptions

invalidQuESTInputError if any code in allPauliCodes is not in {0,1,2,3}, or if numSumTerms <= 0, or if workspace is not of the same type and dimensions as qureg

Author: Tyson Jones

Definition at line 961 of file QuEST.c.

                                                                                                                            {
     validateNumPauliSumTerms(numSumTerms, __func__);
     validatePauliCodes(allPauliCodes, numSumTerms*qureg.numQubitsRepresented, __func__);
     validateMatchingQuregTypes(qureg, workspace, __func__);
     validateMatchingQuregDims(qureg, workspace, __func__);
     
     return statevec_calcExpecPauliSum(qureg, allPauliCodes, termCoeffs, numSumTerms, workspace);
 }

References Qureg::numQubitsRepresented, statevec_calcExpecPauliSum(), validateMatchingQuregDims(), validateMatchingQuregTypes(), validateNumPauliSumTerms(), and validatePauliCodes().

Referenced by TEST_CASE().

◆ calcFidelity()

qreal calcFidelity	(	Qureg	qureg,
		Qureg	pureState
	)

Calculates the fidelity of qureg (a statevector or density matrix) against a reference pure state (necessarily a statevector).

If qureg is a state-vector, this function computes

$|\langle \text{qureg} | \text{pureState} \rangle|^2$

If qureg is a density matrix, this function computes

$\langle \text{pureState} | \text{qureg} | \text{pureState} \rangle$

In either case, the returned fidelity lies in [0, 1] (assuming both input states have valid normalisation). If any of the input Quregs are not normalised, this function will return the real component of the correct linear algebra calculation.

The number of qubits represented in qureg and pureState must match.

Parameters

[in]	qureg	a density matrix or state vector
[in]	pureState	a state vector

Returns: the fidelity between the input registers

Exceptions

invalidQuESTInputError if the second argument (pureState) is not a statevector, or if the number of qubits in qureg and pureState do not match

Author: Tyson Jones

Definition at line 942 of file QuEST.c.

                                                  {
     validateSecondQuregStateVec(pureState, __func__);
     validateMatchingQuregDims(qureg, pureState, __func__);
     
     if (qureg.isDensityMatrix)
         return densmatr_calcFidelity(qureg, pureState);
     else
         return statevec_calcFidelity(qureg, pureState);
 }

References densmatr_calcFidelity(), Qureg::isDensityMatrix, statevec_calcFidelity(), validateMatchingQuregDims(), and validateSecondQuregStateVec().

Referenced by TEST_CASE().

◆ calcHilbertSchmidtDistance()

qreal calcHilbertSchmidtDistance	(	Qureg	a,
		Qureg	b
	)

Computes the Hilbert Schmidt distance between two density matrices a and b, defined as the Frobenius norm of the difference between them.

That is, we define the Hilbert Schmidt distance

$D(a, b) = \| a - b \|_F = \sqrt{ \text{Tr}[ (a-b)(a-b)^\dagger ] }$

This is equivalent to the square-root of the sum of the absolute value squared of the element-differences of the matrices, i.e.

$D(a, b) = \sqrt{ \sum\limits_i \sum\limits_j | a_{ij} - b_{ij} |^2 }$

We caution this may differ by some definitions of the Hilbert Schmidt distance by a square-root.

This function correctly returns the result of the above formulations even when a and b are incorrectly normalised (i.e. are general matrices).

Parameters

[in]	a	a density matrix
[in]	b	an equally-sized density matrix

Exceptions

invalidQuESTInputError if either a or b are not density matrices, or if a and have mismatching dimensions.

Author: Balint Koczor; Tyson Jones (refactored, doc)

Definition at line 988 of file QuEST.c.

                                                    {
     validateDensityMatrQureg(a, __func__);
     validateDensityMatrQureg(b, __func__);
     validateMatchingQuregDims(a, b, __func__);
     
     return densmatr_calcHilbertSchmidtDistance(a, b);
 }

References densmatr_calcHilbertSchmidtDistance(), validateDensityMatrQureg(), and validateMatchingQuregDims().

Referenced by TEST_CASE().

◆ calcInnerProduct()

Complex calcInnerProduct	(	Qureg	bra,
		Qureg	ket
	)

Computes the inner product $\langle \text{bra} | \text{ket} \rangle$ of two equal-size state vectors, given by.

$\langle \text{bra} | \text{ket} \rangle = \sum_i {\text{bra}_i}^* \; \times \; \text{ket}_i$

The same qureg may be passed as both bra and ket, though we recommend users check state-vector normalisation with calcTotalProb which employs Kahan summation for greater accuracy. Neither state-vector is modified.

This function returns the correct inner product even if bra and ket are not correctly normalised states.

Parameters

[in]	bra	qureg to be the 'bra' (i.e. have its values conjugate transposed) in the inner product
[in]	ket	qureg to be the 'ket' in the inner product

Returns: the complex inner product of bra and ket

Exceptions

invalidQuESTInputError if either bra or ket are not state-vectors, or if bra and ket do not have equal dimensions.

Author: Tyson Jones

Definition at line 910 of file QuEST.c.

                                                {
     validateStateVecQureg(bra, __func__);
     validateStateVecQureg(ket, __func__);
     validateMatchingQuregDims(bra, ket,  __func__);
     
     return statevec_calcInnerProduct(bra, ket);
 }

References statevec_calcInnerProduct(), validateMatchingQuregDims(), and validateStateVecQureg().

Referenced by TEST_CASE().

◆ calcProbOfOutcome()

qreal calcProbOfOutcome	(	Qureg	qureg,
		int	measureQubit,
		int	outcome
	)

Gives the probability of a specified qubit being measured in the given outcome (0 or 1).

This performs no actual measurement and does not change the state of the qubits.

For state-vectors, this function works by summing the absolute-value-squared of every amplitude in the state-vector for which measureQubit = 0. If outcome = 1, it returns 1 minus this value. Hence for unnormalised state-vectors, this result will differ from the absolute-value-squared of every amplitude where measureQubit = outcome.

For density matrices, this function sums the diagonal values (should be real) corresponding to measureQubit = 0 (returning 1 minus this if outcome = 1).

Parameters

[in]	qureg	object representing the set of all qubits
[in]	measureQubit	qubit to study
[in]	outcome	for which to find the probability of the qubit being measured in

Returns: probability of qubit measureQubit being measured in the given outcome

Exceptions

invalidQuESTInputError if measureQubit is outside [0, qureg.numQubitsRepresented), or if outcome is not in {0, 1}.

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

Definition at line 926 of file QuEST.c.

                                                                     {
     validateTarget(qureg, measureQubit, __func__);
     validateOutcome(outcome, __func__);
     
     if (qureg.isDensityMatrix)
         return densmatr_calcProbOfOutcome(qureg, measureQubit, outcome);
     else
         return statevec_calcProbOfOutcome(qureg, measureQubit, outcome);
 }

References densmatr_calcProbOfOutcome(), Qureg::isDensityMatrix, statevec_calcProbOfOutcome(), validateOutcome(), and validateTarget().

Referenced by TEST_CASE().

◆ calcPurity()

qreal calcPurity ( Qureg qureg )

Calculates the purity of a density matrix, by the trace of the density matrix squared.

Returns $\text{Tr}(\rho^2)$ . For a pure state, this =1. For a mixed state, the purity is less than 1 and is lower bounded by 1/2^n, where n is the number of qubits. The minimum purity is achieved for the maximally mixed state identity/2^n.

This function does not accept state-vectors, which clearly have purity 1.

Note this function will give incorrect results for non-Hermitian Quregs (i.e. invalid density matrices), which will disagree with $\text{Tr}(\rho^2)$ . Instead, this function returns $\sum_{ij} |\rho_{ij}|^2$ .

Parameters

[in] qureg a density matrix of which to measure the purity

Returns: the purity

Exceptions

invalidQuESTInputError if either combineQureg or otherQureg are not density matrices, or if the dimensions of combineQureg and otherQureg do not match, or if prob is not in [0, 1]

Author: Tyson Jones

Definition at line 936 of file QuEST.c.

                               {
     validateDensityMatrQureg(qureg, __func__);
     
     return densmatr_calcPurity(qureg);
 }

References densmatr_calcPurity(), and validateDensityMatrQureg().

Referenced by TEST_CASE().

◆ calcTotalProb()

qreal calcTotalProb ( Qureg qureg )

A debugging function which calculates the probability of the qubits in qureg being in any state, which should always be 1 for correctly normalised states (hence returning a real number).

For state-vectors $\psi$ , this is the norm of the entire state-vector (the sum of the absolute-value-squared of every amplitude):

$\sum\limits_i |\psi_i|^2$

and for density matrices $\rho$ , it is the trace:

$\text{Trace}(\rho) = \sum\limits_i \rho_{i,i} \;$

For un-normalised density matrices (those directly modified or initialised by the user), this function returns the real component of the trace.

Note this calculation utilises Kahan summation for greater accuracy, and hence is not parallelised and so will be slower than other functions.

Parameters

[in] qureg object representing a set of qubits

Returns: the total probability of the qubits in qureg being in any state

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

Definition at line 903 of file QuEST.c.

                                  {
     if (qureg.isDensityMatrix)  
             return densmatr_calcTotalProb(qureg);
         else
             return statevec_calcTotalProb(qureg);
 }

References densmatr_calcTotalProb(), Qureg::isDensityMatrix, and statevec_calcTotalProb().

Referenced by TEST_CASE().

◆ getAmp()

Complex getAmp	(	Qureg	qureg,
		long long int	index
	)

Get the complex amplitude at a given index in the state vector.

Parameters

[in]	qureg	object representing a set of qubits
[in]	index	index in state vector of probability amplitudes

Returns: amplitude at index, returned as a Complex struct (with .real and .imag attributes)

Exceptions

invalidQuESTInputError if qureg is a density matrix, or if index is outside [0, $2^{N}$ ) where qureg.numQubitsRepresented

Author: Tyson Jones

Definition at line 699 of file QuEST.c.

                                                  {
     validateStateVecQureg(qureg, __func__);
     validateAmpIndex(qureg, index, __func__);
     
     Complex amp;
     amp.real = statevec_getRealAmp(qureg, index);
     amp.imag = statevec_getImagAmp(qureg, index);
     return amp;
 }

References Complex::imag, Complex::real, statevec_getImagAmp(), statevec_getRealAmp(), validateAmpIndex(), and validateStateVecQureg().

Referenced by TEST_CASE().

◆ getDensityAmp()

Complex getDensityAmp	(	Qureg	qureg,
		long long int	row,
		long long int	col
	)

Get an amplitude from a density matrix at a given row and column.

Parameters

[in]	qureg	object representing a density matrix
[in]	row	row of the desired amplitude in the density matrix
[in]	col	column of the desired amplitude in the density matrix

Returns: a Complex scalar representing the desired amplitude

Exceptions

invalidQuESTInputError if qureg is a statevector, or if row or col are outside [0, $2^{N}$ ) where qureg.numQubitsRepresented

Author: Tyson Jones

Definition at line 709 of file QuEST.c.

                                                                          {
     validateDensityMatrQureg(qureg, __func__);
     validateAmpIndex(qureg, row, __func__);
     validateAmpIndex(qureg, col, __func__);
     
     long long ind = row + col*(1LL << qureg.numQubitsRepresented);
     Complex amp;
     amp.real = statevec_getRealAmp(qureg, ind);
     amp.imag = statevec_getImagAmp(qureg, ind);
     return amp;
 }

References Qureg::numQubitsRepresented, Complex::real, statevec_getImagAmp(), statevec_getRealAmp(), validateAmpIndex(), and validateDensityMatrQureg().

Referenced by TEST_CASE().

◆ getImagAmp()

qreal getImagAmp	(	Qureg	qureg,
		long long int	index
	)

Get the imaginary component of the complex probability amplitude at an index in the state vector.

Parameters

[in]	qureg	object representing a set of qubits
[in]	index	index in state vector of probability amplitudes

Returns: imaginary component at that index

Exceptions

invalidQuESTInputError if qureg is a density matrix, or if index is outside [0, $2^{N}$ ) where qureg.numQubitsRepresented

Author: Ania Brown

Definition at line 685 of file QuEST.c.

                                                    {
     validateStateVecQureg(qureg, __func__);
     validateAmpIndex(qureg, index, __func__);
     
     return statevec_getImagAmp(qureg, index);
 }

References statevec_getImagAmp(), validateAmpIndex(), and validateStateVecQureg().

Referenced by TEST_CASE().

◆ getNumAmps()

long long int getNumAmps ( Qureg qureg )

Get the number of probability amplitudes in a qureg object, given by 2^numQubits.

Author: Tyson Jones

Definition at line 672 of file QuEST.c.

                                       {
     validateStateVecQureg(qureg, __func__);
     
     return qureg.numAmpsTotal;
 }

References Qureg::numAmpsTotal, and validateStateVecQureg().

Referenced by TEST_CASE().

◆ getNumQubits()

int getNumQubits ( Qureg qureg )

Get the number of qubits in a qureg object.

Author: Tyson Jones

Definition at line 668 of file QuEST.c.

                               {
     return qureg.numQubitsRepresented;
 }

References Qureg::numQubitsRepresented.

Referenced by TEST_CASE().

◆ getProbAmp()

qreal getProbAmp	(	Qureg	qureg,
		long long int	index
	)

Get the probability of a state-vector at an index in the full state vector.

Parameters

[in]	qureg	object representing a set of qubits
[in]	index	index in state vector of probability amplitudes

Returns: realEl*realEl + imagEl*imagEl

Exceptions

invalidQuESTInputError if qureg is a density matrix, or if index is outside [0, $2^{N}$ ) where qureg.numQubitsRepresented

Author: Ania Brown

Definition at line 692 of file QuEST.c.

                                                    {
     validateStateVecQureg(qureg, __func__);
     validateAmpIndex(qureg, index, __func__);
     
     return statevec_getProbAmp(qureg, index);
 }

References statevec_getProbAmp(), validateAmpIndex(), and validateStateVecQureg().

Referenced by TEST_CASE().

◆ getRealAmp()

qreal getRealAmp	(	Qureg	qureg,
		long long int	index
	)

Get the real component of the complex probability amplitude at an index in the state vector.

Parameters

[in]	qureg	object representing a set of qubits
[in]	index	index in state vector of probability amplitudes

Returns: real component at that index

Exceptions

invalidQuESTInputError if qureg is a density matrix, or if index is outside [0, $2^{N}$ ) where qureg.numQubitsRepresented

Author: Ania Brown

Definition at line 678 of file QuEST.c.

                                                    {
     validateStateVecQureg(qureg, __func__);
     validateAmpIndex(qureg, index, __func__);
     
     return statevec_getRealAmp(qureg, index);
 }

References statevec_getRealAmp(), validateAmpIndex(), and validateStateVecQureg().

Referenced by TEST_CASE().

Functions

Detailed Description

Function Documentation

◆ calcDensityInnerProduct()

◆ calcExpecDiagonalOp()

◆ calcExpecPauliHamil()

◆ calcExpecPauliProd()

◆ calcExpecPauliSum()

◆ calcFidelity()

◆ calcHilbertSchmidtDistance()

◆ calcInnerProduct()

◆ calcProbOfOutcome()

◆ calcPurity()

◆ calcTotalProb()

◆ getAmp()

◆ getDensityAmp()

◆ getImagAmp()

◆ getNumAmps()

◆ getNumQubits()

◆ getProbAmp()

◆ getRealAmp()