- Introduction
- Documentation
- Installation
- Usage example
- Unfolding studies
- Main developers
- Other contributors
This package provides an implementation of a quantum-based solver for the statistical unfolding problem formulated as a Quadratic Unconstrained Binary Optimization (QUBO) problem.
The code is written in Python and based on NumPy
, but it allows to be used on ROOT
data for application in High-Energy Physics (HEP).
The idea is inspired by the work done by Riccardo Di Sipio et al. which can be found here. For a more detailed description of the model, take a look at the Wiki page.
The package currently provides the following algorithms to solve the unfolding problem:
- Simulated annealing: D-Wave implementation of the standard simulated annealing algorithm running on classical hardware resources
- Hybrid solver: complex approach combining both classical computing (for the decomposition of the original problem into smaller sub-problems) and D-Wave quantum annealing on real hardware
- Quantum annealing: quantum approach fully running on D-Wave quantum annealing hardware.
- Wiki page: description of the theoretical model and examples on how to use the package.
- Read the Docs: API documentation for all the available features of the package.
To install the QUnfold
latest version released on PyPI in user-mode you can do:
pip install QUnfold
If you also want to enable the classical Gurobi solver (Python API) both for the integer optimization and QUBO problem, you need to install QUnfold
including extra requirements:
pip install QUnfold[gurobi]
To create a dedicated conda
environment and install QUnfold
in developer-mode you can do:
conda create --name qunfold-dev python==3.10
conda activate qunfold-dev
git clone https://github.com/JustWhit3/QUnfold.git
cd QUnfold
pip install --upgrade -r requirements-dev.txt
pip install -e .[gurobi]
Here is a simple code example showing how to use QUnfold
:
from qunfold import QUnfolder
# Define your input response matrix and measured histogram as numpy arrays
response = ...
measured = ...
binning = ...
# Create the QUnfolder object and initialize the QUBO model
unfolder = QUnfolder(response, measured, binning, lam=0.1)
unfolder.initialize_qubo_model()
# Run one of the available solvers to get the unfolding result
sol, cov = unfolder.solve_simulated_annealing(num_reads=100)
If you are working in High-Energy Physics, your response matrix might be a RooUnfoldResponse
object and your measured histogram is probably stored as a ROOT.TH1
object.
The qunfold.utils
module provides some simple functions to convert these objects to standard numpy arrays:
from qunfold.utils import TH1_to_numpy, TH2_to_numpy
# Convert ROOT.TH1 measured histogram to numpy array
measured = TH1_to_numpy(measured)
# Convert RooUnfoldResponse object to numpy array
response = TH2_to_numpy(response.Hresponse())
For a complete example on how to run the QUnfold
solvers and plot the final results, you can take a look at the examples directory in the repository.
This section contains instructions to solve the unfolding problem by classical methods (widely used in HEP data analysis) as well as the QUnfold
quantum-based method. It also provides several tools and examples to compare the results of the two different approaches.
To run the classical unfolding algorithms you need to install the ROOT
framework developed by CERN (see documentation here) and the specialized RooUnfold
library (see documentation here).
On Linux or Mac OS this can be easily done by running the following script in the root directory of the repository:
./install_roounfold.sh
The code can be used to generate syntetic data samples according to common HEP probability density functions (normal, gamma, exponential, Breit-Wigner, double-peaked) and apply a smearing to roughly simulate the distortion effects due to limitions efficiency, acceptance, and space/time resolution of a given detector.
Then, unfolding is performed by several classical, hybrid, and quantum techniques and the results are studied to compare the performance of the different methods. In particular, the algorithms currently available are the following:
RooUnfold
framework:- Matrix Inversion unfolding (MI)
- Bin-by-Bin unfolding (B2B)
- Iterative Bayesian Unfolding (IBU)
- Tikhonov regularized unfolding (SVD)
QUnfold
library:- D-Wave Simulated Annealing (SA) for QUBO unfolding
- D-Wave Hybrid solver (HYB) for QUBO unfolding
- D-Wave Quantum Annealing (QA) for QUBO unfolding (QA)
Gianluca Bianco |
Simone Gasperini |
Marco Lorusso |