added calcRealAmpSum frontend

[TysonRayJones]

Example PR A

Sub PR 1

This PR demonstrates how to add the user-facing frontend of a new function to the QuEST API. To do so:

1. declare the function in a quest/include/ header file.
2. write the function doc above that declaration.
3. define the function in a corresponding quest/src/api/ file.
4. define new validation functions as necessary.

This API function should contain only simple logic, and call other internal functions defined in quest/src/core/ files as necessary. It typically resembles

void myFunction(int a, int b) {
     validate_userInput(a, __func__);
     validate_userInput(b, __func__);

    localiser_myFunction(a, b);
}

where validate_userInput() is a function declared in validation.hpp which verifies the user's input satisfies necessary preconditions. The so-far undefined function localiser_myFunction() is the entry-point to the backend of the new function, as explained in the next PR (#608).

It is sometimes necessary to define new internal functions needed by the new API function. These will typically be added to

• validation.cpp
• utilities.cpp
• parser.cpp
• printer.cpp
• randomiser.cpp
• memory.cpp

In this PR, it was necessary to define a new validation function in validation.cpp, and declare it in validation.hpp