added C++ convenience overloads

so that C++ users can pass vectors directly to functions, even inline, rather than having to store qubit lists as local variables and pass pointers. This is not only concise, but prevents them from causing insidious seg-faults/dangling errors by attempting to pass inline vector pointers.

Alas this adds quite a lot of new boilerplate; 2000 lines of it! :'( 

See PR #584 for a breakdown into smaller commits.

Author: TysonRayJones

quest/include/calculations.h

@@ -21,11 +21,18 @@
 
 
 /*
- * These signatures are divided into two partitions; those which are
- * natively C and C++ compatible (first partition) and those which are
+ * These signatures are divided into three partitions; those which are
+ * natively C and C++ compatible (first partition), then those which are
  * only exposed to C++ (second partition) because they return 'qcomp' 
- * which cannot cross the C++-to-C ABI. The first partition defines the
- * doc groups, and the second partition functions are added into them.
+ * which cannot cross the C++-to-C ABI, and then finally the C++-only
+ * convenience overloads. The first partition defines the doc groups, and 
+ * the latter partition functions are added into them.
+ */
+
+
+
+/*
+ * C AND C++ AGNOSTIC FUNCTIONS
  */
 
 // enable invocation by both C and C++ binaries
@@ -193,7 +200,7 @@ qreal calcProbOfMultiQubitOutcome(Qureg qureg, int* qubits, int* outcomes, int n
 
 /// @notdoced
 /// @notvalidated
-void  calcProbsOfAllMultiQubitOutcomes(qreal* outcomeProbs, Qureg qureg, int* qubits, int numQubits);
+void calcProbsOfAllMultiQubitOutcomes(qreal* outcomeProbs, Qureg qureg, int* qubits, int numQubits);
 
 
 /** @} */
@@ -279,8 +286,8 @@ Qureg calcReducedDensityMatrix(Qureg qureg, int* retainQubits, int numRetainQubi
  * below functions have a C-compatible wrapper defined in
  * wrappers.h which passes/receives the primitives by pointer;
  * a qcomp ptr can be safely passed from the C++ source binary
- * the user's C binary. We manually add these functions to the
- * Doxygen doc groups defined above
+ * the user's C binary. We manually add these functions to their
+ * respective Doxygen doc groups defined above
  */
 
 
@@ -309,6 +316,54 @@ qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr
 
 
 
+/*
+ * C++ OVERLOADS
+ *
+ * which are only accessible to C++ binaries, and accept
+ * arguments more natural to C++ (e.g. std::vector). We
+ * manually add these to their respective Doxygen doc groups.
+ */
+
+#ifdef __cplusplus
+
+#include <vector>
+
+
+/// @ingroup calc_prob
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector<int> qubits, std::vector<int> outcomes);
+
+
+/// @ingroup calc_prob
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+std::vector<qreal> calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector<int> qubits);
+
+
+/// @ingroup calc_partialtrace
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+Qureg calcPartialTrace(Qureg qureg, std::vector<int> traceOutQubits);
+
+
+/// @ingroup calc_partialtrace
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+Qureg calcReducedDensityMatrix(Qureg qureg, std::vector<int> retainQubits);
+
+
+#endif // __cplusplus
+
+
 #endif // CALCULATIONS_H
 
-/** @} (end doxygen defgroup) */
+/** @} */ // (end file-wide doxygen defgroup)

quest/include/channels.h

@@ -56,6 +56,13 @@
 
 
 
+/*
+ * unlike some other headers, we here intermix the C and C++-only
+ * signatures, grouping them semantically & by their doc groups
+ */
+
+
+
 /** 
  * @defgroup channels_structs Structs
  * @brief Data structures for representing decoherence channels.
@@ -383,11 +390,13 @@ extern "C" {
 
     /// @ingroup channels_setters
     /// @notdoced
+    /// @cpponly
     void setInlineKrausMap(KrausMap map, int numQb, int numOps, std::vector<std::vector<std::vector<qcomp>>> matrices);
 
 
     /// @ingroup channels_setters
     /// @notdoced
+    /// @cpponly
     void setInlineSuperOp(SuperOp op, int numQb, std::vector<std::vector<qcomp>> matrix);
 
 
@@ -458,11 +467,13 @@ extern "C" {
 
     /// @ingroup channels_create
     /// @notdoced
+    /// @cpponly
     KrausMap createInlineKrausMap(int numQubits, int numOperators, std::vector<std::vector<std::vector<qcomp>>> matrices);
 
 
     /// @ingroup channels_create
     /// @notdoced
+    /// @cpponly
     SuperOp createInlineSuperOp(int numQubits, std::vector<std::vector<qcomp>> matrix);
 
 
@@ -521,4 +532,4 @@ extern "C" {
 
 #endif // CHANNELS_H
 
-/** @} (end doxygen defgroup) */
+/** @} */ // (end file-wide doxygen defgroup)

quest/include/debug.h

@@ -16,6 +16,12 @@
 
 #include "quest/include/types.h"
 
+
+
+/*
+ * C AND C++ AGNOSTIC FUNCTIONS
+ */
+
 // enable invocation by both C and C++ binaries
 #ifdef __cplusplus
 extern "C" {
@@ -159,6 +165,39 @@ void getEnvironmentString(char str[200]);
 }
 #endif
 
