Functions for calculating expected values of Hermitian observables. More...

Functions
qreal	calcExpecFullStateDiagMatr (Qureg qureg, FullStateDiagMatr matr)

qreal	calcExpecFullStateDiagMatrPower (Qureg qureg, FullStateDiagMatr matr, qreal exponent)

qcomp	calcExpecNonHermitianFullStateDiagMatr (Qureg qureg, FullStateDiagMatr matr)

qcomp	calcExpecNonHermitianFullStateDiagMatrPower (Qureg qureg, FullStateDiagMatr matrix, qcomp exponent)

qcomp	calcExpecNonHermitianPauliStrSum (Qureg qureg, PauliStrSum sum)

qreal	calcExpecPauliStr (Qureg qureg, PauliStr str)

qreal	calcExpecPauliStrSum (Qureg qureg, PauliStrSum sum)

Detailed Description

Functions for calculating expected values of Hermitian observables.

Function Documentation

◆ calcExpecFullStateDiagMatr()

qreal calcExpecFullStateDiagMatr	(	Qureg	qureg,
		FullStateDiagMatr	matr )

Note: Documentation for this function or struct is under construction!

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 161 of file calculations.cpp.

                                                                        {
    validate_quregFields(qureg, __func__);
    validate_matrixFields(matrix, __func__);
    validate_matrixAndQuregAreCompatible(matrix, qureg, true, __func__);
    validate_matrixIsHermitian(matrix, __func__);
 
    // unused parameters; see calcExpecFullStateDiagMatrPower() for explanation
    qcomp exponent = qcomp(1,0);
    bool useRealPow = false;
 
    qcomp value = (qureg.isDensityMatrix)?
        localiser_densmatr_calcExpecFullStateDiagMatr(qureg, matrix, exponent, useRealPow):
        localiser_statevec_calcExpecFullStateDiagMatr(qureg, matrix, exponent, useRealPow);
 
    // the sub-epsilon imaginary components in matrix never damage the real
    // component of the statevector expectation value, so we do not validate
    // imag(value)~0; we can always safely discard it, and only validate for densmatr:
    if (qureg.isDensityMatrix)
        validate_densMatrExpecDiagMatrValueIsReal(value, exponent, __func__);
 
    return std::real(value);
}

Referenced by TEST_CASE().

◆ calcExpecFullStateDiagMatrPower()

qreal calcExpecFullStateDiagMatrPower	(	Qureg	qureg,
		FullStateDiagMatr	matr,
		qreal	exponent )

Note: Documentation for this function or struct is under construction!

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 185 of file calculations.cpp.

                                                                                             {
    validate_quregFields(qureg, __func__);
    validate_matrixFields(matrix, __func__);
    validate_matrixAndQuregAreCompatible(matrix, qureg, true, __func__);
    validate_matrixExpIsHermitian(matrix, exponent, __func__);
 
    // the backend can use either the pow(qcomp,qcomp) or pow(qreal,qreal) overload;
    // the former is significantly less accurate when the base is real & negative and
    // the exponent is real, because complex pow(a,b) = exp(i b Arg(a)) = exp(i b 2 pi),
    // and the numerical error in pi is compounded by the exponent and the exp(). Because
    // this function assumes approx/intended Hermiticity, it will always use the real-pow
    // overload, discarding the imaginary components of 'matrix' during computation - this
    // is a behaviour unique to this function (other functions collect the erroneous
    // imaginary components before a final validation and discarding).
    const bool useRealPow = true;
 
    qcomp value = (qureg.isDensityMatrix)?
        localiser_densmatr_calcExpecFullStateDiagMatr(qureg, matrix, exponent, useRealPow):
        localiser_statevec_calcExpecFullStateDiagMatr(qureg, matrix, exponent, useRealPow);
 
    // is it impossible for the statevector routine to produce non-zero
    // imaginary components because of our use of real-pow, the result of
    // which is multiplied by abs(amp). Alas, density matrices multiply the
    // result with a complex scalar and can accrue erroneous imaginary
    // components when the density matrix is non-Hermitian, or due to rounding
    // errors. As such, we only post-validate density matrix values.
    if (qureg.isDensityMatrix)
        validate_densMatrExpecDiagMatrValueIsReal(value, exponent, __func__);
 
    return std::real(value);
}

Referenced by TEST_CASE().

◆ calcExpecNonHermitianFullStateDiagMatr()

qcomp calcExpecNonHermitianFullStateDiagMatr	(	Qureg	qureg,
		FullStateDiagMatr	matr )

Note: Documentation for this function or struct is under construction!

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 85 of file calculations.cpp.

                                                                                    {
    validate_quregFields(qureg, __func__);
    validate_matrixFields(matrix, __func__);
    validate_matrixAndQuregAreCompatible(matrix, qureg, true, __func__);
 
    return calcExpecNonHermitianFullStateDiagMatrPower(qureg, matrix, 1); // harmlessly re-validates
}

Referenced by TEST_CASE().

◆ calcExpecNonHermitianFullStateDiagMatrPower()

qcomp calcExpecNonHermitianFullStateDiagMatrPower	(	Qureg	qureg,
		FullStateDiagMatr	matrix,
		qcomp	exponent )

Note: Documentation for this function or struct is under construction!

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 98 of file calculations.cpp.

                                                                                                         {
    validate_quregFields(qureg, __func__);
    validate_matrixFields(matrix, __func__);
    validate_matrixAndQuregAreCompatible(matrix, qureg, true, __func__);
 
    // this function never uses the qreal-pow overload (because we make
    // no assumption matrix is Hermitian i.e. real), and instead always
    // uses the relatively numerically inaccurate qcomp overload
    const bool useRealPow = false;
 
    return (qureg.isDensityMatrix)?
        localiser_densmatr_calcExpecFullStateDiagMatr(qureg, matrix, exponent, useRealPow):
        localiser_statevec_calcExpecFullStateDiagMatr(qureg, matrix, exponent, useRealPow);
}

Referenced by calcExpecNonHermitianFullStateDiagMatr(), and TEST_CASE().

◆ calcExpecNonHermitianPauliStrSum()

qcomp calcExpecNonHermitianPauliStrSum	(	Qureg	qureg,
		PauliStrSum	sum )

Note: Documentation for this function or struct is under construction!

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Definition at line 68 of file calculations.cpp.

                                                                     {
    validate_quregFields(qureg, __func__);
    validate_pauliStrSumFields(sum, __func__);
    validate_pauliStrSumTargets(sum, qureg, __func__);
 
    qcomp value = (qureg.isDensityMatrix)?
        localiser_densmatr_calcExpecPauliStrSum(qureg, sum):
        localiser_statevec_calcExpecPauliStrSum(qureg, sum);
 
    return value;
}

Referenced by TEST_CASE().

◆ calcExpecPauliStr()

qreal calcExpecPauliStr	(	Qureg	qureg,
		PauliStr	str )

Calculates the expectation value of the given Pauli string observable str under the given state qureg without modifying it.

Formulae

Let \( \pstr = \) str.

When qureg is a statevector \(\svpsi\), this function returns
\[ \brapsi \pstr \svpsi \in \mathbb{R}. \]
When qureg is a density matrix \(\dmrho\), this function returns the real component of
\[ \tr{ \pstr \dmrho } \]
which is exact when \(\dmrho\) is physical (specifically Hermitian).

Constraints

The returned value is always real, even when qureg is an unnormalised density matrix, in which case the imaginary component of the above expression is neglected. The full complex value can be obtained using calcExpecNonHermitianPauliStrSum().

Equivalences

When str is general, this function is equivalent to calling calcExpecPauliStrSum() with a PauliStrSum composed of only a single PauliStr term and a unity coefficient.
When str \( = \id^\otimes \), the output is equivalent to that of calcTotalProb().

Example: Qureg qureg = createQureg(10);

initRandomPureState(qureg);

PauliStr str = getInlinePauliStr("XYZ", {0,2,3});

qreal expec = calcExpecPauliStr(qureg, str);

reportScalar("expec", expec);

calcExpecPauliStr
qreal calcExpecPauliStr(Qureg qureg, PauliStr str)
Definition calculations.cpp:133

initRandomPureState
void initRandomPureState(Qureg qureg)
Definition initialisations.cpp:121

getInlinePauliStr
PauliStr getInlinePauliStr(const char *paulis, { list })

createQureg
Qureg createQureg(int numQubits)
Definition qureg.cpp:282

reportScalar
void reportScalar(const char *label, qcomp num)
Definition types.cpp:51

PauliStr
Definition paulis.h:53

Qureg
Definition qureg.h:49

See also

