added calcRealAmpSum frontend

Author: TysonRayJones

quest/include/calculations.h

@@ -42,6 +42,57 @@ extern "C" {
 
 
 
+/** 
+ * @defgroup example_prs Example PR functions
+ * @brief Nonsensical functions to demonstrate good PRs.
+ * @{
+ */
+
+
+/** Calculates the real component of the sum of every amplitude in the state,
+ * but only for states which contain an even number of qubits (for no reason :3 ).
+ * 
+ * @formulae
+ * Let @f$ n @f$ qubits be the number of qubits in @p qureg, assumed even.
+ * 
+ * - When @p qureg is a statevector @f$ \svpsi @f$, this function returns
+ *   @f[ 
+    \text{Re}\left( \sum\limits_i^{2^n} \langle i \svpsi \right) \in \mathbb{R}.
+ *   @f]
+ * - When @p qureg is a density matrix @f$ \dmrho @f$, this function returns
+ *   @f[ 
+    \text{Re}\left( \sum\limits_i^{2^n} \sum\limits_j^{2^n} \bra{i} \dmrho \ket{j} \right) \in \mathbb{R}.
+ *   @f]
+ * 
+ * @constraints
+ * - The number of qubits in the register must be even.
+ * 
+ * @myexample
+ * ```
+    Qureg qureg = createQureg(4);
+    initRandomPureState(qureg);
+
+    qreal reAmpSum = calcRealAmpSum(qureg);
+    reportScalar("reAmpSum", reAmpSum);  
+ * ```
+ * 
+ * @see
+ * - calcTotalProb()
+
+ * @param[in] qureg the state with the processed amplitudes.
+ * @returns The real component of the sum of all contained amplitudes.
+ * @throws @validationerror
+ * - if @p qureg is uninitialised.
+ * - if @p qureg contains an odd number of qubits.
+ * @author Tyson Jones
+ */
+qreal calcRealAmpSum(Qureg qureg);
+
+
+/** @} */
+
+
+
 /** 
  * @defgroup calc_expec Expectation values
  * @brief Functions for calculating expected values of Hermitian observables.

quest/src/api/calculations.cpp

@@ -125,6 +125,22 @@ extern "C" {
 
 
 
+/*
+ * PR DEMOS
+ */
+
+
+qreal calcRealAmpSum(Qureg qureg) {
+    validate_quregFields(qureg, __func__);
+    validate_quregHasEvenNumQubits(qureg, __func__);
+
+    /// @todo
+    /// implement and call new backend function
+    return -1;
+}
+
+
+
 /*
  * EXPECTED VALUES
  */

quest/src/core/validation.cpp

@@ -57,6 +57,14 @@ using std::vector;
 namespace report {
 
 
+    /*
+     * NONSENSE VALIDATION FOR DEMO PR
+     */
+
+    string QUREG_HAS_ODD_NUM_QUBITS =
+        "The given Qureg contained ${NUM_QUBITS} qubits, but must contain an even number.";
+
+
     /*
      *  ENVIRONMENT CREATION
      */
@@ -1306,6 +1314,21 @@ bool isIndexListUnique(int* list, int len) {
 
 
 
+/*
+ * NONSENSE VALIDATION FOR DEMO PR
+ */
+
+void validate_quregHasEvenNumQubits(Qureg qureg, const char* caller) {
+
+    tokenSubs vars = {
+        {"${NUM_QUBITS}", qureg.numQubits}
+    };
+
+    assertThat(qureg.numQubits % 2 == 0, report::QUREG_HAS_ODD_NUM_QUBITS, vars, caller);
+}
+
+
+
 /*
  * ENVIRONMENT CREATION
  */

quest/src/core/validation.hpp

@@ -63,6 +63,14 @@ qreal validateconfig_getEpsilon();
 
 
 
+/*
+ * NONSENSE VALIDATION FOR DEMO PR
+ */
+
+void validate_quregHasEvenNumQubits(Qureg qureg, const char* caller);
+
+
+
 /*
  * ENVIRONMENT CREATION
  */