Updated README.md

Author: EdoPro98

README.md

@@ -32,9 +32,9 @@ SimSiPM is distrubuted as an Open Source project and if you plan to use it pleas
 
 ## <a name="introduction"></a>Introduction
 SimSiPM is a simple and easy to use C++ library providing a set of object-oriented tools with all the functionality needed to describe and simulate Silicon PhotonMultipliers (SiPM) sensors.
-The main goal of SimSiPM is to include the response of SiPM sensors, along with noise and saturation effects, in the description of a generic detector in order to have a more detailed simulation. It can also be used to perform optimization studies considering different SiPMs models.
+The main goal of SimSiPM is to include the response of SiPM sensors, along with noise and saturation effects, in the description of a generic detector in order to have a more detailed simulation. It can also be used to perform optimization studies considering different SiPMs models allowing to choose the most suitable product available on the market.
 
-SimSiPM has beed developed following FCCSW C++ rules and guidelines and it is focused on SiPM simulation for high-energy physics and particle physics experiments however its flexibility allows to simulate any kind of experiments involving SiPM devices.
+SimSiPM code follows FCCSW rules and guidelines concerning C++. SimSiPM has been developed especially for high-energy physics and particle physics experiments, however its flexibility allows to simulate any kind of experiments involving SiPM devices.
 
 SimSiPM does not have any major external dependency making it the perfect candidate to be used in an already existing environment (Geant4 or DD4HEP) or as "stand-alone".
 
@@ -45,22 +45,23 @@ SimSiPM does not have any major external dependency making it the perfect candid
 - Easy to use:
   - Straight forward installation without external dependencies
   - Easy to use Object Oriented paradigm
-  - Python implementation
+  - Python implementation via Pybind11
 - Description of SiPM sensors:
-  - Based on datasheet values or measurable quantities
+  - Driven by parameters that can be obtained from the datasheet or laboratory measurements
   - High level of customization allowing to describe a wide range of use cases
   - Does not include tedious electronic circuit simulations
 - High performance:
   - Very fast signal generation
+  - Reliable description of SiPM signals and related quantities over all the dynamic range
   - Low memory footprint (if you do not intend to save all waveforms!)
 
 
 ## <a name="installation"></a>Installation
-SimSiPM has not external dependencies other than CMake.
+SimSiPM is fully functional without any external dependencies other than CMake.
 #### Optional dependencies:
 - Pybind11: to generate python bindings
-- OpenMP: for multi-core simulations
 - Doxygen: to generate documentation
+- GTest/Pytest: for advanced testing
 
 ### <a name="c++install"></a>C++
 SimSiPM can be installed using the standard CMake workflow:
@@ -70,19 +71,31 @@ cmake -B build -S .
 make -C build
 make -C build install
 ```
-Installation directory can be specified with `-DCMAKE_INSTALL_PREFIX` variable.  
-Python bindings can be installed in the default python site-packages path by adding the variable `-DCOMPILE_PYTHON_BINDINGS=ON` but this requires Pybind11 to be installed.
+It is advisable to enable compiler optimizations like `-O3` and `-mfma -mavx2` since some parts of code are specifically written using intrinsic functions for vectorization.
+
+Installation directory can be specified with `-DCMAKE_INSTALL_PREFIX` variable.
+
+Python bindings can be compiled and installed by adding the variable `-DCOMPILE_PYTHON_BINDINGS=ON` but this requires Pybind11.
+The corresponding python module is called `SiPM` and each class can be accessed as a sub-module.
+
+```py
+import SiPM
+from SiPM import SiPMSensor
+
+print(SiPM.__version__)
+```
+
 
 ### <a name="pyinstall"></a>Python
-It is also possible to install only the python version via pip but performance might not be as good as the source code version:
+It is also possible to use pip to install only the Python version using a precompiled binary wheel. This installation method is easyer but performance may be impaired with respect to the C++/Pybind11 installation.
 ```sh
 pip install SiPM
 ```
 
 ## <a name="C++_basic_usage"></a>C++ basic use
-
+SimSiPM focuses on simplicity! It does not make use of pointers, or custom classes as  parameters of the simulation or input. In most cases a std::vector is all that you need in order to get started.
 ### SiPMProperties
-SiPMProperties object stores all SiPM and simulation parameters
+SiPMProperties class stores all SiPM and simulation parameters. It can be used to define the SiPM detector model in use and it can be shared among different SiPMs in case many identical sensors are needed.
 ```cpp
 #include "SiPMProperties.h"
 using namespace sipm;
@@ -96,7 +109,7 @@ myProperties.setPropery("Xt",0.03);   // Using parameter name
 ```
 
 ### SiPMSensor
-SiPMSensor object is used to store photons and generate signals
+SiPMSensor class is the core of the simulation and is created from a SiPMProperties class. It stores input photoelectrons, it runs the event simulation and gives a signal as output.
 ```cpp
 #include "SiPMProperties.h"
 using namespace sipm;
@@ -109,8 +122,17 @@ mySensor.properties().setAp(0.01);    // Using proper getter/setter
 mySensor.setProperty("Pitch", 25);    // Using parameter name
 ```
 
+### SiPMAnalogSignal
+SiPMAnalogSignal class is a wrapper around std::vector that expands its features. It contains the samples of the SiPM waveform along with some properties and methods used to extract features from the signal.
+```cpp
+SiPMAnalogSignal signal = mySensor.signal();
+double sampling = signal.sampling();
+double sample = signal[10];
+```
+
 ### Input and simulation
-Input of the simulation is either the arriving time of a photon on the SiPM surface or both the arriving time of the photon and its wavelength.
+The only input needed for the simulation of a SiPM event is the arriving time of each photon to the sensitive surface of the SiPM detector.
+In order to have a detailed description of the dependency of the PDE with respect to the photon wavelength it is possible to add the wavelength information togheter with the time information.
 
 It is possible to add individual photons in a loop
 ```cpp
@@ -131,7 +153,7 @@ mySensor.runEvent();           // Runs the simulation
 ```
 
 ### Signal output and signal features
-After running the simulation the signal can be retrieved:
+The simulation can output the signal waveform and can also perform some simple features extraction.
 ```cpp
 SiPMAnalogSignal mySignal = mySensor.signal();
 
@@ -142,15 +164,16 @@ double tot = signal.tot(5,250,0.5);   // (intStart, intGate, threshold)
 
 // It is possible to iterate throw an analog signal
 for(int i=0;i<mySignal.size();++i){
-  // Do something with mySignal[i]
+  double sample = mySignal[i]
+  // Do something with sample
 }
 
 // It is possible to convert an analog signal to a simple vector
 std::vector<double> waveform = mySignal.waveform();
 ```
 
 ### Complete event loop
-A typical event loop would look like:
+This is an example of "stand-alone" usage of SimSiPM. In case SimSiPM is used in Geant4 or other framework, then the generation of photon times has to be caryed by the user (usually in G4UserSteppingAction) and the event has to be simulated after all photons have been added (usually in G4UserEventAction).
 ```cpp
 // Create sensor and set parameters
 SiPMProperties myProperties;
@@ -177,7 +200,7 @@ for(int i=0;i<NEVENTS;++i){
 }
 ```
 ## <a name="python_basic_usage"></a>Python basic use
-Python bindings are generated using Pybind11 so the usage is very similar to C++ but with python syntax.
+Python bindings are generated for all the classes using Pybind11. This allows for an almost 1:1 mapping of the C++ functionalities in Python.
 
 ```python
 from SiPM import SiPMSensor, SiPMProperties
@@ -198,9 +221,9 @@ integral = mySignal.integral(10,250,0.5)
 ## <a name="adv"></a>Advanced use
 ### <a name="pde"></a>PDE
 #### No Pde
-Tracking a large number of photons is a CPU intensive task and since most of photons will not be detected due to photon detection efficiency (PDE) it would be a waste of time.
+Tracking a large number of photons throwgh a scintillator crystal or optical fiber is a very CPU-intensive task. Since most of photons will not be detected due to photon detection efficiency (PDE) it is a waste of time to track all of them.
 
-By default SiPM sensors have PDE set to 100% meaning that every photon is converted to a photoelectron and detected. This allows to generate only the photons that will be detected by the sensor. For example the geometry of IDEA dual-readout calorimeter requires the simulation of 130 millions of optical fibers and in each one of those photons are tracked by Geant4 requiring a lot of CPU time. It would be meaningless to track photons along the fibers if they are not detected!
+By default SiPM sensors have PDE set to 100% meaning that every photon given as input is converted to a photoelectron, detected and generates a signal. This allows to generate and track only the photons that will be detected by the sensor. For example the geometry of IDEA dual-readout calorimeter requires the simulation of 130 millions of optical fibers and in each one of those photons are tracked by Geant4 requiring a lot of CPU time. It would be meaningless to track photons along the fibers if they are not detected, so PDE is evaluated before the tracking of photons.
 
 #### Simple PDE
 It is possible to account for PDE in the simulation using a fixed value of PDE for all photons. In this case the probability to detect a photon is proportional to PDE. This option can be used if the spectrum of emitted photons is very narrow or if the SiPM has a wide and flat spectral response.
