removed setQuregToSuperposition()

since superseded by setQuregToWeightedSum().

Additionally defined internal convenience functions...
- localiser_statevec_scaleAmps
- localiser_statevec_setQuregToClone
which merely call localiser_statevec_setQuregToWeightedSum, for code clarity

Author: TysonRayJones

quest/include/deprecated.h

@@ -865,16 +865,23 @@ static inline void _applyGateSubDiagonalOp(Qureg qureg, int* targets, int numTar
     _WARN_FUNC_RENAMED("cloneQureg()", "setQuregToClone()") \
     setQuregToClone(__VA_ARGS__)
 
+
+
+static inline void _setWeightedQureg(qcomp f1, Qureg q1, qcomp f2, Qureg q2, qcomp fOut, Qureg qOut) {
+    qcomp coeffs[] = {fOut, f1, f2};
+    Qureg quregs[] = {qOut, q1, q2};
+    setQuregToWeightedSum(qOut, coeffs, quregs, 3);
+}
+
 #define setWeightedQureg(f1, q1, f2, q2, fOut, qOut) \
     _WARN_GENERAL_MSG( \
         "The QuEST function 'setWeightedQureg(f1,q1, f2,q2, fOut,qOut)' is deprecated, and replaced with " \
-        "'setQuregToSuperposition(fOut,qOut, f1,q1, f2,q2)' which has been automatically invoked. The new " \
-        "fucntion however accepts only statevectors, not density matrices, so may error at runtime. Beware " \
-        "that the order of the arguments has changed, so that the first supplied Qureg is modified." ) \
-    setQuregToSuperposition( \
-        getQcomp(fOut.real, fOut.imag), qOut, \
-        getQcomp(f1.real, f1.imag), q1, \
-        getQcomp(f2.real, f2.imag), q2)
+        "'setQuregToWeightedSum(qOut, {f1,f2,...}, {q1,q2,..}, len)' which has been automatically invoked. " \
+        "Beware that the order of the arguments has changed, so that the first supplied Qureg is modified." ) \
+    _setWeightedQureg( \
+        _GET_QCOMP_FROM_COMPLEX_STRUCT(f1) ,q1, \
+        _GET_QCOMP_FROM_COMPLEX_STRUCT(f2) ,q2, \
+        _GET_QCOMP_FROM_COMPLEX_STRUCT(fOut), qOut)
 
 
 

quest/include/initialisations.h

@@ -126,28 +126,6 @@ void setQuregToWeightedSum(Qureg out, qcomp* coeffs, Qureg* in, int numIn);
 void setQuregToMixture(Qureg out, qreal* probs, Qureg* in, int numIn);
 
 
-/** @notyetdoced
- * @notyettested
- * 
- * @formulae
- * 
- * Let @f$ f_{\text{out}} = @f$ @p facOut, @f$ f_1 = @f$ @p fac1 and @f$ f_2 = @f$ @p fac2.
- * Similarly, let @f$ \psi_{\text{out}} = @f$ @p out, @f$ \psi_{1} = @f$ @p qureg1 and @f$ \psi_{2} = @f$ @p qureg2.
- * 
- * This function modifies only @p facOut to become
- * @f[
-     |\psi_{\text{out}}\rangle \; \rightarrow \;
-        f_{\text{out}} |\psi_{\text{out}}\rangle \, + \,
-        f_1 |\psi_1\rangle \, + \,
-        f_2 |\psi_2\rangle.
- * @f]
- *
- * All factors are unconstrained and are permitted to be zero, and the same @p Qureg can be duplicated among
- * all arguments.
- */
-void setQuregToSuperposition(qcomp facOut, Qureg out, qcomp fac1, Qureg qureg1, qcomp fac2, Qureg qureg2);
-
-
 /// @notyetdoced
 /// @notyetvalidated
 qreal setQuregToRenormalized(Qureg qureg);

quest/include/operations.h