+
+
+/*
+ * C++ OVERLOADS
+ *
+ * which are only accessible to C++ binaries, and accept
+ * arguments more natural to C++ (e.g. std::vector). We
+ * manually add these to their respective Doxygen doc groups.
+ */
+
+#ifdef __cplusplus
+
+#include <vector>
+
+
+/// @ingroup debug_seed
+/// @nottested
+/// @notdoced
+/// @cpponly
+void setSeeds(std::vector<unsigned> seeds);
+
+
+/// @ingroup debug_seed
+/// @nottested
+/// @notdoced
+/// @cpponly
+std::vector<unsigned> getSeeds();
+
+
+#endif // __cplusplus
+
+
+
 #endif // DEBUG_H
 
-/** @} (end doxygen defgroup) */
+/** @} */ // (end file-wide doxygen defgroup)

quest/include/decoherence.h

@@ -17,12 +17,17 @@
 #include "quest/include/qureg.h"
 #include "quest/include/channels.h"
 
+
+
+/*
+ * C AND C++ AGNOSTIC FUNCTIONS
+ */
+
 // enable invocation by both C and C++ binaries
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-
 /// @notdoced
 /// @notvalidated
 void mixDephasing(Qureg qureg, int qubit, qreal prob);
@@ -53,7 +58,7 @@ void mixQureg(Qureg qureg, Qureg other, qreal prob);
 
 /// @notdoced
 /// @notvalidated
-void mixKrausMap(Qureg qureg, int* qubits, int numQubits, KrausMap map);
+void mixKrausMap(Qureg qureg, int* targets, int numTargets, KrausMap map);
 
 /// @notdoced
 /// @notvalidated
@@ -65,6 +70,36 @@ void mixSuperOp(Qureg qureg, int* targets, int numTargets, SuperOp superop);
 }
 #endif
 
+
+
+/*
+ * C++ OVERLOADS
+ *
+ * which are only accessible to C++ binaries, and accept
+ * arguments more natural to C++ (e.g. std::vector). These
+ * are included in the file-wide doxygen group (no subgroups).
+ */
+
+#ifdef __cplusplus
+
+#include <vector>
+
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+void mixKrausMap(Qureg qureg, std::vector<int> targets, KrausMap map);
+
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+void mixSuperOp(Qureg qureg, std::vector<int> targets, SuperOp superop);
+
+#endif // __cplusplus
+
+
+
 #endif // DECOHERENCE_H
 
-/** @} (end doxygen defgroup) */
+/** @} */ // (end file-wide doxygen defgroup)

quest/include/deprecated.h

@@ -114,12 +114,12 @@ refactor your code to v4, and should absolutely not continue to use the old v3 A
  */
 
 
-// TODO: 
-// we use placeholder message(...) below which only issues a warning,
-// and does not kill compilation; there alas seems to be no cross-platform
-// method of aborting compilation with a _Pragma (and aborting during
-// preprocessing via #error is too soon). We currently work around this by
-// referring to an undefined symbol. Ew!
+/// @todo: 
+/// we use placeholder message(...) below which only issues a warning,
+/// and does not kill compilation; there alas seems to be no cross-platform
+/// method of aborting compilation with a _Pragma (and aborting during
+/// preprocessing via #error is too soon). We currently work around this by
+/// referring to an undefined symbol. Ew!
 
 
 #define _FORCE_COMPILATION_TO_FAIL() \

quest/include/environment.h

@@ -75,4 +75,4 @@ QuESTEnv getQuESTEnv();
 
 #endif // ENVIRONMENT_H
 
-/** @} (end doxygen defgroup) */
+/** @} */ // (end file-wide doxygen defgroup)

quest/include/initialisations.h

@@ -19,6 +19,12 @@
 #include "quest/include/qureg.h"
 #include "quest/include/paulis.h"
 
+
+
+/*
+ * C AND C++ AGNOSTIC FUNCTIONS
+ */
+
 // enable invocation by both C and C++ binaries
 #ifdef __cplusplus
 extern "C" {
@@ -144,6 +150,65 @@ void setQuregToReducedDensityMatrix(Qureg out, Qureg in, int* retainQubits, int
 }
 #endif
 
+
+
+/*
+ * C++ OVERLOADS
+ *
+ * which are only accessible to C++ binaries, and accept
+ * arguments more natural to C++ (e.g. std::vector). We 
+ * manually add these to their respective Doxygen doc groups.
+ */
+
+#ifdef __cplusplus
+
+#include <vector>
+
+
+/// @ingroup init_amps
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+void setQuregAmps(Qureg qureg, qindex startInd, std::vector<qcomp> amps);
+
+
+/// @ingroup init_amps
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+void setDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, std::vector<std::vector<qcomp>> amps);
+
+
+/// @ingroup init_amps
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+void setDensityQuregFlatAmps(Qureg qureg, qindex startInd, std::vector<qcomp> amps);
+
+
+/// @ingroup init_amps
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+void setQuregToPartialTrace(Qureg out, Qureg in, std::vector<int> traceOutQubits);
+
+
+/// @ingroup init_amps
+/// @nottested
+/// @notdoced
+/// @notvalidated
+/// @cpponly
+void setQuregToReducedDensityMatrix(Qureg out, Qureg in, std::vector<int> retainQubits);
+
+
+#endif // __cplusplus
+
+
+
 #endif // INITIALISATIONS_H
 
-/** @} (end doxygen defgroup) */
+/** @} */ // (end file-wide doxygen defgroup)