From 4a4bdac205c6ee4fe57aae8322868284106c49e5 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Sun, 13 Apr 2025 17:47:12 +0200 Subject: [PATCH 01/21] removed references to defunct invalidQuESTInputError replacing with a temporary @validationerror doxygen ALIAS while we figure out how to refer to the new user-set error function --- quest/include/calculations.h | 5 +++-- quest/include/operations.h | 4 ++-- utils/docs/Doxyfile | 1 + 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/quest/include/calculations.h b/quest/include/calculations.h index 54ff5ed9b..9c208ebbc 100644 --- a/quest/include/calculations.h +++ b/quest/include/calculations.h @@ -89,7 +89,7 @@ extern "C" { * @param[in] qureg the reference state. * @param[in] str the observable operator. * @returns The real component of the expectation value. - * @throws invalidQuESTInputError() + * @throws @validationerror * - if @p qureg is uninitialised. * - if @p str contains a (non-identity) Pauli upon a higher-index qubit than exists in @p qureg. * - if the output (with unreturned imaginary component) is not approximately real. @@ -145,10 +145,11 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str); qreal expec = calcExpecPauliStrSum(qureg, sum); reportScalar("expec", expec); * ``` + * * @param[in] qureg the reference state. * @param[in] sum the observable operator. * @returns The real component of the expectation value. - * @throws invalidQuESTInputError() + * @throws @validationerror * - if @p qureg or @p sum are uninitialised. * - if any PauliStr in @p sum targets a higher-index qubit than exists in @p qureg. * - if @p sum is not approximately Hermitian. diff --git a/quest/include/operations.h b/quest/include/operations.h index d4e208a12..b12fc272a 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -81,7 +81,7 @@ extern "C" { * @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 multiply. - * @throws invalidQuESTInputError() + * @throws @validationerror * - if @p qureg or @p matrix are uninitialised. * - if @p target is an invalid qubit index. * @see @@ -153,7 +153,7 @@ digraph { * @param[in,out] qureg the state to modify. * @param[in] target the index of the target qubit. * @param[in] matrix the Z-basis unitary matrix to effect. - * @throws invalidQuESTInputError() + * @throws @validationerror * - if @p qureg or @p matrix are uninitialised. * - if @p matrix is not approximately unitary. * - if @p target is an invalid qubit index. diff --git a/utils/docs/Doxyfile b/utils/docs/Doxyfile index 4a721e1c8..b8abebb12 100644 --- a/utils/docs/Doxyfile +++ b/utils/docs/Doxyfile @@ -307,6 +307,7 @@ ALIASES += "equivalence=@par Equivalences" ALIASES += "constraints=@par Constraints" ALIASES += "formulae=@par Formulae" ALIASES += "diagram=@par Diagram" +ALIASES += "validationerror=error" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For From 35dccbfc6dcf8e70c5ba7ece90812fb67631a299 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 14 Apr 2025 09:42:40 +0200 Subject: [PATCH 02/21] added essential qureg-alloc docs --- quest/include/qureg.h | 280 +++++++++++++++++++++++++++++++++++++++++- utils/docs/Doxyfile | 2 +- 2 files changed, 276 insertions(+), 6 deletions(-) diff --git a/quest/include/qureg.h b/quest/include/qureg.h index 1ef8a43c0..12003facf 100644 --- a/quest/include/qureg.h +++ b/quest/include/qureg.h @@ -90,23 +90,293 @@ typedef struct { */ -/// @notdoced +/** Creates a statevector containing @p numQubits qubits, with automatically chosen deployments, + * initialised in the zero state. + * + * The chosen deployments (multithreading, GPU-acceleration and distribution) are informed by + * which facilities are compiled, available at runtime, beneficial for the specified Qureg size, + * and whether the necessary additional memory structures can fit in accelerators and buffers. + * + * @par State + * Let @f$ N = @f$ @p numQubits. The returned Qureg contains @f$ 2^N @f$ amplitudes, each represented + * by a @c qcomp, initialised to state + * @f[ + \ket{0}^{\otimes N} + \;\; = \;\; + \{ 1, \, 0, \, 0, \, \dots, \, 0 \}. + * @f] + * + * @par Memory + * The total allocated memory will depend upon the automatically chosen deployments, since + * use of GPU-acceleration requires persistent device memory and distribution necessitates + * allocating communication buffers. See createCustomQureg() for more information. + * + * @equivalence + * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=0 and @c -1 + * for all deployments to automate them. + * ``` + Qureg qureg = createCustomQureg(numQubits, 0, -1, -1, -1); + * ``` + * @myexample + * ``` + Qureg qureg = createQureg(30); + reportQuregParams(qureg); + * ``` + * @param[in] numQubits the number of qubits in the output Qureg. + * @returns A new Qureg instance. + * @throws @validationerror + * - if @p numQubits < 1 + * - if the Qureg dimensions would overflow the @c qindex type. + * - if the total Qureg memory would overflow the @c size_t type. + * - if the system contains insufficient RAM (or VRAM) to store the Qureg in any deployment. + * - if any memory allocation unexpectedly fails. + * @notvalidated + * @see + * - createDensityQureg() to create a density matrix which can additionally undergo decoherence. + * - createForcedQureg() to create a statevector which is forced to make use of all available deployments. + * - createCustomQureg() to explicitly set the used deployments. + * @author Tyson Jones + */ Qureg createQureg(int numQubits); -/// @notdoced +/** Creates a density matrix containing @p numQubits qubits, with automatically chosen deployments, + * initialised in the zero state. + * + * The chosen deployments (multithreading, GPU-acceleration and distribution) are informed by + * which facilities are compiled, available at runtime, beneficial for the specified Qureg size, + * and whether the necessary additional memory structures can fit in accelerators and buffers. + * + * @par State + * Let @f$ N = @f$ @p numQubits. The returned Qureg contains @f$ 2^N \times 2^N @f$ amplitudes, each + * represented by a @c qcomp, initialised to state + * @f[ + \ket{0}\bra{0}^{\otimes N} + \;\; = \;\; + \begin{pmatrix} + 1 & 0 & \dots \\ + 0 & 0 & \\ + \vdots & & \ddots + \end{pmatrix}. + * @f] + * + * @par Memory + * A density matrix contains _square_ as many amplitudes as the equal-dimension statevector. + * The total allocated memory will depend upon the automatically chosen deployments, since + * use of GPU-acceleration requires persistent device memory and distribution necessitates + * allocating communication buffers. See createCustomQureg() for more information. + * + * @equivalence + * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=1 and @c -1 + * for all deployments to automate them. + * ``` + Qureg qureg = createCustomQureg(numQubits, 1, -1, -1, -1); + * ``` + * @myexample + * ``` + Qureg qureg = createDensityQureg(15); + reportQuregParams(qureg); + * ``` + * @param[in] numQubits the number of qubits in the output Qureg. + * @returns A new Qureg instance. + * @throws @validationerror + * - if @p numQubits < 1 + * - if the Qureg dimensions would overflow the @c qindex type. + * - if the total Qureg memory would overflow the @c size_t type. + * - if the system contains insufficient RAM (or VRAM) to store the Qureg in any deployment. + * - if any memory allocation unexpectedly fails. + * @notvalidated + * @see + * - createQureg() to create a quadratically-smaller statevector Qureg which cannot undergo decoherence. + * - createForcedDensityQureg() to create a density matrix which is forced to make use of all available deployments. + * - createCustomQureg() to explicitly set the used deployments. + * @author Tyson Jones + */ Qureg createDensityQureg(int numQubits); -/// @notdoced +/** @notdoced + * + * @equivalence + * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=0 and all + * deployments enabled by the QuEST environment. + * ``` + QuESTEnv env = getQuESTEnv(); + Qureg qureg = createCustomQureg( + numQubits, 0, + env.isDistributed, + env.isGpuAccelerated, + env.isMultithreaded); + * ``` + */ Qureg createForcedQureg(int numQubits); -/// @notdoced +/** @notdoced + * + * @equivalence + * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=1 and all + * deployments enabled by the QuEST environment. + * ``` + QuESTEnv env = getQuESTEnv(); + Qureg qureg = createCustomQureg( + numQubits, 1, + env.isDistributed, + env.isGpuAccelerated, + env.isMultithreaded); + * ``` + */ Qureg createForcedDensityQureg(int numQubits); -/// @notdoced +/** Creates a statevector or density matrix with the specified deployments, initialised + * in the zero state. This function is an alternative to createQureg() and createDensityQureg() + * which permits explicitly forcing, disabling, or automating particular deployments. + * + * @par State + * Parameters @p numQubits and @p isDensMatr respectively inform the dimension of the + * Qureg, and whether the Qureg is a density matrix or statevector. + * + * Let @f$ N = @f$ @p numQubits. + * - When @p isDensMatr=0, the returned statevector contains @f$ 2^N @f$ amplitudes, + * initialised to state + * @f[ + \ket{0}^{\otimes N} + \;\; = \;\; + \{ 1, \, 0, \, 0, \, \dots, \, 0 \}. + * @f] + * - When @p isDensMatr=1, the returned density matrix contains @f$ 2^{N}\times 2^{N} @f$ amplitudes, + * initialised to state + * @f[ + \ket{0}\bra{0}^{\otimes N} + \;\; = \;\; + \begin{pmatrix} + 1 & 0 & \dots \\ + 0 & 0 & \\ + \vdots & & \ddots + \end{pmatrix}. + * @f] + * + * @par Deployments + * The remaining parameters decide the deployments used to accelerate the Qureg in subsequent + * simulation, and the associated additional memory allocations. + * - @p useDistrib indicates whether (@c =1) or not (@c =0) to distribute the Qureg's amplitudes + * across all available MPI nodes. This is suitable for Qureg which are too large to fit into a + * single node, and requires allocating an additional communication buffer per-node. When + * @c useDistrib=0 but the QuEST executable is launched in distributed settings, the Qureg + * amplitudes will be duplicated upon every node. + * - @p useGpuAccel indicates whether (@c =1) or not (@c =0) to GPU-accelerate the Qureg, and + * requires allocating additional persistent memory in the GPU VRAM. When combined with + * @c useDistrib=1, every node will allocate both communication buffers _and_ persistent GPU + * memory, and an additional persistent GPU-memory communication buffer. + * - @p useMultithread indicates whether (@c =1) or not (@c =0) to use multithreading when + * subsequently modifying the Qureg with a CPU routine. This requires no additional allocations, + * and typically has no effect when GPU acceleration is also enabled. + * + * The deployment parameters can also be @c -1 to let QuEST choose that parameter, taking into + * account the other forced deployments. While it is always safe to _disable_ a deployment, + * forcing a deployment which is invalid (e.g. because the device has insufficient free memory) + * will throw a validation error. + * + * @par Memory + * The total allocated memory depends on all parameters (_except_ + * @p useMultithread), and the size of the variable-precision @c qcomp used to represent each + * amplitude. This is determined by preprocessor @c FLOAT_PRECISION via + * + *
+ * | @c FLOAT_PRECISION | @c qcomp size (bytes) | + * | --- | --- | + * | 1 | 8 | + * | 2 | 16 | + * | 4 | 16, 20, 32 | + *
+ * where the quad-precision size is platform specific, and is often the size of _two_ + * `long double` primitives. + * + * Let: + * - @f$ N = @f$ @p numQubits + * - @f$ D=2^N @f$ or @f$ =2^{2N} @f$ (the total number of amplitudes in the state) + * - @f$ B = @f$ @c sizeof(qcomp) (the size in bytes) + * - @f$ W @f$ be the total number of distributed nodes (the "world size"). + * + * The allocated CPU memory (RAM) and GPU memory (VRAM) is + * + *
+ * | @p useDistrib | @p useGpuAccel | RAM per node | RAM total | VRAM per node | VRAM total | memory total | + * |---|---|---|---|---|---|---| + * | 0 | 0 | @f$ B \, D @f$ | @f$ W B \, D @f$ | 0 | 0 | @f$ W B \, D @f$ | + * | 0 | 1 | @f$ B \, D @f$ | @f$ W B \, D @f$ | @f$ B \, D @f$ | @f$ W B \, D @f$ | @f$ 2 \, W B \, D @f$ | + * | 1 | 0 | @f$ 2 \, B \, D \, / \, W @f$ | @f$ 2 \, B \, D @f$ | 0 | 0 | @f$ 2 \, B \, D @f$ | + * | 1 | 1 | @f$ 2 \, B \, D \, / \, W @f$ | @f$ 2 \, B \, D @f$ | @f$ 2 \, B \, D \, / \, W @f$ | @f$ 2 \, B \, D @f$ | @f$ 4 \, B \, D @f$ | + *
+ * + * For illustration, using the default @c FLOAT_PRECISION=2 whereby @f$ B = 16 @f$ bytes, the RAM _per node_ + * over varying distributions is: + * + *
+ * | @p isDensMatr | @p numQubits | @f$ W=1 @f$ | @f$ W=2 @f$ | @f$ W=4 @f$ | @f$ W=8 @f$ | @f$ W=16 @f$ | @f$ W=1024 @f$ | + * | ------------- | ------------ | ----------- | ----------- | ----------- | ----------- | ------------ | ------------ | + * | 0 | 20 | 16 MiB | 16 MiB | 8 MiB | 4 MiB | 2 MiB | 32 KiB | + * | 0 | 30 | 16 GiB | 16 GiB | 8 GiB | 4 GiB | 2 GiB | 32 MiB | + * | 0 | 35 | 512 GiB | 512 GiB | 256 GiB | 128 GiB | 64 GiB | 1 GiB | + * | 0 | 40 | 16 TiB | 16 TiB | 8 TiB | 4 TiB | 2 TiB | 32 GiB | + * | 0 | 45 | 512 TiB | 512 TiB | 256 TiB | 128 TiB | 64 TiB | 1 TiB | + * | 0 | 50 | 16 PiB | 16 PiB | 8 PiB | 4 PiB | 2 PiB | 32 TiB | + * | 1 | 10 | 16 MiB | 16 MiB | 8 MiB | 4 MiB | 2 MiB | 32 KiB | + * | 1 | 15 | 16 GiB | 16 GiB | 8 GiB | 4 GiB | 2 GiB | 32 MiB | + * | 1 | 20 | 16 TiB | 16 TiB | 8 TiB | 4 TiB | 2 TiB | 32 GiB | + * | 1 | 25 | 16 PiB | 16 PiB | 8 PiB | 4 PiB | 2 PiB | 32 TiB | + *
+ * + * @constraints + * - Cannot use any deployment which has not been prior enabled during compilation, or disabled by createCustomQuESTEnv(). + * - Cannot distribute @f$ N @f$ qubits over more than @f$ 2^N @f$ nodes (regardless of @p isDensMatr). + * - Cannot distribute when the executable was not launched using MPI (e.g. via @c mpirun). + * - Cannot GPU-accelerate when a GPU is not available at runtime, or has insufficient memory. + * + * @myexample + * ``` + int numQubits = 30; + int isDensMatr = 0; + + int useDistrib = 1; // use distribution + int useMultithread = 0; // don't use multithreading + int useGpuAccel = -1; // automate whether to GPU-accelerate + + Qureg qureg = createCustomQureg( + numQubits, isDensMatr, + useDistrib, useGpuAccel, useMultithread); + + reportQuregParams(qureg); + * ``` + * + * @param[in] numQubits the number of qubits in the output Qureg. + * @param[in] isDensMatr whether the Qureg is a density matrix (@c =1) or statevector (@c =0). + * @param[in] useDistrib whether to force (@c =1), disable (@c =0) or automate (@c =-1) distribution. + * @param[in] useGpuAccel whether to force (@c =1), disable (@c =0) or automate (@c =-1) GPU acceleration. + * @param[in] useMultithread whether to force (@c =1), disable (@c =0) or automate (@c =-1) multithreading. + * @returns A new Qureg instance of the specified dimension and deployments. + * @throws @validationerror + * - if @p numQubits < 1 + * - if @p isDensMatr is not @c 0 or @c 1 + * - if any of @p useDistrib, @p useGpuAccel, @p useMultithread is not @c 0, @c 1 or @c -1. + * - if any of @p useDistrib, @p useGpuAccel, @p useMultithread is forced (@c =1) but is unsupported by the + * active QuESTEnv. This can happen because: + * - the particular deployment was disabled by initCustomQuESTEnv(). + * - the deployment was not enabled during compilation. + * - @p useDistrib=1 but QuEST was not launched by MPI (e.g. via @c mpirun). + * - @p useGpuAccel=1 but a GPU is not accessible at runtime. + * - if @p useDistrib=1 but the Qureg is too small to distribute over the running nodes. + * - if the Qureg dimensions would overflow the @c qindex type. + * - if the total Qureg memory would overflow the @c size_t type. + * - if the system contains insufficient RAM (or VRAM) to store the Qureg. + * - if any memory allocation unexpectedly fails. + * @notvalidated + * @see + * - createQureg() to automate deployments (equivalent to passing @c -1). + * - createForcedQureg() to use all available deployments. + * @author Tyson Jones + */ Qureg createCustomQureg(int numQubits, int isDensMatr, int useDistrib, int useGpuAccel, int useMultithread); diff --git a/utils/docs/Doxyfile b/utils/docs/Doxyfile index b8abebb12..893c02d41 100644 --- a/utils/docs/Doxyfile +++ b/utils/docs/Doxyfile @@ -296,7 +296,7 @@ TAB_SIZE = 4 ALIASES = ALIASES += "nottested=@warning This function has not yet been unit tested and may contain bugs. Please use with caution!" -ALIASES += "notvalidated=@attention This function's input validation has not yet been tested, so erroneous usage may produce unexpected output. Please use with caution!" +ALIASES += "notvalidated=@attention This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!" ALIASES += "notdoced=@note Documentation for this function or struct is under construction!" ALIASES += "cpponly=@remark This function is only available in C++." ALIASES += "conly=@remark This function is only available in C." From 39db589d13a11a8513372fce171a13a2498145ae Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Tue, 22 Apr 2025 00:06:30 +0200 Subject: [PATCH 03/21] added note to setMaxNumReportedSigFigs --- quest/include/debug.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/quest/include/debug.h b/quest/include/debug.h index 5febafa46..719b651b0 100644 --- a/quest/include/debug.h +++ b/quest/include/debug.h @@ -113,7 +113,11 @@ qreal getValidationEpsilon(); void setMaxNumReportedItems(qindex numRows, qindex numCols); -/// @notdoced +/** @notdoced + * > This function does not affect the significant figures in printed memory sizes + * > (e.g. `5.32 KiB`) which is always shown with three significant figures + * > (or four when in bytes, e.g. `1023 bytes`). + */ void setMaxNumReportedSigFigs(int numSigFigs); From 070a24e256cc687e1944720e2b1732d77c32bccb Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Sat, 3 May 2025 23:11:50 +0200 Subject: [PATCH 04/21] corrected function-name typo in internal error message --- quest/src/core/errors.cpp | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/quest/src/core/errors.cpp b/quest/src/core/errors.cpp index b22b48c25..a2c2649ca 100644 --- a/quest/src/core/errors.cpp +++ b/quest/src/core/errors.cpp @@ -381,42 +381,42 @@ void assert_bufferPackerGivenIncreasingQubits(int qubit1, int qubit2, int qubit3 void assert_mixedQuregIsDensityMatrix(Qureg qureg) { if (!qureg.isDensityMatrix) - raiseInternalError("An internal function invoked by mixQuregs() received a statevector where a density matrix was expected."); + raiseInternalError("An internal function invoked by mixQureg() received a statevector where a density matrix was expected."); } void assert_mixedQuregIsStatevector(Qureg qureg) { if (qureg.isDensityMatrix) - raiseInternalError("An internal function invoked by mixQuregs() received a density matrix where a statevector was expected."); + raiseInternalError("An internal function invoked by mixQureg() received a density matrix where a statevector was expected."); } void assert_mixedQuregIsDistributed(Qureg qureg) { if (!qureg.isDistributed) - raiseInternalError("An internal function invoked by mixQuregs() received a non-distributed Qureg where a distributed one was expected."); + raiseInternalError("An internal function invoked by mixQureg() received a non-distributed Qureg where a distributed one was expected."); } void assert_mixedQuregIsLocal(Qureg qureg) { if (qureg.isDistributed) - raiseInternalError("An internal function invoked by mixQuregs() received a distributed Qureg where a non-distributed one was expected."); + raiseInternalError("An internal function invoked by mixQureg() received a distributed Qureg where a non-distributed one was expected."); } void assert_mixedQuregsAreBothOrNeitherDistributed(Qureg a, Qureg b) { if (a.isDistributed != b.isDistributed) - raiseInternalError("An internal function invoked by mixQuregs() received density-matrix Quregs of inconsistent distribution."); + raiseInternalError("An internal function invoked by mixQureg() received density-matrix Quregs of inconsistent distribution."); } void assert_mixQuregTempGpuAllocSucceeded(qcomp* gpuPtr) { if (!mem_isAllocated(gpuPtr)) - raiseInternalError("An internal function invoked by mixQuregs() attempted to allocate temporary GPU memory but failed."); + raiseInternalError("An internal function invoked by mixQureg() attempted to allocate temporary GPU memory but failed."); } void error_mixQuregsAreLocalDensMatrAndDistribStatevec() { - raiseInternalError("An internal function invoked by mixQuregs() received a non-distributed density matrix and a distributed statevector, which is an illegal combination."); + raiseInternalError("An internal function invoked by mixQureg() received a non-distributed density matrix and a distributed statevector, which is an illegal combination."); } void assert_fullStateDiagMatrIsLocal(FullStateDiagMatr matr) { From 3e96b795a275e6eef1171fb970e6edda9e860be8 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Sun, 4 May 2025 00:24:03 +0200 Subject: [PATCH 05/21] renamed @equivalent to @equivalences since the section gives a list of equivalent functions --- quest/include/calculations.h | 4 ++-- quest/include/qureg.h | 8 ++++---- utils/docs/Doxyfile | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/quest/include/calculations.h b/quest/include/calculations.h index 9c208ebbc..b6c39930d 100644 --- a/quest/include/calculations.h +++ b/quest/include/calculations.h @@ -69,7 +69,7 @@ extern "C" { * which case the imaginary component of the above expression is neglected. * The full complex value can be obtained using calcExpecNonHermitianPauliStrSum(). * - * @equivalence + * @equivalences * - When @p str is general, this function is equivalent to calling calcExpecPauliStrSum() with a * PauliStrSum composed of only a single PauliStr term and a unity coefficient. * - When @p str @f$ = \id^\otimes @f$, the output is equivalent to that of calcTotalProb(). @@ -125,7 +125,7 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str); * Hermiticity validation is relaxed and/or @p qureg is an unnormalised density matrix. * The full complex value can be obtained using calcExpecNonHermitianPauliStrSum(). * - * @equivalence + * @equivalences * - This function is mathematically equivalent to (albeit faster than) calling calcExpecPauliStr() upon * each constituent @p PauliStr within @p sum, weighting each by its corresponding coefficient, and * summing the outputs. diff --git a/quest/include/qureg.h b/quest/include/qureg.h index 12003facf..2c3d1a1d4 100644 --- a/quest/include/qureg.h +++ b/quest/include/qureg.h @@ -111,7 +111,7 @@ typedef struct { * use of GPU-acceleration requires persistent device memory and distribution necessitates * allocating communication buffers. See createCustomQureg() for more information. * - * @equivalence + * @equivalences * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=0 and @c -1 * for all deployments to automate them. * ``` @@ -166,7 +166,7 @@ Qureg createQureg(int numQubits); * use of GPU-acceleration requires persistent device memory and distribution necessitates * allocating communication buffers. See createCustomQureg() for more information. * - * @equivalence + * @equivalences * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=1 and @c -1 * for all deployments to automate them. * ``` @@ -197,7 +197,7 @@ Qureg createDensityQureg(int numQubits); /** @notdoced * - * @equivalence + * @equivalences * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=0 and all * deployments enabled by the QuEST environment. * ``` @@ -214,7 +214,7 @@ Qureg createForcedQureg(int numQubits); /** @notdoced * - * @equivalence + * @equivalences * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=1 and all * deployments enabled by the QuEST environment. * ``` diff --git a/utils/docs/Doxyfile b/utils/docs/Doxyfile index 893c02d41..2f2c41710 100644 --- a/utils/docs/Doxyfile +++ b/utils/docs/Doxyfile @@ -303,7 +303,7 @@ ALIASES += "conly=@remark This function is only available in C." ALIASES += "macrodoc=@note This entity is actually a macro." ALIASES += "neverdoced=@warning This entity is a macro, undocumented directly due to a Doxygen limitation. If you see this doc rendered, contact the devs!" ALIASES += "myexample=@par Example" -ALIASES += "equivalence=@par Equivalences" +ALIASES += "equivalences=@par Equivalences" ALIASES += "constraints=@par Constraints" ALIASES += "formulae=@par Formulae" ALIASES += "diagram=@par Diagram" From cea792d703fb8d9109712bfb1a41d27fc9d9f2c3 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Sun, 4 May 2025 00:24:48 +0200 Subject: [PATCH 06/21] added doc stubs to decoherence functions where it's urgent to give their explicit formula to avoid ambiguity --- quest/include/decoherence.h | 301 +++++++++++++++++++++++++++++++++--- 1 file changed, 279 insertions(+), 22 deletions(-) diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index c6b55d6ab..033083449 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -28,38 +28,295 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated -void mixDephasing(Qureg qureg, int qubit, qreal prob); -/// @notdoced -/// @notvalidated -void mixTwoQubitDephasing(Qureg qureg, int qubit1, int qubit2, qreal prob); +/** @notdoced + * + * @formulae + * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob and @f$ t = @f$ @p target. + * + * This function effects + * @f[ + \dmrho \rightarrow (1 - p) \, \dmrho + p \, \hat{Z}_t \,\dmrho\, \hat{Z}_t. + * @f] + * + * @equivalences + * This function is equivalent to (but much faster than): + * - mixPaulis() with a zero probability for the @f$\hat{X}@f$ and @f$\hat{Y}@f$ components. + * ``` + mixPaulis(qureg, target, 0, 0, prob); + * ``` + * - mixKrausMap() with (scaled) @f$\hat{\id}@f$ and @f$\hat{Z}@f$ Kraus operators. + * ``` + qreal a = sqrt(1-prob); + qreal b = sqrt(prob); -/// @notdoced -/// @notvalidated -void mixDepolarising(Qureg qureg, int qubit, qreal prob); + KrausMap map = createInlineKrausMap(1, 2, { + {{a,0},{0, a}}, // a * I + {{b,0},{0,-b}} // b * Z + }); + + mixKrausMap(qureg, &target, 1, map); + * ``` + * - mixQureg() with a duplicated Qureg modified under applyPauliZ(). + * ``` + Qureg clone = createCloneQureg(qureg); + applyPauliZ(clone); + mixQureg(qureg, other, prob); + * ``` + * + * @notvalidated + */ +void mixDephasing(Qureg qureg, int target, qreal prob); -/// @notdoced -/// @notvalidated -void mixTwoQubitDepolarising(Qureg qureg, int qubit1, int qubit2, qreal prob); -/// @notdoced -/// @notvalidated -void mixDamping(Qureg qureg, int qubit, qreal prob); +/** @notdoced + * + * @formulae + * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob, @f$ t_1 = @f$ @p target1 and @f$ t_2 = @f$ @p target2. + * + * This function effects + * @f[ + \dmrho \rightarrow (1 - p) \, \dmrho + \frac{1}{3} p \left( + \hat{Z}_{t_1} \dmrho \hat{Z}_{t_1} + + \hat{Z}_{t_1} \dmrho \hat{Z}_{t_1} + + \hat{Z}_{t_1} \hat{Z}_{t_2} \dmrho \hat{Z}_{t_1} \hat{Z}_{t_2} + \right). + * @f] + * + * @equivalences + * This function is equivalent to (but much faster than): + * - mixKrausMap() with @f$c_1\,\hat{\id}\otimes\hat{\id}@f$, @f$c_2\,\hat{\id}\otimes\hat{Z}@f$, + * @f$c_2\,\hat{Z}\otimes\hat{\id}@f$ and @f$c_2\,\hat{Z}\otimes\hat{Z}@f$ Kraus operators. + * ``` + qreal a = sqrt(1-prob); + qreal b = sqrt(prob/3); -/// @notdoced -/// @notvalidated -void mixPaulis(Qureg qureg, int qubit, qreal probX, qreal probY, qreal probZ); + KrausMap map = createInlineKrausMap(2, 4, { + {{a,0,0,0},{0, a,0,0},{0,0, a,0},{0,0,0, a}}, // a * II + {{b,0,0,0},{0,-b,0,0},{0,0, b,0},{0,0,0,-b}}, // b * IZ + {{b,0,0,0},{0, b,0,0},{0,0,-b,0},{0,0,0,-b}}, // b * ZI + {{b,0,0,0},{0,-b,0,0},{0,0,-b,0},{0,0,0, b}} // b * ZZ + }); + + int targets[] = {target1, target2}; + mixKrausMap(qureg, targets, 2, map); + * ``` + * + * @notvalidated + */ +void mixTwoQubitDephasing(Qureg qureg, int target1, int target2, qreal prob); -/// @notdoced -/// @notvalidated + +/** @notdoced + * + * @formulae + * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob and @f$ t = @f$ @p target. + * + * This function effects + * @f[ + \dmrho \rightarrow (1 - p) \, \dmrho + \frac{1}{3} p \left( + \hat{X}_t \dmrho \hat{X}_t + + \hat{Y}_t \dmrho \hat{Y}_t + + \hat{Z}_t \dmrho \hat{Z}_t + \right). + * @f] + * + * @equivalences + * This function is equivalent to (but much faster than): + * - mixPaulis() with a uniform probability. + * ``` + mixPaulis(qureg, target, prob/3, prob/3, prob/3); + * ``` + * - mixKrausMap() with (scaled) @f$\hat{\id}@f$, @f$\hat{X}@f$, @f$\hat{Y}@f$ and @f$\hat{Z}@f$ Kraus operators. + * ``` + qreal a = sqrt(1-prob); + qreal b = sqrt(prob/3); + + KrausMap map = createInlineKrausMap(1, 4, { + {{a,0},{0, a}}, // a * I + {{0,b},{b, 0}}, // b * X + {{b,0},{0,-b}} // b * Z + {{0,-1i*b},{1i*b,0}}, // b * Y + }); + + mixKrausMap(qureg, &target, 1, map); + * ``` + * + * @notvalidated + */ +void mixDepolarising(Qureg qureg, int target, qreal prob); + + +/** @notdoced + * + * @formulae + * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob, @f$ t_1 = @f$ @p target1 and @f$ t_2 = @f$ @p target2. + * + * This function effects: + * @f[ + \dmrho \; \rightarrow \; + (1 - p) \dmrho + + + \frac{p}{15} \left( + \sum_{\hat{\sigma} \in \{\hat{\id},\hat{X},\hat{Y},\hat{Z}\}} + \sum_{\hat{\sigma}' \in \{\hat{\id},\hat{X},\hat{Y},\hat{Z}\}} + \hat{\sigma}_{t_1} \hat{\sigma}_{t_2}' + \; \dmrho \; + \hat{\sigma}_{t_1} \hat{\sigma}_{t_2}' + \right) + - \frac{p}{15} \hat{\id}_{t_1} \hat{\id}_{t_2} \dmrho \hat{\id}_{t_1} \hat{\id}_{t_2}, + * @f] + * + * or verbosely: + * + * @f[ + \dmrho \; \rightarrow \; + (1 - p) \, \rho + \frac{p}{15} \; + \left( + \begin{gathered} + \hat{X}_{t_1} \, \rho \, \hat{X}_{t_1} + + \hat{Y}_{t_1} \, \rho \, \hat{Y}_{t_1} + + \hat{Z}_{t_1} \, \rho \, \hat{Z}_{t_1} + + \\ + \hat{X}_{t_2} \, \rho \, \hat{X}_{t_2} + + \hat{Y}_{t_2} \, \rho \, \hat{Y}_{t_2} + + \hat{Z}_{t_2} \, \rho \, \hat{Z}_{t_2} + + \\ + \hat{X}_{t_1} \hat{X}_{t_2} \, \rho \, \hat{X}_{t_1} \hat{X}_{t_2} + + \hat{Y}_{t_1} \hat{Y}_{t_2} \, \rho \, \hat{Y}_{t_1} \hat{Y}_{t_2} + + \hat{Z}_{t_1} \hat{Z}_{t_2} \, \rho \, \hat{Z}_{t_1} \hat{Z}_{t_2} + + \\ + \hat{X}_{t_1} \hat{Y}_{t_2} \, \rho \, \hat{X}_{t_1} \hat{Y}_{t_2} + + \hat{Y}_{t_1} \hat{Z}_{t_2} \, \rho \, \hat{Y}_{t_1} \hat{Z}_{t_2} + + \hat{Z}_{t_1} \hat{X}_{t_2} \, \rho \, \hat{Z}_{t_1} \hat{X}_{t_2} + + \\ + \hat{X}_{t_1} \hat{Z}_{t_2} \, \rho \, \hat{X}_{t_1} \hat{Z}_{t_2} + + \hat{Y}_{t_1} \hat{X}_{t_2} \, \rho \, \hat{Y}_{t_1} \hat{Z}_{t_2} + + \hat{Z}_{t_1} \hat{Y}_{t_2} \, \rho \, \hat{Z}_{t_1} \hat{Y}_{t_2} + \end{gathered} + \right). + * @f] + * + * @equivalences + * This function is equivalent to (but much faster than): + * - mixKrausMap() with Kraus operators containing every possible tensor product + * of two Pauli matrices, all scaled by @f$ (p/15)^{1/2} @f$, _except_ for + * @f$ \hat{\id} \otimes \hat{\id} @f$ which is scaled by @f$ (1-16p/15)^{1/2} @f$. + * + * @notvalidated + */ +void mixTwoQubitDepolarising(Qureg qureg, int target1, int target2, qreal prob); + + +/** @notdoced + * + * @formulae + * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob and @f$ t = @f$ @p target. + * + * This function effects + * @f[ + \dmrho \; \rightarrow \; + \hat{K}_t^{(1)} \dmrho \, {\hat{K}_t^{(2)}}^\dagger + + \hat{K}_t^{(2)} \dmrho \, {\hat{K}_t^{(2)}}^\dagger + * @f] + * where @f$ \hat{K}^{(1)} @f$ and @f$ \hat{K}^{(2)} @f$ are one-qubit Kraus operators + * @f[ + \hat{K}^{(1)} = \begin{pmatrix} 1 & 0 \\ 0 & \sqrt{1-p} \end{pmatrix}, + \;\; + \hat{K}^{(1)} = \begin{pmatrix} 0 & \sqrt{p} \\ 0 & 0 \end{pmatrix}. + * @f] + * + * @equivalences + * This function is equivalent to (but much faster than): + * - mixKrausMap() with the above Kraus operators. + * ``` + KrausMap map = createInlineKrausMap(1, 2, { + {{1,0},{0,sqrt(1-prob)}}, // K1 + {{0,sqrt(p)},{0,0}} // K2 + }); + + mixKrausMap(qureg, &target, 1, map); + * ``` + * + * @notvalidated + */ +void mixDamping(Qureg qureg, int target, qreal prob); + + +/** @notdoced + * + * @formulae + * Let @f$ \dmrho = @f$ @p qureg, @f$ t = @f$ @p target, and + * @f$ p_x = @f$ @p probX, @f$ p_y = @f$ @p probY, @f$ p_z = @f$ @p probZ. + * + * This function effects + * @f[ + \dmrho \rightarrow (1 - p) \, \dmrho + p \left( + p_x \, \hat{X}_t \dmrho \hat{X}_t + + p_y \, \hat{Y}_t \dmrho \hat{Y}_t + + p_z \, \hat{Z}_t \dmrho \hat{Z}_t + \right). + * @f] + * + * @equivalences + * This function is equivalent to (but much faster than): + * - mixKrausMap() with (scaled) @f$\hat{\id}@f$, @f$\hat{X}@f$, @f$\hat{Y}@f$ and @f$\hat{Z}@f$ Kraus operators. + * ``` + qreal a = sqrt(1-probX-probY-probZ); + qreal b = sqrt(probX/3); + qreal c = sqrt(probY/3); + qreal d = sqrt(probZ/3); + + KrausMap map = createInlineKrausMap(1, 4, { + {{a,0},{0, a}}, // a * I + {{0,b},{b, 0}}, // b * X + {{d,0},{0,-d}} // d * Z + {{0,-1i*c},{1i*c,0}}, // c * Y + }); + + mixKrausMap(qureg, &target, 1, map); + * ``` + * + * @notvalidated + */ +void mixPaulis(Qureg qureg, int target, qreal probX, qreal probY, qreal probZ); + + +/** @notdoced + * + * @formulae + * Let @f$ \dmrho_1 = @f$ @p qureg, @f$ \dmrho_2 = @f$ @p other and @f$ p = @f$ @p prob. + * + * This function effects + * @f[ + \dmrho_1 \;\rightarrow \; + (1 - p) \, \dmrho_1 + + p \, \dmrho_2. + * @f] + * + * @notvalidated + */ void mixQureg(Qureg qureg, Qureg other, qreal prob); -/// @notdoced -/// @notvalidated + +/** @notdoced + * + * @formulae + * Let @f$ \dmrho = @f$ @p qureg, @f$ \vec{t} = @f$ @p targets and @f$ \hat{K}^{(i)} @f$ + * denote the @f$i@f$-th Kraus operator in @p map. + * + * This function effects + * @f[ + \dmrho \; \rightarrow \; + \sum\limits_i + \hat{K}_{\vec{t}}^{(i)} \dmrho \, {\hat{K}_{\vec{t}}^{(i)}}^\dagger + * @f] + * + * @notvalidated + */ void mixKrausMap(Qureg qureg, int* targets, int numTargets, KrausMap map); + /// @notdoced /// @notvalidated void mixSuperOp(Qureg qureg, int* targets, int numTargets, SuperOp superop); From 80a8c9cb12c55e95f7fad1c06094557caa3c9ed2 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Sun, 4 May 2025 00:32:35 +0200 Subject: [PATCH 07/21] adjusting decoherence stub spacing --- quest/include/decoherence.h | 44 +++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index 033083449..082725d05 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -36,7 +36,11 @@ extern "C" { * * This function effects * @f[ - \dmrho \rightarrow (1 - p) \, \dmrho + p \, \hat{Z}_t \,\dmrho\, \hat{Z}_t. + \dmrho + \;\rightarrow\; + (1 - p) \, \dmrho + \,+\, + p \, \hat{Z}_t \,\dmrho\, \hat{Z}_t. * @f] * * @equivalences @@ -76,9 +80,15 @@ void mixDephasing(Qureg qureg, int target, qreal prob); * * This function effects * @f[ - \dmrho \rightarrow (1 - p) \, \dmrho + \frac{1}{3} p \left( - \hat{Z}_{t_1} \dmrho \hat{Z}_{t_1} + - \hat{Z}_{t_1} \dmrho \hat{Z}_{t_1} + + \dmrho + \;\rightarrow\; + (1 - p) \, \dmrho + \,+\, + \frac{p}{3} \left( + \hat{Z}_{t_1} \dmrho \hat{Z}_{t_1} + \,+\, + \hat{Z}_{t_1} \dmrho \hat{Z}_{t_1} + \,+\, \hat{Z}_{t_1} \hat{Z}_{t_2} \dmrho \hat{Z}_{t_1} \hat{Z}_{t_2} \right). * @f] @@ -114,9 +124,10 @@ void mixTwoQubitDephasing(Qureg qureg, int target1, int target2, qreal prob); * * This function effects * @f[ - \dmrho \rightarrow (1 - p) \, \dmrho + \frac{1}{3} p \left( - \hat{X}_t \dmrho \hat{X}_t + - \hat{Y}_t \dmrho \hat{Y}_t + + \dmrho \;\rightarrow\; + (1 - p) \, \dmrho \,+\, \frac{p}{3} \left( + \hat{X}_t \dmrho \hat{X}_t \,+\, + \hat{Y}_t \dmrho \hat{Y}_t \,+\, \hat{Z}_t \dmrho \hat{Z}_t \right). * @f] @@ -216,7 +227,8 @@ void mixTwoQubitDepolarising(Qureg qureg, int target1, int target2, qreal prob); * This function effects * @f[ \dmrho \; \rightarrow \; - \hat{K}_t^{(1)} \dmrho \, {\hat{K}_t^{(2)}}^\dagger + + \hat{K}_t^{(1)} \dmrho \, {\hat{K}_t^{(2)}}^\dagger + \,+\, \hat{K}_t^{(2)} \dmrho \, {\hat{K}_t^{(2)}}^\dagger * @f] * where @f$ \hat{K}^{(1)} @f$ and @f$ \hat{K}^{(2)} @f$ are one-qubit Kraus operators @@ -251,11 +263,14 @@ void mixDamping(Qureg qureg, int target, qreal prob); * * This function effects * @f[ - \dmrho \rightarrow (1 - p) \, \dmrho + p \left( - p_x \, \hat{X}_t \dmrho \hat{X}_t + - p_y \, \hat{Y}_t \dmrho \hat{Y}_t + - p_z \, \hat{Z}_t \dmrho \hat{Z}_t - \right). + \dmrho \;\rightarrow\; + (1 - p) \, \dmrho + \,+\, + p_x \, \hat{X}_t \dmrho \hat{X}_t + \,+\, + p_y \, \hat{Y}_t \dmrho \hat{Y}_t + \,+\, + p_z \, \hat{Z}_t \dmrho \hat{Z}_t. * @f] * * @equivalences @@ -290,7 +305,8 @@ void mixPaulis(Qureg qureg, int target, qreal probX, qreal probY, qreal probZ); * This function effects * @f[ \dmrho_1 \;\rightarrow \; - (1 - p) \, \dmrho_1 + + (1 - p) \, \dmrho_1 + \,+\, p \, \dmrho_2. * @f] * From d5644a2a798685261c164073a53a84bd1498bb22 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Sun, 4 May 2025 00:35:25 +0200 Subject: [PATCH 08/21] another missed typo another embarrassing commit --- quest/include/decoherence.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index 082725d05..4dc199e80 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -95,8 +95,8 @@ void mixDephasing(Qureg qureg, int target, qreal prob); * * @equivalences * This function is equivalent to (but much faster than): - * - mixKrausMap() with @f$c_1\,\hat{\id}\otimes\hat{\id}@f$, @f$c_2\,\hat{\id}\otimes\hat{Z}@f$, - * @f$c_2\,\hat{Z}\otimes\hat{\id}@f$ and @f$c_2\,\hat{Z}\otimes\hat{Z}@f$ Kraus operators. + * - mixKrausMap() with (scaled) @f$\hat{\id}\otimes\hat{\id}@f$, @f$\hat{\id}\otimes\hat{Z}@f$, + * @f$\hat{Z}\otimes\hat{\id}@f$ and @f$\hat{Z}\otimes\hat{Z}@f$ Kraus operators. * ``` qreal a = sqrt(1-prob); qreal b = sqrt(prob/3); From 51c23d751dc9a83e9b401db03ce06db5379b9fe0 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Sun, 4 May 2025 00:38:25 +0200 Subject: [PATCH 09/21] we pray to the doc gods this is the final embarrassment --- quest/include/decoherence.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index 4dc199e80..dbecdeb96 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -278,9 +278,9 @@ void mixDamping(Qureg qureg, int target, qreal prob); * - mixKrausMap() with (scaled) @f$\hat{\id}@f$, @f$\hat{X}@f$, @f$\hat{Y}@f$ and @f$\hat{Z}@f$ Kraus operators. * ``` qreal a = sqrt(1-probX-probY-probZ); - qreal b = sqrt(probX/3); - qreal c = sqrt(probY/3); - qreal d = sqrt(probZ/3); + qreal b = sqrt(probX); + qreal c = sqrt(probY); + qreal d = sqrt(probZ); KrausMap map = createInlineKrausMap(1, 4, { {{a,0},{0, a}}, // a * I From 100c1d38932cec6a698cf5bff05f837211133851 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Wed, 7 May 2025 02:28:51 +0200 Subject: [PATCH 10/21] added doc links to example PR --- docs/architecture.md | 4 ++++ docs/contributing.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index 1ad8f3a40..9da920f2a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -7,6 +7,10 @@ @author Tyson Jones --> +> [!TIP] +> See [PR #615](https://github.com/QuEST-Kit/QuEST/pull/615) for an illustration of integrating +> new functions into the QuEST software architecture. + All user-visible API signatures are contained in `include/`, divided into semantic submodules (like `calculations.h` and `qureg.h`), but all exposed by `quest.h`. They are all strictly `C` _and_ `C++` compatible, hence their `.h` file extension. The source code within `src/` is divided between five subdirectories, listed below in order of increasing control flow depth. All code is parsed strictly by `C++`, hence all files have `.cpp` and `.hpp` extensions. diff --git a/docs/contributing.md b/docs/contributing.md index cdeb61d67..bd8ce8221 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -13,3 +13,7 @@ In the meantime, feel free to open an issue, a discussion or a pull request, or reach out to `tyson.jones.input@gmail.com`. + +> [!TIP] +> See [PR #615](https://github.com/QuEST-Kit/QuEST/pull/615) for an illustration of integrating +> new functions into the QuEST software architecture. From fae527d8a59015868637f46140e945d359fa72b2 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 12 May 2025 14:19:14 +0200 Subject: [PATCH 11/21] renaming not-yet-documented command from e.g. notdoced to notyetdoced, to reflect that this command _should_ be later replaced and removed (as opposed to neverdoced) --- quest/include/calculations.h | 92 ++--- quest/include/channels.h | 52 +-- quest/include/debug.h | 44 +- quest/include/decoherence.h | 48 +-- quest/include/environment.h | 18 +- quest/include/initialisations.h | 104 ++--- quest/include/matrices.h | 156 ++++---- quest/include/modes.h | 6 +- quest/include/operations.h | 688 ++++++++++++++++---------------- quest/include/precision.h | 12 +- quest/include/qureg.h | 60 +-- quest/include/types.h | 36 +- utils/docs/Doxyfile | 6 +- 13 files changed, 661 insertions(+), 661 deletions(-) diff --git a/quest/include/calculations.h b/quest/include/calculations.h index b6c39930d..c2cee9541 100644 --- a/quest/include/calculations.h +++ b/quest/include/calculations.h @@ -93,7 +93,7 @@ extern "C" { * - if @p qureg is uninitialised. * - if @p str contains a (non-identity) Pauli upon a higher-index qubit than exists in @p qureg. * - if the output (with unreturned imaginary component) is not approximately real. - * @notvalidated + * @notyetvalidated * @author Tyson Jones */ qreal calcExpecPauliStr(Qureg qureg, PauliStr str); @@ -154,7 +154,7 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str); * - if any PauliStr in @p sum targets a higher-index qubit than exists in @p qureg. * - if @p sum is not approximately Hermitian. * - if the output (with unreturned imaginary component) is not approximately real. -* @notvalidated +* @notyetvalidated * @see * - calcExpecNonHermitianPauliStrSum() * - calcExpecFullStateDiagMatr() @@ -163,13 +163,13 @@ qreal calcExpecPauliStr(Qureg qureg, PauliStr str); qreal calcExpecPauliStrSum(Qureg qureg, PauliStrSum sum); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcExpecFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcExpecFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matr, qreal exponent); @@ -184,23 +184,23 @@ qreal calcExpecFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matr, qreal */ -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcProbOfBasisState(Qureg qureg, qindex index); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcProbOfQubitOutcome(Qureg qureg, int qubit, int outcome); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcProbOfMultiQubitOutcome(Qureg qureg, int* qubits, int* outcomes, int numQubits); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void calcProbsOfAllMultiQubitOutcomes(qreal* outcomeProbs, Qureg qureg, int* qubits, int numQubits); @@ -215,13 +215,13 @@ void calcProbsOfAllMultiQubitOutcomes(qreal* outcomeProbs, Qureg qureg, int* qub */ -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcTotalProb(Qureg qureg); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcPurity(Qureg qureg); @@ -236,12 +236,12 @@ qreal calcPurity(Qureg qureg); */ -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcFidelity(Qureg qureg, Qureg other); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal calcDistance(Qureg qureg1, Qureg qureg2); @@ -256,13 +256,13 @@ qreal calcDistance(Qureg qureg1, Qureg qureg2); */ -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated Qureg calcPartialTrace(Qureg qureg, int* traceOutQubits, int numTraceQubits); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated Qureg calcReducedDensityMatrix(Qureg qureg, int* retainQubits, int numRetainQubits); @@ -293,26 +293,26 @@ Qureg calcReducedDensityMatrix(Qureg qureg, int* retainQubits, int numRetainQubi /// @ingroup calc_comparisons -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qcomp calcInnerProduct(Qureg qureg1, Qureg qureg2); /// @ingroup calc_expec -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qcomp calcExpecNonHermitianPauliStrSum(Qureg qureg, PauliStrSum sum); /// @ingroup calc_expec -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qcomp calcExpecNonHermitianFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr); /// @ingroup calc_expec -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent); @@ -331,33 +331,33 @@ qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr /// @ingroup calc_prob -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector qubits, std::vector outcomes); /// @ingroup calc_prob -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly std::vector calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector qubits); /// @ingroup calc_partialtrace -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly Qureg calcPartialTrace(Qureg qureg, std::vector traceOutQubits); /// @ingroup calc_partialtrace -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly Qureg calcReducedDensityMatrix(Qureg qureg, std::vector retainQubits); diff --git a/quest/include/channels.h b/quest/include/channels.h index 10d28f9aa..05ee79454 100644 --- a/quest/include/channels.h +++ b/quest/include/channels.h @@ -70,7 +70,7 @@ */ -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -97,7 +97,7 @@ typedef struct { } SuperOp; -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -177,44 +177,44 @@ extern "C" { /// @ingroup channels_create - /// @notdoced + /// @notyetdoced KrausMap createKrausMap(int numQubits, int numOperators); /// @ingroup channels_sync - /// @notdoced + /// @notyetdoced void syncKrausMap(KrausMap map); /// @ingroup channels_destroy - /// @notdoced + /// @notyetdoced void destroyKrausMap(KrausMap map); /// @ingroup channels_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportKrausMap(KrausMap map); /// @ingroup channels_create - /// @notdoced + /// @notyetdoced SuperOp createSuperOp(int numQubits); /// @ingroup channels_sync - /// @notdoced + /// @notyetdoced void syncSuperOp(SuperOp op); /// @ingroup channels_destroy - /// @notdoced + /// @notyetdoced void destroySuperOp(SuperOp op); /// @ingroup channels_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportSuperOp(SuperOp op); @@ -241,12 +241,12 @@ extern "C" { /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced void setKrausMap(KrausMap map, qcomp*** matrices); /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced void setSuperOp(SuperOp op, qcomp** matrix); @@ -279,13 +279,13 @@ extern "C" { /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setKrausMap(KrausMap map, std::vector>> matrices); /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setSuperOp(SuperOp op, std::vector> matrix); @@ -360,13 +360,13 @@ extern "C" { #if 0 /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @conly /// @macrodoc void setKrausMap(KrausMap map, qcomp matrices[map.numMatrices][map.numRows][map.numRows]); /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @conly /// @macrodoc void setSuperOp(SuperOp op, qcomp matrix[op.numRows][op.numRows]); @@ -405,13 +405,13 @@ extern "C" { /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setInlineKrausMap(KrausMap map, int numQb, int numOps, std::vector>> matrices); /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setInlineSuperOp(SuperOp op, int numQb, std::vector> matrix); @@ -460,12 +460,12 @@ extern "C" { #if 0 /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @macrodoc void setInlineKrausMap(KrausMap map, int numQb, int numOps, {{{ matrices }}}); /// @ingroup channels_setters - /// @notdoced + /// @notyetdoced /// @macrodoc void setInlineSuperOp(SuperOp op, int numQb, {{ matrix }}); @@ -495,13 +495,13 @@ extern "C" { /// @ingroup channels_create - /// @notdoced + /// @notyetdoced /// @cpponly KrausMap createInlineKrausMap(int numQubits, int numOperators, std::vector>> matrices); /// @ingroup channels_create - /// @notdoced + /// @notyetdoced /// @cpponly SuperOp createInlineSuperOp(int numQubits, std::vector> matrix); @@ -551,12 +551,12 @@ extern "C" { #if 0 /// @ingroup channels_create - /// @notdoced + /// @notyetdoced /// @macrodoc KrausMap createInlineKrausMap(int numQb, int numOps, {{{ matrices }}}); /// @ingroup channels_create - /// @notdoced + /// @notyetdoced /// @macrodoc SuperOp createInlineSuperOp(int numQb, {{ matrix }}); diff --git a/quest/include/debug.h b/quest/include/debug.h index 719b651b0..9b2cefe57 100644 --- a/quest/include/debug.h +++ b/quest/include/debug.h @@ -42,19 +42,19 @@ extern "C" { */ -/// @notdoced +/// @notyetdoced void setSeeds(unsigned* seeds, int numSeeds); -/// @notdoced +/// @notyetdoced void setSeedsToDefault(); -/// @notdoced +/// @notyetdoced void getSeeds(unsigned* seeds); -/// @notdoced +/// @notyetdoced int getNumSeeds(); @@ -73,27 +73,27 @@ int getNumSeeds(); */ -/// @notdoced +/// @notyetdoced void setInputErrorHandler(void (*callback)(const char* func, const char* msg)); -/// @notdoced +/// @notyetdoced void setValidationOn(); -/// @notdoced +/// @notyetdoced void setValidationOff(); -/// @notdoced +/// @notyetdoced void setValidationEpsilonToDefault(); -/// @notdoced +/// @notyetdoced void setValidationEpsilon(qreal eps); -/// @notdoced +/// @notyetdoced qreal getValidationEpsilon(); @@ -108,12 +108,12 @@ qreal getValidationEpsilon(); */ -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void setMaxNumReportedItems(qindex numRows, qindex numCols); -/** @notdoced +/** @notyetdoced * > This function does not affect the significant figures in printed memory sizes * > (e.g. `5.32 KiB`) which is always shown with three significant figures * > (or four when in bytes, e.g. `1023 bytes`). @@ -121,7 +121,7 @@ void setMaxNumReportedItems(qindex numRows, qindex numCols); void setMaxNumReportedSigFigs(int numSigFigs); -/// @notdoced +/// @notyetdoced void setNumReportedNewlines(int numNewlines); @@ -136,11 +136,11 @@ void setNumReportedNewlines(int numNewlines); */ -/// @notdoced +/// @notyetdoced qindex getGpuCacheSize(); -/// @notdoced +/// @notyetdoced void clearGpuCache(); @@ -155,8 +155,8 @@ void clearGpuCache(); */ -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void getEnvironmentString(char str[200]); @@ -185,15 +185,15 @@ void getEnvironmentString(char str[200]); /// @ingroup debug_seed -/// @nottested -/// @notdoced +/// @notyettested +/// @notyetdoced /// @cpponly void setSeeds(std::vector seeds); /// @ingroup debug_seed -/// @nottested -/// @notdoced +/// @notyettested +/// @notyetdoced /// @cpponly std::vector getSeeds(); diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index dbecdeb96..277e01a99 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -29,7 +29,7 @@ extern "C" { #endif -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob and @f$ t = @f$ @p target. @@ -68,12 +68,12 @@ extern "C" { mixQureg(qureg, other, prob); * ``` * - * @notvalidated + * @notyetvalidated */ void mixDephasing(Qureg qureg, int target, qreal prob); -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob, @f$ t_1 = @f$ @p target1 and @f$ t_2 = @f$ @p target2. @@ -112,12 +112,12 @@ void mixDephasing(Qureg qureg, int target, qreal prob); mixKrausMap(qureg, targets, 2, map); * ``` * - * @notvalidated + * @notyetvalidated */ void mixTwoQubitDephasing(Qureg qureg, int target1, int target2, qreal prob); -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob and @f$ t = @f$ @p target. @@ -153,12 +153,12 @@ void mixTwoQubitDephasing(Qureg qureg, int target1, int target2, qreal prob); mixKrausMap(qureg, &target, 1, map); * ``` * - * @notvalidated + * @notyetvalidated */ void mixDepolarising(Qureg qureg, int target, qreal prob); -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob, @f$ t_1 = @f$ @p target1 and @f$ t_2 = @f$ @p target2. @@ -214,12 +214,12 @@ void mixDepolarising(Qureg qureg, int target, qreal prob); * of two Pauli matrices, all scaled by @f$ (p/15)^{1/2} @f$, _except_ for * @f$ \hat{\id} \otimes \hat{\id} @f$ which is scaled by @f$ (1-16p/15)^{1/2} @f$. * - * @notvalidated + * @notyetvalidated */ void mixTwoQubitDepolarising(Qureg qureg, int target1, int target2, qreal prob); -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho = @f$ @p qureg, @f$ p = @f$ @p prob and @f$ t = @f$ @p target. @@ -250,12 +250,12 @@ void mixTwoQubitDepolarising(Qureg qureg, int target1, int target2, qreal prob); mixKrausMap(qureg, &target, 1, map); * ``` * - * @notvalidated + * @notyetvalidated */ void mixDamping(Qureg qureg, int target, qreal prob); -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho = @f$ @p qureg, @f$ t = @f$ @p target, and @@ -292,12 +292,12 @@ void mixDamping(Qureg qureg, int target, qreal prob); mixKrausMap(qureg, &target, 1, map); * ``` * - * @notvalidated + * @notyetvalidated */ void mixPaulis(Qureg qureg, int target, qreal probX, qreal probY, qreal probZ); -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho_1 = @f$ @p qureg, @f$ \dmrho_2 = @f$ @p other and @f$ p = @f$ @p prob. @@ -310,12 +310,12 @@ void mixPaulis(Qureg qureg, int target, qreal probX, qreal probY, qreal probZ); p \, \dmrho_2. * @f] * - * @notvalidated + * @notyetvalidated */ void mixQureg(Qureg qureg, Qureg other, qreal prob); -/** @notdoced +/** @notyetdoced * * @formulae * Let @f$ \dmrho = @f$ @p qureg, @f$ \vec{t} = @f$ @p targets and @f$ \hat{K}^{(i)} @f$ @@ -328,13 +328,13 @@ void mixQureg(Qureg qureg, Qureg other, qreal prob); \hat{K}_{\vec{t}}^{(i)} \dmrho \, {\hat{K}_{\vec{t}}^{(i)}}^\dagger * @f] * - * @notvalidated + * @notyetvalidated */ void mixKrausMap(Qureg qureg, int* targets, int numTargets, KrausMap map); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void mixSuperOp(Qureg qureg, int* targets, int numTargets, SuperOp superop); @@ -357,15 +357,15 @@ void mixSuperOp(Qureg qureg, int* targets, int numTargets, SuperOp superop); #include -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly void mixKrausMap(Qureg qureg, std::vector targets, KrausMap map); -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly void mixSuperOp(Qureg qureg, std::vector targets, SuperOp superop); diff --git a/quest/include/environment.h b/quest/include/environment.h index 3657cf00f..0880b1d7d 100644 --- a/quest/include/environment.h +++ b/quest/include/environment.h @@ -29,7 +29,7 @@ extern "C" { * local copy of this struct with getQuESTEnv(). */ -/// @notdoced +/// @notyetdoced typedef struct { // deployment mode @@ -44,26 +44,26 @@ typedef struct { } QuESTEnv; -/// @notdoced +/// @notyetdoced void initQuESTEnv(); -/// @notdoced +/// @notyetdoced void initCustomQuESTEnv(int useDistrib, int useGpuAccel, int useMultithread); -/// @notdoced +/// @notyetdoced void finalizeQuESTEnv(); -/// @notdoced +/// @notyetdoced void syncQuESTEnv(); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void reportQuESTEnv(); -/// @notdoced +/// @notyetdoced int isQuESTEnvInit(); -/// @notdoced +/// @notyetdoced QuESTEnv getQuESTEnv(); diff --git a/quest/include/initialisations.h b/quest/include/initialisations.h index 716971f6d..bcc875487 100644 --- a/quest/include/initialisations.h +++ b/quest/include/initialisations.h @@ -39,49 +39,49 @@ extern "C" { */ -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initBlankState(Qureg qureg); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initZeroState(Qureg qureg); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initPlusState(Qureg qureg); -/// @notdoced -/// @notvalidated -/// @nottested +/// @notyetdoced +/// @notyetvalidated +/// @notyettested void initPureState(Qureg qureg, Qureg pure); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initClassicalState(Qureg qureg, qindex stateInd); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initDebugState(Qureg qureg); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initArbitraryPureState(Qureg qureg, qcomp* amps); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initRandomPureState(Qureg qureg); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void initRandomMixedState(Qureg qureg, qindex numPureStates); @@ -96,48 +96,48 @@ void initRandomMixedState(Qureg qureg, qindex numPureStates); */ -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void setQuregAmps(Qureg qureg, qindex startInd, qcomp* amps, qindex numAmps); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void setDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, qcomp** amps, qindex numRows, qindex numCols); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void setDensityQuregFlatAmps(Qureg qureg, qindex startInd, qcomp* amps, qindex numAmps); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void setQuregToClone(Qureg targetQureg, Qureg copyQureg); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void setQuregToSuperposition(qcomp facOut, Qureg out, qcomp fac1, Qureg qureg1, qcomp fac2, Qureg qureg2); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal setQuregToRenormalized(Qureg qureg); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void setQuregToPauliStrSum(Qureg qureg, PauliStrSum sum); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void setQuregToPartialTrace(Qureg out, Qureg in, int* traceOutQubits, int numTraceQubits); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void setQuregToReducedDensityMatrix(Qureg out, Qureg in, int* retainQubits, int numRetainQubits); @@ -166,41 +166,41 @@ void setQuregToReducedDensityMatrix(Qureg out, Qureg in, int* retainQubits, int /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly void setQuregAmps(Qureg qureg, qindex startInd, std::vector amps); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly void setDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, std::vector> amps); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly void setDensityQuregFlatAmps(Qureg qureg, qindex startInd, std::vector amps); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly void setQuregToPartialTrace(Qureg out, Qureg in, std::vector traceOutQubits); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly void setQuregToReducedDensityMatrix(Qureg out, Qureg in, std::vector retainQubits); diff --git a/quest/include/matrices.h b/quest/include/matrices.h index 9606c7f0e..d5f6a012c 100644 --- a/quest/include/matrices.h +++ b/quest/include/matrices.h @@ -60,7 +60,7 @@ */ -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -71,7 +71,7 @@ typedef struct { } CompMatr1; -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -82,7 +82,7 @@ typedef struct { } CompMatr2; -/// @notdoced +/// @notyetdoced typedef struct { // beware that CompMatr instances are sometimes 'spoofed' inside localiser.cpp, @@ -128,7 +128,7 @@ typedef struct { */ -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -139,7 +139,7 @@ typedef struct { } DiagMatr1; -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -150,7 +150,7 @@ typedef struct { } DiagMatr2; -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -187,7 +187,7 @@ typedef struct { */ -/// @notdoced +/// @notyetdoced typedef struct { int numQubits; @@ -307,7 +307,7 @@ extern void _validateNewElemsPtrNotNull(qcomp* ptr, const char* caller); /// @ingroup matrices_getters -/// @notdoced +/// @notyetdoced static inline CompMatr1 getCompMatr1(qcomp** in) { _validateNewNestedElemsPtrNotNull(in, 1, __func__); @@ -323,7 +323,7 @@ static inline CompMatr1 getCompMatr1(qcomp** in) { /// @ingroup matrices_getters -/// @notdoced +/// @notyetdoced static inline CompMatr2 getCompMatr2(qcomp** in) { _validateNewNestedElemsPtrNotNull(in, 2, __func__); @@ -341,7 +341,7 @@ static inline CompMatr2 getCompMatr2(qcomp** in) { /// @ingroup matrices_getters -/// @notdoced +/// @notyetdoced static inline DiagMatr1 getDiagMatr1(qcomp* in) { _validateNewElemsPtrNotNull(in, __func__); @@ -355,7 +355,7 @@ static inline DiagMatr1 getDiagMatr1(qcomp* in) { /// @ingroup matrices_getters -/// @notdoced +/// @notyetdoced static inline DiagMatr2 getDiagMatr2(qcomp* in) { _validateNewElemsPtrNotNull(in, __func__); @@ -414,35 +414,35 @@ static inline CompMatr2 _getCompMatr2FromArr(qcomp in[4][4]) { /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced static inline CompMatr1 getCompMatr1(qcomp in[2][2]) { return _getCompMatr1FromArr(in); } /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced static inline CompMatr2 getCompMatr2(qcomp in[4][4]) { return _getCompMatr2FromArr(in); } /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @cpponly CompMatr1 getCompMatr1(std::vector> in); /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @cpponly CompMatr2 getCompMatr2(std::vector> in); /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @cpponly DiagMatr1 getDiagMatr1(std::vector in); /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @cpponly DiagMatr2 getDiagMatr2(std::vector in); @@ -561,22 +561,22 @@ static inline CompMatr2 _getCompMatr2FromArr(qcomp in[4][4]) { #if 0 /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @macrodoc CompMatr1 getInlineCompMatr1({{ matrix }}); /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @macrodoc CompMatr2 getInlineCompMatr2({{ matrix }}); /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @macrodoc DiagMatr1 getInlineDiagMatr1({ list }); /// @ingroup matrices_getters - /// @notdoced + /// @notyetdoced /// @macrodoc DiagMatr2 getInlineDiagMatr2({ list }); @@ -596,52 +596,52 @@ extern "C" { /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced CompMatr createCompMatr(int numQubits); /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced DiagMatr createDiagMatr(int numQubits); /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced FullStateDiagMatr createFullStateDiagMatr(int numQubits); /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced FullStateDiagMatr createCustomFullStateDiagMatr(int numQubits, int useDistrib, int useGpuAccel, int useMultithread); /// @ingroup matrices_destroy - /// @notdoced + /// @notyetdoced void destroyCompMatr(CompMatr matrix); /// @ingroup matrices_destroy - /// @notdoced + /// @notyetdoced void destroyDiagMatr(DiagMatr matrix); /// @ingroup matrices_destroy - /// @notdoced + /// @notyetdoced void destroyFullStateDiagMatr(FullStateDiagMatr matrix); /// @ingroup matrices_sync - /// @notdoced + /// @notyetdoced void syncCompMatr(CompMatr matr); /// @ingroup matrices_sync - /// @notdoced + /// @notyetdoced void syncDiagMatr(DiagMatr matr); /// @ingroup matrices_sync - /// @notdoced + /// @notyetdoced void syncFullStateDiagMatr(FullStateDiagMatr matr); @@ -670,18 +670,18 @@ extern "C" { /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced void setCompMatr(CompMatr matr, qcomp** vals); /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced void setDiagMatr(DiagMatr out, qcomp* in); /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void setFullStateDiagMatr(FullStateDiagMatr out, qindex startInd, qcomp* in, qindex numElems); @@ -712,20 +712,20 @@ extern "C" { /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setCompMatr(CompMatr out, std::vector> in); /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setDiagMatr(DiagMatr out, std::vector in); /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested /// @cpponly void setFullStateDiagMatr(FullStateDiagMatr out, qindex startInd, std::vector in); @@ -777,7 +777,7 @@ extern "C" { #if 0 /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced /// @macrodoc /// @conly void setCompMatr(CompMatr matr, qcomp arr[matr.numRows][matr.numRows]); @@ -817,20 +817,20 @@ extern "C" { /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setInlineCompMatr(CompMatr matr, int numQb, std::vector> in); /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced /// @cpponly void setInlineDiagMatr(DiagMatr matr, int numQb, std::vector in); /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested /// @cpponly void setInlineFullStateDiagMatr(FullStateDiagMatr matr, qindex startInd, qindex numElems, std::vector in); @@ -894,18 +894,18 @@ extern "C" { #if 0 /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced /// @macrodoc void setInlineCompMatr(CompMatr matr, int numQb, {{ matrix }}); /// @ingroup matrices_setters - /// @notdoced + /// @notyetdoced /// @macrodoc void setInlineDiagMatr(DiagMatr matr, int numQb, { list }); /// @ingroup matrices_setters - /// @nottested - /// @notdoced + /// @notyettested + /// @notyetdoced /// @macrodoc void setInlineFullStateDiagMatr(FullStateDiagMatr matr, qindex startInd, qindex numElems, { list }); @@ -976,13 +976,13 @@ extern "C" { /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced /// @cpponly CompMatr createInlineCompMatr(int numQb, std::vector> elems); /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced /// @cpponly DiagMatr createInlineDiagMatr(int numQb, std::vector elems); @@ -1032,12 +1032,12 @@ extern "C" { #if 0 /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced /// @macrodoc CompMatr createInlineCompMatr(int numQb, {{ matrix }}); /// @ingroup matrices_create - /// @notdoced + /// @notyetdoced /// @macrodoc DiagMatr createInlineDiagMatr(int numQb, { list }); @@ -1069,38 +1069,38 @@ extern "C" { /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void setDiagMatrFromMultiVarFunc(DiagMatr out, qcomp (*func)(qindex*), int* numQubitsPerVar, int numVars, int areSigned); /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void setDiagMatrFromMultiDimLists(DiagMatr out, void* lists, int* numQubitsPerDim, int numDims); /// @ingroup matrices_create - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested FullStateDiagMatr createFullStateDiagMatrFromPauliStrSum(PauliStrSum in); /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void setFullStateDiagMatrFromPauliStrSum(FullStateDiagMatr out, PauliStrSum in); /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void setFullStateDiagMatrFromMultiVarFunc(FullStateDiagMatr out, qcomp (*func)(qindex*), int* numQubitsPerVar, int numVars, int areSigned); /// @ingroup matrices_setters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void setFullStateDiagMatrFromMultiDimLists(FullStateDiagMatr out, void* lists, int* numQubitsPerDim, int numDims); @@ -1122,44 +1122,44 @@ extern "C" { /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportCompMatr1(CompMatr1 matrix); /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportCompMatr2(CompMatr2 matrix); /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportCompMatr(CompMatr matrix); /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportDiagMatr1(DiagMatr1 matrix); /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportDiagMatr2(DiagMatr2 matrix); /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportDiagMatr(DiagMatr matrix); /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportFullStateDiagMatr(FullStateDiagMatr matr); diff --git a/quest/include/modes.h b/quest/include/modes.h index 84e030488..b90797acd 100644 --- a/quest/include/modes.h +++ b/quest/include/modes.h @@ -93,17 +93,17 @@ #if 0 - /// @notdoced + /// @notyetdoced /// @macrodoc const int PERMIT_NODES_TO_SHARE_GPU = 0; - /// @notdoced + /// @notyetdoced /// @macrodoc const int INCLUDE_DEPRECATED_FUNCTIONS = 0; - /// @notdoced + /// @notyetdoced /// @macrodoc const int DISABLE_DEPRECATION_WARNINGS = 0; diff --git a/quest/include/operations.h b/quest/include/operations.h index b12fc272a..2f4ae28b8 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -198,7 +198,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyControlledCompMatr1(Qureg qureg, int control, int target, CompMatr1 matrix); @@ -240,7 +240,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyMultiControlledCompMatr1(Qureg qureg, int* controls, int numControls, int target, CompMatr1 matrix); @@ -282,7 +282,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyMultiStateControlledCompMatr1(Qureg qureg, int* controls, int* states, int numControls, int target, CompMatr1 matrix); @@ -295,16 +295,16 @@ void applyMultiStateControlledCompMatr1(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledCompMatr1(Qureg qureg, std::vector controls, int target, CompMatr1 matrix); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledCompMatr1(Qureg qureg, std::vector controls, std::vector states, int target, CompMatr1 matrix); @@ -327,7 +327,7 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyCompMatr2(Qureg qureg, int target1, int target2, CompMatr2 matr); @@ -355,7 +355,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyCompMatr2(Qureg qureg, int target1, int target2, CompMatr2 matrix); @@ -390,7 +390,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyControlledCompMatr2(Qureg qureg, int control, int target1, int target2, CompMatr2 matr); @@ -431,7 +431,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyMultiControlledCompMatr2(Qureg qureg, int* controls, int numControls, int target1, int target2, CompMatr2 matr); @@ -473,7 +473,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyMultiStateControlledCompMatr2(Qureg qureg, int* controls, int* states, int numControls, int target1, int target2, CompMatr2 matr); @@ -486,16 +486,16 @@ void applyMultiStateControlledCompMatr2(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledCompMatr2(Qureg qureg, std::vector controls, int target1, int target2, CompMatr2 matr); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledCompMatr2(Qureg qureg, std::vector controls, std::vector states, int numControls, int target1, int target2, CompMatr2 matr); @@ -518,23 +518,23 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matr); -/// @notdoced +/// @notyetdoced void applyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matr); -/// @notdoced +/// @notyetdoced void applyControlledCompMatr(Qureg qureg, int control, int* targets, int numTargets, CompMatr matr); -/// @notdoced +/// @notyetdoced void applyMultiControlledCompMatr(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, CompMatr matr); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, CompMatr matr); @@ -546,37 +546,37 @@ void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void multiplyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyControlledCompMatr(Qureg qureg, int control, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledCompMatr(Qureg qureg, std::vector controls, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledCompMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, CompMatr matr); @@ -599,23 +599,23 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced void applyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced void applyControlledDiagMatr1(Qureg qureg, int control, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced void applyMultiControlledDiagMatr1(Qureg qureg, int* controls, int numControls, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledDiagMatr1(Qureg qureg, int* controls, int* states, int numControls, int target, DiagMatr1 matr); @@ -627,16 +627,16 @@ void applyMultiStateControlledDiagMatr1(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledDiagMatr1(Qureg qureg, std::vector controls, int target, DiagMatr1 matr); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledDiagMatr1(Qureg qureg, std::vector controls, std::vector states, int target, DiagMatr1 matr); @@ -659,23 +659,23 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced void applyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced void applyControlledDiagMatr2(Qureg qureg, int control, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced void applyMultiControlledDiagMatr2(Qureg qureg, int* controls, int numControls, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledDiagMatr2(Qureg qureg, int* controls, int* states, int numControls, int target1, int target2, DiagMatr2 matr); @@ -687,16 +687,16 @@ void applyMultiStateControlledDiagMatr2(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledDiagMatr2(Qureg qureg, std::vector controls, int target1, int target2, DiagMatr2 matr); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledDiagMatr2(Qureg qureg, std::vector controls, std::vector states, int target1, int target2, DiagMatr2 matr); @@ -719,43 +719,43 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced void applyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced void applyControlledDiagMatr(Qureg qureg, int control, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced void applyMultiControlledDiagMatr(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledDiagMatr(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced void multiplyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notdoced +/// @notyetdoced void applyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notdoced +/// @notyetdoced void applyControlledDiagMatrPower(Qureg qureg, int control, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notdoced +/// @notyetdoced void applyMultiControlledDiagMatrPower(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); @@ -767,72 +767,72 @@ void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* sta #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void multiplyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyControlledDiagMatr(Qureg qureg, int control, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledDiagMatr(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledDiagMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void multiplyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyControlledDiagMatrPower(Qureg qureg, int control, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -855,23 +855,23 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void multiplyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void multiplyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void applyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void applyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent); @@ -897,51 +897,51 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void applyS(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyControlledS(Qureg qureg, int control, int target); -/// @notdoced +/// @notyetdoced void applyMultiControlledS(Qureg qureg, int* controls, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledS(Qureg qureg, int* controls, int* states, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyT(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyControlledT(Qureg qureg, int control, int target); -/// @notdoced +/// @notyetdoced void applyMultiControlledT(Qureg qureg, int* controls, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledT(Qureg qureg, int* controls, int* states, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyHadamard(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyControlledHadamard(Qureg qureg, int control, int target); -/// @notdoced +/// @notyetdoced void applyMultiControlledHadamard(Qureg qureg, int* controls, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledHadamard(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -953,44 +953,44 @@ void applyMultiStateControlledHadamard(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledS(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledS(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledT(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledT(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledHadamard(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledHadamard(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1013,7 +1013,7 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplySwap(Qureg qureg, int qubit1, int qubit2); @@ -1044,36 +1044,36 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applySwap(Qureg qureg, int qubit1, int qubit2); -/// @notdoced +/// @notyetdoced void applyControlledSwap(Qureg qureg, int control, int qubit1, int qubit2); -/// @notdoced +/// @notyetdoced void applyMultiControlledSwap(Qureg qureg, int* controls, int numControls, int qubit1, int qubit2); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledSwap(Qureg qureg, int* controls, int* states, int numControls, int qubit1, int qubit2); -/// @notdoced +/// @notyetdoced void applySqrtSwap(Qureg qureg, int qubit1, int qubit2); -/// @notdoced +/// @notyetdoced void applyControlledSqrtSwap(Qureg qureg, int control, int qubit1, int qubit2); -/// @notdoced +/// @notyetdoced void applyMultiControlledSqrtSwap(Qureg qureg, int* controls, int numControls, int qubit1, int qubit2); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledSqrtSwap(Qureg qureg, int* controls, int* states, int numControls, int qubit1, int qubit2); @@ -1085,30 +1085,30 @@ void applyMultiStateControlledSqrtSwap(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledSwap(Qureg qureg, std::vector controls, std::vector states, int qubit1, int qubit2); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledSqrtSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledSqrtSwap(Qureg qureg, std::vector controls, std::vector states, int numControls, int qubit1, int qubit2); @@ -1131,63 +1131,63 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyPauliX(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void multiplyPauliY(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void multiplyPauliZ(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyPauliX(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyPauliY(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyPauliZ(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyControlledPauliX(Qureg qureg, int control, int target); -/// @notdoced +/// @notyetdoced void applyControlledPauliY(Qureg qureg, int control, int target); -/// @notdoced +/// @notyetdoced void applyControlledPauliZ(Qureg qureg, int control, int target); -/// @notdoced +/// @notyetdoced void applyMultiControlledPauliX(Qureg qureg, int* controls, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiControlledPauliY(Qureg qureg, int* controls, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiControlledPauliZ(Qureg qureg, int* controls, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledPauliX(Qureg qureg, int* controls, int* states, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledPauliY(Qureg qureg, int* controls, int* states, int numControls, int target); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledPauliZ(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -1199,44 +1199,44 @@ void applyMultiStateControlledPauliZ(Qureg qureg, int* controls, int* states, in #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledPauliX(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledPauliY(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledPauliZ(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledPauliX(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledPauliY(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledPauliZ(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1259,23 +1259,23 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyPauliStr(Qureg qureg, PauliStr str); -/// @notdoced +/// @notyetdoced void applyPauliStr(Qureg qureg, PauliStr str); -/// @notdoced +/// @notyetdoced void applyControlledPauliStr(Qureg qureg, int control, PauliStr str); -/// @notdoced +/// @notyetdoced void applyMultiControlledPauliStr(Qureg qureg, int* controls, int numControls, PauliStr str); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledPauliStr(Qureg qureg, int* controls, int* states, int numControls, PauliStr str); @@ -1287,16 +1287,16 @@ void applyMultiStateControlledPauliStr(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledPauliStr(Qureg qureg, std::vector controls, PauliStr str); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledPauliStr(Qureg qureg, std::vector controls, std::vector states, PauliStr str); @@ -1319,67 +1319,67 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void applyRotateX(Qureg qureg, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyRotateY(Qureg qureg, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyRotateZ(Qureg qureg, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyControlledRotateX(Qureg qureg, int control, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyControlledRotateY(Qureg qureg, int control, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyControlledRotateZ(Qureg qureg, int control, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiControlledRotateX(Qureg qureg, int* controls, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiControlledRotateY(Qureg qureg, int* controls, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiControlledRotateZ(Qureg qureg, int* controls, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledRotateX(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledRotateY(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledRotateZ(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced void applyRotateAroundAxis(Qureg qureg, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); -/// @notdoced +/// @notyetdoced void applyControlledRotateAroundAxis(Qureg qureg, int ctrl, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); -/// @notdoced +/// @notyetdoced void applyMultiControlledRotateAroundAxis(Qureg qureg, int* ctrls, int numCtrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledRotateAroundAxis(Qureg qureg, int* ctrls, int* states, int numCtrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1391,58 +1391,58 @@ void applyMultiStateControlledRotateAroundAxis(Qureg qureg, int* ctrls, int* sta #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledRotateX(Qureg qureg, std::vector controls, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledRotateY(Qureg qureg, std::vector controls, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledRotateZ(Qureg qureg, std::vector controls, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledRotateX(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledRotateY(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledRotateZ(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, std::vector states, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1465,23 +1465,23 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyPauliGadget(Qureg qureg, PauliStr str, qreal angle); -/// @notdoced +/// @notyetdoced void applyPauliGadget(Qureg qureg, PauliStr str, qreal angle); -/// @notdoced +/// @notyetdoced void applyControlledPauliGadget(Qureg qureg, int control, PauliStr str, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiControlledPauliGadget(Qureg qureg, int* controls, int numControls, PauliStr str, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledPauliGadget(Qureg qureg, int* controls, int* states, int numControls, PauliStr str, qreal angle); @@ -1493,16 +1493,16 @@ void applyMultiStateControlledPauliGadget(Qureg qureg, int* controls, int* state #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledPauliGadget(Qureg qureg, std::vector controls, PauliStr str, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledPauliGadget(Qureg qureg, std::vector controls, std::vector states, PauliStr str, qreal angle); @@ -1525,31 +1525,31 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle); -/// @notdoced +/// @notyetdoced void applyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle); -/// @notdoced +/// @notyetdoced void applyControlledPhaseGadget(Qureg qureg, int control, int* targets, int numTargets, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiControlledPhaseGadget(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledPhaseGadget(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, qreal angle); -/// @notdoced +/// @notyetdoced void applyPhaseFlip(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced void applyPhaseShift(Qureg qureg, int target, qreal angle); @@ -1577,7 +1577,7 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyTwoQubitPhaseFlip( Qureg qureg, int target1, int target2); @@ -1608,16 +1608,16 @@ digraph { } * @enddot * - * @notdoced + * @notyetdoced */ void applyTwoQubitPhaseShift(Qureg qureg, int target1, int target2, qreal angle); -/// @notdoced +/// @notyetdoced void applyMultiQubitPhaseFlip(Qureg qureg, int* targets, int numTargets); -/// @notdoced +/// @notyetdoced void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal angle); @@ -1629,51 +1629,51 @@ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void multiplyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyControlledPhaseGadget(Qureg qureg, int control, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector states, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiQubitPhaseFlip(Qureg qureg, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiQubitPhaseShift(Qureg qureg, std::vector targets, qreal angle); @@ -1696,13 +1696,13 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void multiplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void applyTrotterizedPauliStrSumGadget(Qureg qureg, PauliStrSum sum, qreal angle, int order, int reps); @@ -1728,23 +1728,23 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced void multiplyMultiQubitNot(Qureg qureg, int* targets, int numTargets); -/// @notdoced +/// @notyetdoced void applyMultiQubitNot(Qureg qureg, int* targets, int numTargets); -/// @notdoced +/// @notyetdoced void applyControlledMultiQubitNot(Qureg qureg, int control, int* targets, int numTargets); -/// @notdoced +/// @notyetdoced void applyMultiControlledMultiQubitNot(Qureg qureg, int* controls, int numControls, int* targets, int numTargets); -/// @notdoced +/// @notyetdoced void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets); @@ -1756,37 +1756,37 @@ void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* sta #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void multiplyMultiQubitNot(Qureg qureg, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiQubitNot(Qureg qureg, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyControlledMultiQubitNot(Qureg qureg, int control, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiStateControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector states, std::vector targets); @@ -1809,33 +1809,33 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated int applyQubitMeasurement(Qureg qureg, int target); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated int applyQubitMeasurementAndGetProb(Qureg qureg, int target, qreal* probability); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal applyForcedQubitMeasurement(Qureg qureg, int target, int outcome); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qindex applyMultiQubitMeasurement(Qureg qureg, int* qubits, int numQubits); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qindex applyMultiQubitMeasurementAndGetProb(Qureg qureg, int* qubits, int numQubits, qreal* probability); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated qreal applyForcedMultiQubitMeasurement(Qureg qureg, int* qubits, int* outcomes, int numQubits); @@ -1847,16 +1847,16 @@ qreal applyForcedMultiQubitMeasurement(Qureg qureg, int* qubits, int* outcomes, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly qindex applyMultiQubitMeasurementAndGetProb(Qureg qureg, std::vector qubits, qreal* probability); -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly qreal applyForcedMultiQubitMeasurement(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -1879,13 +1879,13 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void applyQubitProjector(Qureg qureg, int target, int outcome); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void applyMultiQubitProjector(Qureg qureg, int* qubits, int* outcomes, int numQubits); @@ -1897,9 +1897,9 @@ void applyMultiQubitProjector(Qureg qureg, int* qubits, int* outcomes, int numQu #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyMultiQubitProjector(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -1922,13 +1922,13 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void applyQuantumFourierTransform(Qureg qureg, int* targets, int numTargets); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void applyFullQuantumFourierTransform(Qureg qureg); @@ -1940,9 +1940,9 @@ void applyFullQuantumFourierTransform(Qureg qureg); #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly void applyQuantumFourierTransform(Qureg qureg, std::vector targets); diff --git a/quest/include/precision.h b/quest/include/precision.h index 0214daf6f..cfd150855 100644 --- a/quest/include/precision.h +++ b/quest/include/precision.h @@ -38,7 +38,7 @@ // spoofing above macro as const to doc #if 0 - /// @notdoced + /// @notyetdoced /// @macrodoc typedef long long int INDEX_TYPE; @@ -64,7 +64,7 @@ // spoofing above macro as typedef to doc #if 0 - /// @notdoced + /// @notyetdoced /// @macrodoc typedef long long unsigned int PAULI_MASK_TYPE; @@ -98,11 +98,11 @@ // spoofing above macros as typedefs and consts to doc #if 0 - /// @notdoced + /// @notyetdoced /// @macrodoc const int FLOAT_PRECISION = 2; - /// @notdoced + /// @notyetdoced /// @macrodoc typedef double int FLOAT_TYPE; @@ -146,7 +146,7 @@ // spoofing above macros as typedefs and consts to doc #if 0 - /// @notdoced + /// @notyetdoced /// @macrodoc const qreal DEFAULT_VALIDATION_EPSILON = 1E-12; @@ -172,7 +172,7 @@ // spoofing above macros as typedefs and consts to doc #if 0 - /// @notdoced + /// @notyetdoced /// @macrodoc const char* QREAL_FORMAT_SPECIFIER = "%.14g"; diff --git a/quest/include/qureg.h b/quest/include/qureg.h index 2c3d1a1d4..05e0bd4cd 100644 --- a/quest/include/qureg.h +++ b/quest/include/qureg.h @@ -45,7 +45,7 @@ extern "C" { */ -/// @notdoced +/// @notyetdoced typedef struct { // deployment configuration @@ -130,7 +130,7 @@ typedef struct { * - if the total Qureg memory would overflow the @c size_t type. * - if the system contains insufficient RAM (or VRAM) to store the Qureg in any deployment. * - if any memory allocation unexpectedly fails. - * @notvalidated + * @notyetvalidated * @see * - createDensityQureg() to create a density matrix which can additionally undergo decoherence. * - createForcedQureg() to create a statevector which is forced to make use of all available deployments. @@ -185,7 +185,7 @@ Qureg createQureg(int numQubits); * - if the total Qureg memory would overflow the @c size_t type. * - if the system contains insufficient RAM (or VRAM) to store the Qureg in any deployment. * - if any memory allocation unexpectedly fails. - * @notvalidated + * @notyetvalidated * @see * - createQureg() to create a quadratically-smaller statevector Qureg which cannot undergo decoherence. * - createForcedDensityQureg() to create a density matrix which is forced to make use of all available deployments. @@ -195,7 +195,7 @@ Qureg createQureg(int numQubits); Qureg createDensityQureg(int numQubits); -/** @notdoced +/** @notyetdoced * * @equivalences * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=0 and all @@ -212,7 +212,7 @@ Qureg createDensityQureg(int numQubits); Qureg createForcedQureg(int numQubits); -/** @notdoced +/** @notyetdoced * * @equivalences * - This function is equivalent to calling createCustomQureg(), passing @c isDensMatr=1 and all @@ -371,7 +371,7 @@ Qureg createForcedDensityQureg(int numQubits); * - if the total Qureg memory would overflow the @c size_t type. * - if the system contains insufficient RAM (or VRAM) to store the Qureg. * - if any memory allocation unexpectedly fails. - * @notvalidated + * @notyetvalidated * @see * - createQureg() to automate deployments (equivalent to passing @c -1). * - createForcedQureg() to use all available deployments. @@ -380,7 +380,7 @@ Qureg createForcedDensityQureg(int numQubits); Qureg createCustomQureg(int numQubits, int isDensMatr, int useDistrib, int useGpuAccel, int useMultithread); -/// @notdoced +/// @notyetdoced Qureg createCloneQureg(Qureg qureg); @@ -395,7 +395,7 @@ Qureg createCloneQureg(Qureg qureg); */ -/// @notdoced +/// @notyetdoced void destroyQureg(Qureg qureg); @@ -410,13 +410,13 @@ void destroyQureg(Qureg qureg); */ -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void reportQuregParams(Qureg qureg); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void reportQureg(Qureg qureg); @@ -436,23 +436,23 @@ void reportQureg(Qureg qureg); */ -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void syncQuregToGpu(Qureg qureg); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void syncQuregFromGpu(Qureg qureg); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void syncSubQuregToGpu(Qureg qureg, qindex localStartInd, qindex numLocalAmps); -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void syncSubQuregFromGpu(Qureg qureg, qindex localStartInd, qindex numLocalAmps); @@ -467,11 +467,11 @@ void syncSubQuregFromGpu(Qureg qureg, qindex localStartInd, qindex numLocalAmps) */ -/// @notdoced +/// @notyetdoced void getQuregAmps(qcomp* outAmps, Qureg qureg, qindex startInd, qindex numAmps); -/// @notdoced +/// @notyetdoced void getDensityQuregAmps(qcomp** outAmps, Qureg qureg, qindex startRow, qindex startCol, qindex numRows, qindex numCols); @@ -502,12 +502,12 @@ void getDensityQuregAmps(qcomp** outAmps, Qureg qureg, qindex startRow, qindex s /// @ingroup qureg_get -/// @notdoced +/// @notyetdoced qcomp getQuregAmp(Qureg qureg, qindex index); /// @ingroup qureg_get -/// @notdoced +/// @notyetdoced qcomp getDensityQuregAmp(Qureg qureg, qindex row, qindex column); @@ -526,17 +526,17 @@ qcomp getDensityQuregAmp(Qureg qureg, qindex row, qindex column); /// @ingroup qureg_get -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly std::vector getQuregAmps(Qureg qureg, qindex startInd, qindex numAmps); /// @ingroup qureg_get -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly std::vector> getDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, qindex numRows, qindex numCols); diff --git a/quest/include/types.h b/quest/include/types.h index ba172e9b9..d185eff02 100644 --- a/quest/include/types.h +++ b/quest/include/types.h @@ -87,7 +87,7 @@ typedef INDEX_TYPE qindex; * code, to avoid C & C++ qcomp interoperability issues. */ -/// @notdoced +/// @notyetdoced static inline qcomp getQcomp(qreal re, qreal im) { #if defined(__cplusplus) @@ -169,7 +169,7 @@ static inline qcomp getQcomp(qreal re, qreal im) { // spoofing above macro as const to doc #if 0 - /// @notdoced + /// @notyetdoced /// @macrodoc const int DEFINE_ARITHMETIC_OVERLOADS = 1; @@ -294,47 +294,47 @@ static inline qcomp getQcomp(qreal re, qreal im) { #include - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested extern "C" void reportStr(const char* str); - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested /// @cpponly void reportStr(std::string str); - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested extern "C" void reportScalar(const char* label, qcomp num); - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportScalar(const char* label, qreal num); - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested /// @cpponly void reportScalar(std::string label, qcomp num); - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested /// @cpponly void reportScalar(std::string label, qreal num); #else - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportStr(const char* str); - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportScalar(const char* label, qcomp num); diff --git a/utils/docs/Doxyfile b/utils/docs/Doxyfile index 2f2c41710..7e7c22372 100644 --- a/utils/docs/Doxyfile +++ b/utils/docs/Doxyfile @@ -295,9 +295,9 @@ TAB_SIZE = 4 # @} or use a double escape (\\{ and \\}) ALIASES = -ALIASES += "nottested=@warning This function has not yet been unit tested and may contain bugs. Please use with caution!" -ALIASES += "notvalidated=@attention This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!" -ALIASES += "notdoced=@note Documentation for this function or struct is under construction!" +ALIASES += "notyettested=@warning This function has not yet been unit tested and may contain bugs. Please use with caution!" +ALIASES += "notyetvalidated=@attention This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!" +ALIASES += "notyetdoced=@note Documentation for this function or struct is under construction!" ALIASES += "cpponly=@remark This function is only available in C++." ALIASES += "conly=@remark This function is only available in C." ALIASES += "macrodoc=@note This entity is actually a macro." From b1448b40dbc3bf1c9354e2f4852f0c8ac6dac9e8 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 12 May 2025 23:53:43 +0200 Subject: [PATCH 12/21] linked API doc to examples --- quest/include/channels.h | 226 ++++++++++++++---- quest/include/matrices.h | 504 ++++++++++++++++++++++++++++++--------- quest/include/paulis.h | 178 ++++++++++---- 3 files changed, 701 insertions(+), 207 deletions(-) diff --git a/quest/include/channels.h b/quest/include/channels.h index 05ee79454..c0f5433f6 100644 --- a/quest/include/channels.h +++ b/quest/include/channels.h @@ -176,13 +176,28 @@ extern "C" { #endif - /// @ingroup channels_create - /// @notyetdoced + /** @ingroup channels_create + * @notyetdoced + * + * @see + * - createInlineKrausMap + * - createSuperOp() + * - setKrausMap() + * - setInlineKrausMap + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.cpp) examples + */ KrausMap createKrausMap(int numQubits, int numOperators); - /// @ingroup channels_sync - /// @notyetdoced + /** @ingroup channels_sync + * @notyetdoced + * + * @see + * - setKrausMap() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.cpp) examples + */ void syncKrausMap(KrausMap map); @@ -197,13 +212,28 @@ extern "C" { void reportKrausMap(KrausMap map); - /// @ingroup channels_create - /// @notyetdoced + /** @ingroup channels_create + * @notyetdoced + * + * @see + * - createInlineSuperOp() + * - createKrausMap() + * - setSuperOp() + * - setInlineSuperOp() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.cpp) examples + */ SuperOp createSuperOp(int numQubits); - /// @ingroup channels_sync - /// @notyetdoced + /** @ingroup channels_sync + * @notyetdoced + * + * @see + * - setSuperOp() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.cpp) examples + */ void syncSuperOp(SuperOp op); @@ -240,13 +270,27 @@ extern "C" { #endif - /// @ingroup channels_setters - /// @notyetdoced + /** @ingroup channels_setters + * @notyetdoced + * + * @see + * - setInlineKrausMap() + * - syncKrausMap() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.cpp) examples + */ void setKrausMap(KrausMap map, qcomp*** matrices); - /// @ingroup channels_setters - /// @notyetdoced + /** @ingroup channels_setters + * @notyetdoced + * + * @see + * - setInlineSuperOp() + * - syncSuperOp() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.cpp) examples + */ void setSuperOp(SuperOp op, qcomp** matrix); @@ -278,15 +322,25 @@ extern "C" { // C++ overloads to accept vectors, which also enables vector initialiser literals - /// @ingroup channels_setters - /// @notyetdoced - /// @cpponly + /** @ingroup channels_setters + * @notyetdoced + * @cpponly + * + * @see + * - setInlineKrausMap() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.cpp) examples + */ void setKrausMap(KrausMap map, std::vector>> matrices); - /// @ingroup channels_setters - /// @notyetdoced - /// @cpponly + /** @ingroup channels_setters + * @notyetdoced + * @cpponly + * + * @see + * - setInlineSuperOp() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.cpp) examples + */ void setSuperOp(SuperOp op, std::vector> matrix); @@ -359,18 +413,31 @@ extern "C" { // spoofing macros as functions #if 0 - /// @ingroup channels_setters - /// @notyetdoced - /// @conly - /// @macrodoc + + /** @ingroup channels_setters + * @notyetdoced + * @conly + * @macrodoc + * + * @see + * - setInlineKrausMap() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.c) examples + */ void setKrausMap(KrausMap map, qcomp matrices[map.numMatrices][map.numRows][map.numRows]); - /// @ingroup channels_setters - /// @notyetdoced - /// @conly - /// @macrodoc + + /** @ingroup channels_setters + * @notyetdoced + * @conly + * @macrodoc + * + * @see + * - setInlineSuperOp() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.c) examples + */ void setSuperOp(SuperOp op, qcomp matrix[op.numRows][op.numRows]); + #endif @@ -404,15 +471,27 @@ extern "C" { // validate that they match the struct dimensions (which requires validating the structs). - /// @ingroup channels_setters - /// @notyetdoced - /// @cpponly + /** @ingroup channels_setters + * @notyetdoced + * @cpponly + * + * @see + * - setKrausMap() + * - syncKrausMap() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.cpp) examples + */ void setInlineKrausMap(KrausMap map, int numQb, int numOps, std::vector>> matrices); - /// @ingroup channels_setters - /// @notyetdoced - /// @cpponly + /** @ingroup channels_setters + * @notyetdoced + * @cpponly + * + * @see + * - setSuperOp() + * - syncSuperOp() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.cpp) examples + */ void setInlineSuperOp(SuperOp op, int numQb, std::vector> matrix); @@ -451,7 +530,6 @@ extern "C" { #define setInlineKrausMap(map, numQb, numOps, ...) \ _setInlineKrausMap((map), (numQb), (numOps), (qcomp[(numOps)][1<<(numQb)][1<<(numQb)]) __VA_ARGS__) - /// @neverdoced #define setInlineSuperOp(matr, numQb, ...) \ _setInlineSuperOp((matr), (numQb), (qcomp[1<<(2*(numQb))][1<<(2*(numQb))]) __VA_ARGS__) @@ -459,16 +537,31 @@ extern "C" { // spoofing macros as functions #if 0 - /// @ingroup channels_setters - /// @notyetdoced - /// @macrodoc + + /** @ingroup channels_setters + * @notyetdoced + * @macrodoc + * + * @see + * - setKrausMap() + * - syncKrausMap() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.c) examples + */ void setInlineKrausMap(KrausMap map, int numQb, int numOps, {{{ matrices }}}); - /// @ingroup channels_setters - /// @notyetdoced - /// @macrodoc + + /** @ingroup channels_setters + * @notyetdoced + * @macrodoc + * + * @see + * - setSuperOp() + * - syncSuperOp() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.c) examples + */ void setInlineSuperOp(SuperOp op, int numQb, {{ matrix }}); + #endif #else @@ -494,15 +587,29 @@ extern "C" { // C++ accepts vector initialiser lists - /// @ingroup channels_create - /// @notyetdoced - /// @cpponly + /** @ingroup channels_create + * @notyetdoced + * @cpponly + * + * @see + * - createKrausMap() + * - setKrausMap() + * - syncKrausMap() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.cpp) examples + */ KrausMap createInlineKrausMap(int numQubits, int numOperators, std::vector>> matrices); - /// @ingroup channels_create - /// @notyetdoced - /// @cpponly + /** @ingroup channels_create + * @notyetdoced + * @cpponly + * + * @see + * - createSuperOp() + * - setSuperOp() + * - syncSuperOp() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.cpp) examples + */ SuperOp createInlineSuperOp(int numQubits, std::vector> matrix); @@ -550,16 +657,33 @@ extern "C" { // spoofing macros as functions #if 0 - /// @ingroup channels_create - /// @notyetdoced - /// @macrodoc + + /** @ingroup channels_create + * @notyetdoced + * @macrodoc + * + * @see + * - createKrausMap() + * - setKrausMap() + * - syncKrausMap() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_krausmaps.c) examples + */ KrausMap createInlineKrausMap(int numQb, int numOps, {{{ matrices }}}); - /// @ingroup channels_create - /// @notyetdoced - /// @macrodoc + + /** @ingroup channels_create + * @notyetdoced + * @macrodoc + * + * @see + * - createSuperOp() + * - setSuperOp() + * - syncSuperOp() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_superoperators.c) examples + */ SuperOp createInlineSuperOp(int numQb, {{ matrix }}); + #endif #else diff --git a/quest/include/matrices.h b/quest/include/matrices.h index d5f6a012c..8ff4e9ff3 100644 --- a/quest/include/matrices.h +++ b/quest/include/matrices.h @@ -306,8 +306,18 @@ extern void _validateNewElemsPtrNotNull(qcomp* ptr, const char* caller); #endif -/// @ingroup matrices_getters -/// @notyetdoced +/** @ingroup matrices_getters + * @notyetdoced + * + * @see + * - reportCompMatr1() + * - getInlineCompMatr2() + * - getDiagMatr1() + * - getCompMatr2() + * - createCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ static inline CompMatr1 getCompMatr1(qcomp** in) { _validateNewNestedElemsPtrNotNull(in, 1, __func__); @@ -322,8 +332,17 @@ static inline CompMatr1 getCompMatr1(qcomp** in) { } -/// @ingroup matrices_getters -/// @notyetdoced +/** @ingroup matrices_getters + * @notyetdoced + * + * @see + * - reportCompMatr2() + * - getInlineCompMatr2() + * - getDiagMatr2() + * - createCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ static inline CompMatr2 getCompMatr2(qcomp** in) { _validateNewNestedElemsPtrNotNull(in, 2, __func__); @@ -340,8 +359,18 @@ static inline CompMatr2 getCompMatr2(qcomp** in) { } -/// @ingroup matrices_getters -/// @notyetdoced +/** @ingroup matrices_getters + * @notyetdoced + * + * @see + * - reportDiagMatr1() + * - getInlineDiagMatr1() + * - getCompMatr1() + * - getDiagMatr2() + * - createDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ static inline DiagMatr1 getDiagMatr1(qcomp* in) { _validateNewElemsPtrNotNull(in, __func__); @@ -354,8 +383,17 @@ static inline DiagMatr1 getDiagMatr1(qcomp* in) { } -/// @ingroup matrices_getters -/// @notyetdoced +/** @ingroup matrices_getters + * @notyetdoced + * + * @see + * - reportDiagMatr2() + * - getInlineDiagMatr2() + * - getCompMatr2() + * - createDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ static inline DiagMatr2 getDiagMatr2(qcomp* in) { _validateNewElemsPtrNotNull(in, __func__); @@ -423,27 +461,61 @@ static inline CompMatr2 _getCompMatr2FromArr(qcomp in[4][4]) { static inline CompMatr2 getCompMatr2(qcomp in[4][4]) { return _getCompMatr2FromArr(in); } - /// @ingroup matrices_getters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_getters + * @notyetdoced + * @cpponly + * + * @see + * - reportCompMatr1() + * - getInlineCompMatr1() + * - getDiagMatr1() + * - getCompMatr2() + * - createCompMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ CompMatr1 getCompMatr1(std::vector> in); - /// @ingroup matrices_getters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_getters + * @notyetdoced + * @cpponly + * + * @see + * - reportCompMatr2() + * - getInlineCompMatr2() + * - getDiagMatr2() + * - createCompMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ CompMatr2 getCompMatr2(std::vector> in); - /// @ingroup matrices_getters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_getters + * @notyetdoced + * @cpponly + * + * @see + * - reportDiagMatr1() + * - getInlineDiagMatr1() + * - getCompMatr1() + * - getDiagMatr2() + * - createDiagMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ DiagMatr1 getDiagMatr1(std::vector in); - /// @ingroup matrices_getters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_getters + * @notyetdoced + * @cpponly + * + * @see + * - reportDiagMatr2() + * - getInlineDiagMatr2() + * - getCompMatr2() + * - createDiagMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ DiagMatr2 getDiagMatr2(std::vector in); @@ -560,24 +632,58 @@ static inline CompMatr2 _getCompMatr2FromArr(qcomp in[4][4]) { // spoofing above macros as functions to doc #if 0 - /// @ingroup matrices_getters - /// @notyetdoced - /// @macrodoc + /** @ingroup matrices_getters + * @notyetdoced + * @macrodoc + * + * @see + * - reportCompMatr1() + * - getInlineDiagMatr1() + * - getInlineCompMatr2() + * - createCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ CompMatr1 getInlineCompMatr1({{ matrix }}); - /// @ingroup matrices_getters - /// @notyetdoced - /// @macrodoc + /** @ingroup matrices_getters + * @notyetdoced + * @macrodoc + * + * @see + * - reportCompMatr2() + * - getInlineDiagMatr2() + * - createCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ CompMatr2 getInlineCompMatr2({{ matrix }}); - /// @ingroup matrices_getters - /// @notyetdoced - /// @macrodoc + /** @ingroup matrices_getters + * @notyetdoced + * @macrodoc + * + * @see + * - reportDiagMatr1() + * - getInlineCompMatr1() + * - getInlineDiagMatr2() + * - createDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ DiagMatr1 getInlineDiagMatr1({ list }); - /// @ingroup matrices_getters - /// @notyetdoced - /// @macrodoc + /** @ingroup matrices_getters + * @notyetdoced + * @macrodoc + * + * @see + * - reportDiagMatr2() + * - getInlineCompMatr2() + * - createDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ DiagMatr2 getInlineDiagMatr2({ list }); #endif @@ -595,23 +701,63 @@ extern "C" { #endif - /// @ingroup matrices_create - /// @notyetdoced + /** @ingroup matrices_create + * @notyetdoced + * + * @see + * - setCompMatr() + * - syncCompMatr() + * - createInlineCompMatr() + * - createDiagMatr() + * - getCompMatr1() + * - getCompMatr2() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ CompMatr createCompMatr(int numQubits); - /// @ingroup matrices_create - /// @notyetdoced + /** @ingroup matrices_create + * @notyetdoced + * + * @see + * - setDiagMatr() + * - syncDiagMatr() + * - createInlineDiagMatr() + * - createCompMatr() + * - getDiagMatr1() + * - getDiagMatr2() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ DiagMatr createDiagMatr(int numQubits); - /// @ingroup matrices_create - /// @notyetdoced + /** @ingroup matrices_create + * @notyetdoced + * + * @see + * - createCustomFullStateDiagMatr() + * - setFullStateDiagMatr() + * - syncFullStateDiagMatr() + * - createDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ FullStateDiagMatr createFullStateDiagMatr(int numQubits); - /// @ingroup matrices_create - /// @notyetdoced + /** @ingroup matrices_create + * @notyetdoced + * + * @see + * - createFullStateDiagMatr() + * - setFullStateDiagMatr() + * - syncFullStateDiagMatr() + * - createDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ FullStateDiagMatr createCustomFullStateDiagMatr(int numQubits, int useDistrib, int useGpuAccel, int useMultithread); @@ -669,19 +815,40 @@ extern "C" { #endif - /// @ingroup matrices_setters - /// @notyetdoced + /** @ingroup matrices_setters + * @notyetdoced + * + * @see + * - setInlineCompMatr() + * - reportCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setCompMatr(CompMatr matr, qcomp** vals); - /// @ingroup matrices_setters - /// @notyetdoced + /** @ingroup matrices_setters + * @notyetdoced + * + * @see + * - setInlineDiagMatr() + * - reportDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setDiagMatr(DiagMatr out, qcomp* in); - /// @ingroup matrices_setters - /// @notyetdoced - /// @notyettested + /** @ingroup matrices_setters + * @notyetdoced + * @notyettested + * + * @see + * - setInlineFullStateDiagMatr() + * - reportFullStateDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setFullStateDiagMatr(FullStateDiagMatr out, qindex startInd, qcomp* in, qindex numElems); @@ -711,22 +878,40 @@ extern "C" { // C++ defines vector overloads, permitting inline initialisation - /// @ingroup matrices_setters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_setters + * @notyetdoced + * @cpponly + * + * @see + * - setInlineCompMatr() + * - reportCompMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setCompMatr(CompMatr out, std::vector> in); - /// @ingroup matrices_setters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_setters + * @notyetdoced + * @cpponly + * + * @see + * - setInlineDiagMatr() + * - reportDiagMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setDiagMatr(DiagMatr out, std::vector in); - /// @ingroup matrices_setters - /// @notyetdoced - /// @notyettested - /// @cpponly + /** @ingroup matrices_setters + * @notyetdoced + * @notyettested + * @cpponly + * + * @see + * - setInlineFullStateDiagMatr() + * - reportFullStateDiagMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setFullStateDiagMatr(FullStateDiagMatr out, qindex startInd, std::vector in); @@ -776,10 +961,16 @@ extern "C" { // spoofing above macro as functions to doc #if 0 - /// @ingroup matrices_setters - /// @notyetdoced - /// @macrodoc - /// @conly + /** @ingroup matrices_setters + * @notyetdoced + * @macrodoc + * @conly + * + * @see + * - setInlineCompMatr() + * - reportCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) examples + */ void setCompMatr(CompMatr matr, qcomp arr[matr.numRows][matr.numRows]); #endif @@ -816,22 +1007,39 @@ extern "C" { // validate that they match the struct dimensions (which requires validating the structs). - /// @ingroup matrices_setters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_setters + * @notyetdoced + * @cpponly + * + * @see + * - reportCompMatr() + * - createInlineCompMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setInlineCompMatr(CompMatr matr, int numQb, std::vector> in); - /// @ingroup matrices_setters - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_setters + * @notyetdoced + * @cpponly + * + * @see + * - reportDiagMatr() + * - createInlineDiagMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setInlineDiagMatr(DiagMatr matr, int numQb, std::vector in); - /// @ingroup matrices_setters - /// @notyetdoced - /// @notyettested - /// @cpponly + /** @ingroup matrices_setters + * @notyetdoced + * @notyettested + * @cpponly + * + * @see + * - reportFullStateDiagMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ void setInlineFullStateDiagMatr(FullStateDiagMatr matr, qindex startInd, qindex numElems, std::vector in); @@ -893,22 +1101,43 @@ extern "C" { // spoofing above macros as functions to doc #if 0 - /// @ingroup matrices_setters - /// @notyetdoced - /// @macrodoc + + /** @ingroup matrices_setters + * @notyetdoced + * @macrodoc + * + * @see + * - reportCompMatr() + * - createInlineCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) examples + */ void setInlineCompMatr(CompMatr matr, int numQb, {{ matrix }}); - /// @ingroup matrices_setters - /// @notyetdoced - /// @macrodoc + + /** @ingroup matrices_setters + * @notyetdoced + * @macrodoc + * + * @see + * - reportDiagMatr() + * - createInlineDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) examples + */ void setInlineDiagMatr(DiagMatr matr, int numQb, { list }); - /// @ingroup matrices_setters - /// @notyettested - /// @notyetdoced - /// @macrodoc + + /** @ingroup matrices_setters + * @notyettested + * @notyetdoced + * @macrodoc + * + * @see + * - reportFullStateDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) examples + */ void setInlineFullStateDiagMatr(FullStateDiagMatr matr, qindex startInd, qindex numElems, { list }); + #endif @@ -975,15 +1204,25 @@ extern "C" { // C++ accepts vector initialiser lists - /// @ingroup matrices_create - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_create + * @notyetdoced + * @cpponly + * + * @see + * - reportCompMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ CompMatr createInlineCompMatr(int numQb, std::vector> elems); - /// @ingroup matrices_create - /// @notyetdoced - /// @cpponly + /** @ingroup matrices_create + * @notyetdoced + * @cpponly + * + * @see + * - reportDiagMatr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.cpp) examples + */ DiagMatr createInlineDiagMatr(int numQb, std::vector elems); @@ -1031,16 +1270,29 @@ extern "C" { // spoofing above macros as functions to doc #if 0 - /// @ingroup matrices_create - /// @notyetdoced - /// @macrodoc + + /** @ingroup matrices_create + * @notyetdoced + * @macrodoc + * + * @see + * - reportCompMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) examples + */ CompMatr createInlineCompMatr(int numQb, {{ matrix }}); - /// @ingroup matrices_create - /// @notyetdoced - /// @macrodoc + + /** @ingroup matrices_create + * @notyetdoced + * @macrodoc + * + * @see + * - reportDiagMatr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_matrices.c) examples + */ DiagMatr createInlineDiagMatr(int numQb, { list }); + #endif #else @@ -1121,33 +1373,58 @@ extern "C" { #endif - /// @ingroup matrices_reporters - /// @notyetdoced - /// @notyettested + /** @ingroup matrices_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.cpp) examples + */ void reportCompMatr1(CompMatr1 matrix); - /// @ingroup matrices_reporters - /// @notyetdoced - /// @notyettested + /** @ingroup matrices_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.cpp) examples + */ void reportCompMatr2(CompMatr2 matrix); - /// @ingroup matrices_reporters - /// @notyetdoced - /// @notyettested + /** @ingroup matrices_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.cpp) examples + */ void reportCompMatr(CompMatr matrix); - /// @ingroup matrices_reporters - /// @notyetdoced - /// @notyettested + /** @ingroup matrices_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.cpp) examples + */ void reportDiagMatr1(DiagMatr1 matrix); - /// @ingroup matrices_reporters - /// @notyetdoced - /// @notyettested + /** @ingroup matrices_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.cpp) examples + */ void reportDiagMatr2(DiagMatr2 matrix); @@ -1157,9 +1434,14 @@ extern "C" { void reportDiagMatr(DiagMatr matrix); - /// @ingroup matrices_reporters - /// @notyetdoced - /// @notyettested + /** @ingroup matrices_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_matrices.cpp) examples + */ void reportFullStateDiagMatr(FullStateDiagMatr matr); diff --git a/quest/include/paulis.h b/quest/include/paulis.h index 55f48c485..98f2ef043 100644 --- a/quest/include/paulis.h +++ b/quest/include/paulis.h @@ -49,7 +49,7 @@ */ -/// @notdoced +/// @notyetdoced typedef struct { // represent Pauli strings as base-4 numerals, split into their @@ -61,7 +61,7 @@ typedef struct { } PauliStr; -/// @notdoced +/// @notyetdoced typedef struct { qindex numTerms; @@ -113,8 +113,14 @@ typedef struct { extern "C" { #endif - /// @ingroup paulis_create - /// @notdoced + /** @ingroup paulis_create + * @notyetdoced + * + * @see + * - reportPauliStr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStr getPauliStr(const char* paulis, int* indices, int numPaulis); #ifdef __cplusplus @@ -134,26 +140,47 @@ extern "C" { // {0,3,1} are valid std::string instances, causing overload ambiguity. Blegh! - /// @ingroup paulis_create - /// @notdoced + /** @ingroup paulis_create + * @notyetdoced + * + * @see + * - reportPauliStr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStr getPauliStr(int* paulis, int* indices, int numPaulis); - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - reportPauliStr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStr getPauliStr(std::string paulis, int* indices, int numPaulis); - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - reportPauliStr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStr getPauliStr(std::string paulis, std::vector indices); - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - reportPauliStr() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStr getPauliStr(std::string paulis); @@ -196,9 +223,15 @@ extern "C" { // spoofing above macro as function to doc #if 0 - /// @ingroup paulis_create - /// @notdoced - /// @macrodoc + /** @ingroup paulis_create + * @notyetdoced + * @macrodoc + * + * @see + * - reportPauliStr() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp)examples + */ PauliStr getInlinePauliStr(const char* paulis, { list }); #endif @@ -219,23 +252,47 @@ extern "C" { #endif - /// @ingroup paulis_create - /// @notdoced + /** @ingroup paulis_create + * @notyetdoced + * + * @see + * - reportPauliStrSum() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createPauliStrSum(PauliStr* strings, qcomp* coeffs, qindex numTerms); - /// @ingroup paulis_create - /// @notdoced + /** @ingroup paulis_create + * @notyetdoced + * + * @see + * - reportPauliStrSum() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createInlinePauliStrSum(const char* str); - /// @ingroup paulis_create - /// @notdoced + /** @ingroup paulis_create + * @notyetdoced + * + * @see + * - reportPauliStrSum() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createPauliStrSumFromFile(const char* fn); - /// @ingroup paulis_create - /// @notdoced + /** @ingroup paulis_create + * @notyetdoced + * + * @see + * - reportPauliStrSum() + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createPauliStrSumFromReversedFile(const char* fn); @@ -248,27 +305,47 @@ extern "C" { #ifdef __cplusplus - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - reportPauliStrSum() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createPauliStrSum(std::vector strings, std::vector coeffs); - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - reportPauliStrSum() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createInlinePauliStrSum(std::string str); - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - reportPauliStrSum() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createPauliStrSumFromFile(std::string fn); - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - reportPauliStrSum() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createPauliStrSumFromReversedFile(std::string fn); @@ -288,7 +365,7 @@ extern "C" { /// @ingroup paulis_destroy - /// @notdoced + /// @notyetdoced void destroyPauliStrSum(PauliStrSum sum); @@ -309,14 +386,25 @@ extern "C" { #endif - /// @ingroup paulis_reporters - /// @notdoced - /// @nottested + /** @ingroup paulis_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_paulis.cpp) examples + */ void reportPauliStr(PauliStr str); - /// @ingroup paulis_reporters - /// @notdoced - /// @nottested + + /** @ingroup paulis_reporters + * @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_paulis.c) or + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_paulis.cpp) examples + */ void reportPauliStrSum(PauliStrSum str); From 3d8172a6d9c23c9282574e57c33537c931812bc7 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 12 May 2025 23:58:16 +0200 Subject: [PATCH 13/21] added missing doc to example links --- quest/include/debug.h | 7 ++++++- quest/include/environment.h | 16 +++++++++++++--- quest/include/qureg.h | 18 ++++++++++++++---- 3 files changed, 33 insertions(+), 8 deletions(-) diff --git a/quest/include/debug.h b/quest/include/debug.h index 9b2cefe57..586aab7f7 100644 --- a/quest/include/debug.h +++ b/quest/include/debug.h @@ -73,7 +73,12 @@ int getNumSeeds(); */ -/// @notyetdoced +/** @notyetdoced + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/setting_errorhandler.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/setting_errorhandler.cpp) examples + */ void setInputErrorHandler(void (*callback)(const char* func, const char* msg)); diff --git a/quest/include/environment.h b/quest/include/environment.h index 0880b1d7d..df24ab258 100644 --- a/quest/include/environment.h +++ b/quest/include/environment.h @@ -47,7 +47,12 @@ typedef struct { /// @notyetdoced void initQuESTEnv(); -/// @notyetdoced +/** @notyetdoced + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_environments.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_environments.cpp) examples + */ void initCustomQuESTEnv(int useDistrib, int useGpuAccel, int useMultithread); /// @notyetdoced @@ -56,8 +61,13 @@ void finalizeQuESTEnv(); /// @notyetdoced void syncQuESTEnv(); -/// @notyetdoced -/// @notyettested +/** @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_environments.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_environments.cpp) examples + */ void reportQuESTEnv(); /// @notyetdoced diff --git a/quest/include/qureg.h b/quest/include/qureg.h index 05e0bd4cd..63ed03351 100644 --- a/quest/include/qureg.h +++ b/quest/include/qureg.h @@ -410,13 +410,23 @@ void destroyQureg(Qureg qureg); */ -/// @notyetdoced -/// @notyettested +/** @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_quregs.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_quregs.cpp) examples + */ void reportQuregParams(Qureg qureg); -/// @notyetdoced -/// @notyettested +/** @notyetdoced + * @notyettested + * + * @see + * - [C](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_quregs.c) and + * [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/reporting_quregs.cpp) examples + */ void reportQureg(Qureg qureg); From 90161482efcc0d757fee840ba47a89567b764dd5 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 19 May 2025 00:15:32 +0200 Subject: [PATCH 14/21] added more essential doc formulae for: - setQuregToSuperposition - applyRotateX - applyRotateY - applyRotateZ - applyRotateAroundAxis - applyPauliGadget - applyPhaseGadget - applyPhaseShift - applyTwoQubitPhaseShift - applyMultiQubitPhaseShift - applyPhaseFlip - applyTwoQubitPhaseFlip - applyMultiQubitPhaseFlip - applyTrotterizedPauliStrSumGadget I believe this concludes the formulae for all functions with conventional parameterisations --- quest/include/calculations.h | 6 +- quest/include/initialisations.h | 21 +- quest/include/operations.h | 449 ++++++++++++++++++++++++++++++-- utils/docs/latex/commands.tex | 1 + 4 files changed, 455 insertions(+), 22 deletions(-) diff --git a/quest/include/calculations.h b/quest/include/calculations.h index c2cee9541..560e1f543 100644 --- a/quest/include/calculations.h +++ b/quest/include/calculations.h @@ -76,8 +76,10 @@ extern "C" { * * @myexample * ``` - Qureg qureg = createQureg(4); - PauliStr str = getPauliStr("XYZ"); + Qureg qureg = createQureg(10); + initRandomPureState(qureg); + + PauliStr str = getInlinePauliStr("XYZ", {0,2,3}); qreal expec = calcExpecPauliStr(qureg, str); reportScalar("expec", expec); diff --git a/quest/include/initialisations.h b/quest/include/initialisations.h index bcc875487..9827ea172 100644 --- a/quest/include/initialisations.h +++ b/quest/include/initialisations.h @@ -116,8 +116,25 @@ void setDensityQuregFlatAmps(Qureg qureg, qindex startInd, qcomp* amps, qindex n void setQuregToClone(Qureg targetQureg, Qureg copyQureg); -/// @notyetdoced -/// @notyettested +/** @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); diff --git a/quest/include/operations.h b/quest/include/operations.h index 2f4ae28b8..5abfb4bdb 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -1319,15 +1319,114 @@ extern "C" { #endif -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * Let @f$ \theta = @f$ @p angle. + * This function effects unitary + * @f[ + \hat{R}_{x}(\theta) + = + \exp \left( + - \iu \frac{\theta}{2} + \hat{\sigma}_x + \right) + * @f] + * upon the @p target qubit, where @f$ \hat{\sigma}_x @f$ is the Pauli X matrix. + * + * @equivalences + * - This function is entirely equivalent to calling applyPauliGadget() with a single-site PauliStr. + * ``` + applyPauliGadget(qureg, getInlinePauliStr("X", {target}), angle); + * ``` + * - This function is faster than, but otherwise equivalent to, invoking applyRotateAroundAxis() + * with an axis vector equal to the X-axis. + * ``` + applyRotateAroundAxis(qureg, target, qreal angle, 1,0,0); + * ``` + * - This function is faster than, but otherwise equivalent to, effecting @f$ \hat{R}_{x}(\theta) @f$ as a CompMatr1. + * ``` + qcomp c = cos(angle/2); + qcomp s = sin(angle/2) * (-1.i); + CompMatr1 matr = getInlineCompMatr1({{c, s}, {s, c}}); + applyCompMatr1(qureg, target, matr); + * ``` + */ void applyRotateX(Qureg qureg, int target, qreal angle); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * Let @f$ \theta = @f$ @p angle. + * This function effects unitary + * @f[ + \hat{R}_{y}(\theta) + = + \exp \left( + - \iu \frac{\theta}{2} + \hat{\sigma}_y + \right) + * @f] + * upon the @p target qubit, where @f$ \hat{\sigma}_y @f$ is the Pauli Y matrix. + * + * @equivalences + * - This function is entirely equivalent to calling applyPauliGadget() with a single-site PauliStr. + * ``` + applyPauliGadget(qureg, getInlinePauliStr("Y", {target}), angle); + * ``` + * - This function is faster than, but otherwise equivalent to, invoking applyRotateAroundAxis() + * with an axis vector equal to the Y-axis. + * ``` + applyRotateAroundAxis(qureg, target, qreal angle, 0,1,0); + * ``` + * - This function is faster than, but otherwise equivalent to, effecting @f$ \hat{R}_{y}(\theta) @f$ as a CompMatr1. + * ``` + qcomp c = cos(angle/2); + qcomp s = sin(angle/2); + CompMatr1 matr = getInlineCompMatr1({{c, -s}, {s, c}}); + applyCompMatr1(qureg, target, matr); + * ``` + */ void applyRotateY(Qureg qureg, int target, qreal angle); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * Let @f$ \theta = @f$ @p angle. + * This function effects unitary + * @f[ + \hat{R}_{z}(\theta) + = + \exp \left( + - \iu \frac{\theta}{2} + \hat{\sigma}_z + \right) + * @f] + * upon the @p target qubit, where @f$ \hat{\sigma}_z @f$ is the Pauli Z matrix. + * + * @equivalences + * - This function is entirely equivalent to calling applyPauliGadget() with a single-site PauliStr. + * ``` + applyPauliGadget(qureg, getInlinePauliStr("Z", {target}), angle); + * ``` + * - This function is faster than, but otherwise equivalent to, invoking applyRotateAroundAxis() + * with an axis vector equal to the Z-axis. + * ``` + applyRotateAroundAxis(qureg, target, qreal angle, 0,0,1); + * ``` + * - This function is faster than, but otherwise equivalent to, effecting @f$ \hat{R}_{z}(\theta) @f$ as a DiagMatr1. + * ``` + qcomp a = cexp(- angle / 2 * 1.i); + qcomp b = cexp( angle / 2 * 1.i); + DiagMatr1 matr = getInlineDiagMatr1({a, b}); + applyDiagMatr1(qureg, target, matr); + * ``` + */ void applyRotateZ(Qureg qureg, int target, qreal angle); @@ -1367,8 +1466,62 @@ void applyMultiStateControlledRotateY(Qureg qureg, int* controls, int* states, i void applyMultiStateControlledRotateZ(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); -/// @notyetdoced -void applyRotateAroundAxis(Qureg qureg, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); +/** @notyetdoced + * + * @formulae + * + * Let @f$ \theta = @f$ @p angle and @f$ \vec{n} = ( @f$ @p axisX, @p axisY, @p axisZ @f$ ) @f$, + * with corresponding unit vector @f$ \bar{n} @f$. + * Further, let @f$ \vec{\sigma} = (\hat{\sigma}_x, \hat{\sigma}_y, \hat{\sigma}_z) @f$ denote a vector of the Pauli matrices. + * + * This function effects unitary + * @f[ + \hat{R}_{\bar{n}}(\theta) + = + \exp \left( + - \iu \frac{\theta}{2} + \bar{n} \cdot \vec{\sigma} + \right) + * @f] + * upon the target qubit. Explicitly, + * @f[ + \hat{R}_{\bar{n}}(\theta) + \equiv + \begin{pmatrix} + \cos\left( \frac{\theta}{2} \right) - \iu \, \bar{n}_z \sin\left( \frac{\theta}{2} \right) + & + - \, (\bar{n}_y + \bar{n}_x \, \iu ) \sin\left( \frac{\theta}{2} \right) + \\ + (\bar{n}_y - \bar{n}_x \, \iu ) \sin\left( \frac{\theta}{2} \right) + & + \cos\left( \frac{\theta}{2} \right) + \iu \, \bar{n}_z \sin\left( \frac{\theta}{2} \right) + \end{pmatrix} + * @f] + * where + * @f[ + \bar{n}_i + = + \frac{\vec{n}_i}{\| \vec{n} \|_2} + = + \frac{\vec{n}_i}{ \sqrt{ {\vec{n}_x}^2 + {\vec{n}_y}^2 + {\vec{n}_z}^2 } }. + * @f] + * + * @equivalences + * - Assuming @f$ \| \vec{n} \|_2 \ne 0 @f$, this function is agnostic to the normalisation + * of the axis vector. + * ``` + applyRotateAroundAxis(qureg, target, angle, x, y, z); + applyRotateAroundAxis(qureg, target, angle, 5*x,5*y,5*z); // equivalent + * ``` + * - This function is entirely equivalent to preparing @f$ \hat{R}_{\bar{n}}(\theta) @f$ + * as a CompMatr1 and effecting it upon the state via applyCompMatr1(). + * - This function is both more accurate and efficient than equivalently instantiating a + * three-term PauliStrSum @f$ \hat{H} = \bar{n} \cdot \vec{\sigma}@f$ and effecting + * @f$ \exp \left(\iu \alpha \hat{H} \right) @f$ via applyTrotterizedPauliStrSumGadget() + * with @f$ \alpha = - \theta/2 @f$ and very many repetitions. + * + */ +void applyRotateAroundAxis(Qureg qureg, int target, qreal angle, qreal axisX, qreal axisY, qreal axisZ); /// @notyetdoced @@ -1469,7 +1622,61 @@ extern "C" { void multiplyPauliGadget(Qureg qureg, PauliStr str, qreal angle); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * Let @f$ \hat{\sigma} = @f$ @p str and @f$ \theta = @f$ @p angle. + * + * This function effects unitary + * @f[ + R_{\hat{\sigma}}(\theta) = \exp \left( - \iu \, \frac{\theta}{2} \, \hat{\sigma} \right), + * @f] + * which affects only the qubits for which @f$ \hat{\sigma} @f$ is not the identity + * Pauli. As such, this effects a multi-qubit rotation around an arbitrary Pauli string. + * + * @equivalences + * - Because @f$ R_{\hat{\sigma}}(\theta) @f$ satisfies + * @f[ + R_{\hat{\sigma}}(\theta) \equiv + \cos\left( \frac{\theta}{2} \right) \, \id + - \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. + * ``` + // 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); + * ``` + * - 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. + * - When @p str contains only @f$ \id @f$ Paulis, this function merely effects a change + * of global phase upon statevectors of @f$ -\theta/2 @f$, leaving density matrices + * unchanged. + * ``` + qcomp factor = cexp(- theta / 2 * 1.i); + setQuregToSuperposition(factor, qureg, 0,qureg,0,qureg); + * ``` + * + * @myexample + * ``` + Qureg qureg = createQureg(10); + qreal theta = 3.14; + + // verbosely + int numPaulis = 4; + char* paulis = "XYIZ"; + int targets[] = {0,1,5,7}; + PauliStr str = getPauliStr(paulis, targets, numPaulis); + applyPauliGadget(qureg, str, angle); + + // concisely + applyPauliGadget(qureg, getInlinePauliStr("XYZ",{0,1,7}), theta); + * ``` + */ void applyPauliGadget(Qureg qureg, PauliStr str, qreal angle); @@ -1529,7 +1736,23 @@ extern "C" { void multiplyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * Let @f$ \vec{t} = @f$ @p targets and @f$ \theta = @f$ @p angle. + * + * This function effects diagonal unitary + * @f[ + R_{\hat{Z}}(\theta) = \exp \left( - \iu \, \frac{\theta}{2} \, \bigotimes_{t \,\in\, \vec{t}} \hat{Z}_t \right). + * @f] + * + * @equivalences + * - This function is equivalent to calling applyPauliGadget() with a PauliStr containing only @f$ \hat{Z} @f$ and @f$ \id @f$. + * This latter function will actually automatically invoke applyPhaseGadget() which has an optimised implementation. + * - This function is equivalent to, albeit much faster than, preparing a DiagMatr with @f$ \pm 1 @f$ elements (depending upon + * the parity of the targeted set bits) and effecting it with applyDiagMatr(). + */ void applyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle); @@ -1545,15 +1768,52 @@ void applyMultiControlledPhaseGadget(Qureg qureg, int* controls, int numControls void applyMultiStateControlledPhaseGadget(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, qreal angle); -/// @notyetdoced +/** @notyetdoced + * + * This function is a mere alias of applyPauliZ(), meaningfully differing only for many targets. + */ void applyPhaseFlip(Qureg qureg, int target); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * Let @f$ \theta = @f$ @p angle. This function effects diagonal unitary + * + * @f[ + \hat{U}(\theta) = \begin{pmatrix} 1 & 0 \\ 0 & e^{\iu \theta} \end{pmatrix} + * @f] + * upon the @p target qubit. + * + * @equivalences + * - This function is equivalent to, albeit much faster than, a Z-axis rotation with + * an adjustment to the global phase (which is redundant upon density matrices). + * @f[ + * \hat{U}(\theta) \equiv \hat{R}_z(\theta) \cdot e^{\iu \frac{\theta}{2}} \hat{\id} + * @f] + * ``` + applyRotateZ(qureg, target, angle); + applyPauliGadget(qureg, getPauliStr("I"), angle); // global phase + * ``` + */ void applyPhaseShift(Qureg qureg, int target, qreal angle); -/** Applies a two-qubit phase flip upon @p qubit1 and @p qubit2 of @p qureg. +/** @notyetdoced + * + * Applies a two-qubit phase flip upon qubits @p target1 and @p target2 of @p qureg. + * + * @formulae + * + * This function flips the sign of all computational basis states for which + * the targeted qubits are in state @f$ \ket{1}\ket{1} @f$. This is equivalent + * to the diagonal unitary + * + * @f[ + \hat{U}(\theta) = \begin{pmatrix} 1 \\ & 1 \\ & & 1 \\ & & & -1 \end{pmatrix}, + * @f] + * effected upon the target qubits. * * @diagram * @dot @@ -1577,12 +1837,41 @@ digraph { } * @enddot * - * @notyetdoced + * @equivalences + * - The target qubits are interchangeable, ergo + * ``` + applyTwoQubitPhaseFlip(qureg, target1, target2); + applyTwoQubitPhaseFlip(qureg, target2, target1); // equivalent + * ``` + * - This function is entirely equivalent to a controlled Pauli-Z unitary (or a hypothetical + * controlled variant of applyPhaseFlip()) with either target qubit substituted for the control qubit. + * ``` + applyControlledPauliZ(qureg, target1, target2); + * ``` + * - This function is faster and more accurate than, but otherwise equivalent to, a two-qubit phase shift + * with angle @f$ = \pi @f$. + * ``` + applyTwoQubitPhaseShift(qureg, target1, target2, 3.141592653); // approx equiv + * ``` */ -void applyTwoQubitPhaseFlip( Qureg qureg, int target1, int target2); +void applyTwoQubitPhaseFlip(Qureg qureg, int target1, int target2); -/** Applies a two-qubit phase flip upon @p qubit1 and @p qubit2 of @p qureg. +/** @notyetdoced + * + * Applies a two-qubit phase shift upon qubits @p target1 and @p target2 of @p qureg. + * + * @formulae + * + * Let @f$ \theta = @f$ @p angle. + * This function multiplies factor @f$ e^{\iu \theta} @f$ upon all computational basis states + * for which the targeted qubits are in state @f$ \ket{1}\ket{1} @f$. This is equivalent + * to the diagonal unitary + * + * @f[ + \hat{U}(\theta) = \begin{pmatrix} 1 \\ & 1 \\ & & 1 \\ & & & e^{\iu \theta} \end{pmatrix}, + * @f] + * effected upon the target qubits. * * @diagram * @dot @@ -1608,16 +1897,91 @@ digraph { } * @enddot * - * @notyetdoced + * @equivalences + * - The target qubits are interchangeable, ergo + * ``` + applyTwoQubitPhaseShift(qureg, target1, target2, angle); + applyTwoQubitPhaseShift(qureg, target2, target1, angle); // equivalent + * ``` + * - This function is equivalent to a controlled variant of applyPhaseShift(), treating + * either target qubit as the control qubit. + * - This function generalises applyTwoQubitPhaseFlip() to arbitrary changes in phase. */ void applyTwoQubitPhaseShift(Qureg qureg, int target1, int target2, qreal angle); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * This function flips the sign of all computational basis states for which + * the targeted qubits are all in state @f$ \ket{1} @f$. This is equivalent + * to the diagonal unitary + * @f[ + \hat{U}(\theta) = \begin{pmatrix} 1 \\ & \ddots \\ & & 1 \\ & & & -1 \end{pmatrix}, + * @f] + * effected upon the target qubits. + * + * @equivalences + * - The ordering of @p targets has no affect on the effected operation. + * - This function is entirely equivalent to a multi-controlled Pauli-Z unitary (or a hypothetical + * many-controlled variant of applyPhaseFlip()) with all but one arbitrary target qubit becoming + * control qubits. + * ``` + applyMultiControlledPauliZ(qureg, targets, numTargets-1, targets[0]); + * ``` + * - This function is faster and more accurate than, but otherwise equivalent to, a multi-qubit phase shift + * with angle @f$ = \pi @f$. + * ``` + applyMultiQubitPhaseShift(qureg, targets, numTargets, 3.141592653); // approx equiv + * ``` + */ void applyMultiQubitPhaseFlip(Qureg qureg, int* targets, int numTargets); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * Let @f$ \theta = @f$ @p angle. + * This function multiplies factor @f$ e^{\iu \theta} @f$ upon all computational basis states + * for which all targeted qubits are in state @f$ \ket{1} @f$. This is equivalent + * to the diagonal unitary + * @f[ + \hat{U}(\theta) = \begin{pmatrix} 1 \\ & \ddots \\ & & 1 \\ & & & e^{\iu \theta} \end{pmatrix}, + * @f] + * effected upon the target qubits. + * + * @diagram + * @dot +digraph { + rankdir=LR; + layout=neato; + node [fontsize=10, fontname="Menlo"]; + edge [dir=none]; + + topWireL [shape=plaintext, label="target1", pos="0,.5!"]; + topWireM [shape=point, label="", width=.1, pos=".75,.5!"] + topWireR [shape=plaintext, label="", pos="1.5,.5!"]; + + botWireL [shape=plaintext, label="target2", pos="0,0!"]; + botWireM [shape=point, label="", width=.1, pos=".75,0!"]; + botWireR [shape=plaintext, label="", pos="1.5,0!"]; + + topWireL -> topWireR; + botWireL -> botWireR; + botWireM -> topWireM; + + angle [shape=plaintext, label="θ", pos=".85,-.2!"]; +} + * @enddot + * + * @equivalences + * - The ordering of @p targets has no affect on the effected operation. + * - This function is equivalent to a multi-controlled variant of applyPhaseShift(), treating all + * but one arbitrary target qubit as control qubits. + * - This function generalises applyMultiQubitPhaseFlip() to arbitrary changes in phase. + */ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal angle); @@ -1701,8 +2065,57 @@ extern "C" { void multiplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace); -/// @notyetdoced -/// @notyettested +/** @notyetdoced + * @notyettested + * + * @formulae + * + * Let @f$ \hat{H} = @f$ @p sum and @f$ \theta = @f$ @p angle. This function approximates the action of + * @f[ + \exp \left(\iu \, \theta \, \hat{H} \right) + * @f] + * via a Trotter-Suzuki decomposition of the specified @p order and number of repetitions (@p reps). + * + * + * To be precise, let @f$ r = @f$ @p reps and assume @p sum is composed of + * @f$ T @f$-many terms of the form + * @f[ + \hat{H} = \sum\limits_j^T c_j \, \hat{\sigma}_j + * @f] + * where @f$ c_j @f$ is the (necessarily real) coefficient of the @f$ j @f$-th PauliStr @f$ \hat{\sigma}_j @f$. + * + * - When @p order=1, this function performs first-order Trotterisation, whereby + * @f[ + \exp(\iu \, \theta \, \hat{H} ) + \approx + \prod\limits^{r} + \prod\limits_{j=1}^{T} + \exp \left( \iu \, \frac{\theta \, c_j}{r} \, \hat\sigma_j \right). + * @f] + * - When @p order=2, this function performs the lowest order "symmetrized" Suzuki decomposition, whereby + * @f[ + \exp(\iu \, \theta \, \hat{H} ) + \approx + \prod\limits^{r} \left[ + \prod\limits_{j=1}^{T} \exp \left( \iu \frac{\theta \, c_j}{2 \, r} \hat\sigma_j \right) + \prod\limits_{j=T}^{1} \exp \left( \iu \frac{\theta \, c_j}{2 \, r} \hat\sigma_j \right) + \right]. + * @f] + * - Greater, even values of @p order (denoted by symbol @f$ n @f$) invoke higher-order symmetrized decompositions + * @f$ S[\theta,n,r] @f$. Letting @f$ p = \left( 4 - 4^{1/(n-1)} \right)^{-1} @f$, these satisfy + * @f{align*} + S[\theta, n, 1] &= + \left( \prod\limits^2 S[p \, \theta, n-2, 1] \right) + S[ (1-4p)\,\theta, n-2, 1] + \left( \prod\limits^2 S[p \, \theta, n-2, 1] \right), + \\ + S[\theta, n, r] &= + \prod\limits^{r} S\left[\frac{\theta}{r}, n, 1\right]. + * @f} + * + * > These formulations are taken from 'Finding Exponential Product Formulas + * > of Higher Orders', Naomichi Hatano and Masuo Suzuki (2005) (arXiv). + */ void applyTrotterizedPauliStrSumGadget(Qureg qureg, PauliStrSum sum, qreal angle, int order, int reps); diff --git a/utils/docs/latex/commands.tex b/utils/docs/latex/commands.tex index 790e1545f..dfd5da5cd 100644 --- a/utils/docs/latex/commands.tex +++ b/utils/docs/latex/commands.tex @@ -15,6 +15,7 @@ \newcommand{\brapsi}{\bra{\psi}} \newcommand{\dmrho}{\mathbf{\rho}} \newcommand{\pstr}{\sigma^{\otimes}} +\newcommand{\iu}{\mathrm{i}} \renewcommand{\poormanscomment}{ The validation epsilon, which should maybe have a special (bold?) symbol } From c3f3dbbe3004deee84ff30af7c79a49face30877 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 19 May 2025 00:18:40 +0200 Subject: [PATCH 15/21] added equivalence note about zero-parameter --- quest/include/operations.h | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/quest/include/operations.h b/quest/include/operations.h index 5abfb4bdb..25e165114 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -1352,6 +1352,7 @@ extern "C" { CompMatr1 matr = getInlineCompMatr1({{c, s}, {s, c}}); applyCompMatr1(qureg, target, matr); * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyRotateX(Qureg qureg, int target, qreal angle); @@ -1389,6 +1390,7 @@ void applyRotateX(Qureg qureg, int target, qreal angle); CompMatr1 matr = getInlineCompMatr1({{c, -s}, {s, c}}); applyCompMatr1(qureg, target, matr); * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyRotateY(Qureg qureg, int target, qreal angle); @@ -1426,6 +1428,7 @@ void applyRotateY(Qureg qureg, int target, qreal angle); DiagMatr1 matr = getInlineDiagMatr1({a, b}); applyDiagMatr1(qureg, target, matr); * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyRotateZ(Qureg qureg, int target, qreal angle); @@ -1519,7 +1522,7 @@ void applyMultiStateControlledRotateZ(Qureg qureg, int* controls, int* states, i * three-term PauliStrSum @f$ \hat{H} = \bar{n} \cdot \vec{\sigma}@f$ and effecting * @f$ \exp \left(\iu \alpha \hat{H} \right) @f$ via applyTrotterizedPauliStrSumGadget() * with @f$ \alpha = - \theta/2 @f$ and very many repetitions. - * + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyRotateAroundAxis(Qureg qureg, int target, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1676,6 +1679,7 @@ void multiplyPauliGadget(Qureg qureg, PauliStr str, qreal angle); // concisely applyPauliGadget(qureg, getInlinePauliStr("XYZ",{0,1,7}), theta); * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyPauliGadget(Qureg qureg, PauliStr str, qreal angle); @@ -1752,6 +1756,7 @@ void multiplyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle) * This latter function will actually automatically invoke applyPhaseGadget() which has an optimised implementation. * - This function is equivalent to, albeit much faster than, preparing a DiagMatr with @f$ \pm 1 @f$ elements (depending upon * the parity of the targeted set bits) and effecting it with applyDiagMatr(). + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle); @@ -1796,6 +1801,7 @@ void applyPhaseFlip(Qureg qureg, int target); applyRotateZ(qureg, target, angle); applyPauliGadget(qureg, getPauliStr("I"), angle); // global phase * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyPhaseShift(Qureg qureg, int target, qreal angle); @@ -1906,6 +1912,7 @@ digraph { * - This function is equivalent to a controlled variant of applyPhaseShift(), treating * either target qubit as the control qubit. * - This function generalises applyTwoQubitPhaseFlip() to arbitrary changes in phase. + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyTwoQubitPhaseShift(Qureg qureg, int target1, int target2, qreal angle); @@ -1981,6 +1988,7 @@ digraph { * - This function is equivalent to a multi-controlled variant of applyPhaseShift(), treating all * but one arbitrary target qubit as control qubits. * - This function generalises applyMultiQubitPhaseFlip() to arbitrary changes in phase. + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal angle); From a3e447da3c26a6657b76e86447adf1a5676b4bd6 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 19 May 2025 01:20:45 +0200 Subject: [PATCH 16/21] linked C++-only func doc to C func --- quest/include/calculations.h | 4 ++ quest/include/debug.h | 2 + quest/include/decoherence.h | 2 + quest/include/initialisations.h | 5 +++ quest/include/operations.h | 66 +++++++++++++++++++++++++++++++++ quest/include/paulis.h | 5 +++ quest/include/qureg.h | 2 + quest/include/types.h | 2 + 8 files changed, 88 insertions(+) diff --git a/quest/include/calculations.h b/quest/include/calculations.h index 560e1f543..c0c9e69b4 100644 --- a/quest/include/calculations.h +++ b/quest/include/calculations.h @@ -337,6 +337,7 @@ qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see calcProbOfMultiQubitOutcome() qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -345,6 +346,7 @@ qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector qubits, std::vec /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see calcProbsOfAllMultiQubitOutcomes() std::vector calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector qubits); @@ -353,6 +355,7 @@ std::vector calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector traceOutQubits); @@ -361,6 +364,7 @@ Qureg calcPartialTrace(Qureg qureg, std::vector traceOutQubits); /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see calcReducedDensityMatrix() Qureg calcReducedDensityMatrix(Qureg qureg, std::vector retainQubits); diff --git a/quest/include/debug.h b/quest/include/debug.h index 586aab7f7..58a54405b 100644 --- a/quest/include/debug.h +++ b/quest/include/debug.h @@ -193,6 +193,7 @@ void getEnvironmentString(char str[200]); /// @notyettested /// @notyetdoced /// @cpponly +/// @see setSeeds() void setSeeds(std::vector seeds); @@ -200,6 +201,7 @@ void setSeeds(std::vector seeds); /// @notyettested /// @notyetdoced /// @cpponly +/// @see getSeeds() std::vector getSeeds(); diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index 277e01a99..0ad291f54 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -361,12 +361,14 @@ void mixSuperOp(Qureg qureg, int* targets, int numTargets, SuperOp superop); /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see mixKrausMap() void mixKrausMap(Qureg qureg, std::vector targets, KrausMap map); /// @notyettested /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see mixSuperOp() void mixSuperOp(Qureg qureg, std::vector targets, SuperOp superop); #endif // __cplusplus diff --git a/quest/include/initialisations.h b/quest/include/initialisations.h index 9827ea172..06599fdda 100644 --- a/quest/include/initialisations.h +++ b/quest/include/initialisations.h @@ -187,6 +187,7 @@ void setQuregToReducedDensityMatrix(Qureg out, Qureg in, int* retainQubits, int /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see setQuregAmps() void setQuregAmps(Qureg qureg, qindex startInd, std::vector amps); @@ -195,6 +196,7 @@ void setQuregAmps(Qureg qureg, qindex startInd, std::vector amps); /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see setDensityQuregAmps() void setDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, std::vector> amps); @@ -203,6 +205,7 @@ void setDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, std::vec /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see setDensityQuregFlatAmps() void setDensityQuregFlatAmps(Qureg qureg, qindex startInd, std::vector amps); @@ -211,6 +214,7 @@ void setDensityQuregFlatAmps(Qureg qureg, qindex startInd, std::vector am /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see setQuregToPartialTrace() void setQuregToPartialTrace(Qureg out, Qureg in, std::vector traceOutQubits); @@ -219,6 +223,7 @@ void setQuregToPartialTrace(Qureg out, Qureg in, std::vector traceOutQubits /// @notyetdoced /// @notyetvalidated /// @cpponly +/// @see setQuregToReducedDensityMatrix() void setQuregToReducedDensityMatrix(Qureg out, Qureg in, std::vector retainQubits); diff --git a/quest/include/operations.h b/quest/include/operations.h index 25e165114..309eb2eb5 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -299,6 +299,7 @@ void applyMultiStateControlledCompMatr1(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledCompMatr1() void applyMultiControlledCompMatr1(Qureg qureg, std::vector controls, int target, CompMatr1 matrix); @@ -306,6 +307,7 @@ void applyMultiControlledCompMatr1(Qureg qureg, std::vector controls, int t /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledCompMatr1(Qureg qureg, std::vector controls, std::vector states, int target, CompMatr1 matrix); @@ -490,6 +492,7 @@ void applyMultiStateControlledCompMatr2(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledCompMatr2() void applyMultiControlledCompMatr2(Qureg qureg, std::vector controls, int target1, int target2, CompMatr2 matr); @@ -497,6 +500,7 @@ void applyMultiControlledCompMatr2(Qureg qureg, std::vector controls, int t /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledCompMatr2() void applyMultiStateControlledCompMatr2(Qureg qureg, std::vector controls, std::vector states, int numControls, int target1, int target2, CompMatr2 matr); @@ -550,6 +554,7 @@ void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see multiplyCompMatr() void multiplyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); @@ -564,6 +569,7 @@ void applyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyControlledCompMatr() void applyControlledCompMatr(Qureg qureg, int control, std::vector targets, CompMatr matr); @@ -571,6 +577,7 @@ void applyControlledCompMatr(Qureg qureg, int control, std::vector targets, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledCompMatr() void applyMultiControlledCompMatr(Qureg qureg, std::vector controls, std::vector targets, CompMatr matr); @@ -578,6 +585,7 @@ void applyMultiControlledCompMatr(Qureg qureg, std::vector controls, std::v /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledCompMatr() void applyMultiStateControlledCompMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, CompMatr matr); @@ -631,6 +639,7 @@ void applyMultiStateControlledDiagMatr1(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledDiagMatr1() void applyMultiControlledDiagMatr1(Qureg qureg, std::vector controls, int target, DiagMatr1 matr); @@ -638,6 +647,7 @@ void applyMultiControlledDiagMatr1(Qureg qureg, std::vector controls, int t /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledDiagMatr1() void applyMultiStateControlledDiagMatr1(Qureg qureg, std::vector controls, std::vector states, int target, DiagMatr1 matr); @@ -691,6 +701,7 @@ void applyMultiStateControlledDiagMatr2(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledDiagMatr2() void applyMultiControlledDiagMatr2(Qureg qureg, std::vector controls, int target1, int target2, DiagMatr2 matr); @@ -698,6 +709,7 @@ void applyMultiControlledDiagMatr2(Qureg qureg, std::vector controls, int t /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledDiagMatr2() void applyMultiStateControlledDiagMatr2(Qureg qureg, std::vector controls, std::vector states, int target1, int target2, DiagMatr2 matr); @@ -771,6 +783,7 @@ void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* sta /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see multiplyDiagMatr() void multiplyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); @@ -778,6 +791,7 @@ void multiplyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyDiagMatr() void applyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); @@ -785,6 +799,7 @@ void applyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyControlledDiagMatr() void applyControlledDiagMatr(Qureg qureg, int control, std::vector targets, DiagMatr matrix); @@ -792,6 +807,7 @@ void applyControlledDiagMatr(Qureg qureg, int control, std::vector targets, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledDiagMatr() void applyMultiControlledDiagMatr(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix); @@ -799,6 +815,7 @@ void applyMultiControlledDiagMatr(Qureg qureg, std::vector controls, std::v /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledDiagMatr() void applyMultiStateControlledDiagMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix); @@ -806,6 +823,7 @@ void applyMultiStateControlledDiagMatr(Qureg qureg, std::vector controls, s /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see multiplyDiagMatrPower() void multiplyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -813,6 +831,7 @@ void multiplyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matri /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyDiagMatrPower() void applyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -820,6 +839,7 @@ void applyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyControlledDiagMatrPower() void applyControlledDiagMatrPower(Qureg qureg, int control, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -827,6 +847,7 @@ void applyControlledDiagMatrPower(Qureg qureg, int control, std::vector tar /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledDiagMatrPower() void applyMultiControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -834,6 +855,7 @@ void applyMultiControlledDiagMatrPower(Qureg qureg, std::vector controls, s /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledDiagMatrPower() void applyMultiStateControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -957,6 +979,7 @@ void applyMultiStateControlledHadamard(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledS() void applyMultiControlledS(Qureg qureg, std::vector controls, int target); @@ -964,6 +987,7 @@ void applyMultiControlledS(Qureg qureg, std::vector controls, int target); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledS() void applyMultiStateControlledS(Qureg qureg, std::vector controls, std::vector states, int target); @@ -971,6 +995,7 @@ void applyMultiStateControlledS(Qureg qureg, std::vector controls, std::vec /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledT() void applyMultiControlledT(Qureg qureg, std::vector controls, int target); @@ -978,6 +1003,7 @@ void applyMultiControlledT(Qureg qureg, std::vector controls, int target); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledT() void applyMultiStateControlledT(Qureg qureg, std::vector controls, std::vector states, int target); @@ -985,6 +1011,7 @@ void applyMultiStateControlledT(Qureg qureg, std::vector controls, std::vec /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledHadamard() void applyMultiControlledHadamard(Qureg qureg, std::vector controls, int target); @@ -992,6 +1019,7 @@ void applyMultiControlledHadamard(Qureg qureg, std::vector controls, int ta /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledHadamard() void applyMultiStateControlledHadamard(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1089,6 +1117,7 @@ void applyMultiStateControlledSqrtSwap(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledSwap() void applyMultiControlledSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); @@ -1096,6 +1125,7 @@ void applyMultiControlledSwap(Qureg qureg, std::vector controls, int qubit1 /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledSwap() void applyMultiStateControlledSwap(Qureg qureg, std::vector controls, std::vector states, int qubit1, int qubit2); @@ -1103,6 +1133,7 @@ void applyMultiStateControlledSwap(Qureg qureg, std::vector controls, std:: /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledSqrtSwap() void applyMultiControlledSqrtSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); @@ -1110,6 +1141,7 @@ void applyMultiControlledSqrtSwap(Qureg qureg, std::vector controls, int qu /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledSqrtSwap() void applyMultiStateControlledSqrtSwap(Qureg qureg, std::vector controls, std::vector states, int numControls, int qubit1, int qubit2); @@ -1203,6 +1235,7 @@ void applyMultiStateControlledPauliZ(Qureg qureg, int* controls, int* states, in /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledPauliX() void applyMultiControlledPauliX(Qureg qureg, std::vector controls, int target); @@ -1210,6 +1243,7 @@ void applyMultiControlledPauliX(Qureg qureg, std::vector controls, int targ /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledPauliY() void applyMultiControlledPauliY(Qureg qureg, std::vector controls, int target); @@ -1217,6 +1251,7 @@ void applyMultiControlledPauliY(Qureg qureg, std::vector controls, int targ /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledPauliZ() void applyMultiControlledPauliZ(Qureg qureg, std::vector controls, int target); @@ -1224,6 +1259,7 @@ void applyMultiControlledPauliZ(Qureg qureg, std::vector controls, int targ /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledPauliX() void applyMultiStateControlledPauliX(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1231,6 +1267,7 @@ void applyMultiStateControlledPauliX(Qureg qureg, std::vector controls, std /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledPauliY() void applyMultiStateControlledPauliY(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1238,6 +1275,7 @@ void applyMultiStateControlledPauliY(Qureg qureg, std::vector controls, std /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledPauliZ() void applyMultiStateControlledPauliZ(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1291,6 +1329,7 @@ void applyMultiStateControlledPauliStr(Qureg qureg, int* controls, int* states, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledPauliStr() void applyMultiControlledPauliStr(Qureg qureg, std::vector controls, PauliStr str); @@ -1298,6 +1337,7 @@ void applyMultiControlledPauliStr(Qureg qureg, std::vector controls, PauliS /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledPauliStr() void applyMultiStateControlledPauliStr(Qureg qureg, std::vector controls, std::vector states, PauliStr str); @@ -1551,6 +1591,7 @@ void applyMultiStateControlledRotateAroundAxis(Qureg qureg, int* ctrls, int* sta /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledRotateX() void applyMultiControlledRotateX(Qureg qureg, std::vector controls, int target, qreal angle); @@ -1558,6 +1599,7 @@ void applyMultiControlledRotateX(Qureg qureg, std::vector controls, int tar /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledRotateY() void applyMultiControlledRotateY(Qureg qureg, std::vector controls, int target, qreal angle); @@ -1565,6 +1607,7 @@ void applyMultiControlledRotateY(Qureg qureg, std::vector controls, int tar /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledRotateZ() void applyMultiControlledRotateZ(Qureg qureg, std::vector controls, int target, qreal angle); @@ -1572,6 +1615,7 @@ void applyMultiControlledRotateZ(Qureg qureg, std::vector controls, int tar /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledRotateX() void applyMultiStateControlledRotateX(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); @@ -1579,6 +1623,7 @@ void applyMultiStateControlledRotateX(Qureg qureg, std::vector controls, st /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledRotateY() void applyMultiStateControlledRotateY(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); @@ -1586,6 +1631,7 @@ void applyMultiStateControlledRotateY(Qureg qureg, std::vector controls, st /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledRotateZ() void applyMultiStateControlledRotateZ(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); @@ -1593,6 +1639,7 @@ void applyMultiStateControlledRotateZ(Qureg qureg, std::vector controls, st /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledRotateAroundAxis() void applyMultiControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1600,6 +1647,7 @@ void applyMultiControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, i /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledRotateAroundAxis() void applyMultiStateControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, std::vector states, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1708,6 +1756,7 @@ void applyMultiStateControlledPauliGadget(Qureg qureg, int* controls, int* state /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledPauliGadget() void applyMultiControlledPauliGadget(Qureg qureg, std::vector controls, PauliStr str, qreal angle); @@ -1715,6 +1764,7 @@ void applyMultiControlledPauliGadget(Qureg qureg, std::vector controls, Pau /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledPauliGadget() void applyMultiStateControlledPauliGadget(Qureg qureg, std::vector controls, std::vector states, PauliStr str, qreal angle); @@ -2005,6 +2055,7 @@ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see multiplyPhaseGadget() void multiplyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); @@ -2012,6 +2063,7 @@ void multiplyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyPhaseGadget() void applyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); @@ -2019,6 +2071,7 @@ void applyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyControlledPhaseGadget() void applyControlledPhaseGadget(Qureg qureg, int control, std::vector targets, qreal angle); @@ -2026,6 +2079,7 @@ void applyControlledPhaseGadget(Qureg qureg, int control, std::vector targe /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledPhaseGadget() void applyMultiControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector targets, qreal angle); @@ -2033,6 +2087,7 @@ void applyMultiControlledPhaseGadget(Qureg qureg, std::vector controls, std /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledPhaseGadget() void applyMultiStateControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector states, std::vector targets, qreal angle); @@ -2040,6 +2095,7 @@ void applyMultiStateControlledPhaseGadget(Qureg qureg, std::vector controls /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiQubitPhaseFlip() void applyMultiQubitPhaseFlip(Qureg qureg, std::vector targets); @@ -2047,6 +2103,7 @@ void applyMultiQubitPhaseFlip(Qureg qureg, std::vector targets); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiQubitPhaseShift() void applyMultiQubitPhaseShift(Qureg qureg, std::vector targets, qreal angle); @@ -2181,6 +2238,7 @@ void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* sta /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see multiplyMultiQubitNot() void multiplyMultiQubitNot(Qureg qureg, std::vector targets); @@ -2188,6 +2246,7 @@ void multiplyMultiQubitNot(Qureg qureg, std::vector targets); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiQubitNot() void applyMultiQubitNot(Qureg qureg, std::vector targets); @@ -2195,6 +2254,7 @@ void applyMultiQubitNot(Qureg qureg, std::vector targets); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyControlledMultiQubitNot() void applyControlledMultiQubitNot(Qureg qureg, int control, std::vector targets); @@ -2202,6 +2262,7 @@ void applyControlledMultiQubitNot(Qureg qureg, int control, std::vector tar /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiControlledMultiQubitNot() void applyMultiControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector targets); @@ -2209,6 +2270,7 @@ void applyMultiControlledMultiQubitNot(Qureg qureg, std::vector controls, s /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiStateControlledMultiQubitNot() void applyMultiStateControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector states, std::vector targets); @@ -2272,6 +2334,7 @@ qreal applyForcedMultiQubitMeasurement(Qureg qureg, int* qubits, int* outcomes, /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiQubitMeasurementAndGetProb() qindex applyMultiQubitMeasurementAndGetProb(Qureg qureg, std::vector qubits, qreal* probability); @@ -2279,6 +2342,7 @@ qindex applyMultiQubitMeasurementAndGetProb(Qureg qureg, std::vector qubits /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyForcedMultiQubitMeasurement() qreal applyForcedMultiQubitMeasurement(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -2322,6 +2386,7 @@ void applyMultiQubitProjector(Qureg qureg, int* qubits, int* outcomes, int numQu /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyMultiQubitProjector() void applyMultiQubitProjector(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -2365,6 +2430,7 @@ void applyFullQuantumFourierTransform(Qureg qureg); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyQuantumFourierTransform() void applyQuantumFourierTransform(Qureg qureg, std::vector targets); diff --git a/quest/include/paulis.h b/quest/include/paulis.h index 98f2ef043..1d08169f2 100644 --- a/quest/include/paulis.h +++ b/quest/include/paulis.h @@ -156,6 +156,7 @@ extern "C" { * @cpponly * * @see + * - getPauliStr() * - reportPauliStr() * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples */ @@ -310,6 +311,7 @@ extern "C" { * @cpponly * * @see + * - createPauliStrSum() * - reportPauliStrSum() * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples */ @@ -321,6 +323,7 @@ extern "C" { * @cpponly * * @see + * - createInlinePauliStrSum() * - reportPauliStrSum() * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples */ @@ -332,6 +335,7 @@ extern "C" { * @cpponly * * @see + * - createPauliStrSumFromFile() * - reportPauliStrSum() * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples */ @@ -343,6 +347,7 @@ extern "C" { * @cpponly * * @see + * - createPauliStrSumFromReversedFile() * - reportPauliStrSum() * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples */ diff --git a/quest/include/qureg.h b/quest/include/qureg.h index 63ed03351..39d744f0a 100644 --- a/quest/include/qureg.h +++ b/quest/include/qureg.h @@ -540,6 +540,7 @@ qcomp getDensityQuregAmp(Qureg qureg, qindex row, qindex column); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see getQuregAmps() std::vector getQuregAmps(Qureg qureg, qindex startInd, qindex numAmps); @@ -548,6 +549,7 @@ std::vector getQuregAmps(Qureg qureg, qindex startInd, qindex numAmps); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see getDensityQuregAmps() std::vector> getDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, qindex numRows, qindex numCols); diff --git a/quest/include/types.h b/quest/include/types.h index d185eff02..c006b02cd 100644 --- a/quest/include/types.h +++ b/quest/include/types.h @@ -302,6 +302,7 @@ static inline qcomp getQcomp(qreal re, qreal im) { /// @notyetdoced /// @notyettested /// @cpponly + /// @see reportStr() void reportStr(std::string str); @@ -318,6 +319,7 @@ static inline qcomp getQcomp(qreal re, qreal im) { /// @notyetdoced /// @notyettested /// @cpponly + /// @see reportScalar() void reportScalar(std::string label, qcomp num); From 74de7ea4d945c59e8b24547df8a97c2c80b9f256 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 19 May 2025 01:25:32 +0200 Subject: [PATCH 17/21] linked multiply* doc to multiplyCompMatr1 which defines "multiply" as oppose to"apply" --- quest/include/operations.h | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/quest/include/operations.h b/quest/include/operations.h index 309eb2eb5..376cf1567 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -330,6 +330,9 @@ extern "C" { /// @notyetdoced +/// @see +/// - applyCompMatr2() +/// - multiplyCompMatr1() void multiplyCompMatr2(Qureg qureg, int target1, int target2, CompMatr2 matr); @@ -522,8 +525,13 @@ extern "C" { #endif -/// @notyetdoced -void multiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matr); +/** @notyetdoced + * + * @see + * - applyCompMatr() + * - multiplyCompMatr1() + */ +void multiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matrix); /// @notyetdoced @@ -608,6 +616,7 @@ extern "C" { /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr); @@ -670,6 +679,7 @@ extern "C" { /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr); @@ -732,6 +742,7 @@ extern "C" { /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix); @@ -752,6 +763,9 @@ void applyMultiStateControlledDiagMatr(Qureg qureg, int* controls, int* states, /// @notyetdoced +/// @see +/// - multiplyCompMatr1() +/// - applyDiagMatrPower() void multiplyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); @@ -879,11 +893,16 @@ extern "C" { /// @notyetdoced /// @notyetvalidated +/// @see +/// - multiplyCompMatr1 void multiplyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix); /// @notyetdoced /// @notyetvalidated +/// @see +/// - multiplyCompMatr1 +/// - applyDiagMatrPower void multiplyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent); @@ -1042,6 +1061,7 @@ extern "C" { /// @notyetdoced +/// @see multiplyCompMatr1() void multiplySwap(Qureg qureg, int qubit1, int qubit2); @@ -1164,14 +1184,17 @@ extern "C" { /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyPauliX(Qureg qureg, int target); /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyPauliY(Qureg qureg, int target); /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyPauliZ(Qureg qureg, int target); @@ -1298,6 +1321,7 @@ extern "C" { /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyPauliStr(Qureg qureg, PauliStr str); @@ -1670,6 +1694,9 @@ extern "C" { /// @notyetdoced +/// @see +/// - multiplyCompMatr1() +/// - applyPauliGadget() void multiplyPauliGadget(Qureg qureg, PauliStr str, qreal angle); @@ -1787,6 +1814,9 @@ extern "C" { /// @notyetdoced +/// @see +/// - multiplyCompMatr1() +/// - applyPhaseGadget void multiplyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle); @@ -2127,6 +2157,7 @@ extern "C" { /// @notyetdoced /// @notyetvalidated +/// @see multiplyCompMatr1() void multiplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace); @@ -2207,6 +2238,7 @@ extern "C" { /// @notyetdoced +/// @see multiplyCompMatr1() void multiplyMultiQubitNot(Qureg qureg, int* targets, int numTargets); From 135d4c07db7a6ed084267162454f0e5dd97f6231 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 19 May 2025 01:31:12 +0200 Subject: [PATCH 18/21] linked applyMultiStateControlled* doc to (...)CompMatr1() which defines what is meant by "multi state controlled". --- quest/include/operations.h | 135 ++++++++++++++++++++++++++++++++----- 1 file changed, 119 insertions(+), 16 deletions(-) diff --git a/quest/include/operations.h b/quest/include/operations.h index 376cf1567..80fef13b1 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -169,7 +169,9 @@ digraph { void applyCompMatr1(Qureg qureg, int target, CompMatr1 matrix); -/** Applies a singly-controlled one-qubit dense unitary @p matrix to the specified +/** @notyetdoced + * + * Applies a singly-controlled one-qubit dense unitary @p matrix to the specified * @p target qubit of @p qureg. * * @diagram @@ -198,12 +200,15 @@ digraph { } * @enddot * - * @notyetdoced + * @see + * - applyCompMatr1() */ void applyControlledCompMatr1(Qureg qureg, int control, int target, CompMatr1 matrix); -/** Applies a multiply-controlled one-qubit dense unitary @p matrix to the specified +/** @notyetdoced + * + * Applies a multiply-controlled one-qubit dense unitary @p matrix to the specified * @p target qubit of @p qureg. * * @diagram @@ -240,12 +245,15 @@ digraph { } * @enddot * - * @notyetdoced + * @see + * - applyCompMatr1() */ void applyMultiControlledCompMatr1(Qureg qureg, int* controls, int numControls, int target, CompMatr1 matrix); -/** Applies an arbitrarily-controlled one-qubit dense unitary @p matrix to the specified +/** @notyetdoced + * + * Applies an arbitrarily-controlled one-qubit dense unitary @p matrix to the specified * @p target qubit of @p qureg, conditioned upon the @p controls being in the given @p states. * * @diagram @@ -282,7 +290,8 @@ digraph { } * @enddot * - * @notyetdoced + * @see + * - applyCompMatr1() */ void applyMultiStateControlledCompMatr1(Qureg qureg, int* controls, int* states, int numControls, int target, CompMatr1 matrix); @@ -336,7 +345,9 @@ extern "C" { void multiplyCompMatr2(Qureg qureg, int target1, int target2, CompMatr2 matr); -/** Applies a general two-qubit dense unitary @p matrix to qubits @p target1 and +/** @notyetdoced + * + * Applies a general two-qubit dense unitary @p matrix to qubits @p target1 and * @p target2 (treated as increasing significance) of @p qureg. * * @diagram @@ -360,12 +371,15 @@ digraph { } * @enddot * - * @notyetdoced + * @see + * - applyCompMatr1() */ void applyCompMatr2(Qureg qureg, int target1, int target2, CompMatr2 matrix); -/** Applies a singly-controlled two-qubit dense unitary @p matrix to qubits +/** @notyetdoced + * + * Applies a singly-controlled two-qubit dense unitary @p matrix to qubits * @p target1 and @p target2 (treated as increasing significance) of @p qureg. * * @diagram @@ -395,12 +409,15 @@ digraph { } * @enddot * - * @notyetdoced + * @see + * - applyCompMatr2() */ void applyControlledCompMatr2(Qureg qureg, int control, int target1, int target2, CompMatr2 matr); -/** Applies a multiply-controlled two-qubit dense unitary @p matrix to qubits +/** @notyetdoced + * + * Applies a multiply-controlled two-qubit dense unitary @p matrix to qubits * @p target1 and @p target2 (treated as increasing significance) of @p qureg. * * @diagram @@ -436,12 +453,15 @@ digraph { } * @enddot * - * @notyetdoced + * @see + * - applyCompMatr2() */ void applyMultiControlledCompMatr2(Qureg qureg, int* controls, int numControls, int target1, int target2, CompMatr2 matr); -/** Applies an arbitrarily-controlled two-qubit dense unitary @p matrix to qubits +/** @notyetdoced + * + * Applies an arbitrarily-controlled two-qubit dense unitary @p matrix to qubits * @p target1 and @p target2 (treated as increasing significance) of @p qureg, * conditioned upon the @p controls being in the given @p states. * @@ -478,7 +498,9 @@ digraph { } * @enddot * - * @notyetdoced + * @see + * - applyCompMatr2() + * - applyMultiStateControlledCompMatr1() */ void applyMultiStateControlledCompMatr2(Qureg qureg, int* controls, int* states, int numControls, int target1, int target2, CompMatr2 matr); @@ -534,19 +556,42 @@ extern "C" { void multiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matrix); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * Let @f$ M = @f$ @p matrix. + * The qubits within @p targets are treated to be ordered least to most significant with respect + * to @f$ M @f$. That is, if @f$ M @f$ was hypothetically separable single-qubit matrices + * @f[ + M \equiv A \otimes B \otimes C \otimes \dots + * @f] + * then this function would effect + * @f[ + \hat{M}_{\text{targets}} \equiv A_{\text{targets}[0]} B_{\text{targets}[1]} C_{\text{targets}[2]} \dots + * @f] + * + * @see + * - applyCompMatr1() + */ void applyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matr); /// @notyetdoced +/// @see +/// - applyControlledCompMatr1() void applyControlledCompMatr(Qureg qureg, int control, int* targets, int numTargets, CompMatr matr); /// @notyetdoced +/// @see +/// - applyMultiControlledCompMatr1() void applyMultiControlledCompMatr(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, CompMatr matr); /// @notyetdoced +/// @see +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, CompMatr matr); @@ -570,6 +615,7 @@ void multiplyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); /// @notyetvalidated /// @notyetdoced /// @cpponly +/// @see applyCompMatr() void applyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); @@ -621,18 +667,22 @@ void multiplyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr); /// @notyetdoced +/// @see applyCompMatr1() void applyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr); /// @notyetdoced +/// @see applyControlledCompMatr1() void applyControlledDiagMatr1(Qureg qureg, int control, int target, DiagMatr1 matr); /// @notyetdoced +/// @see applyMultiControlledCompMatr1() void applyMultiControlledDiagMatr1(Qureg qureg, int* controls, int numControls, int target, DiagMatr1 matr); /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatr1(Qureg qureg, int* controls, int* states, int numControls, int target, DiagMatr1 matr); @@ -684,18 +734,22 @@ void multiplyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr); /// @notyetdoced +/// @see applyCompMatr1() void applyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr); /// @notyetdoced +/// @see applyControlledCompMatr1() void applyControlledDiagMatr2(Qureg qureg, int control, int target1, int target2, DiagMatr2 matr); /// @notyetdoced +/// @see applyMultiControlledCompMatr1() void applyMultiControlledDiagMatr2(Qureg qureg, int* controls, int numControls, int target1, int target2, DiagMatr2 matr); /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatr2(Qureg qureg, int* controls, int* states, int numControls, int target1, int target2, DiagMatr2 matr); @@ -747,18 +801,22 @@ void multiplyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix /// @notyetdoced +/// @see applyCompMatr1() void applyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix); /// @notyetdoced +/// @see applyControlledCompMatr1() void applyControlledDiagMatr(Qureg qureg, int control, int* targets, int numTargets, DiagMatr matrix); /// @notyetdoced +/// @see applyMultiControlledCompMatr1() void applyMultiControlledDiagMatr(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, DiagMatr matrix); /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatr(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, DiagMatr matrix); @@ -769,19 +827,33 @@ void applyMultiStateControlledDiagMatr(Qureg qureg, int* controls, int* states, void multiplyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notyetdoced +/** @notyetdoced + * + * @formulae + * + * This function is equivalent to applyDiagMatr() except that @p matrix is raised to the given @p exponent. + */ void applyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); /// @notyetdoced +/// @see +/// - applyDiagMatrPower() +/// - applyControlledCompMatr1() void applyControlledDiagMatrPower(Qureg qureg, int control, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); /// @notyetdoced +/// @see +/// - applyDiagMatrPower() +/// - applyMultiControlledCompMatr1() void applyMultiControlledDiagMatrPower(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); /// @notyetdoced +/// @see +/// - applyDiagMatrPower() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); @@ -913,6 +985,8 @@ void applyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix); /// @notyetdoced /// @notyetvalidated +/// @see +/// - applyDiagMatrPower void applyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent); @@ -951,6 +1025,7 @@ void applyMultiControlledS(Qureg qureg, int* controls, int numControls, int targ /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledS(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -967,6 +1042,7 @@ void applyMultiControlledT(Qureg qureg, int* controls, int numControls, int targ /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledT(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -983,6 +1059,7 @@ void applyMultiControlledHadamard(Qureg qureg, int* controls, int numControls, i /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledHadamard(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -1106,6 +1183,7 @@ void applyMultiControlledSwap(Qureg qureg, int* controls, int numControls, int q /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledSwap(Qureg qureg, int* controls, int* states, int numControls, int qubit1, int qubit2); @@ -1122,6 +1200,7 @@ void applyMultiControlledSqrtSwap(Qureg qureg, int* controls, int numControls, i /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledSqrtSwap(Qureg qureg, int* controls, int* states, int numControls, int qubit1, int qubit2); @@ -1235,14 +1314,17 @@ void applyMultiControlledPauliZ(Qureg qureg, int* controls, int numControls, int /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliX(Qureg qureg, int* controls, int* states, int numControls, int target); /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliY(Qureg qureg, int* controls, int* states, int numControls, int target); /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliZ(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -1338,6 +1420,7 @@ void applyMultiControlledPauliStr(Qureg qureg, int* controls, int numControls, P /// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliStr(Qureg qureg, int* controls, int* states, int numControls, PauliStr str); @@ -1522,14 +1605,23 @@ void applyMultiControlledRotateZ(Qureg qureg, int* controls, int numControls, in /// @notyetdoced +/// @see +/// - applyRotateX() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateX(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); /// @notyetdoced +/// @see +/// - applyRotateY() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateY(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); /// @notyetdoced +/// @see +/// - applyRotateZ() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateZ(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); @@ -1600,6 +1692,9 @@ void applyMultiControlledRotateAroundAxis(Qureg qureg, int* ctrls, int numCtrls, /// @notyetdoced +/// @see +/// - applyRotateAroundAxis() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateAroundAxis(Qureg qureg, int* ctrls, int* states, int numCtrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1768,6 +1863,9 @@ void applyMultiControlledPauliGadget(Qureg qureg, int* controls, int numControls /// @notyetdoced +/// @see +/// - applyPauliGadget() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliGadget(Qureg qureg, int* controls, int* states, int numControls, PauliStr str, qreal angle); @@ -1850,6 +1948,9 @@ void applyMultiControlledPhaseGadget(Qureg qureg, int* controls, int numControls /// @notyetdoced +/// @see +/// - applyPhaseGadget() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledPhaseGadget(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, qreal angle); @@ -2255,6 +2356,8 @@ void applyMultiControlledMultiQubitNot(Qureg qureg, int* controls, int numContro /// @notyetdoced +/// @see +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets); From 4e273e4c070369399306d18280600f4bff6a8144 Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 19 May 2025 01:42:52 +0200 Subject: [PATCH 19/21] divided @cpponly into @cppvectoroverload since there were two kinds of meaningfully distinct @cpponly functions: - those which were identical to the agnostic functions except for accepting a vector in lieu of a pointer and length parameter (mostly in operations.h) - those which were notably distinct, e.g. returning vectors or requiring different initialisations of the arguments. The former have been @cppvectoroverload while the latter remain @cpponly --- quest/include/calculations.h | 6 +- quest/include/debug.h | 2 +- quest/include/decoherence.h | 4 +- quest/include/operations.h | 134 +++++++++++++++++------------------ utils/docs/Doxyfile | 1 + 5 files changed, 74 insertions(+), 73 deletions(-) diff --git a/quest/include/calculations.h b/quest/include/calculations.h index c0c9e69b4..3d721b573 100644 --- a/quest/include/calculations.h +++ b/quest/include/calculations.h @@ -336,7 +336,7 @@ qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr /// @notyettested /// @notyetdoced /// @notyetvalidated -/// @cpponly +/// @cppoverload /// @see calcProbOfMultiQubitOutcome() qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -354,7 +354,7 @@ std::vector calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector traceOutQubits); @@ -363,7 +363,7 @@ Qureg calcPartialTrace(Qureg qureg, std::vector traceOutQubits); /// @notyettested /// @notyetdoced /// @notyetvalidated -/// @cpponly +/// @cppoverload /// @see calcReducedDensityMatrix() Qureg calcReducedDensityMatrix(Qureg qureg, std::vector retainQubits); diff --git a/quest/include/debug.h b/quest/include/debug.h index 58a54405b..e3d098838 100644 --- a/quest/include/debug.h +++ b/quest/include/debug.h @@ -192,7 +192,7 @@ void getEnvironmentString(char str[200]); /// @ingroup debug_seed /// @notyettested /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see setSeeds() void setSeeds(std::vector seeds); diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index 0ad291f54..689ec640f 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -360,14 +360,14 @@ void mixSuperOp(Qureg qureg, int* targets, int numTargets, SuperOp superop); /// @notyettested /// @notyetdoced /// @notyetvalidated -/// @cpponly +/// @cppvectoroverload /// @see mixKrausMap() void mixKrausMap(Qureg qureg, std::vector targets, KrausMap map); /// @notyettested /// @notyetdoced /// @notyetvalidated -/// @cpponly +/// @cppvectoroverload /// @see mixSuperOp() void mixSuperOp(Qureg qureg, std::vector targets, SuperOp superop); diff --git a/quest/include/operations.h b/quest/include/operations.h index 80fef13b1..57e1dab31 100644 --- a/quest/include/operations.h +++ b/quest/include/operations.h @@ -307,7 +307,7 @@ void applyMultiStateControlledCompMatr1(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledCompMatr1() void applyMultiControlledCompMatr1(Qureg qureg, std::vector controls, int target, CompMatr1 matrix); @@ -315,7 +315,7 @@ void applyMultiControlledCompMatr1(Qureg qureg, std::vector controls, int t /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledCompMatr1(Qureg qureg, std::vector controls, std::vector states, int target, CompMatr1 matrix); @@ -516,7 +516,7 @@ void applyMultiStateControlledCompMatr2(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledCompMatr2() void applyMultiControlledCompMatr2(Qureg qureg, std::vector controls, int target1, int target2, CompMatr2 matr); @@ -524,7 +524,7 @@ void applyMultiControlledCompMatr2(Qureg qureg, std::vector controls, int t /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledCompMatr2() void applyMultiStateControlledCompMatr2(Qureg qureg, std::vector controls, std::vector states, int numControls, int target1, int target2, CompMatr2 matr); @@ -606,7 +606,7 @@ void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see multiplyCompMatr() void multiplyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); @@ -614,7 +614,7 @@ void multiplyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyCompMatr() void applyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); @@ -622,7 +622,7 @@ void applyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyControlledCompMatr() void applyControlledCompMatr(Qureg qureg, int control, std::vector targets, CompMatr matr); @@ -630,7 +630,7 @@ void applyControlledCompMatr(Qureg qureg, int control, std::vector targets, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledCompMatr() void applyMultiControlledCompMatr(Qureg qureg, std::vector controls, std::vector targets, CompMatr matr); @@ -638,7 +638,7 @@ void applyMultiControlledCompMatr(Qureg qureg, std::vector controls, std::v /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledCompMatr() void applyMultiStateControlledCompMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, CompMatr matr); @@ -697,7 +697,7 @@ void applyMultiStateControlledDiagMatr1(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledDiagMatr1() void applyMultiControlledDiagMatr1(Qureg qureg, std::vector controls, int target, DiagMatr1 matr); @@ -705,7 +705,7 @@ void applyMultiControlledDiagMatr1(Qureg qureg, std::vector controls, int t /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledDiagMatr1() void applyMultiStateControlledDiagMatr1(Qureg qureg, std::vector controls, std::vector states, int target, DiagMatr1 matr); @@ -764,7 +764,7 @@ void applyMultiStateControlledDiagMatr2(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledDiagMatr2() void applyMultiControlledDiagMatr2(Qureg qureg, std::vector controls, int target1, int target2, DiagMatr2 matr); @@ -772,7 +772,7 @@ void applyMultiControlledDiagMatr2(Qureg qureg, std::vector controls, int t /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledDiagMatr2() void applyMultiStateControlledDiagMatr2(Qureg qureg, std::vector controls, std::vector states, int target1, int target2, DiagMatr2 matr); @@ -868,7 +868,7 @@ void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* sta /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see multiplyDiagMatr() void multiplyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); @@ -876,7 +876,7 @@ void multiplyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyDiagMatr() void applyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); @@ -884,7 +884,7 @@ void applyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyControlledDiagMatr() void applyControlledDiagMatr(Qureg qureg, int control, std::vector targets, DiagMatr matrix); @@ -892,7 +892,7 @@ void applyControlledDiagMatr(Qureg qureg, int control, std::vector targets, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledDiagMatr() void applyMultiControlledDiagMatr(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix); @@ -900,7 +900,7 @@ void applyMultiControlledDiagMatr(Qureg qureg, std::vector controls, std::v /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledDiagMatr() void applyMultiStateControlledDiagMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix); @@ -908,7 +908,7 @@ void applyMultiStateControlledDiagMatr(Qureg qureg, std::vector controls, s /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see multiplyDiagMatrPower() void multiplyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -916,7 +916,7 @@ void multiplyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matri /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyDiagMatrPower() void applyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -924,7 +924,7 @@ void applyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyControlledDiagMatrPower() void applyControlledDiagMatrPower(Qureg qureg, int control, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -932,7 +932,7 @@ void applyControlledDiagMatrPower(Qureg qureg, int control, std::vector tar /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledDiagMatrPower() void applyMultiControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -940,7 +940,7 @@ void applyMultiControlledDiagMatrPower(Qureg qureg, std::vector controls, s /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledDiagMatrPower() void applyMultiStateControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -1074,7 +1074,7 @@ void applyMultiStateControlledHadamard(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledS() void applyMultiControlledS(Qureg qureg, std::vector controls, int target); @@ -1082,7 +1082,7 @@ void applyMultiControlledS(Qureg qureg, std::vector controls, int target); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledS() void applyMultiStateControlledS(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1090,7 +1090,7 @@ void applyMultiStateControlledS(Qureg qureg, std::vector controls, std::vec /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledT() void applyMultiControlledT(Qureg qureg, std::vector controls, int target); @@ -1098,7 +1098,7 @@ void applyMultiControlledT(Qureg qureg, std::vector controls, int target); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledT() void applyMultiStateControlledT(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1106,7 +1106,7 @@ void applyMultiStateControlledT(Qureg qureg, std::vector controls, std::vec /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledHadamard() void applyMultiControlledHadamard(Qureg qureg, std::vector controls, int target); @@ -1114,7 +1114,7 @@ void applyMultiControlledHadamard(Qureg qureg, std::vector controls, int ta /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledHadamard() void applyMultiStateControlledHadamard(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1215,7 +1215,7 @@ void applyMultiStateControlledSqrtSwap(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledSwap() void applyMultiControlledSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); @@ -1223,7 +1223,7 @@ void applyMultiControlledSwap(Qureg qureg, std::vector controls, int qubit1 /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledSwap() void applyMultiStateControlledSwap(Qureg qureg, std::vector controls, std::vector states, int qubit1, int qubit2); @@ -1231,7 +1231,7 @@ void applyMultiStateControlledSwap(Qureg qureg, std::vector controls, std:: /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledSqrtSwap() void applyMultiControlledSqrtSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); @@ -1239,7 +1239,7 @@ void applyMultiControlledSqrtSwap(Qureg qureg, std::vector controls, int qu /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledSqrtSwap() void applyMultiStateControlledSqrtSwap(Qureg qureg, std::vector controls, std::vector states, int numControls, int qubit1, int qubit2); @@ -1339,7 +1339,7 @@ void applyMultiStateControlledPauliZ(Qureg qureg, int* controls, int* states, in /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledPauliX() void applyMultiControlledPauliX(Qureg qureg, std::vector controls, int target); @@ -1347,7 +1347,7 @@ void applyMultiControlledPauliX(Qureg qureg, std::vector controls, int targ /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledPauliY() void applyMultiControlledPauliY(Qureg qureg, std::vector controls, int target); @@ -1355,7 +1355,7 @@ void applyMultiControlledPauliY(Qureg qureg, std::vector controls, int targ /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledPauliZ() void applyMultiControlledPauliZ(Qureg qureg, std::vector controls, int target); @@ -1363,7 +1363,7 @@ void applyMultiControlledPauliZ(Qureg qureg, std::vector controls, int targ /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledPauliX() void applyMultiStateControlledPauliX(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1371,7 +1371,7 @@ void applyMultiStateControlledPauliX(Qureg qureg, std::vector controls, std /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledPauliY() void applyMultiStateControlledPauliY(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1379,7 +1379,7 @@ void applyMultiStateControlledPauliY(Qureg qureg, std::vector controls, std /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledPauliZ() void applyMultiStateControlledPauliZ(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1435,7 +1435,7 @@ void applyMultiStateControlledPauliStr(Qureg qureg, int* controls, int* states, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledPauliStr() void applyMultiControlledPauliStr(Qureg qureg, std::vector controls, PauliStr str); @@ -1443,7 +1443,7 @@ void applyMultiControlledPauliStr(Qureg qureg, std::vector controls, PauliS /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledPauliStr() void applyMultiStateControlledPauliStr(Qureg qureg, std::vector controls, std::vector states, PauliStr str); @@ -1709,7 +1709,7 @@ void applyMultiStateControlledRotateAroundAxis(Qureg qureg, int* ctrls, int* sta /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledRotateX() void applyMultiControlledRotateX(Qureg qureg, std::vector controls, int target, qreal angle); @@ -1717,7 +1717,7 @@ void applyMultiControlledRotateX(Qureg qureg, std::vector controls, int tar /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledRotateY() void applyMultiControlledRotateY(Qureg qureg, std::vector controls, int target, qreal angle); @@ -1725,7 +1725,7 @@ void applyMultiControlledRotateY(Qureg qureg, std::vector controls, int tar /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledRotateZ() void applyMultiControlledRotateZ(Qureg qureg, std::vector controls, int target, qreal angle); @@ -1733,7 +1733,7 @@ void applyMultiControlledRotateZ(Qureg qureg, std::vector controls, int tar /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledRotateX() void applyMultiStateControlledRotateX(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); @@ -1741,7 +1741,7 @@ void applyMultiStateControlledRotateX(Qureg qureg, std::vector controls, st /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledRotateY() void applyMultiStateControlledRotateY(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); @@ -1749,7 +1749,7 @@ void applyMultiStateControlledRotateY(Qureg qureg, std::vector controls, st /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledRotateZ() void applyMultiStateControlledRotateZ(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); @@ -1757,7 +1757,7 @@ void applyMultiStateControlledRotateZ(Qureg qureg, std::vector controls, st /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledRotateAroundAxis() void applyMultiControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1765,7 +1765,7 @@ void applyMultiControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, i /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledRotateAroundAxis() void applyMultiStateControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, std::vector states, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1880,7 +1880,7 @@ void applyMultiStateControlledPauliGadget(Qureg qureg, int* controls, int* state /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledPauliGadget() void applyMultiControlledPauliGadget(Qureg qureg, std::vector controls, PauliStr str, qreal angle); @@ -1888,7 +1888,7 @@ void applyMultiControlledPauliGadget(Qureg qureg, std::vector controls, Pau /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledPauliGadget() void applyMultiStateControlledPauliGadget(Qureg qureg, std::vector controls, std::vector states, PauliStr str, qreal angle); @@ -2185,7 +2185,7 @@ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see multiplyPhaseGadget() void multiplyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); @@ -2193,7 +2193,7 @@ void multiplyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyPhaseGadget() void applyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); @@ -2201,7 +2201,7 @@ void applyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyControlledPhaseGadget() void applyControlledPhaseGadget(Qureg qureg, int control, std::vector targets, qreal angle); @@ -2209,7 +2209,7 @@ void applyControlledPhaseGadget(Qureg qureg, int control, std::vector targe /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledPhaseGadget() void applyMultiControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector targets, qreal angle); @@ -2217,7 +2217,7 @@ void applyMultiControlledPhaseGadget(Qureg qureg, std::vector controls, std /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledPhaseGadget() void applyMultiStateControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector states, std::vector targets, qreal angle); @@ -2225,7 +2225,7 @@ void applyMultiStateControlledPhaseGadget(Qureg qureg, std::vector controls /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiQubitPhaseFlip() void applyMultiQubitPhaseFlip(Qureg qureg, std::vector targets); @@ -2233,7 +2233,7 @@ void applyMultiQubitPhaseFlip(Qureg qureg, std::vector targets); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiQubitPhaseShift() void applyMultiQubitPhaseShift(Qureg qureg, std::vector targets, qreal angle); @@ -2372,7 +2372,7 @@ void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* sta /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see multiplyMultiQubitNot() void multiplyMultiQubitNot(Qureg qureg, std::vector targets); @@ -2380,7 +2380,7 @@ void multiplyMultiQubitNot(Qureg qureg, std::vector targets); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiQubitNot() void applyMultiQubitNot(Qureg qureg, std::vector targets); @@ -2388,7 +2388,7 @@ void applyMultiQubitNot(Qureg qureg, std::vector targets); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyControlledMultiQubitNot() void applyControlledMultiQubitNot(Qureg qureg, int control, std::vector targets); @@ -2396,7 +2396,7 @@ void applyControlledMultiQubitNot(Qureg qureg, int control, std::vector tar /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiControlledMultiQubitNot() void applyMultiControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector targets); @@ -2404,7 +2404,7 @@ void applyMultiControlledMultiQubitNot(Qureg qureg, std::vector controls, s /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiStateControlledMultiQubitNot() void applyMultiStateControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector states, std::vector targets); @@ -2468,7 +2468,7 @@ qreal applyForcedMultiQubitMeasurement(Qureg qureg, int* qubits, int* outcomes, /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiQubitMeasurementAndGetProb() qindex applyMultiQubitMeasurementAndGetProb(Qureg qureg, std::vector qubits, qreal* probability); @@ -2476,7 +2476,7 @@ qindex applyMultiQubitMeasurementAndGetProb(Qureg qureg, std::vector qubits /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyForcedMultiQubitMeasurement() qreal applyForcedMultiQubitMeasurement(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -2520,7 +2520,7 @@ void applyMultiQubitProjector(Qureg qureg, int* qubits, int* outcomes, int numQu /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyMultiQubitProjector() void applyMultiQubitProjector(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -2564,7 +2564,7 @@ void applyFullQuantumFourierTransform(Qureg qureg); /// @notyettested /// @notyetvalidated /// @notyetdoced -/// @cpponly +/// @cppvectoroverload /// @see applyQuantumFourierTransform() void applyQuantumFourierTransform(Qureg qureg, std::vector targets); diff --git a/utils/docs/Doxyfile b/utils/docs/Doxyfile index 7e7c22372..d4a308a5a 100644 --- a/utils/docs/Doxyfile +++ b/utils/docs/Doxyfile @@ -299,6 +299,7 @@ ALIASES += "notyettested=@warning This function has not yet been unit tested and ALIASES += "notyetvalidated=@attention This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!" ALIASES += "notyetdoced=@note Documentation for this function or struct is under construction!" ALIASES += "cpponly=@remark This function is only available in C++." +ALIASES += "cppvectoroverload=@remark This function is merely a C++-only overload which accepts a vector(s) in lieu of a pointer(s) and length parameter. All other attributed are unchanged." ALIASES += "conly=@remark This function is only available in C." ALIASES += "macrodoc=@note This entity is actually a macro." ALIASES += "neverdoced=@warning This entity is a macro, undocumented directly due to a Doxygen limitation. If you see this doc rendered, contact the devs!" From 09d4ae0cbd933c5044bceefde82bd7460ccc72fe Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Mon, 19 May 2025 01:45:05 +0200 Subject: [PATCH 20/21] temporarily hiding cppvectoroverload since they differ trivially from the language-agnostic functions (ptr,len vs vector) yet clutter the API documentation --- utils/docs/Doxyfile | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/utils/docs/Doxyfile b/utils/docs/Doxyfile index d4a308a5a..a01ce3d85 100644 --- a/utils/docs/Doxyfile +++ b/utils/docs/Doxyfile @@ -299,7 +299,6 @@ ALIASES += "notyettested=@warning This function has not yet been unit tested and ALIASES += "notyetvalidated=@attention This function's input validation has not yet been unit tested, so erroneous usage may produce unexpected output. Please use with caution!" ALIASES += "notyetdoced=@note Documentation for this function or struct is under construction!" ALIASES += "cpponly=@remark This function is only available in C++." -ALIASES += "cppvectoroverload=@remark This function is merely a C++-only overload which accepts a vector(s) in lieu of a pointer(s) and length parameter. All other attributed are unchanged." ALIASES += "conly=@remark This function is only available in C." ALIASES += "macrodoc=@note This entity is actually a macro." ALIASES += "neverdoced=@warning This entity is a macro, undocumented directly due to a Doxygen limitation. If you see this doc rendered, contact the devs!" @@ -310,6 +309,13 @@ ALIASES += "formulae=@par Formulae" ALIASES += "diagram=@par Diagram" ALIASES += "validationerror=error" +# We are temporarily hiding the @cppvectoroverload functions since they differ +# trivially from the language-agnostic functions (ptr,len vs vector) yet clutter +# the API documentation +## ALIASES += "cppvectoroverload=@remark This function is merely a C++-only overload which accepts a vector(s) in lieu of a pointer(s) and length parameter. All other attributed are unchanged." +ALIASES += "cppvectoroverload=@private" + + # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all From 46cc7736890657535de802e199d12b75a50ea52a Mon Sep 17 00:00:00 2001 From: Tyson Jones Date: Thu, 22 May 2025 19:51:52 +0200 Subject: [PATCH 21/21] fixed launch.md typo --- docs/launch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch.md b/docs/launch.md index 447e0ff01..cdc9caecb 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -573,7 +573,7 @@ For convenience however, we offer some example [SLURM](https://slurm.schedmd.com #SBATCH --nodes=4 #SBATCH --ntasks-per-node=1 #SBATCH --cpus-per-task=8 -OMP_NUM_THREADS=8 mpirun ./myexec +OMP_NUM_THREADS=8 srun ./myexec ``` 1 machine with 4 local GPUs: