Insert `QuEST` into debug API

[TysonRayJones]

The debug API functions...

• setSeeds()
• setSeedsToDefault()
• getSeeds()
• getNumSeeds()
• setInputErrorHandler()
• setValidationOn()
• setValidationOff()
• setValidationEpsilonToDefault()
• setValidationEpsilon()
• getValidationEpsilon()
• setMaxNumReportedItems()
• setMaxNumReportedSigFigs()
• setNumReportedNewlines()
• setReportedPauliChars()
• setReportedPauliStrStyle()
• getGpuCacheSize()
• clearGpuCache()
• getEnvironmentString()

are named irksomely generically, and are likely to collide with user symbols (setSeeds()?! What was I thinking?!), or those of other libraries/dependencies.

In contrast, the environment API functions...

• initQuESTEnv()
• initCustomQuESTEnv()
• finalizeQuESTEnv()
• syncQuESTEnv()
• reportQuESTEnv()
• isQuESTEnvInit()
• getQuESTEnv()
  conveniently contain QuEST, disambiguating from user namespace.

We should rename the debug functions to also include QuEST. The remaining API is fine, since containing either the name of a QuEST type (e.g. Qureg, CompMatr PauliStr, ...) or are an unambiguously "QuESTy" operation (applyHadamard, calcFidelity, ...)

While doing this, we may also consider renaming potentially ambiguous preprocessors (such as FLOAT_PRECISION), in addition to the CMake flags already nominated for rename in #709 .

[TysonRayJones]

@otbrown Were any major API breaks planned for v4.3? (I consider the Trotter permuteTerms argument to be a very minor break). Would bumping only a minor version (to v4.3, rather than v5) be inappropriate with the notable API break proposed in this issue?

[otbrown]

Hallo, it's an interesting question!

I personally think this is absolutely fine -- you're right that technically such a break in the public API requires a major version bump, but as with the Trotter interface, I'd be surprised to learn that anyone who wasn't you or I even knew about these functions! Actually moreso with these functions... Given that version 3->4 was a full rewrite of the codebase, 4->5 being "we changed these debug functions" would feel a bit flat.

What I think might be sensible is if we sit down (at some point) and formally identify the bits of the API that we want to protect with semantic versioning, and the bits that might be 'at-risk' between minor versions. Stuff like this debug functionality could permanently be at-risk, while experimental new features like the Trotter interface or the custom MPI could start at-risk, and eventually be promoted to protected once we decide we're happy with them. That gives us the freedom to try new stuff without having to get it right first time, but also means users can be confident that we're not going to change applyHadamard without at least giving them the heads-up of a major version bump.

[otbrown]

My colleague Neil at the Software Sustainability Institute makes the very valid point that unsigned ints are free, and we're unlikely to run out. The fact that I feel silly moving to 5.0 for this relatively minor change isn't necessarily a good reason not to do it 😆 He also notes it may be confusing to have some parts of the API under semantic versioning, and some not.

I do think that whichever decision we make, we should commit to it going forward.

Options are:

1. Reserve major version changes for core API breaks or substantial new features -- major version is marketing! (Though we should clearly document what counts as "core API".)
2. Proper semantic versioning -- public API changes, major version changes. Roll on v100!

[otbrown]

(If we go for option 2, then one compromise might be to push this change until we have something more exciting for v5.0.0)

[TysonRayJones]

I happen to share your intuitions - that a major version bump because some debug functions were renamed seems underwhelming! I quite like your reasoning that certain API groups like debug are "at risk", and warrant breaking semantic versioning.

And to the devil in the back of our minds that says:

But "custom obedience" to semantic versioning becomes not semantic versioning, evidenced as soon as a user happens to be using a non-core function, bumps up the minor version, and finds that their build unexpectedly breaks.

Then I guess we simply are not using semantic versioning ¯\_(ツ)_/¯ Which is fine by me! The v4.3 release notes can clearly communicate the API breaks and compatibility issues 🙏