added postMultiply functions (#657)

For every existing multiply*() function, such as multiplyCompMatr(), this commit adds a corresponding postMultiply*() function which operates upon a density matrix from the right-hand side. This is useful for preparing density matrices in non-physical states which appear as sub-expressions within things like commutators and the Linbladian. 

Implementing these functions involved:
- updating the templating of "any target dense matrix" function, inadvertently simplifying the associated instantiation and dispatch macros by re-using those for the "any target diagonal matrix" function
- adding new utilities and logic for obtaining/effecting the transpose of a function, to undo the transpose effected via operation upon the bra-qubits of a vectorised density matrix
- extending and refactoring the unit tests with postMultiply references

We additionally added the below expected but missing functions from the API:
- multiplyPauliX
- multiplyPauliY
- multiplyPauliZ

Author: TysonRayJones

quest/include/operations.h

@@ -89,13 +89,65 @@ extern "C" {
  * - getCompMatr1()
  * - getInlineCompMatr1()
  * - applyCompMatr1()
+ * - postMultiplyCompMatr1()
  * - applyQubitProjector()
  * - multiplyCompMatr()
  * @author Tyson Jones
  */
 void multiplyCompMatr1(Qureg qureg, int target, CompMatr1 matrix);
 
 
+/** @notyettested
+ * 
+ * Multiplies a general one-qubit dense @p matrix upon the specified @p target 
+ * qubit of the density matrix @p qureg, from the right-hand side.
+ *  
+ * @formulae
+ * Let @f$ \dmrho = @f$ @p qureg, @f$ \hat{M} = @f$ @p matrix and @f$ t = @f$ @p target, 
+ * and notate @f$\hat{M}_t@f$ as per applyCompMatr1(). Unlike applyCompMatr1() however,
+ * this function only ever right-multiplies @p matrix upon @p qureg.
+ * 
+ * Explicitly
+ *   @f[ 
+        \dmrho \rightarrow \dmrho \, \hat{M}_t
+ *   @f]
+ * where @f$ \hat{M} @f$ is not conjugated nor transposed, and there are no additional 
+ * constraints like unitarity.
+ * 
+ * In general, this function will break the normalisation of @p qureg and result in a
+ * non-physical state, and is useful for preparing sub-expressions of formulae like
+ * the Linbladian.
+ *
+ * @myexample
+ * ```
+    Qureg qureg = createDensityQureg(5);
+
+    CompMatr1 matrix = getInlineCompMatr1({
+        {0.1, 0.2},
+        {0.3i, 0.4i}
+    });
+
+    postMultiplyCompMatr1(qureg, 2, matrix); 
+ * ```
+ *
+ * @param[in,out] qureg  the state to modify.
+ * @param[in]     target the index of the target qubit.
+ * @param[in]     matrix the Z-basis matrix to post-multiply.
+ * @throws @validationerror
+ * - if @p qureg or @p matrix are uninitialised.
+ * - if @p qureg is not a density matrix.
+ * - if @p target is an invalid qubit index.
+ * @see
+ * - getCompMatr1()
+ * - getInlineCompMatr1()
+ * - applyCompMatr1()
+ * - multiplyCompMatr1()
+ * - multiplyCompMatr()
+ * @author Tyson Jones
+ */
+void postMultiplyCompMatr1(Qureg qureg, int target, CompMatr1 matrix);
+
+
 /** Applies a general one-qubit dense unitary @p matrix to the specified @p target 
  * qubit of @p qureg.
  * 
@@ -162,6 +214,7 @@ digraph {
  * - getCompMatr1()
  * - getInlineCompMatr1()
  * - multiplyCompMatr1()
+ * - postMultiplyCompMatr1()
  * - applyControlledCompMatr1()
  * - applyCompMatr2()
  * - applyCompMatr()
@@ -346,6 +399,14 @@ extern "C" {
 void multiplyCompMatr2(Qureg qureg, int target1, int target2, CompMatr2 matr);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+/// @see
+/// - postMultiplyCompMatr1
+void postMultiplyCompMatr2(Qureg qureg, int target1, int target2, CompMatr2 matrix);
+
+
 /** @notyetdoced
  * 
  * Applies a general two-qubit dense unitary @p matrix to qubits @p target1 and
@@ -557,6 +618,14 @@ extern "C" {
 void multiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matrix);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+/// @see
+/// - postMultiplyCompMatr1
+void postMultiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matrix);
+
+
 /** @notyetdoced
  * 
  * @formulae
@@ -612,6 +681,14 @@ void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states,
 void multiplyCompMatr(Qureg qureg, std::vector<int> targets, CompMatr matr);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+/// @cppvectoroverload
+/// @see postMultiplyCompMatr()
+void postMultiplyCompMatr(Qureg qureg, std::vector<int> targets, CompMatr matr);
+
+
 /// @notyettested
 /// @notyetvalidated
 /// @notyetdoced
@@ -667,6 +744,12 @@ extern "C" {
 void multiplyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+void postMultiplyDiagMatr1(Qureg qureg, int target, DiagMatr1 matrix);
+
+
 /// @notyetdoced
 /// @see applyCompMatr1()
 void applyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr);
@@ -734,6 +817,12 @@ extern "C" {
 void multiplyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+void postMultiplyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matrix);
+
+
 /// @notyetdoced
 /// @see applyCompMatr1()
 void applyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr);
@@ -801,6 +890,12 @@ extern "C" {
 void multiplyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+void postMultiplyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix);
+
+
 /// @notyetdoced
 /// @see applyCompMatr1()
 void applyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix);
@@ -828,6 +923,12 @@ void applyMultiStateControlledDiagMatr(Qureg qureg, int* controls, int* states,
 void multiplyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+void postMultiplyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent);
+
+
 /** @notyetdoced
  *
  * @formulae
@@ -874,6 +975,14 @@ void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* sta
 void multiplyDiagMatr(Qureg qureg, std::vector<int> targets, DiagMatr matrix);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+/// @cppvectoroverload
+/// @see postMultiplyDiagMatr()
+void postMultiplyDiagMatr(Qureg qureg, std::vector<int> targets, DiagMatr matrix);
+
+
 /// @notyettested
 /// @notyetvalidated
 /// @notyetdoced
@@ -914,6 +1023,14 @@ void applyMultiStateControlledDiagMatr(Qureg qureg, std::vector<int> controls, s
 void multiplyDiagMatrPower(Qureg qureg, std::vector<int> targets, DiagMatr matrix, qcomp exponent);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+/// @cppvectoroverload
+/// @see postMultiplyDiagMatrPower()
+void postMultiplyDiagMatrPower(Qureg qureg, std::vector<int> targets, DiagMatr matrix, qcomp exponent);
+
+
 /// @notyettested
 /// @notyetvalidated
 /// @notyetdoced
@@ -979,6 +1096,18 @@ void multiplyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix);
 void multiplyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix);
+
+
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent);
+
+
 /// @notyetdoced
 /// @notyetvalidated
 void applyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix);
@@ -1143,6 +1272,12 @@ extern "C" {
 void multiplySwap(Qureg qureg, int qubit1, int qubit2);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplySwap(Qureg qureg, int qubit1, int qubit2);
+
+
 /** Applies a SWAP gate between @p qubit1 and @p qubit2 of @p qureg.
  * 
  * @diagram
@@ -1264,20 +1399,41 @@ extern "C" {
 
 
 /// @notyetdoced
+/// @notyettested
 /// @see multiplyCompMatr1()
 void multiplyPauliX(Qureg qureg, int target);
 
 
 /// @notyetdoced
+/// @notyettested
 /// @see multiplyCompMatr1()
 void multiplyPauliY(Qureg qureg, int target);
 
 
 /// @notyetdoced
+/// @notyettested
 /// @see multiplyCompMatr1()
 void multiplyPauliZ(Qureg qureg, int target);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @see postMultiplyCompMatr1()
+void postMultiplyPauliX(Qureg qureg, int target);
+
+
+/// @notyetdoced
+/// @notyettested
+/// @see postMultiplyCompMatr1()
+void postMultiplyPauliY(Qureg qureg, int target);
+
+
+/// @notyetdoced
+/// @notyettested
+/// @see postMultiplyCompMatr1()
+void postMultiplyPauliZ(Qureg qureg, int target);
+
+
 /// @notyetdoced
 void applyPauliX(Qureg qureg, int target);
 
@@ -1408,6 +1564,12 @@ extern "C" {
 void multiplyPauliStr(Qureg qureg, PauliStr str);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplyPauliStr(Qureg qureg, PauliStr str);
+
+
 /// @notyetdoced
 void applyPauliStr(Qureg qureg, PauliStr str);
 
@@ -1796,6 +1958,12 @@ extern "C" {
 void multiplyPauliGadget(Qureg qureg, PauliStr str, qreal angle);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplyPauliGadget(Qureg qureg, PauliStr str, qreal angle);
+
+
 /** @notyetdoced
  * 
  * @formulae
@@ -1929,6 +2097,12 @@ extern "C" {
 void multiplyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle);
+
+
 /** @notyetdoced
  * 
  * @formulae
@@ -2201,6 +2375,14 @@ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal
 void multiplyPhaseGadget(Qureg qureg, std::vector<int> targets, qreal angle);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+/// @cppvectoroverload
+/// @see postMultiplyPhaseGadget()
+void postMultiplyPhaseGadget(Qureg qureg, std::vector<int> targets, qreal angle);
+
+
 /// @notyettested
 /// @notyetvalidated
 /// @notyetdoced
@@ -2273,6 +2455,12 @@ extern "C" {
 void multiplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace);
+
+
 /** @notyettested
  * 
  * Effects (an approximation to) the exponential of @p sum, weighted by @p angle, upon @p qureg,
@@ -2558,6 +2746,12 @@ extern "C" {
 void multiplyMultiQubitNot(Qureg qureg, int* targets, int numTargets);
 
 
+/// @notyetdoced
+/// @notyettested
+/// @notyetvalidated
+void postMultiplyMultiQubitNot(Qureg qureg, int* targets, int numTargets);
+
+
 /// @notyetdoced
 void applyMultiQubitNot(Qureg qureg, int* targets, int numTargets);
 
@@ -2592,6 +2786,14 @@ void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* sta
 void multiplyMultiQubitNot(Qureg qureg, std::vector<int> targets);
 
 
+/// @notyettested
+/// @notyetvalidated
+/// @notyetdoced
+/// @cppvectoroverload
+/// @see postMultiplyMultiQubitNot()
+void postMultiplyMultiQubitNot(Qureg qureg, std::vector<int> targets);
+
+
 /// @notyettested
 /// @notyetvalidated
 /// @notyetdoced