QUnfold

QUnfold copied to clipboard

Table of contents

• Introduction
• Documentation
• Developer environment
• Pip installation
• How to use
  • NumPy case
  • ROOT case
• Tests
• Examples
• Studies
  • Install HEP dependencies
  • Run the analysis
  • Run the paper studies
• Projects using QUnfold
• Credits
  • Main developers

Introduction

This module consists of an implementation of the unfolding statistical approach using quantum computation and in particular a quadratic unconstrain binary optimization approach. To find a detailed implementation of the model you can look at this wiki page. This software is based on NumPy, but you can easily run it also using ROOT framework data (see below).

For the moment you can use it in two modes:

• Simulated annealing (solve_simulated_annealing): which uses simulated quantum computer to compute the result.
• Quantum annealing (solve_quantum_annealing): which uses D-Wave resources to perform quantum annealing to compute the result.
• Hybrid solver (solve_hybrid_sampler): which uses D-Wave resources to perform hybrid quantum annealing (classical + quantum hardware) to compute the result.

Idea was born by me and Simone during a quantum computing school of Cineca and is inspired by the work done by Riccardo Di Sipio et al. which can be found here.

:warning: The project is currently work-in-progress and it is still not ready for production. Some improvements and issues should be investigated and solved before releasing and packaging an official version of the software. Any help would be more than welcome! See the contribution file if interested.

Documentation

Research documentation:

• Poster at the 2023 Julich Summer School.

Further documentation:

• Wiki pages: contain detailed description of each feature and examples.
• ReadtheDocs page: contains documentation about all the functions and classes of the module.
• Contributing file: contains instructions about how to contribute.

Developer environment

To setup the environment for QUnfold development you need conda:

conda create --name qunfold-dev python==3.10
conda activate qunfold-dev
pip install -r requirements.txt
pip install -e src/

and every time you open a new shell:

conda activate qunfold-dev

Pip installation

To install the latest released version of QUnfold from PyPI you can do:

pip install QUnfold

How to use

NumPy case

To run QUnfold on a dataset you can do the following steps:

# Import QUnfold base class and plotter
from QUnfold import QUnfoldQUBO
from QUnfold import QUnfoldPlotter

# Read numpy data from a file or sample them
truth = ... # truth distribution
measured = ... # measured distribution
response = ... # response matrix
binning = ... # binning of the distributions

# Run unfolding
unfolder = QUnfoldQUBO(response, measured, lam=0.1)
unfolder.initialize_qubo_model()
unfolded_SA, error_SA, cov_matrix_SA, corr_matrix_SA = unfolder.solve_simulated_annealing(num_reads=10, num_toys=100)

# Plot results
plotter = QUnfoldPlotter(
    response=response,
    measured=measured,
    truth=truth,
    unfolded=unfolded_SA,
    error=error_SA,
    binning=binning,
    chi2=compute_chi2(unfolded, truth, cov_matrix),
)
plotter.plotResponse()
plotter.plot()

which will produce a similar result to this unfolded normal distribution:

:warning: The response matrix must be normalized in order to keep the correct binary encoding of input data. The procedure is described in this twiki page.

:warning: To get more information about how the error and covariance/correlation matrices are compute see this twiki page.

ROOT case

To use ROOT data add the following steps at the beginning of the code:

# Import ROOT converters
from QUnfold.utility import TH1_to_array, TH2_to_array

# Read data as before...
# Convert data from ROOT to numpy
truth = TH1_to_array(truth)
measured = TH1_to_array(measured)
response = TH2_to_array(response.Hresponse())

# Run analysis as before...

Tests

Tests are performed using pytest in verbose mode. To run them:

python -m pytest tests

Examples

Look at the examples folder for more details. To run the example:

python examples/simneal_script.py

Results are saved into the /examples directory.

Studies

This section contains instructions to run unfolding with other packages in order to do comparisons with QUnfold. All the code lies under the studies directory.

Install HEP dependencies

To run all the studies you will need to install some HEP dependencies:

• ROOT: v6.28/10.

• RooUnfold: v3.0.0. See this user guide for a good user guide, the official Doxygen page and the repository.

This dependencies can be easily installed from the root directory of the repository using the related scripts:

./scripts/fetchROOT.sh
source HEP_deps/root/bin/thisroot.sh
./scripts/fetchRooUnfold.sh

They will be installed into the HEP_deps directory of the repository.

If you want to use the ROOT version of the repo you must do this command every time you plan to run a code which contains the ROOT package:

source HEP_deps/root/bin/thisroot.sh

Run the analysis

To run the whole analysis script:

python studies/analysis.py

Pseudo-data will be generated following common distributions (normal, exponential, etc...) which will be unfolded using RooUnfold and the following common classical methods:

• Iterative Bayesian unfolding (4 iters)
• Tikhonov regularized SVD unfolding (K=2)

Comparisons are performed with the following QUnfold methods:

• Simulated Annealing - QUBO unfolding
• D-Wave Hybrid solver - QUBO unfolding

The output plots and chi2 for each distribution will be saved into an external img directory.

:warning: An error related to RooUnfold may appear, you can ignore it since it is a false positive.

Run the paper studies

To run the code related to the technical QUnfold paper we are developing:

python studies/paper.py

Projects using QUnfold

List of projects which import and use QUnfold:

• PyXSec: Python framework to measure differential cross-section of particle physics processes using classical- and quantum-computing based techniques.

Credits

Main developers

Gianluca Bianco

Simone Gasperini

Other contributors

DrWatt