@@ -216,13 +239,13 @@ mySensor.setProperty("Pde",0.27); // or mySensor.properties().setPde(0.27);
 To revert back at default setting of 100% PDE use `setPdeType(sipm::SiPMProperties::PdeType::kSimplePde)`
 
 #### Spectral PDE
-In some SiPM sensors PDE strongly depends on photon wavelength. In some cases it might be necessary to consider the spectral response of the SiPM for a more accurate simulation.
+In SiPM sensors PDE strongly depends on photon wavelength. In some cases it might be necessary to consider the spectral response of the SiPM for a more accurate simulation.
 This can be done by feeding the SiPM settings with two arrays containing wavelengths and corresponding PDEs.
 
 In this case it is also necessary to input photon wavelength along with its time.
 ```cpp
-std::vector<double> wlen = {300, 400, 500, 600, 700, 800};
-std::vector<double> pde  = {0.01, 0.20, 0.33, 0.27, 0.15, 0.05};
+std::vector<double> wlen = {800, 750, 700, 650, 600, 550, 500, 450, 400, 350, 300};
+std::vector<double> pde = {0.22, 0.30, 0.40, 0.45, 0.50, 0.50, 0.45, 0.35, 0.25, 0.15, 0.0};
 
 myProperties.setPdeType(sipm::SiPMProperties::PdeType::kSpectrumPde);
 myProperties.setPdeSpectrum(wlen,pde);
@@ -237,27 +260,30 @@ mySensor.addPhoton(photonTime, photonWlen);
 ```
 <p align="center"><img src="images/pde.png" width=500></p>
 
-The values inserted by the user are linearly interpolated to calculate the PDE for each wavelength so it is better to add a reasonable number of values.
+The input values for PDE given by the user are interpolated using the formula below to obtain additional 25 values over the given range. Then, during the simulation, values are linearly interpolated between the points of the newly obtained curve.
+
+<p align="center"><img src="images/interpolation.svg" width=400></p>
+
 
 ### <a name="hit"></a>Hit distribution
-By default photoelectrons are considered to be distributed uniformly on the surface of the SiPM. In most cases this assumption resembles what happens in a typical setup but sometimes the geometry of the sensor or the optical characteristics of the setup lead to an inhomogeneous distribution of the light on the sensor's surface.
+By default photoelectrons hits are considered to be uniformly distributed on the surface of the SiPM. In most cases this assumption resembles what happens in a typical setup but sometimes the geometry of the sensor or the optical characteristics of the setup lead to an inhomogeneous distribution of the light on the sensor's surface.
 
 #### Uniform hit distribution
-This is the default setting. Each SiPM cell has the same probability to be hitted.
+This is the default setting: each SiPM cell has the same probability to be hitted. This setting should work in most of scenarios.
 ```cpp
 myPropertie.setHitDistribution(sipm::SiPMProperties::HitDistribution::kUniform);
 ```
 
 #### Circular hit distribution
-In this case 95% of photons are placed in a circle centered in the sensor and with a diameter that is the same as the sensor's side lenght. The remaining 5% is distributed uniformly on the sensor.
+In this case 90% of photons are placed in a circle centered in the sensor and with a diameter that is the same as the sensor's side lenght. The remaining 10% is distributed outside this circle. This setting resembles those cases where light is focused in the central region.
 <p align="center"><img src="images/circleHits.png" width=250></p>
 
 ```cpp
 myPropertie.setHitDistribution(sipm::SiPMProperties::HitDistribution::kCircle);
 ```
 
 #### Gaussian hit distribution
-In this case 95% of the photons are distributed following a gaussian distribution centered in the sensor. The remaining 5% is distributed uniformly on the sensor.  
+In this case 95% of the photons are distributed following a gaussian distribution centered in the sensor. The remaining 5% is distributed uniformly on the sensor.
 <p align="center"><img src="images/gaussianHits.png" width=250></p>
 
 ```cpp