added calcRealAmpSum tests

[TysonRayJones]

Example PR A

Sub PR 3

This PR demonstrates how to define unit tests for a new API function. Here, we test calcRealAmpSum as implemented in #607 and #608.

It is essential to rigorously unit test every new QuEST function. Each function corresponds to a single Catch2 TEST_CASE, defined in a file in tests/unit/. The test filename is identical to the filename in quest/src/api/ containing the API function.

The unit tests re-create the behaviour of a QuEST function through direct, non-accelerated, naive linear algebra. They are ergo exceptionally slow, but perform precisely what the test operations are defined to do. For example, a Hadamard gate is tensored into a full-state matrix (with dimension 2^qubits) and is multiplied onto a vector via matrix-vector multiplication. This is performed using the myriad of utility functions in tests/utils/. It is sometimes necessary, like in this PR, to define new utility functions.

Beware that some unit tests are filled with boilerplate and complicated usages of macros and generic programming. This is to avoid code duplication between the tests of similar functions, while rigorously testing every aspect of QuEST's varied API functionality. The structure of the unit tests differ between the major groups of API functions. In order of increasing complexity, they are

• (trivial) types.cpp
• (trivial) environment.cpp
• (trivial) paulis.cpp
• (trivial) qureg.cpp
• (trivial) channels.cpp
• (simple) initialisations.cpp
• (simple) debug.cpp
• (simple) matrices.cpp
• (moderate) decoherence.cpp
• (complicated) calculations.cpp
• (nightmarish) operations.cpp

This PR added a test to calculations.cpp which expands the TEST_ALL_QUREGS() macro defined therein.

These example PRs have so far implemented calcRealAmpSum(), returning a real number (qreal). The natural companion function calcAmpSum(), which returns a complex number (qcomp), requires some additional steps as explained in #610.