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 PauliStrSum does 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!