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. 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: diff --git a/quest/include/calculations.h b/quest/include/calculations.h index 54ff5ed9b..3d721b573 100644 --- a/quest/include/calculations.h +++ b/quest/include/calculations.h @@ -69,15 +69,17 @@ 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(). * * @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); @@ -89,11 +91,11 @@ 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. - * @notvalidated + * @notyetvalidated * @author Tyson Jones */ qreal calcExpecPauliStr(Qureg qureg, PauliStr str); @@ -125,7 +127,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. @@ -145,15 +147,16 @@ 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. * - if the output (with unreturned imaginary component) is not approximately real. -* @notvalidated +* @notyetvalidated * @see * - calcExpecNonHermitianPauliStrSum() * - calcExpecFullStateDiagMatr() @@ -162,13 +165,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); @@ -183,23 +186,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); @@ -214,13 +217,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); @@ -235,12 +238,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); @@ -255,13 +258,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); @@ -292,26 +295,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); @@ -330,34 +333,38 @@ qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr /// @ingroup calc_prob -/// @nottested -/// @notdoced -/// @notvalidated -/// @cpponly +/// @notyettested +/// @notyetdoced +/// @notyetvalidated +/// @cppoverload +/// @see calcProbOfMultiQubitOutcome() qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector qubits, std::vector outcomes); /// @ingroup calc_prob -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly +/// @see calcProbsOfAllMultiQubitOutcomes() std::vector calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector qubits); /// @ingroup calc_partialtrace -/// @nottested -/// @notdoced -/// @notvalidated -/// @cpponly +/// @notyettested +/// @notyetdoced +/// @notyetvalidated +/// @cppoverload +/// @see calcPartialTrace() Qureg calcPartialTrace(Qureg qureg, std::vector traceOutQubits); /// @ingroup calc_partialtrace -/// @nottested -/// @notdoced -/// @notvalidated -/// @cpponly +/// @notyettested +/// @notyetdoced +/// @notyetvalidated +/// @cppoverload +/// @see calcReducedDensityMatrix() Qureg calcReducedDensityMatrix(Qureg qureg, std::vector retainQubits); diff --git a/quest/include/channels.h b/quest/include/channels.h index 10d28f9aa..c0f5433f6 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; @@ -176,45 +176,75 @@ extern "C" { #endif - /// @ingroup channels_create - /// @notdoced + /** @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 - /// @notdoced + /** @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); /// @ingroup channels_destroy - /// @notdoced + /// @notyetdoced void destroyKrausMap(KrausMap map); /// @ingroup channels_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportKrausMap(KrausMap map); - /// @ingroup channels_create - /// @notdoced + /** @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 - /// @notdoced + /** @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); /// @ingroup channels_destroy - /// @notdoced + /// @notyetdoced void destroySuperOp(SuperOp op); /// @ingroup channels_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportSuperOp(SuperOp op); @@ -240,13 +270,27 @@ extern "C" { #endif - /// @ingroup channels_setters - /// @notdoced + /** @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 - /// @notdoced + /** @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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/debug.h b/quest/include/debug.h index 5febafa46..e3d098838 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,32 @@ int getNumSeeds(); */ -/// @notdoced +/** @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)); -/// @notdoced +/// @notyetdoced void setValidationOn(); -/// @notdoced +/// @notyetdoced void setValidationOff(); -/// @notdoced +/// @notyetdoced void setValidationEpsilonToDefault(); -/// @notdoced +/// @notyetdoced void setValidationEpsilon(qreal eps); -/// @notdoced +/// @notyetdoced qreal getValidationEpsilon(); @@ -108,16 +113,20 @@ 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`). + */ void setMaxNumReportedSigFigs(int numSigFigs); -/// @notdoced +/// @notyetdoced void setNumReportedNewlines(int numNewlines); @@ -132,11 +141,11 @@ void setNumReportedNewlines(int numNewlines); */ -/// @notdoced +/// @notyetdoced qindex getGpuCacheSize(); -/// @notdoced +/// @notyetdoced void clearGpuCache(); @@ -151,8 +160,8 @@ void clearGpuCache(); */ -/// @notdoced -/// @nottested +/// @notyetdoced +/// @notyettested void getEnvironmentString(char str[200]); @@ -181,16 +190,18 @@ void getEnvironmentString(char str[200]); /// @ingroup debug_seed -/// @nottested -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetdoced +/// @cppvectoroverload +/// @see setSeeds() void setSeeds(std::vector seeds); /// @ingroup debug_seed -/// @nottested -/// @notdoced +/// @notyettested +/// @notyetdoced /// @cpponly +/// @see getSeeds() std::vector getSeeds(); diff --git a/quest/include/decoherence.h b/quest/include/decoherence.h index c6b55d6ab..689ec640f 100644 --- a/quest/include/decoherence.h +++ b/quest/include/decoherence.h @@ -28,40 +28,313 @@ 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); +/** @notyetdoced + * + * @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); + + 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); + * ``` + * + * @notyetvalidated + */ +void mixDephasing(Qureg qureg, int target, qreal prob); + -/// @notdoced -/// @notvalidated -void mixDepolarising(Qureg qureg, int qubit, qreal prob); +/** @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. + * + * This function effects + * @f[ + \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] + * + * @equivalences + * This function is equivalent to (but much faster than): + * - 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); -/// @notdoced -/// @notvalidated -void mixTwoQubitDepolarising(Qureg qureg, int qubit1, int qubit2, qreal prob); + 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); + * ``` + * + * @notyetvalidated + */ +void mixTwoQubitDephasing(Qureg qureg, int target1, int target2, qreal prob); -/// @notdoced -/// @notvalidated -void mixDamping(Qureg qureg, int qubit, qreal prob); -/// @notdoced -/// @notvalidated -void mixPaulis(Qureg qureg, int qubit, qreal probX, qreal probY, qreal probZ); +/** @notyetdoced + * + * @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{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] + * + * @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); + * ``` + * + * @notyetvalidated + */ +void mixDepolarising(Qureg qureg, int target, qreal prob); + + +/** @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. + * + * 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$. + * + * @notyetvalidated + */ +void mixTwoQubitDepolarising(Qureg qureg, int target1, int target2, qreal prob); -/// @notdoced -/// @notvalidated + +/** @notyetdoced + * + * @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); + * ``` + * + * @notyetvalidated + */ +void mixDamping(Qureg qureg, int target, qreal prob); + + +/** @notyetdoced + * + * @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_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 + * 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); + qreal c = sqrt(probY); + qreal d = sqrt(probZ); + + 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); + * ``` + * + * @notyetvalidated + */ +void mixPaulis(Qureg qureg, int target, qreal probX, qreal probY, qreal probZ); + + +/** @notyetdoced + * + * @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] + * + * @notyetvalidated + */ void mixQureg(Qureg qureg, Qureg other, qreal prob); -/// @notdoced -/// @notvalidated + +/** @notyetdoced + * + * @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] + * + * @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); @@ -84,16 +357,18 @@ void mixSuperOp(Qureg qureg, int* targets, int numTargets, SuperOp superop); #include -/// @nottested -/// @notdoced -/// @notvalidated -/// @cpponly +/// @notyettested +/// @notyetdoced +/// @notyetvalidated +/// @cppvectoroverload +/// @see mixKrausMap() void mixKrausMap(Qureg qureg, std::vector targets, KrausMap map); -/// @nottested -/// @notdoced -/// @notvalidated -/// @cpponly +/// @notyettested +/// @notyetdoced +/// @notyetvalidated +/// @cppvectoroverload +/// @see mixSuperOp() void mixSuperOp(Qureg qureg, std::vector targets, SuperOp superop); #endif // __cplusplus diff --git a/quest/include/environment.h b/quest/include/environment.h index 3657cf00f..df24ab258 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,36 @@ typedef struct { } QuESTEnv; -/// @notdoced +/// @notyetdoced void initQuESTEnv(); -/// @notdoced +/** @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); -/// @notdoced +/// @notyetdoced void finalizeQuESTEnv(); -/// @notdoced +/// @notyetdoced void syncQuESTEnv(); -/// @notdoced -/// @nottested +/** @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(); -/// @notdoced +/// @notyetdoced int isQuESTEnvInit(); -/// @notdoced +/// @notyetdoced QuESTEnv getQuESTEnv(); diff --git a/quest/include/initialisations.h b/quest/include/initialisations.h index 716971f6d..06599fdda 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,65 @@ 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 + * + * @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); -/// @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,42 +183,47 @@ void setQuregToReducedDensityMatrix(Qureg out, Qureg in, int* retainQubits, int /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly +/// @see setQuregAmps() void setQuregAmps(Qureg qureg, qindex startInd, std::vector amps); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly +/// @see setDensityQuregAmps() void setDensityQuregAmps(Qureg qureg, qindex startRow, qindex startCol, std::vector> amps); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly +/// @see setDensityQuregFlatAmps() void setDensityQuregFlatAmps(Qureg qureg, qindex startInd, std::vector amps); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly +/// @see setQuregToPartialTrace() void setQuregToPartialTrace(Qureg out, Qureg in, std::vector traceOutQubits); /// @ingroup init_amps -/// @nottested -/// @notdoced -/// @notvalidated +/// @notyettested +/// @notyetdoced +/// @notyetvalidated /// @cpponly +/// @see setQuregToReducedDensityMatrix() void setQuregToReducedDensityMatrix(Qureg out, Qureg in, std::vector retainQubits); diff --git a/quest/include/matrices.h b/quest/include/matrices.h index 9606c7f0e..8ff4e9ff3 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; @@ -306,8 +306,18 @@ extern void _validateNewElemsPtrNotNull(qcomp* ptr, const char* caller); #endif -/// @ingroup matrices_getters -/// @notdoced +/** @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 -/// @notdoced +/** @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 -/// @notdoced +/** @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 -/// @notdoced +/** @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__); @@ -414,36 +452,70 @@ 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 - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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,53 +701,93 @@ extern "C" { #endif - /// @ingroup matrices_create - /// @notdoced + /** @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 - /// @notdoced + /** @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 - /// @notdoced + /** @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 - /// @notdoced + /** @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); /// @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); @@ -669,19 +815,40 @@ extern "C" { #endif - /// @ingroup matrices_setters - /// @notdoced + /** @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 - /// @notdoced + /** @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 - /// @notdoced - /// @nottested + /** @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @nottested - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @nottested - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @nottested - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 - /// @notdoced - /// @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 @@ -1069,38 +1321,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); @@ -1121,45 +1373,75 @@ extern "C" { #endif - /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /** @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 - /// @notdoced - /// @nottested + /** @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 - /// @notdoced - /// @nottested + /** @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 - /// @notdoced - /// @nottested + /** @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 - /// @notdoced - /// @nottested + /** @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); /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /// @notyetdoced + /// @notyettested void reportDiagMatr(DiagMatr matrix); - /// @ingroup matrices_reporters - /// @notdoced - /// @nottested + /** @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/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 d4e208a12..57e1dab31 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. @@ -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 * - * @notdoced + * @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 * - * @notdoced + * @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 * - * @notdoced + * @see + * - applyCompMatr1() */ void applyMultiStateControlledCompMatr1(Qureg qureg, int* controls, int* states, int numControls, int target, CompMatr1 matrix); @@ -295,17 +304,19 @@ void applyMultiStateControlledCompMatr1(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledCompMatr1() void applyMultiControlledCompMatr1(Qureg qureg, std::vector controls, int target, CompMatr1 matrix); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledCompMatr1(Qureg qureg, std::vector controls, std::vector states, int target, CompMatr1 matrix); @@ -327,11 +338,16 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see +/// - applyCompMatr2() +/// - multiplyCompMatr1() 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 @@ -355,12 +371,15 @@ digraph { } * @enddot * - * @notdoced + * @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 @@ -390,12 +409,15 @@ digraph { } * @enddot * - * @notdoced + * @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 @@ -431,12 +453,15 @@ digraph { } * @enddot * - * @notdoced + * @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. * @@ -473,7 +498,9 @@ digraph { } * @enddot * - * @notdoced + * @see + * - applyCompMatr2() + * - applyMultiStateControlledCompMatr1() */ void applyMultiStateControlledCompMatr2(Qureg qureg, int* controls, int* states, int numControls, int target1, int target2, CompMatr2 matr); @@ -486,17 +513,19 @@ void applyMultiStateControlledCompMatr2(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledCompMatr2() void applyMultiControlledCompMatr2(Qureg qureg, std::vector controls, int target1, int target2, CompMatr2 matr); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledCompMatr2() void applyMultiStateControlledCompMatr2(Qureg qureg, std::vector controls, std::vector states, int numControls, int target1, int target2, CompMatr2 matr); @@ -518,23 +547,51 @@ extern "C" { #endif -/// @notdoced -void multiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matr); +/** @notyetdoced + * + * @see + * - applyCompMatr() + * - multiplyCompMatr1() + */ +void multiplyCompMatr(Qureg qureg, int* targets, int numTargets, CompMatr matrix); -/// @notdoced +/** @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); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyControlledCompMatr1() void applyControlledCompMatr(Qureg qureg, int control, int* targets, int numTargets, CompMatr matr); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyMultiControlledCompMatr1() void applyMultiControlledCompMatr(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, CompMatr matr); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, CompMatr matr); @@ -546,38 +603,43 @@ void applyMultiStateControlledCompMatr(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see multiplyCompMatr() void multiplyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyCompMatr() void applyCompMatr(Qureg qureg, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyControlledCompMatr() void applyControlledCompMatr(Qureg qureg, int control, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledCompMatr() void applyMultiControlledCompMatr(Qureg qureg, std::vector controls, std::vector targets, CompMatr matr); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledCompMatr() void applyMultiStateControlledCompMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, CompMatr matr); @@ -599,23 +661,28 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() void multiplyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced +/// @see applyCompMatr1() void applyDiagMatr1(Qureg qureg, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced +/// @see applyControlledCompMatr1() void applyControlledDiagMatr1(Qureg qureg, int control, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced +/// @see applyMultiControlledCompMatr1() void applyMultiControlledDiagMatr1(Qureg qureg, int* controls, int numControls, int target, DiagMatr1 matr); -/// @notdoced +/// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatr1(Qureg qureg, int* controls, int* states, int numControls, int target, DiagMatr1 matr); @@ -627,17 +694,19 @@ void applyMultiStateControlledDiagMatr1(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledDiagMatr1() void applyMultiControlledDiagMatr1(Qureg qureg, std::vector controls, int target, DiagMatr1 matr); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledDiagMatr1() void applyMultiStateControlledDiagMatr1(Qureg qureg, std::vector controls, std::vector states, int target, DiagMatr1 matr); @@ -659,23 +728,28 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() void multiplyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced +/// @see applyCompMatr1() void applyDiagMatr2(Qureg qureg, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced +/// @see applyControlledCompMatr1() void applyControlledDiagMatr2(Qureg qureg, int control, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced +/// @see applyMultiControlledCompMatr1() void applyMultiControlledDiagMatr2(Qureg qureg, int* controls, int numControls, int target1, int target2, DiagMatr2 matr); -/// @notdoced +/// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatr2(Qureg qureg, int* controls, int* states, int numControls, int target1, int target2, DiagMatr2 matr); @@ -687,17 +761,19 @@ void applyMultiStateControlledDiagMatr2(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledDiagMatr2() void applyMultiControlledDiagMatr2(Qureg qureg, std::vector controls, int target1, int target2, DiagMatr2 matr); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledDiagMatr2() void applyMultiStateControlledDiagMatr2(Qureg qureg, std::vector controls, std::vector states, int target1, int target2, DiagMatr2 matr); @@ -719,43 +795,65 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() void multiplyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced +/// @see applyCompMatr1() void applyDiagMatr(Qureg qureg, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced +/// @see applyControlledCompMatr1() void applyControlledDiagMatr(Qureg qureg, int control, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced +/// @see applyMultiControlledCompMatr1() void applyMultiControlledDiagMatr(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatr(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, DiagMatr matrix); -/// @notdoced +/// @notyetdoced +/// @see +/// - multiplyCompMatr1() +/// - applyDiagMatrPower() void multiplyDiagMatrPower(Qureg qureg, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notdoced +/** @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); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyDiagMatrPower() +/// - applyControlledCompMatr1() void applyControlledDiagMatrPower(Qureg qureg, int control, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyDiagMatrPower() +/// - applyMultiControlledCompMatr1() void applyMultiControlledDiagMatrPower(Qureg qureg, int* controls, int numControls, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyDiagMatrPower() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, DiagMatr matrix, qcomp exponent); @@ -767,73 +865,83 @@ void applyMultiStateControlledDiagMatrPower(Qureg qureg, int* controls, int* sta #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see multiplyDiagMatr() void multiplyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyDiagMatr() void applyDiagMatr(Qureg qureg, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyControlledDiagMatr() void applyControlledDiagMatr(Qureg qureg, int control, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledDiagMatr() void applyMultiControlledDiagMatr(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledDiagMatr() void applyMultiStateControlledDiagMatr(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see multiplyDiagMatrPower() void multiplyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyDiagMatrPower() void applyDiagMatrPower(Qureg qureg, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyControlledDiagMatrPower() void applyControlledDiagMatrPower(Qureg qureg, int control, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledDiagMatrPower() void applyMultiControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector targets, DiagMatr matrix, qcomp exponent); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledDiagMatrPower() void applyMultiStateControlledDiagMatrPower(Qureg qureg, std::vector controls, std::vector states, std::vector targets, DiagMatr matrix, qcomp exponent); @@ -855,23 +963,30 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated +/// @see +/// - multiplyCompMatr1 void multiplyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated +/// @see +/// - multiplyCompMatr1 +/// - applyDiagMatrPower void multiplyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated void applyFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matrix); -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated +/// @see +/// - applyDiagMatrPower void applyFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent); @@ -897,51 +1012,54 @@ 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 +/// @see applyMultiStateControlledCompMatr1() 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 +/// @see applyMultiStateControlledCompMatr1() 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 +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledHadamard(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -953,45 +1071,51 @@ void applyMultiStateControlledHadamard(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledS() void applyMultiControlledS(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledS() void applyMultiStateControlledS(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledT() void applyMultiControlledT(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledT() void applyMultiStateControlledT(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledHadamard() void applyMultiControlledHadamard(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledHadamard() void applyMultiStateControlledHadamard(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1013,7 +1137,8 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() void multiplySwap(Qureg qureg, int qubit1, int qubit2); @@ -1044,36 +1169,38 @@ 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 +/// @see applyMultiStateControlledCompMatr1() 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 +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledSqrtSwap(Qureg qureg, int* controls, int* states, int numControls, int qubit1, int qubit2); @@ -1085,31 +1212,35 @@ void applyMultiStateControlledSqrtSwap(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledSwap() void applyMultiControlledSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledSwap() void applyMultiStateControlledSwap(Qureg qureg, std::vector controls, std::vector states, int qubit1, int qubit2); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledSqrtSwap() void applyMultiControlledSqrtSwap(Qureg qureg, std::vector controls, int qubit1, int qubit2); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledSqrtSwap() void applyMultiStateControlledSqrtSwap(Qureg qureg, std::vector controls, std::vector states, int numControls, int qubit1, int qubit2); @@ -1131,63 +1262,69 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() void multiplyPauliX(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() void multiplyPauliY(Qureg qureg, int target); -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() 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 +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliX(Qureg qureg, int* controls, int* states, int numControls, int target); -/// @notdoced +/// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliY(Qureg qureg, int* controls, int* states, int numControls, int target); -/// @notdoced +/// @notyetdoced +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliZ(Qureg qureg, int* controls, int* states, int numControls, int target); @@ -1199,45 +1336,51 @@ void applyMultiStateControlledPauliZ(Qureg qureg, int* controls, int* states, in #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledPauliX() void applyMultiControlledPauliX(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledPauliY() void applyMultiControlledPauliY(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledPauliZ() void applyMultiControlledPauliZ(Qureg qureg, std::vector controls, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledPauliX() void applyMultiStateControlledPauliX(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledPauliY() void applyMultiStateControlledPauliY(Qureg qureg, std::vector controls, std::vector states, int target); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledPauliZ() void applyMultiStateControlledPauliZ(Qureg qureg, std::vector controls, std::vector states, int target); @@ -1259,23 +1402,25 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() 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 +/// @see applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliStr(Qureg qureg, int* controls, int* states, int numControls, PauliStr str); @@ -1287,17 +1432,19 @@ void applyMultiStateControlledPauliStr(Qureg qureg, int* controls, int* states, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledPauliStr() void applyMultiControlledPauliStr(Qureg qureg, std::vector controls, PauliStr str); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledPauliStr() void applyMultiStateControlledPauliStr(Qureg qureg, std::vector controls, std::vector states, PauliStr str); @@ -1319,67 +1466,235 @@ extern "C" { #endif -/// @notdoced +/** @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); + * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. + */ void applyRotateX(Qureg qureg, int target, qreal angle); -/// @notdoced +/** @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); + * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. + */ void applyRotateY(Qureg qureg, int target, qreal angle); -/// @notdoced +/** @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); + * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. + */ 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 +/// @see +/// - applyRotateX() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateX(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyRotateY() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateY(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); -/// @notdoced +/// @notyetdoced +/// @see +/// - applyRotateZ() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateZ(Qureg qureg, int* controls, int* states, int numControls, int target, qreal angle); -/// @notdoced -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. + * - 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); -/// @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 +/// @see +/// - applyRotateAroundAxis() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledRotateAroundAxis(Qureg qureg, int* ctrls, int* states, int numCtrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1391,59 +1706,67 @@ void applyMultiStateControlledRotateAroundAxis(Qureg qureg, int* ctrls, int* sta #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledRotateX() void applyMultiControlledRotateX(Qureg qureg, std::vector controls, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledRotateY() void applyMultiControlledRotateY(Qureg qureg, std::vector controls, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledRotateZ() void applyMultiControlledRotateZ(Qureg qureg, std::vector controls, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledRotateX() void applyMultiStateControlledRotateX(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledRotateY() void applyMultiStateControlledRotateY(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledRotateZ() void applyMultiStateControlledRotateZ(Qureg qureg, std::vector controls, std::vector states, int target, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledRotateAroundAxis() void applyMultiControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledRotateAroundAxis() void applyMultiStateControlledRotateAroundAxis(Qureg qureg, std::vector ctrls, std::vector states, int targ, qreal angle, qreal axisX, qreal axisY, qreal axisZ); @@ -1465,23 +1788,84 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see +/// - multiplyCompMatr1() +/// - applyPauliGadget() void multiplyPauliGadget(Qureg qureg, PauliStr str, qreal angle); -/// @notdoced +/** @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); + * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. + */ 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 +/// @see +/// - applyPauliGadget() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledPauliGadget(Qureg qureg, int* controls, int* states, int numControls, PauliStr str, qreal angle); @@ -1493,17 +1877,19 @@ void applyMultiStateControlledPauliGadget(Qureg qureg, int* controls, int* state #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledPauliGadget() void applyMultiControlledPauliGadget(Qureg qureg, std::vector controls, PauliStr str, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledPauliGadget() void applyMultiStateControlledPauliGadget(Qureg qureg, std::vector controls, std::vector states, PauliStr str, qreal angle); @@ -1525,35 +1911,96 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see +/// - multiplyCompMatr1() +/// - applyPhaseGadget void multiplyPhaseGadget(Qureg qureg, int* targets, int numTargets, qreal angle); -/// @notdoced +/** @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(). + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. + */ 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 +/// @see +/// - applyPhaseGadget() +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledPhaseGadget(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets, qreal angle); -/// @notdoced +/** @notyetdoced + * + * This function is a mere alias of applyPauliZ(), meaningfully differing only for many targets. + */ void applyPhaseFlip(Qureg qureg, int target); -/// @notdoced +/** @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 + * ``` + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. + */ 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 +2024,41 @@ digraph { } * @enddot * - * @notdoced + * @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 +2084,93 @@ digraph { } * @enddot * - * @notdoced + * @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. + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. */ void applyTwoQubitPhaseShift(Qureg qureg, int target1, int target2, qreal angle); -/// @notdoced +/** @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); -/// @notdoced +/** @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. + * - Passing @p angle=0 is equivalent to effecting the identity, leaving the state unchanged. + */ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal angle); @@ -1629,52 +2182,59 @@ void applyMultiQubitPhaseShift(Qureg qureg, int* targets, int numTargets, qreal #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see multiplyPhaseGadget() void multiplyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyPhaseGadget() void applyPhaseGadget(Qureg qureg, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyControlledPhaseGadget() void applyControlledPhaseGadget(Qureg qureg, int control, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledPhaseGadget() void applyMultiControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledPhaseGadget() void applyMultiStateControlledPhaseGadget(Qureg qureg, std::vector controls, std::vector states, std::vector targets, qreal angle); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiQubitPhaseFlip() void applyMultiQubitPhaseFlip(Qureg qureg, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiQubitPhaseShift() void applyMultiQubitPhaseShift(Qureg qureg, std::vector targets, qreal angle); @@ -1696,13 +2256,63 @@ extern "C" { #endif -/// @notdoced -/// @notvalidated +/// @notyetdoced +/// @notyetvalidated +/// @see multiplyCompMatr1() void multiplyPauliStrSum(Qureg qureg, PauliStrSum sum, Qureg workspace); -/// @notdoced -/// @nottested +/** @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); @@ -1728,23 +2338,26 @@ extern "C" { #endif -/// @notdoced +/// @notyetdoced +/// @see multiplyCompMatr1() 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 +/// @see +/// - applyMultiStateControlledCompMatr1() void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* states, int numControls, int* targets, int numTargets); @@ -1756,38 +2369,43 @@ void applyMultiStateControlledMultiQubitNot(Qureg qureg, int* controls, int* sta #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see multiplyMultiQubitNot() void multiplyMultiQubitNot(Qureg qureg, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiQubitNot() void applyMultiQubitNot(Qureg qureg, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyControlledMultiQubitNot() void applyControlledMultiQubitNot(Qureg qureg, int control, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiControlledMultiQubitNot() void applyMultiControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector targets); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiStateControlledMultiQubitNot() void applyMultiStateControlledMultiQubitNot(Qureg qureg, std::vector controls, std::vector states, std::vector targets); @@ -1809,33 +2427,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,17 +2465,19 @@ qreal applyForcedMultiQubitMeasurement(Qureg qureg, int* qubits, int* outcomes, #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiQubitMeasurementAndGetProb() qindex applyMultiQubitMeasurementAndGetProb(Qureg qureg, std::vector qubits, qreal* probability); -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyForcedMultiQubitMeasurement() qreal applyForcedMultiQubitMeasurement(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -1879,13 +2499,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,10 +2517,11 @@ void applyMultiQubitProjector(Qureg qureg, int* qubits, int* outcomes, int numQu #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyMultiQubitProjector() void applyMultiQubitProjector(Qureg qureg, std::vector qubits, std::vector outcomes); @@ -1922,13 +2543,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,10 +2561,11 @@ void applyFullQuantumFourierTransform(Qureg qureg); #ifdef __cplusplus -/// @nottested -/// @notvalidated -/// @notdoced -/// @cpponly +/// @notyettested +/// @notyetvalidated +/// @notyetdoced +/// @cppvectoroverload +/// @see applyQuantumFourierTransform() void applyQuantumFourierTransform(Qureg qureg, std::vector targets); diff --git a/quest/include/paulis.h b/quest/include/paulis.h index 55f48c485..1d08169f2 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,48 @@ 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 + * - getPauliStr() + * - 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 +224,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 +253,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 +306,51 @@ extern "C" { #ifdef __cplusplus - /// @ingroup paulis_create - /// @notdoced - /// @cpponly + /** @ingroup paulis_create + * @notyetdoced + * @cpponly + * + * @see + * - createPauliStrSum() + * - 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 + * - createInlinePauliStrSum() + * - 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 + * - createPauliStrSumFromFile() + * - 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 + * - createPauliStrSumFromReversedFile() + * - reportPauliStrSum() + * - [C++](https://github.com/QuEST-Kit/QuEST/blob/devel/examples/isolated/initialising_paulis.cpp) examples + */ PauliStrSum createPauliStrSumFromReversedFile(std::string fn); @@ -288,7 +370,7 @@ extern "C" { /// @ingroup paulis_destroy - /// @notdoced + /// @notyetdoced void destroyPauliStrSum(PauliStrSum sum); @@ -309,14 +391,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); 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 1ef8a43c0..39d744f0a 100644 --- a/quest/include/qureg.h +++ b/quest/include/qureg.h @@ -45,7 +45,7 @@ extern "C" { */ -/// @notdoced +/// @notyetdoced typedef struct { // deployment configuration @@ -90,27 +90,297 @@ 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. + * + * @equivalences + * - 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. + * @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. + * - 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. + * + * @equivalences + * - 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. + * @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. + * - createCustomQureg() to explicitly set the used deployments. + * @author Tyson Jones + */ Qureg createDensityQureg(int numQubits); -/// @notdoced +/** @notyetdoced + * + * @equivalences + * - 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 +/** @notyetdoced + * + * @equivalences + * - 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. + * @notyetvalidated + * @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); -/// @notdoced +/// @notyetdoced Qureg createCloneQureg(Qureg qureg); @@ -125,7 +395,7 @@ Qureg createCloneQureg(Qureg qureg); */ -/// @notdoced +/// @notyetdoced void destroyQureg(Qureg qureg); @@ -140,13 +410,23 @@ void destroyQureg(Qureg qureg); */ -/// @notdoced -/// @nottested +/** @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); -/// @notdoced -/// @nottested +/** @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); @@ -166,23 +446,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); @@ -197,11 +477,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); @@ -232,12 +512,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); @@ -256,18 +536,20 @@ qcomp getDensityQuregAmp(Qureg qureg, qindex row, qindex column); /// @ingroup qureg_get -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @notyetvalidated +/// @notyetdoced /// @cpponly +/// @see getQuregAmps() std::vector getQuregAmps(Qureg qureg, qindex startInd, qindex numAmps); /// @ingroup qureg_get -/// @nottested -/// @notvalidated -/// @notdoced +/// @notyettested +/// @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 ba172e9b9..c006b02cd 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,49 @@ 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 + /// @see reportStr() 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 + /// @see reportScalar() 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/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) { diff --git a/utils/docs/Doxyfile b/utils/docs/Doxyfile index 4a721e1c8..a01ce3d85 100644 --- a/utils/docs/Doxyfile +++ b/utils/docs/Doxyfile @@ -295,18 +295,26 @@ 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 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." 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" +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 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 }