calcExpecPauliStrSum()
calcExpecFullStateDiagMatr()

Parameters

[in]	qureg	the reference state.
[in]	str	the observable operator.

Returns: The real component of the expectation value.

Exceptions

error

if qureg is uninitialised.
if str contains a (non-identity) Pauli upon a higher-index qubit than exists in qureg.
if the output (with unreturned imaginary component) is not approximately real.

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

Author: Tyson Jones

Definition at line 133 of file calculations.cpp.

                                                   {
    validate_quregFields(qureg, __func__);
    validate_pauliStrTargets(qureg, str, __func__);
 
    qcomp value = (qureg.isDensityMatrix)?
        localiser_densmatr_calcExpecPauliStr(qureg, str):
        localiser_statevec_calcExpecPauliStr(qureg, str);
 
    validate_expecPauliStrValueIsReal(value, qureg.isDensityMatrix, __func__);
    return std::real(value);
}

Referenced by TEST_CASE().

◆ calcExpecPauliStrSum()

qreal calcExpecPauliStrSum	(	Qureg	qureg,
		PauliStrSum	sum )

Calculates the expectation value of the given Hermitian observable sum - a weighted sum of Pauli strings - under the given state qureg, without modifying it.

Formulae

Let \( \hat{H} = \) sum.

When qureg is a statevector \(\svpsi\), this function returns
\[ \brapsi \hat{H} \svpsi \in \mathbb{R}. \]
When qureg is a density matrix \(\dmrho\), this function returns the real component of
\[ \tr{ \hat{H} \dmrho } \]
which is the exact expectation value when \(\dmrho\) is physical (specifically Hermitian).

Constraints

Hermiticity of sum requires that every coefficient within is real. Validation will check sum is approximately Hermitian, i.e. that
\[ |\im{c}| \le \valeps \]
for all \(c \in \) sum.coeffs. Adjust \(\valeps\) using setValidationEpsilon().
The returned value is always real, and the imaginary component is neglected even when Hermiticity validation is relaxed and/or qureg is an unnormalised density matrix. The full complex value can be obtained using calcExpecNonHermitianPauliStrSum().

Equivalences

This function is mathematically equivalent to (albeit faster than) calling calcExpecPauliStr() upon each constituent PauliStr within sum, weighting each by its corresponding coefficient, and summing the outputs.
When sum contains only \(\pauliz\) and \(\id\) operators, its corresponding operator matrix is diagonal, and could be instead effected with calcExpecFullStateDiagMatr(). This may be faster when sum contains very-many terms and operates upon all qubits of the register.

Example: Qureg qureg = createQureg(5);

PauliStrSum sum = createInlinePauliStrSum(R"(

0.123 XXIXX

1.234 XYZXZ

-1E-2 IIIII

)");

qreal expec = calcExpecPauliStrSum(qureg, sum);

reportScalar("expec", expec);

calcExpecPauliStrSum
qreal calcExpecPauliStrSum(Qureg qureg, PauliStrSum sum)
Definition calculations.cpp:146

createInlinePauliStrSum
PauliStrSum createInlinePauliStrSum(const char *str)
Definition paulis.cpp:428

PauliStrSum
Definition paulis.h:65

Parameters

[in]	qureg	the reference state.
[in]	sum	the observable operator.

Returns: The real component of the expectation value.

Exceptions

error

if qureg or sum are uninitialised.
if any PauliStr in sum targets a higher-index qubit than exists in qureg.
if sum is not approximately Hermitian.
if the output (with unreturned imaginary component) is not approximately real.

Attention: This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!

See also

calcExpecNonHermitianPauliStrSum()
calcExpecFullStateDiagMatr()

Author: Tyson Jones

Definition at line 146 of file calculations.cpp.

                                                         {
    validate_quregFields(qureg, __func__);
    validate_pauliStrSumFields(sum, __func__);
    validate_pauliStrSumTargets(sum, qureg, __func__);
    validate_pauliStrSumIsHermitian(sum, __func__);
 
    qcomp value = (qureg.isDensityMatrix)?
        localiser_densmatr_calcExpecPauliStrSum(qureg, sum):
        localiser_statevec_calcExpecPauliStrSum(qureg, sum);
 
    validate_expecPauliStrSumValueIsReal(value, qureg.isDensityMatrix, __func__);
    return std::real(value);
}

Referenced by TEST_CASE().