Implement Pauli sorting

[vaferreiQMT]

Howdy! This is the first of two PRs on transformations of PauliStrSums mainly focusing on improving the accuracy of Trotter methods. This PR specifically introduces methods to sort the terms within a PauliStrSum.

Main changes:

• Core: added methods to calculate and apply permutations to sort a PauliStrSum.
• API: Added methods to sort lexicographically and by magnitude (along with tests).
• Documentation: added a Setters section for Pauli docs, for the sorting methods and future methods that transform Pauli strings.

Key details:

• Since the sorting logic is only expected to be used outside hot loops, I have tried to keep the permutation logic as simple as possible and not reinvent the wheel, e.g. using std::sort rather than some custom implementation.
• When applying the permutations we require both some temporary storage to construct and invert the permutation, however since the number of terms in a PauliStrSum generally only scales polynomially, this shouldn't be an issue (e.g. even for extremely large chemical systems this additional memory would be negligible)

I think that about covers it. As always happy to tweak, move or update stuff if anything jumps out at you.

Cheers!

[TysonRayJones]

1. Ooh interesting. Can you explain the motivation for these functions? I imagine lexicographic sorting is intended for users to restore to a deterministic ordering after doing randomised Trotter. Is the coefficient sorting for some importance sampling method?

2. Relatedly, I'm wondering now whether, in lieu of actually modifying the user-accessible strings and coeffs struct fields, we should have exposed a new order field which is just an array of indices. The randomised Trotter functions can consult(strings[order[i]], coeffs[order[i]]) instead of (strings[i], coeffs[i]), and the Trotter function can permute order as it pleases. Then users won't be astonished by the printed PauliStrSum order changing (or being different from that which was printed previously). It would enable to cheaply modify coefficients of specific strings (in their original index). Your new functions here would continue to work by modifying order (but perhaps need a semantic rename).

   It's not too late to do this since randomised-Trotter hasn't yet been released. Attending a new field to user-facing struct PauliStrSumdoes break ABI, but that's never been a big deal for QuEST since entirely compiled from source. @otbrown Do you have any thoughts on this?

3. So far I've been absolutely anal about validating temporary memory is allocated successfully, when it is sized by a user-controllable parameter. Even though it seems silly, I think it's worth doing so here at least for consistency. Not so much to catch actual memory exhaustion - I agree it'll never happen - but instead to make explicit where we are performing all potentially-non-trivial internal memory allocs. I know it makes the code less modular and pretty (you must now pass an error callback, or the temporary memory, to paulis_sortGeneric) but it at least assuages a future reader who spots it as an unchecked internal alloc.

[vaferreiQMT]

Howdy!

For 1. the magnitude sorting comes from Tranter et al., which suggested it as a cheap method for improving the accuracy of Trotter methods for chemical systems. From my testing it does seem to be surprisingly effective for chemical systems, though it won't be a silver bullet for all Hamiltonians. Nevertheless, I thought it was cheap and useful enough for chemicals systems and for analysing generic Hamiltonians, that it could be relevant.

For 2. I will leave it up to you and Oliver to decide what you think is best, but I'll be happy to update the PR after.

For 3. I agree with your thoughts. I was bouncing between including or not including the temporary memory validation before submitting the PR, so happy to add that back.

Cheers!

[otbrown]

Hi both,

First, apologies for the delayed response, it's been one of those daysweeks months!

RE Tyson's 2nd point:
I quite like this idea since, as you say, it's less astonishing and may be easier to follow/debug for developers since once can always print the order array. Since it's not in a performance critical location, I don't think the additional cost of the abstraction is a concern, and I agree that ABI isn't relevant. Especially not for new functionality!

[TysonRayJones]

1. Hmm interesting. Have you seen "magnitude ordering" for Trotterisation in any other work? Confessedly I am not fully clear about the logic:

   Perhaps the most immediately obvious ordering scheme is themagnitude ordering. Here, terms are ordered according to the magnitude of their coefficient, from largest to smallest—the term with the largest
   magnitude coefficient is simulated first, followed by the second largest magnitude coefficient, and so on.
   This ordering scheme has the immediate appeal that high magnitude terms are simulated first. As a result,
   one could expect a reduction in the number of high magnitude terms in the error operator. Loosely, this
   is due to implementing high magnitude terms first, as opposed to later in the sequence where they may
   compound earlier errors. However, this approach does not take into consideration the structure of the
   error operator—high magnitude terms may not result in a meaningful increase in error if, for example,
   they commute with many other terms.

   I see they (additionally) discuss magnitude ordering within commuting groups, and it is worth noting that sortPauliStrSumMagnitude() will not enable that - but there is so far no handling of commuting groups in the Trotter functions anyway.

   After this function however, I'd advise against implementing further functions of this kind before commuting group functionality, given it is the canonical and well studied improvement. It's likely not worth supporting a zoo of esoteric methods with mostly unknown performances; the user can always just reorder their PauliStrSum themselves.

   I like sortPauliStrSumMagnitude() anyway since it is just as sensible (if not more) than lexicographic ordering of a PauliStrSum generally (i.e. independently of Trotterisation), which is itself natural enough.

2. Ok nice! I'll implement this on the weekend, if nobody beats me to it. This PR can proceed without it; I'll work out of devel.

3. Wew add in the temp alloc when you get a sec (if not, I'll squash it in on the weekend) and we'll merge this PR

[TysonRayJones]

Queue rapid edits:

[TysonRayJones]

Merging - I'll deal with any remaining test issues in subsequent PR

[TysonRayJones]

@vaferreiQMT@otbrown#713 highlights an unrealised side-effecting of adding .ordering. Any thoughts? :S