Function localiser_statevec_calcExpecPauliStrSum

quest/src/core/localiser.cpp:2078–2151

qcomp localiser_statevec_calcExpecPauliStrSum(Qureg qureg, PauliStrSum sum) {
    assert_localiserGivenStateVec(qureg);

    // this function does not process each PauliStr within sum independently; instead, we
    // leverage that strings differing only by I <-> Z and X <-> Y in the prefix qubits
    // have identical communication patterns, and so can all be processed after one round 
    // of amps exchange. 
    
    /// @todo 
    /// We can optimise further in a similar spirit to above by grouping identically-
    /// communicating strings into those which differ only by suffix I <-> Z and X <-> Y,
    /// which have identical amplitude-mixing patterns, to avoid repeated enumeration of 
    /// all amplitudes and reduce the associated memory-movement / caching costs.
    /// (This is facilitated "for free" by cuStateVec in GPU settings, although we do not
    /// wish to here differentiate localiser logic based on CPU vs GPU deployment)

    qcomp totalValue = 0;

    using Key = PAULI_MASK_TYPE;
    using Term = tuple<PauliStr,qcomp>;
    std::unordered_map<Key, vector<Term>> groups;

    // group sum's terms into those with identical communication patterns
    for (int i=0; i<sum.numTerms; i++) {
        Term term = tuple{sum.strings[i], sum.coeffs[i]};
        Key totalKey = paulis_getKeyOfSameMixedAmpsGroup(sum.strings[i]);
        Key prefixKey = getBitsLeftOfIndex(totalKey, qureg.logNumAmpsPerNode - 1); // 0 if !qureg.isDistributed

        groups[prefixKey].push_back(term);
    }

    // process each group in-turn
    for (auto& [key, terms] : groups) {

        // perform communication once per-group, if necessary
        int pairRank = flipBits(qureg.rank, key);
        if (pairRank != qureg.rank)
            comm_exchangeAmpsToBuffers(qureg, pairRank);

        // determine backend function to invoke upon all terms in group (likely _subB)
        auto termFunc = (pairRank == qureg.rank)?
            getStateVecExpecAllSuffixPauliStr :
            accel_statevec_calcExpecPauliStr_subB;

        // for each term within the current group...
        for (auto& [str, coeff] : terms) {
            auto [targsX, targsY, targsZ] = paulis_getSeparateInds(str);
            auto [prefixX, suffixX] = util_getPrefixAndSuffixQubits(targsX, qureg);
            auto [prefixY, suffixY] = util_getPrefixAndSuffixQubits(targsY, qureg);
            auto [prefixZ, suffixZ] = util_getPrefixAndSuffixQubits(targsZ, qureg);
            
            // contribute coeff * prefix-coeff * suffix-sum
            qcomp termFactor = paulis_getPrefixPaulisElem(qureg, prefixY, prefixZ);
            qcomp termValue = termFactor * termFunc(qureg, suffixX, suffixY, suffixZ);

            /// @todo
            /// use Kahan summation to improve (for free) the accuracy of totalValue
            /// here! This sum is always serial, so we should always use it! It is