The Quantum Exact Simulation Toolkit v4.1.0
Loading...
Searching...
No Matches
calculations.h
1/** @file
2 * API signatures for calculating properties of quantum states,
3 * such as probabilities, expectation values and partial traces.
4 *
5 * @author Tyson Jones
6 *
7 * @defgroup calculations Calculations
8 * @ingroup api
9 * @brief Functions for calculating properties of quantum states without modifying them.
10 * @{
11 */
12
13#ifndef CALCULATIONS_H
14#define CALCULATIONS_H
15
16#include "quest/include/types.h"
17#include "quest/include/qureg.h"
18#include "quest/include/paulis.h"
19#include "quest/include/matrices.h"
20
21
22
23/*
24 * These signatures are divided into three partitions; those which are
25 * natively C and C++ compatible (first partition), then those which are
26 * only exposed to C++ (second partition) because they return 'qcomp'
27 * which cannot cross the C++-to-C ABI, and then finally the C++-only
28 * convenience overloads. The first partition defines the doc groups, and
29 * the latter partition functions are added into them.
30 */
31
32
33
34/*
35 * C AND C++ AGNOSTIC FUNCTIONS
36 */
37
38// enable invocation by both C and C++ binaries
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43
44
45/**
46 * @defgroup calc_expec Expectation values
47 * @brief Functions for calculating expected values of Hermitian observables.
48 * @{
49 */
50
51
52/** Calculates the expectation value of the given Pauli string observable @p str under the given
53 * state @p qureg without modifying it.
54 *
55 * @formulae
56 * Let @f$ \pstr = @f$ @p str.
57 * - When @p qureg is a statevector @f$\svpsi@f$, this function returns
58 * @f[
59 \brapsi \pstr \svpsi \in \mathbb{R}.
60 * @f]
61 * - When @p qureg is a density matrix @f$\dmrho@f$, this function returns the real component of
62 * @f[
63 \tr{ \pstr \dmrho }
64 * @f]
65 * which is exact when @f$\dmrho@f$ is physical (specifically Hermitian).
66 *
67 * @constraints
68 * - The returned value is always real, even when @p qureg is an unnormalised density matrix, in
69 * which case the imaginary component of the above expression is neglected.
70 * The full complex value can be obtained using calcExpecNonHermitianPauliStrSum().
71 *
72 * @equivalences
73 * - When @p str is general, this function is equivalent to calling calcExpecPauliStrSum() with a
74 * PauliStrSum composed of only a single PauliStr term and a unity coefficient.
75 * - When @p str @f$ = \id^\otimes @f$, the output is equivalent to that of calcTotalProb().
76 *
77 * @myexample
78 * ```
79 Qureg qureg = createQureg(10);
80 initRandomPureState(qureg);
81
82 PauliStr str = getInlinePauliStr("XYZ", {0,2,3});
83
84 qreal expec = calcExpecPauliStr(qureg, str);
85 reportScalar("expec", expec);
86 * ```
87 *
88 * @see
89 * - calcExpecPauliStrSum()
90 * - calcExpecFullStateDiagMatr()
91 * @param[in] qureg the reference state.
92 * @param[in] str the observable operator.
93 * @returns The real component of the expectation value.
94 * @throws @validationerror
95 * - if @p qureg is uninitialised.
96 * - if @p str contains a (non-identity) Pauli upon a higher-index qubit than exists in @p qureg.
97 * - if the output (with unreturned imaginary component) is not approximately real.
98 * @notyetvalidated
99 * @author Tyson Jones
100 */
101qreal calcExpecPauliStr(Qureg qureg, PauliStr str);
102
103
104/** Calculates the expectation value of the given Hermitian observable @p sum - a weighted sum of
105 * Pauli strings - under the given state @p qureg, without modifying it.
106 *
107 * @formulae
108 * Let @f$ \hat{H} = @f$ @p sum.
109 * - When @p qureg is a statevector @f$\svpsi@f$, this function returns
110 * @f[
111 \brapsi \hat{H} \svpsi \in \mathbb{R}.
112 * @f]
113 * - When @p qureg is a density matrix @f$\dmrho@f$, this function returns the real component of
114 * @f[
115 \tr{ \hat{H} \dmrho }
116 * @f]
117 * which is the exact expectation value when @f$\dmrho@f$ is physical (specifically Hermitian).
118 *
119 * @constraints
120 * - Hermiticity of @p sum requires that every coefficient within is real.
121 * Validation will check @p sum is _approximately_ Hermitian, i.e. that
122 * @f[
123 |\im{c}| \le \valeps
124 * @f]
125 * for all @f$c \in @f$ `sum.coeffs`. Adjust @f$\valeps@f$ using setValidationEpsilon().
126 * - The returned value is always real, and the imaginary component is neglected even when
127 * Hermiticity validation is relaxed and/or @p qureg is an unnormalised density matrix.
128 * The full complex value can be obtained using calcExpecNonHermitianPauliStrSum().
129 *
130 * @equivalences
131 * - This function is mathematically equivalent to (albeit faster than) calling calcExpecPauliStr() upon
132 * each constituent @p PauliStr within @p sum, weighting each by its corresponding coefficient, and
133 * summing the outputs.
134 * - When @p sum contains only @f$\pauliz@f$ and @f$\id@f$ operators, its corresponding operator matrix
135 * is diagonal, and could be instead effected with calcExpecFullStateDiagMatr(). This may be faster when
136 * @p sum contains very-many terms and operates upon all qubits of the register.
137 *
138 * @myexample
139 * ```
140 Qureg qureg = createQureg(5);
141 PauliStrSum sum = createInlinePauliStrSum(R"(
142 0.123 XXIXX
143 1.234 XYZXZ
144 -1E-2 IIIII
145 )");
146
147 qreal expec = calcExpecPauliStrSum(qureg, sum);
148 reportScalar("expec", expec);
149 * ```
150 *
151 * @param[in] qureg the reference state.
152 * @param[in] sum the observable operator.
153 * @returns The real component of the expectation value.
154 * @throws @validationerror
155 * - if @p qureg or @p sum are uninitialised.
156 * - if any PauliStr in @p sum targets a higher-index qubit than exists in @p qureg.
157 * - if @p sum is not approximately Hermitian.
158 * - if the output (with unreturned imaginary component) is not approximately real.
159* @notyetvalidated
160 * @see
161 * - calcExpecNonHermitianPauliStrSum()
162 * - calcExpecFullStateDiagMatr()
163 * @author Tyson Jones
164 */
165qreal calcExpecPauliStrSum(Qureg qureg, PauliStrSum sum);
166
167
168/// @notyetdoced
169/// @notyetvalidated
171
172
173/// @notyetdoced
174/// @notyetvalidated
175qreal calcExpecFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matr, qreal exponent);
176
177
178/** @} */
179
180
181
182/**
183 * @defgroup calc_prob Probabilities
184 * @brief Functions for non-destructively calculating the probabilities of measurement outcomes.
185 * @{
186 */
187
188
189/// @notyetdoced
190/// @notyetvalidated
191qreal calcProbOfBasisState(Qureg qureg, qindex index);
192
193
194/// @notyetdoced
195/// @notyetvalidated
196qreal calcProbOfQubitOutcome(Qureg qureg, int qubit, int outcome);
197
198
199/// @notyetdoced
200/// @notyetvalidated
201qreal calcProbOfMultiQubitOutcome(Qureg qureg, int* qubits, int* outcomes, int numQubits);
202
203
204/// @notyetdoced
205/// @notyetvalidated
206void calcProbsOfAllMultiQubitOutcomes(qreal* outcomeProbs, Qureg qureg, int* qubits, int numQubits);
207
208
209/** @} */
210
211
212
213/**
214 * @defgroup calc_properties Properties
215 * @brief Functions for calculating single-state properties like normalisation and purity.
216 * @{
217 */
218
219
220/// @notyetdoced
221/// @notyetvalidated
222qreal calcTotalProb(Qureg qureg);
223
224
225/// @notyetdoced
226/// @notyetvalidated
227qreal calcPurity(Qureg qureg);
228
229
230/** @} */
231
232
233
234/**
235 * @defgroup calc_comparisons Comparisons
236 * @brief Functions for comparing multiple quantum states.
237 * @{
238 */
239
240
241/// @notyetdoced
242/// @notyetvalidated
243qreal calcFidelity(Qureg qureg, Qureg other);
244
245/// @notyetdoced
246/// @notyetvalidated
247qreal calcDistance(Qureg qureg1, Qureg qureg2);
248
249
250/** @} */
251
252
253
254/**
255 * @defgroup calc_partialtrace Partial trace
256 * @brief Functions for calculating reduced density matrices, creating a new output Qureg.
257 * @{
258 */
259
260
261/// @notyetdoced
262/// @notyetvalidated
263Qureg calcPartialTrace(Qureg qureg, int* traceOutQubits, int numTraceQubits);
264
265
266/// @notyetdoced
267/// @notyetvalidated
268Qureg calcReducedDensityMatrix(Qureg qureg, int* retainQubits, int numRetainQubits);
269
270
271/** @} */
272
273
274// end de-mangler
275#ifdef __cplusplus
276}
277#endif
278
279
280
281/*
282 * C++ ONLY FUNCTIONS
283 *
284 * which are not directly C-compatible because they pass or
285 * return qcomp primitives by-value (rather than by pointer).
286 * This is prohibited because the C and C++ ABI does not agree
287 * on a complex type, though C's _Complex has the same memory
288 * layout as C++'s std::complex<>. To work around this, the
289 * below functions have a C-compatible wrapper defined in
290 * wrappers.h which passes/receives the primitives by pointer;
291 * a qcomp ptr can be safely passed from the C++ source binary
292 * the user's C binary. We manually add these functions to their
293 * respective Doxygen doc groups defined above
294 */
295
296
297/// @ingroup calc_comparisons
298/// @notyetdoced
299/// @notyetvalidated
300qcomp calcInnerProduct(Qureg qureg1, Qureg qureg2);
301
302
303/// @ingroup calc_expec
304/// @notyetdoced
305/// @notyetvalidated
307
308
309/// @ingroup calc_expec
310/// @notyetdoced
311/// @notyetvalidated
313
314
315/// @ingroup calc_expec
316/// @notyetdoced
317/// @notyetvalidated
318qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent);
319
320
321
322/*
323 * C++ OVERLOADS
324 *
325 * which are only accessible to C++ binaries, and accept
326 * arguments more natural to C++ (e.g. std::vector). We
327 * manually add these to their respective Doxygen doc groups.
328 */
329
330#ifdef __cplusplus
331
332#include <vector>
333
334
335/// @ingroup calc_prob
336/// @notyettested
337/// @notyetdoced
338/// @notyetvalidated
339/// @cppoverload
340/// @see calcProbOfMultiQubitOutcome()
341qreal calcProbOfMultiQubitOutcome(Qureg qureg, std::vector<int> qubits, std::vector<int> outcomes);
342
343
344/// @ingroup calc_prob
345/// @notyettested
346/// @notyetdoced
347/// @notyetvalidated
348/// @cpponly
349/// @see calcProbsOfAllMultiQubitOutcomes()
350std::vector<qreal> calcProbsOfAllMultiQubitOutcomes(Qureg qureg, std::vector<int> qubits);
351
352
353/// @ingroup calc_partialtrace
354/// @notyettested
355/// @notyetdoced
356/// @notyetvalidated
357/// @cppoverload
358/// @see calcPartialTrace()
359Qureg calcPartialTrace(Qureg qureg, std::vector<int> traceOutQubits);
360
361
362/// @ingroup calc_partialtrace
363/// @notyettested
364/// @notyetdoced
365/// @notyetvalidated
366/// @cppoverload
367/// @see calcReducedDensityMatrix()
368Qureg calcReducedDensityMatrix(Qureg qureg, std::vector<int> retainQubits);
369
370
371#endif // __cplusplus
372
373
374#endif // CALCULATIONS_H
375
376/** @} */ // (end file-wide doxygen defgroup)
qcomp calcInnerProduct(Qureg qureg1, Qureg qureg2)
qreal calcFidelity(Qureg qureg, Qureg other)
qreal calcDistance(Qureg qureg1, Qureg qureg2)
qreal calcExpecFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr)
qreal calcExpecFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matr, qreal exponent)
qcomp calcExpecNonHermitianFullStateDiagMatr(Qureg qureg, FullStateDiagMatr matr)
qreal calcExpecPauliStrSum(Qureg qureg, PauliStrSum sum)
qcomp calcExpecNonHermitianPauliStrSum(Qureg qureg, PauliStrSum sum)
qcomp calcExpecNonHermitianFullStateDiagMatrPower(Qureg qureg, FullStateDiagMatr matrix, qcomp exponent)
qreal calcExpecPauliStr(Qureg qureg, PauliStr str)
Qureg calcReducedDensityMatrix(Qureg qureg, int *retainQubits, int numRetainQubits)
Qureg calcPartialTrace(Qureg qureg, int *traceOutQubits, int numTraceQubits)
qreal calcProbOfQubitOutcome(Qureg qureg, int qubit, int outcome)
void calcProbsOfAllMultiQubitOutcomes(qreal *outcomeProbs, Qureg qureg, int *qubits, int numQubits)
qreal calcProbOfBasisState(Qureg qureg, qindex index)
qreal calcProbOfMultiQubitOutcome(Qureg qureg, int *qubits, int *outcomes, int numQubits)
qreal calcPurity(Qureg qureg)
qreal calcTotalProb(Qureg qureg)
Definition qureg.h:49