Metadata-Version: 2.4
Name: mbqs
Version: 1.0.0
Summary: Many-body quantum score.
Project-URL: Homepage, https://github.com/HaroldErbin/mbqs
Project-URL: Issues, https://github.com/HaroldErbin/mbqs/issues
Author-email: Harold Erbin <harold.erbin@gmail.com>, Grégoire Misguich <gregoire.misguich@ipht.fr>
License-Expression: EUPL-1.2
License-File: LICENSE.md
Keywords: many-body physics,quantum computing application benchmark,quantum simulations,quantum spin models
Requires-Python: ~=3.12.0
Requires-Dist: argcomplete
Requires-Dist: numpy
Requires-Dist: pulser
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: pip; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff~=0.15.3; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Provides-Extra: examples
Requires-Dist: emu-mps; extra == 'examples'
Requires-Dist: ipykernel; extra == 'examples'
Description-Content-Type: text/markdown

# MBQS: Many-Body Quantum Score – A scalable benchmark for digital and analog quantum processors

This packages provides a set of tools to compute the Many-Body Quantum Score (MBQS),
which is designed to benchmark the performance of quantum processors in simulating
many-body quantum systems [arXiv:[2601.03461](https://arxiv.org/abs/2601.03461)][^1].
The score is obtained by comparing a given metric, called $P_2(L)$, with a threshold
$\epsilon$.

The MBQS metric is parametrized by an initial state $\psi$ and computed according to
the following protocol:

1. Setup a spin chain with $L$ spin $\frac{1}{2}$ equally spaced on a $1d$ ring.
2. Initialize the register with the state $\ket{\psi}$.
3. Evolve the system (quench) with the Ising Hamiltonian at the critical point $g = 1$
   for a duration $t_*(L)$ (“surge time”).
4. Perform measurements $\{ \sigma^z_i \}$ and compute the connected 2-point functions:

  $$
  g^{(2)}_\ell(t)
      := \Braket{\sigma^z_1 \sigma^z_\ell}_c
      := \Braket{\sigma^z_1 \sigma^z_\ell} - \Braket{\sigma^z_1} \Braket{\sigma^z_\ell}.
  $$

5.  Compute the metric (average relative error with respect to the theoretical values
    in Ising model):

  $$
  P_2(L)
      := \frac{1}{\lfloor L/2 \rfloor - 1} \sum_{\ell = 2}^{\lfloor L/2 \rfloor}
          \left| \frac{g^{(2) \text{th}}_{\ell}(t_\ast) - g^{(2) \text{exp}}_{\ell}(t_\ast)}{g^{(2) \text{th}}_{\ell}(t_\ast)} \right|.
  $$

The MBQS score S with the initial state $\psi$ corresponds to the largest problem
size $L$ reached before failing the test with a threshold $\epsilon$, but excluding
system sizes below some cut-off:

$$
S
    = L
\quad
\Longrightarrow
\quad
\forall L' \le L:
    \quad
    P_2(L') \le \epsilon.
$$

In this package, we provide the evaluation for the folloling initial states:

- $\ket{+ \cdots +}$
- $\ket{\downarrow \cdots \downarrow}$

The surge time is defined to be the time at which the antipodal connected 2-point
function is maximum. The only exception is for $L = 3$ and with the down state: it is
defined to be the time for which the 1-point function is maximum (because the 2-point
function has a large plateau).

> [!WARNING]
> The definition of the surge time for L = 3 is different compared to the original
> paper.

## Usage

We provide the computations of the surge time and correlation functions at that time
using three different methods:
1. Exact simulation with qutip (for $L \lesssim 20$ on a laptop).
2. Exact solution with free fermions (for any $L$; **not yet implemented**).
3. Tabulated data from free fermions (for $L \le 50$).

The qutip method is provided as a way to check the results for low L but it is
not scalable to large systems. The free fermions method is exact and can be used
for any $L$. The tabulated data method is taken from the free fermions: for larger $L$,
it falls back to free fermions.

We also provide utilities to map the critical Ising model on a neutral atom QPU.


### As a Python package

You can use `mbqs` as a package. The most important classes are available as top-level
imports: `MBQS`, `MBQSProtocol`, `RydbergMapping`. You can check the unit tests and CLI
actions to find how to use them.


### Command-line interface

- Display in console the parameters needed to run the protocol for a given system size:

```bash
mbqs protocol -J 1. -L 4
```

- Display in console the parameters needed to run the protocol for several system
  sizes:

```bash
mbqs protocol -J 1. -L {4..6}
```

- Parameters for running the protocol on an neutral atom analog quantum simulator can
  be added using the `--include-rydberg` flag or using the interatomic distance as a
  parameter instead of the coupling constant:

```bash
mbqs protocol -J 1. -L 4 --include-rydberg
mbqs protocol -a 7.75 -L 4
```

- Save a json file with the protocol parameters (use `--verbose` to also display in
  the console):

```bash
mbqs protocol -J 1. -L {4..6} --json protocol.json
```

- Compute the theoretical correlations at the surge time:

```bash
mbqs correlations -L 3
```

- Compute the correlations from a file of samples:

```bash
mbqs correlations -i samples.json
```

- Evaluate the metric from correlations functions in a file:

```bash
# without parameters in file
mbqs scorer -i examples/correlations_samples.json -L 3 --threshold 0.3
# with parameters
mbqs scorer -i examples/correlations_exact.json
```

- Evaluate the metric from samples in a file:

```bash
mbqs scorer -i examples/samples.json
```

- Evaluate the score for a file containing correlations functions for different system
  sizes:

```bash
mbqs scorer -i examples/correlations_sequence.json
```

Examples of json files can be found in the `examples` directory.

Autocompletion can be enabled for the `mbqs` command by running the following command
(only for the current session):

```bash
eval "$(register-python-argcomplete mbqs)"
```

To make it persistent (for example, for bash on Linux), you can execute the following
commands:

```bash
mkdir -p ~/.local/share/bash-completion/completions
register-python-argcomplete mbqs > ~/.local/share/bash-completion/completions/mbqs
```


## Contributing

To install all the dependencies including the development tools, run:

```bash
uv venv
make install-dev
```

Before performing a commit, ensure that the following returns no error or warning:

```bash
make check
make test
```


[^1]: Erbin, H., Burdeau, P.-L., Bertrand, C., Ayral, T., & Misguich, G. (2026).
      *Many-body Quantum Score: a scalable benchmark for digital and analog quantum
      processors and first test on a commercial neutral atom device*. arXiv:
      [2601.03461](https://arxiv.org/abs/2601.03461)
