Metadata-Version: 2.1
Name: root-tomography
Version: 0.7
Summary: Python library for the root approach quantum tomography
Home-page: https://github.com/PQCLab/pyRootTomography
Author: Boris Bantysh
Author-email: bbantysh60000@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE

# Root approach quantum tomography

Python library for the discrete variables quantum state tomography using root approach and maximum likelihood estimation. The library contains a set of tools for quantum state reconstruction by the complementary measurements results, estimation of statistical adequacy and theoretical analysis of reconstruction fidelity.

- [Installation](#installation)
- [Definitions](#definitions)
- [Algorithm](#algorithm)
- [Data format](#format)
- [Quantum state tomography](#qst)
- [References](#references)
- [License](#license)

## <a name="installation">Installation</a>
```
pip install root-tomography
```

## <a name="definitions">Definitions</a>
Consider a quantum state in the Hilbert space of dimension <img alt="d" src="https://render.githubusercontent.com/render/math?math=d" />. The root approach to quantum state tomography implies reconstructing a purified quantum state <img alt="psi" src="https://render.githubusercontent.com/render/math?math=\psi" /> of size <img alt="d-by-r" src="https://render.githubusercontent.com/render/math?math=d\times r" /> instead of corresponding rank-<img alt="r" src="https://render.githubusercontent.com/render/math?math=r" /> **density matrix** <img alt="rho=psi*psi" src="https://render.githubusercontent.com/render/math?math=\rho=\psi\psi^\dagger" />. Thus, matrix <img alt="psi" src="https://render.githubusercontent.com/render/math?math=\psi" /> defines a **square root** of the density matrix.

We measure the reconstruction accuracy by Uhlmann's **fidelity** between the true state <img alt="rho" src="https://render.githubusercontent.com/render/math?math=\rho" /> and the reconstructed state <img alt="sigma" src="https://render.githubusercontent.com/render/math?math=\sigma" />:
<p align="center"><img alt="fidelity" src="https://render.githubusercontent.com/render/math?math=\displaystyle F(\rho,\sigma)=\left[\textrm{Tr}\sqrt{\sqrt\rho\sigma\sqrt\rho}\right]^2." /></p>

According to the quantum state estimation theory the **infidelity distribution** is bounded by the general chi-squared distribution with <img alt="nu" src="https://render.githubusercontent.com/render/math?math=\nu" /> degrees of freedom [[1]](#ref1):
<p align="center"><img alt="infidelity as random variable" src="https://render.githubusercontent.com/render/math?math=\displaystyle 1-F\sim\sum_{j=1}^{\nu}{d_j\xi_j^2}," /></p>

where <img alt="d_j" src="https://render.githubusercontent.com/render/math?math=d_j" /> are positive parameters and <img alt="xi_j" src="https://render.githubusercontent.com/render/math?math=\xi_j" /> are independent random variables with standard normal distribution. The expected value and variance of infidelity are thus
<p align="center"><img alt="infidelity mean and variance" src="https://render.githubusercontent.com/render/math?math=\displaystyle \langle1-F\rangle=\sum_{j=1}^{\nu}{d_j}, \qquad \sigma_{1-F}^2=2\sum_{j=1}^{\nu}{d_j^2}." /></p>

As the infidelity lower bound is inverse proportional to the total sample size <img alt="N" src="https://render.githubusercontent.com/render/math?math=N" /> over all measurements, we also use the so-called **loss function** <img alt="L=N*mean(1-F)" src="https://render.githubusercontent.com/render/math?math=L=N\langle1-F\rangle" /> independent of the sample size.

## <a name="algorithm">Algorithm</a>
We use the _maximum likelihood_ parameters estimation (MLE). In the case of quantum state tomography MLE results in the _likelihood equation_ [[1]](#ref1). Taking the density matrix normalization condition, one obtains
<p align="center"><img alt="likelihood equation" src="https://render.githubusercontent.com/render/math?math=\displaystyle \mu\psi=J(\psi\psi^\dagger)\psi," /></p>

where <img alt="mu" src="https://render.githubusercontent.com/render/math?math=\mu" /> is a constant (usually equal to the total observed counts <img alt="sum(k_j)" src="https://render.githubusercontent.com/render/math?math=\sum_j{k_j}" />) and
<p align="center"><img alt="J definitions" src="https://render.githubusercontent.com/render/math?math=\displaystyle J(\rho)=b_0(\rho) I %2B \sum_j{b_j(\rho)P_j}." /></p>

The sums are taken over all measurements operators in all measurements schemes. The actual values of <img alt="b_0" src="https://render.githubusercontent.com/render/math?math=b_0" /> and <img alt="b_j" src="https://render.githubusercontent.com/render/math?math=b_j" /> depend on the measurements statistics (see [Measurements statistics](#statistics) section).

An equation solution is obtained by the fixed-point iteration method:
<p align="center"><img alt="fixed-point iterations" src="https://render.githubusercontent.com/render/math?math=\displaystyle \psi_{i%2B1}=(1-a)\mu^{-1}J(\psi\psi^\dagger)\psi_i %2B a\psi_i." /></p>

Here <img alt="a" src="https://render.githubusercontent.com/render/math?math=a" /> is the regularization parameter. We use Moore-Penrose pseudo-inversion to get <img alt="psi_0" src="https://render.githubusercontent.com/render/math?math=\psi_0" />.

The root approach quantum tomography implies setting the model rank <img alt="r" src="https://render.githubusercontent.com/render/math?math=r" />. If the rank is unknown we estimate it using the _adequacy criterion_ [[1]](#ref1). To do this we vary <img alt="r" src="https://render.githubusercontent.com/render/math?math=r" /> from 1 to its maximal value until the reconstruction result becomes statistically significant at some pre-chosen significance level. The procedure is also terminated if the p-value of the rank-<img alt="(r+1)" src="https://render.githubusercontent.com/render/math?math=(r%2B1)" /> model is lower than p-value of the rank-<img alt="r" src="https://render.githubusercontent.com/render/math?math=r" /> model.


## <a name="format">Data format</a>
For the **quantum state tomography** one must specify a set of complementary measurement experiments over a quantum state density matrix <img alt="rho" src="https://render.githubusercontent.com/render/math?math=\rho" />. Every experiment may be repeated many times with some sets of possible measurement outcomes. The probability to get _k_-th outcome is determined by the measurement operator <img alt="P_k" src="https://render.githubusercontent.com/render/math?math=P_k" /> as <img alt="p_k=trace(rho*P_k)" src="https://render.githubusercontent.com/render/math?math=p_k=\textrm{Tr}(\rho P_k)" />. The set of measurement operators and the number of experiments repetitions define the **_measurements protocol_**. The number of observations for each outcome define the **_measurements results_**. The following code describe the required data format.
```python
proto  # List of measurement operators matrices
proto[j]  # 3d numpy array of measurement operator matrices in j-th measurement scheme
proto[j][k, :, :]  # Measurement operator matrix for k-th outcome in j-th measurement scheme
```
```python
nshots  # List of measurement schemes repetitions
nshots[j]  # Number of j-th scheme repetitions
```
```python
clicks  # List of outcomes
clicks[j]  # 1d numpy array of measurement outcomes in j-th scheme
clicks[j][k]  # Number of k-th outcome observations in j-th scheme
```
One can specify `nshots` as a single integer describing the total sample size. Then it is automatically divided equally over all measurement schemes.

One can also pass a 3d numpy array for measurement operators and a 1d array for measurements results implying only a single possible outcome in each measurement:
```python
proto[j, :, :]  # Measurement operator matrix for j-th measurement scheme
nshots[j]  # Number of j-th scheme repetitions
clicks[j]  # Number of observations in j-th scheme
```

## <a name="qst">Quantum state tomography</a>

Examples directory of the project contains a set of examples that show basic features of the library. Below we briefly review the quantum state tomography example.

Consider an example of a pure ququart state reconstruction using mutually-unbiased bases measurement protocol.
```python
from root_tomography.experiment import proto_measurement
from root_tomography.entity import State

dim = 4  # System dimension
r_true = 1  # True state rank
state_true = State.random(dim, r_true)  # True state
nshots = 10 ** 3  # Total sample size
proto = proto_measurement("mub", dim=dim)  # Generate measurements operators
```

The `Experiment` class of `experiment` module allows one to store the tomography data.
```python
from root_tomography.experiment import Experiment

ex = Experiment(dim, State)  # Generate experiment instance
ex.set_data(proto=proto, nshots=nshots)  # Set measurements protocol
ex.set_data(clicks=clicks)  # Set measurements data
```

One can also perform the measurement simulation.
```python
ex.simulate(state_true.dm)  # Performs the simulation and stores it
```


The reconstruction is performed using the `reconstruct_state` function of `estimator` module. By default the state rank is estimated automatically using the adequacy criteria.
```python
from root_tomography.estimator import reconstruct_state

state_rec = reconstruct_state(ex, display=10)
fid = State.fidelity(state_true, state_rec)
print(f"Fidelity: {fid:.6f}")
```

Output:
```
=== Automatic rank estimation ===
=> Try rank 1
Optimization: fixed point iteration method
Iteration 37 		 Delta 9.42e-09
=> Rank 1 is statistically significant at significance level 0.05000. Procedure terminated.
Fidelity: 0.995364
```

Using the fiducial approach and the theoretical infidelity distribution one can use the reconstruction result to estimate the guaranteed reconstruction fidelity. In the following code we estimate the 95%-probability fidelity bound ![F_95](https://latex.codecogs.com/svg.latex?F_%7B95%7D). That means that we get the fidelity ![F_95](https://latex.codecogs.com/svg.latex?F_%7B95%7D) or higher with probability 95%.
```python
from root_tomography.bound import bound
from root_tomography import gchi2

d = bound(state_rec, ex)  # Calculate variances
fid95 = 1 - gchi2.ppf(d, 0.95)  # Get fidelity bound
print(f"Fiducial 95% fidelity bound: {fid95:.6f}")
```

Output:
```
Fiducial 95% fidelity bound: 0.992822
```

The following code plots the infidelity distribution based on the true state and shows the fidelity of reconstructed state.
```python
import matplotlib.pyplot as plt

d = bound(state_true, ex)
p, df = gchi2.pdf(d)
plt.figure("Infidelity")
plt.plot(df, p, label="Theory")
plt.plot([1-fid, 1-fid], [0, max(p)*1.05], label="Reconstruction")
plt.xlabel("infidelity")
plt.legend()
plt.show()
```

![Theoretical distribution and reconstruction result](examples/infidelity.png?x=5)

The theoretical infidelity mean and variance could be obtained from the variance vector.
```python
sum(d)  # Mean infidelity
2 * sum(d ** 2)  # Infidelity variance
1-sum(d)  # Mean fidelity
```

## <a name="references">References</a>

<a name="ref1">[1]</a> Bogdanov Yu. I. Unified statistical method for reconstructing quantum states by purification // _JETP_ **108(6)** 928-935 (2009); doi: 10.1134/S106377610906003X

## <a name="license">License</a>

All code found in this repository is licensed under GPL v3