@@ -1670,14 +1670,16 @@ extern "C" {
           - \iu  \sin\left( \frac{\theta}{2} \right) \, \hat{\sigma},
  *   @f]
  *   this function is equivalent to (but much faster than) effecting @f$ \hat{\sigma} @f$
- *   upon a clone which is subsequently superposed.
+ *   upon a clone which is subsequently combined.
  *   ```
      // prepare |temp> = str |qureg>
      Qureg temp = createCloneQureg(qureg);
      applyPauliStr(temp, str);
 
      // set |qureg> = cos(theta/2) |qureg> - i sin(theta/2) str |qureg>
-     setQuregToSuperposition(cos(theta/2), qureg, - 1.0i * sin(theta/2), temp, 0, temp);
+     qcomp coeffs[] = {cos(theta/2), -1i * sin(theta/2)};
+     Qureg quregs[] = {qureg, temp};
+     setQuregToWeightedSum(qureg, coeffs, quregs, 2);
  *   ```
  * - When @p str contains only @f$ \hat{Z} @f$ or @f$ \id @f$ Paulis, this function will
  *   automatically invoke applyPhaseGadget() which leverages an optimised implementation.
@@ -1686,7 +1688,7 @@ extern "C" {
  *   unchanged.
  *   ```
      qcomp factor = cexp(- theta / 2 * 1.i);
-     setQuregToSuperposition(factor, qureg, 0,qureg,0,qureg);
+     setQuregToWeightedSum(qureg, &factor, &qureg, 1);
  *   ```
  * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged.
  *

quest/src/api/initialisations.cpp

@@ -33,7 +33,6 @@ using std::vector;
 extern "C" {
 
 
-
 /*
  * INIT
  */
@@ -72,12 +71,9 @@ void initPureState(Qureg qureg, Qureg pure) {
     validate_quregFields(pure, __func__);
     validate_quregCanBeInitialisedToPureState(qureg, pure, __func__);
 
-    // when qureg=statevec, we lazily invoke setQuregToSuperposition which
-    // invokes superfluous floating-point operations which will be happily
-    // occluded by the memory movement costs
     (qureg.isDensityMatrix)?
         localiser_densmatr_initPureState(qureg, pure):
-        localiser_statevec_setQuregToSuperposition(0, qureg, 1, pure, 0, pure);
+        localiser_statevec_setQuregToClone(qureg, pure);
 }
 
 
@@ -185,17 +181,7 @@ void setQuregToClone(Qureg targetQureg, Qureg copyQureg) {
     // appreciable slowdown since simulation is memory-bound
     (targetQureg.isDensityMatrix)?
         localiser_densmatr_mixQureg(0, targetQureg, 1, copyQureg):
-        localiser_statevec_setQuregToSuperposition(0, targetQureg, 1, copyQureg, 0, copyQureg);
-}
-
-
-void setQuregToSuperposition(qcomp facOut, Qureg out, qcomp fac1, Qureg qureg1, qcomp fac2, Qureg qureg2) {
-    validate_quregFields(out, __func__);
-    validate_quregFields(qureg1, __func__);
-    validate_quregFields(qureg2, __func__);
-    validate_quregsCanBeSuperposed(out, qureg1, qureg2, __func__); // asserts statevectors
-
-    localiser_statevec_setQuregToSuperposition(facOut, out, fac1, qureg1, fac2, qureg2);
+        localiser_statevec_setQuregToClone(targetQureg, copyQureg);
 }
 
 
@@ -207,7 +193,7 @@ qreal setQuregToRenormalized(Qureg qureg) {
 
     qreal norm = (qureg.isDensityMatrix)? prob : std::sqrt(prob);
     qreal fac = 1 / norm;
-    localiser_statevec_setQuregToSuperposition(fac, qureg, 0, qureg, 0, qureg);
+    localiser_statevec_scaleAmps(qureg, fac);
 
     return fac;
 }

quest/src/api/multiplication.cpp

@@ -644,13 +644,13 @@ void leftapplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace) {
     validate_pauliStrSumTargets(sum, qureg, __func__);
 
     // clone qureg to workspace, set qureg to blank
-    localiser_statevec_setQuregToSuperposition(0, workspace, 1, qureg, 0, qureg);
+    localiser_statevec_setQuregToClone(workspace, qureg);
     localiser_statevec_initUniformState(qureg, 0);
 
     // left-multiply each term in-turn, mixing into output qureg, then undo using idempotency
     for (qindex i=0; i<sum.numTerms; i++) {
         localiser_statevec_anyCtrlPauliTensor(workspace, {}, {}, sum.strings[i]);
-        localiser_statevec_setQuregToSuperposition(1, qureg, sum.coeffs[i], workspace, 0, workspace);
+        localiser_statevec_setQuregToWeightedSum(qureg, {1, sum.coeffs[i]}, {qureg, workspace});
         localiser_statevec_anyCtrlPauliTensor(workspace, {}, {}, sum.strings[i]);
     }
 
@@ -666,7 +666,7 @@ void rightapplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace) {
     validate_pauliStrSumTargets(sum, qureg, __func__);
 
     // clone qureg to workspace, set qureg to blank
-    localiser_statevec_setQuregToSuperposition(0, workspace, 1, qureg, 0, qureg);
+    localiser_statevec_setQuregToClone(workspace, qureg);
     localiser_statevec_initUniformState(qureg, 0);
 
     // post-multiply each term in-turn, mixing into output qureg, then undo using idempotency
@@ -675,7 +675,7 @@ void rightapplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace) {
         qcomp factor = paulis_getSignOfPauliStrConj(str); // undoes transpose
 
         localiser_statevec_anyCtrlPauliTensor(workspace, {}, {}, str, factor);
-        localiser_statevec_setQuregToSuperposition(1, qureg, sum.coeffs[i], workspace, 0, workspace);
+        localiser_statevec_setQuregToWeightedSum(qureg, {1, sum.coeffs[i]}, {qureg, workspace});
         localiser_statevec_anyCtrlPauliTensor(workspace, {}, {}, str, factor);
     }
 

quest/src/core/accelerator.cpp

@@ -556,15 +556,6 @@ void accel_statevec_setQuregToWeightedSum_sub(Qureg outQureg, vector<qcomp> coef
 }
 
 
-void accel_statevec_setQuregToSuperposition_sub(qcomp facOut, Qureg outQureg, qcomp fac1, Qureg inQureg1, qcomp fac2, Qureg inQureg2) {
-
-    // consult outQureg's deployment (other quregs should match, though we dangerously do not assert this post-validation)
-    (outQureg.isGpuAccelerated)?
-        gpu_statevec_setQuregToSuperposition_sub(facOut, outQureg, fac1, inQureg1, fac2, inQureg2):
-        cpu_statevec_setQuregToSuperposition_sub(facOut, outQureg, fac1, inQureg1, fac2, inQureg2); 
-}
-
-
 void accel_densmatr_mixQureg_subA(qreal outProb, Qureg out, qreal inProb, Qureg in) {
 
     // quregs are equally-sized density matrices and are equally-distributed... 

quest/src/core/accelerator.hpp

@@ -234,8 +234,6 @@ void accel_statevector_anyCtrlPauliTensorOrGadget_subB(Qureg qureg, vector<int>
 
 void accel_statevec_setQuregToWeightedSum_sub(Qureg outQureg, vector<qcomp> coeffs, vector<Qureg> inQuregs);
 
-void accel_statevec_setQuregToSuperposition_sub(qcomp facOut, Qureg outQureg, qcomp fac1, Qureg inQureg1, qcomp fac2, Qureg inQureg2);
-
 void accel_densmatr_mixQureg_subA(qreal outProb, Qureg out, qreal inProb, Qureg in);
 void accel_densmatr_mixQureg_subB(qreal outProb, Qureg out, qreal inProb, Qureg in);
 void accel_densmatr_mixQureg_subC(qreal outProb, Qureg out, qreal inProb);

quest/src/core/errors.cpp

@@ -563,17 +563,6 @@ void assert_quregDistribAndFullStateDiagMatrLocal(Qureg qureg, FullStateDiagMatr
         raiseInternalError("The FullStateDiagMatr was unexpectedly distributed.");
 }
 
-void assert_superposedQuregDimsAndDeploysMatch(Qureg facOut, Qureg in1, Qureg in2) {
-
-    if (
-        facOut.isDistributed    != in1.isDistributed    || in1.isDistributed    != in2.isDistributed    ||
-        facOut.isDensityMatrix  != in1.isDensityMatrix  || in1.isDensityMatrix  != in2.isDensityMatrix  ||
-        facOut.isGpuAccelerated != in1.isGpuAccelerated || in1.isGpuAccelerated != in2.isGpuAccelerated ||
-        facOut.numQubits        != in1.numQubits        || in1.numQubits        != in2.numQubits
-    )
-        raiseInternalError("An internal function *_setQuregToSuperposition() received Quregs of mismatching dimensions and/or deployments.");
-}
-
 
 
 /*

quest/src/core/errors.hpp

@@ -204,9 +204,6 @@ void assert_quregAndFullStateDiagMatrHaveSameDistrib(Qureg qureg, FullStateDiagM
 
 void assert_quregDistribAndFullStateDiagMatrLocal(Qureg qureg, FullStateDiagMatr matr);
 
-void assert_superposedQuregDimsAndDeploysMatch(Qureg facOut, Qureg in1, Qureg in2);
-
-
 
 /*
  * CPU ERRORS

quest/src/core/localiser.cpp

@@ -676,6 +676,11 @@ void localiser_fullstatediagmatr_setElemsToPauliStrSum(FullStateDiagMatr out, Pa
     accel_fullstatediagmatr_setElemsToPauliStrSum(out, in);
 }
 
+void localiser_statevec_scaleAmps(Qureg qureg, qcomp factor) {
+
+    localiser_statevec_setQuregToWeightedSum(qureg, {factor}, {qureg});
+}
+
 
 
 /*
@@ -1384,17 +1389,15 @@ void localiser_statevec_setQuregToWeightedSum(Qureg outQureg, vector<qcomp> coef
 }
 
 
-void localiser_statevec_setQuregToSuperposition(qcomp facOut, Qureg outQureg, qcomp fac1, Qureg inQureg1, qcomp fac2, Qureg inQureg2) {
+void localiser_statevec_setQuregToClone(Qureg out, Qureg in) {
 
     /// @todo
-    /// this function requires (as validated) distributions are identical.
-    /// It would be trivial to generalise this so that Qureg distributions
-    /// can differ (we merely spoof local Quregs, offsetting their memory).
-    /// They must still however be identically GPU-accelerated; this is a
-    /// low priority because this situation is non-sensical
+    /// we lazily re-use setQuregToWeightedSum(), inducing a gratuitous
+    /// x1 multiplication per element which we expected is completely
+    /// occluded by memory movement costs. We should check this and
+    /// potentially replace this function with (NUMA-aware?) memory copying!
 
-    // given Qureg dimensions must match, this is always embarrassingly parallel
-    accel_statevec_setQuregToSuperposition_sub(facOut, outQureg, fac1, inQureg1, fac2, inQureg2);
+    localiser_statevec_setQuregToWeightedSum(out, {1}, {in});
 }
 
 
@@ -2327,7 +2330,7 @@ void localiser_statevec_multiQubitProjector(Qureg qureg, vector<int> qubits, vec
     // all other nodes has some or all states consistent with suffix outcomes
     removePrefixQubitsAndStates(qureg, qubits, outcomes);
     (qubits.empty())?
-        accel_statevec_setQuregToSuperposition_sub(1/std::sqrt(prob), qureg,0,qureg, 0,qureg): // scale by norm
+        localiser_statevec_scaleAmps(qureg, 1/std::sqrt(prob)):
         accel_statevec_multiQubitProjector_sub(qureg, qubits, outcomes, prob);
 }