- Introduction
- Documentation
- Developer environment
- Pip installation
- How to use
- Tests
- Examples
- Studies
- Projects using QUnfold
- Credits
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.
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.
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
To install the latest released version of QUnfold
from PyPI you can do:
pip install QUnfold
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:
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 are performed using pytest
in verbose mode. To run them:
python -m pytest tests
Look at the examples folder for more details. To run the example:
python examples/simneal_script.py
Results are saved into the /examples
directory.
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.
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
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.
RooUnfold
may appear, you can ignore it since it is a false positive.
To run the code related to the technical QUnfold paper we are developing:
python studies/paper.py
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.
Gianluca Bianco |
Simone Gasperini |
DrWatt |