Uploading the code

.gitignore

@@ -1,5 +1,11 @@
-# Prerequisites
-*.d
+# CMake
+CMakeCache.txt
+CMakeFiles/
+Makefile
+cmake_install.cmake
+run/CMakeFiles/
+run/cmake_install.cmake
+benchmark/APFEL
 
 # Compiled Object files
 *.slo
@@ -30,3 +36,16 @@
 *.exe
 *.out
 *.app
+
+# LaTex
+*.aux
+*.idx
+*.log
+*.pdf
+
+.ipynb_checkpoints
+
+build
+bin/MontBlanc-config
+inc/MontBlanc/version.h
+bin/MontBlanc-config

CMakeLists.txt

@@ -0,0 +1,145 @@
+cmake_minimum_required (VERSION 3.5)
+# Set a default build type if none was specified
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  message(STATUS "Setting build type to 'Release' as none was specified.")
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
+  # Set the possible values of build type for cmake-gui
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release"
+    "MinSizeRel" "RelWithDebInfo")
+endif()
+
+if (NOT DEFINED CMAKE_MACOSX_RPATH)
+   set(CMAKE_MACOSX_RPATH 0)
+endif()
+
+# the project name
+project(MontBlanc)
+
+# activating some global properties for the project
+set(MontBlanc_VERSION 1.0.0)
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# export version to file
+configure_file(
+  "${PROJECT_SOURCE_DIR}/inc/MontBlanc/version.h.in"
+  "${PROJECT_SOURCE_DIR}/inc/MontBlanc/version.h"
+)
+
+find_package(PkgConfig REQUIRED)
+pkg_search_module(YAML REQUIRED yaml-cpp)
+pkg_search_module(EIGEN3 REQUIRED eigen3)
+find_package(Ceres REQUIRED)
+include_directories(${CERES_INCLUDE_DIRS})
+pkg_search_module(GLOG REQUIRED libglog)
+pkg_search_module(GFLAGS REQUIRED gflags)
+
+# Configuration script
+set(prefix ${CMAKE_INSTALL_PREFIX})
+set(exec_prefix "${prefix}")
+set(includedir "${prefix}/include")
+set(libdir "${prefix}/lib")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/bin/MontBlanc-config.in"
+  "${PROJECT_SOURCE_DIR}/bin/MontBlanc-config"
+)
+
+include_directories(${PROJECT_SOURCE_DIR}/inc)
+
+# LHAPDF
+find_program(LHAPDF_CONFIG lhapdf-config REQUIRED)
+if (LHAPDF_CONFIG)
+  exec_program(${LHAPDF_CONFIG}
+    ARGS --cflags
+    OUTPUT_VARIABLE LHAPDF_CXX_FLAGS
+  )
+  set(LHAPDF_CXX_FLAGS ${LHAPDF_CXX_FLAGS} CACHE STRING INTERNAL)
+  exec_program(${LHAPDF_CONFIG}
+    ARGS --libs
+    OUTPUT_VARIABLE LHAPDF_LIBRARIES
+  )
+  set(LHAPDF_LIBRARIES ${LHAPDF_LIBRARIES} CACHE STRING INTERNAL)
+else(LHAPDF_CONFIG)
+  message(FATAL_ERROR "LHAPDF not found!")
+endif(LHAPDF_CONFIG)
+
+# APFEL++
+find_program(APFELXX_CONFIG apfelxx-config REQUIRED)
+if (APFELXX_CONFIG)
+  exec_program(${APFELXX_CONFIG}
+    ARGS --cppflags
+    OUTPUT_VARIABLE APFELXX_CXX_FLAGS
+  )
+  set(APFELXX_CXX_FLAGS ${APFELXX_CXX_FLAGS} CACHE STRING INTERNAL)
+  exec_program(${APFELXX_CONFIG}
+    ARGS --ldflags
+    OUTPUT_VARIABLE APFELXX_LIBRARIES
+  )
+  set(APFELXX_LIBRARIES ${APFELXX_LIBRARIES} CACHE STRING INTERNAL)
+else(APFELXX_CONFIG)
+  message(FATAL_ERROR "APFEL+ not found!")
+endif(APFELXX_CONFIG)
+
+# NANGAPARBAT
+find_program(NANGAPARBAT_CONFIG NangaParbat-config REQUIRED)
+if (NANGAPARBAT_CONFIG)
+  exec_program(${NANGAPARBAT_CONFIG}
+    ARGS --cppflags
+    OUTPUT_VARIABLE NANGAPARBAT_CXX_FLAGS
+  )
+  set(NANGAPARBAT_CXX_FLAGS ${NANGAPARBAT_CXX_FLAGS} CACHE STRING INTERNAL)
+  exec_program(${NANGAPARBAT_CONFIG}
+    ARGS --ldflags
+    OUTPUT_VARIABLE NANGAPARBAT_LIBRARIES
+  )
+  set(NANGAPARBAT_LIBRARIES ${NANGAPARBAT_LIBRARIES} CACHE STRING
+  INTERNAL)
+else(NANGAPARBAT_CONFIG)
+  message(FATAL_ERROR "NANGAPARBAT not found!")
+endif(NANGAPARBAT_CONFIG)
+
+# GSL
+find_program(GSL_CONFIG gsl-config REQUIRED)
+if (GSL_CONFIG)
+  exec_program(${GSL_CONFIG}
+    ARGS --cflags
+    OUTPUT_VARIABLE GSL_CXX_FLAGS
+  )
+  set(GSL_CXX_FLAGS ${GSL_CXX_FLAGS} CACHE STRING INTERNAL)
+  exec_program(${GSL_CONFIG}
+    ARGS --libs
+    OUTPUT_VARIABLE GSL_LIBRARIES
+  )
+  set(GSL_LIBRARIES ${GSL_LIBRARIES} CACHE STRING INTERNAL)
+else(GSL_CONFIG)
+  message(FATAL_ERROR "GSL not found!")
+endif(GSL_CONFIG)
+
+# NNAD
+find_program(NNAD_CONFIG nnad-config REQUIRED)
+if (NNAD_CONFIG)
+  exec_program(${NNAD_CONFIG}
+    ARGS --cflags
+    OUTPUT_VARIABLE NNAD_CFLAGS
+  )
+  set(NNAD_CFLAGS ${NNAD_CFLAGS} CACHE STRING INTERNAL)
+endif(NNAD_CONFIG)
+
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}") 
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${NNAD_CFLAGS} ${EIGEN3_CFLAGS} ${Ceres_CFLAGS} ${GLOG_CFLAGS} ${GFLAGS_CFLAGS} ${LHAPDF_CXX_FLAGS} ${APFELXX_CXX_FLAGS} ${NANGAPARBAT_CXX_FLAGS} ${GSL_CXX_FLAGS} ${YAML_CFLAGS} -Wall -fPIC -Wunused")
+
+# build target library
+add_subdirectory(src)
+add_subdirectory(run)
+add_subdirectory(tests)
+
+#option(BUILD_TESTS "Build tests code" ON)
+#if(BUILD_TESTS)
+#  enable_testing()
+#  add_subdirectory(tests)
+#endif(BUILD_TESTS)
+
+install(FILES ${PROJECT_SOURCE_DIR}/bin/MontBlanc-config
+	   DESTINATION bin
+	   PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)

README.md

@@ -0,0 +1,96 @@
+![alt text](resources/MontBlanc.jpg "Mont Blanc")
+
+# MontBlanc
+
+`MontBlanc` is a code devoted to the extraction of collinear distributions. So far, it has been used to determine the fragmentation functions (FFs) of the pion from experimental data for single-inclusive annihilation and semi-inclusive deep-inelastic scattering. Details concerning this fit of FFs in particular and the methodology in general can be found in the reference below.
+
+The FF sets in the LHAPDF format for both positive and negative pions as well as for their sum can be found [here](FFSets/).
+
+## Requirements
+
+In order for the code to pe compiled, the following dependencies need to be preinstalled:
+
+- [`NangaParbat`](https://github.com/vbertone/NangaParbat)
+- [`apfelxx`](https://github.com/vbertone/apfelxx)
+- [`NNAD`](https://github.com/rabah-khalek/NNAD)
+- [`ceres-solver`](http://ceres-solver.org)
+- [`LHAPDF`](https://lhapdf.hepforge.org)
+- [`yaml-cpp`](https://github.com/jbeder/yaml-cpp)
+- [`GLS`](https://www.gnu.org/software/gsl/)
+
+## Compilation and installation
+
+The `MontBlanc` library only relies on `cmake` for configuration and installation. This is done by following the standard procedure:
+```
+mkdir build
+cd build
+cmake ..
+make -j
+make install
+```
+The library can be uninstalled by running:
+```
+make clean
+xargs rm < install_manifest.txt
+```
+
+## Usage
+
+The relevant source code to perform a fit and analyse the results can be found in the `run/` folder. However, in the following we assume to be in the `build/run/` folder that will be created after the `cmake` procedure detailed above and that contains the executables. In this folder we need to create a subfolder called `fit/` that will be used to store the results. A short description of each code is as follows:
+
+1. `Optimize`: this code is responsible for performing the fit. An example of the usage of this code is:
+    ```
+    ./Optimize 1 ../../config/MAPFF10_210301_SIA_SIDIS_7fl_pos_woSLDc.yaml ../../data/ fit/
+    ```
+    The first argument indicates the Monte Carlo replica index, the second points to the input card containing the main parameters of the fit as well as the data sets to be fitted (see [here](config/MAPFF10_210301_SIA_SIDIS_7fl_pos_woSLDc.yaml) for a commented example and [here](data/README.md) for additional information concerning the data sets), the third points to the folder where the data files are contained, and the last argument is the folder where the results of the fit will be dumped. This code produces in the folder `fit/` a file called `BestParameters.yaml` that contains the best fit parameters of the NN along with some additional information such as the training, validation, and global χ<sup>2</sup>'s. In addition, this code will place in the `fit/` folder two additional subfolders, `log/` and `data/`, containing respectively the log file of the fit and the data files for the fitted experimental sets. If a new fit with a different Monte Carlo replica index is run specifying the `fit/` as a destination for the results, the best fit parameters of this new fit will be appended to the `BestParameters.yaml` file and a new log file will be created in the `fit/log/` subfolder. Notice that Monte Carlo replica indices equal or larger than one correspond to actual random fluctuations of the central values of the experimental data, while the index 0 corresponds to a fit to the central values, i.e. no fluctuations are performed. If the code `Optimize` is run without any arugments it will prompt a short usage description.
+
+2. `LHAPDFGrid`: this code produces an LHAPDF grid for a given fit. In order to produce a grid for the fit in the `fit/` folder, the syntax is:
+    ```
+    ./LHAPDFGrid fit/
+    ```
+    The produced grid can be found in the `fit/` folder under the name `LHAPDFSet` and corresponds to positive pion FFs. This set will eventually be used for analysing the results. It possible to customise the output by providing the script with additional options. Specifically, it possible to produce a grid for negative as well as for the sum of positive and negative pion FFs, to change the default name, and to specificy the number of replicas to be produced. The last option is applicable only when more fits have been run in the `fit/` folder and the number of user-provided replicas does not exceed the number of fits. For example, assuming to have performed 120 fits, the following:
+    ```
+    ./LHAPDFGrid fit/ PIm MySetForPim 100
+    ```
+    will produce a set named `MySetForPim` for negative pions and with 101 replicas where the zero-replica is the average over the following 100. Similarly, the following:
+    ```
+    ./LHAPDFGrid fit/ PIp   MySetForPip   100
+    ./LHAPDFGrid fit/ PIsum MySetForPisum 100
+    ```
+    will respectively produce a grid for positive pions (default) and for the sum of positive and negative pions. In addition, the `LHAPDFGrid` code sorts the replicas in the global χ<sup>2</sup> from the smallest to the largest. Therefore, the resulting set will containg the 100 replicas out of 120 with best global χ<sup>2</sup>'s. Also in this case, if the code `LHAPDFGrid` is run without any arugments it will prompt a short usage description.
+
+3. `ComputeChi2s`: as the name says, the code computes the χ<sup>2</sup>'s using the fit results. The syntax is:
+    ```
+    ./ComputeChi2s fit/
+    ```
+    This code relies on the presence of an LHAPDF grid in the fit folder named `LHAPDFSet` and will result in the creation of the file `fit/Chi2s.yaml` containing the χ<sup>2</sup> for the single experiments included in the fit. It is also possible to change the name of the FF set to be used to compute the χ<sup>2</sup>'s. For example:
+    ```
+    ./ComputeChi2s fit/ MySetForPim
+    ```
+    will compute the χ<sup>2</sup>'s using the `MySetForPim` set that has to be either in the `fit/` folder or in the LHAPDF data directory (that can be retrieved by running the command `lhapdf-config --datadir` from shell).
+
+4. `Predictions`: this code computes the predictions for all the points included in the fit. It is used as:
+    ```
+    ./Predictions fit/
+    ```
+    Also this code relies on the presence of an LHAPDF grid in the fit folder named `LHAPDFSet` and will produce the file `fit/Predictions.yaml`. Again, it is possible to use a different name for the FF set to be used to compute the χ<sup>2</sup>'s. For example:
+    ```
+    ./Predictions fit/ MySetForPim
+    ```
+    will compute the predictions using the `MySetForPim` set that has to be either in the `fit/` folder or in the LHAPDF data directory.
+
+The results produced by the codes described above can finally be visualised by copying  into the `fit/` folder and running the template `jupyter` notebook [`AnalysePredictions.ipynb`](analysis/AnalysePredictions.ipynb) that is in the `analysis/` folder. This is exactly how the fit of pion FFs documented in the reference below has been obtained and any user should be able to reproduce it by following the steps above. For reference, we have linked the folder of the baseline fit [here](Results/MAPFF10NLOPIp) along with the corresponding `jupyter` [notebook](Results/MAPFF10NLOPIp/AnalysePredictions.ipynb).
+
+## Reference
+
+If you use this code you might want to refer to and cite the following reference:
+
+- Rabah Abdul Khalek, Valerio Bertone, Emanuele R. Nocera, "A determination of unpolarised pion framentation functions using semi-inclusive deep-inelating-scattering data: MAPFF1.0", arXiv:xxxx.xxxxx
+
+## Contacts
+
+For additional information or questions, contact us using the email adresses below:
+
+- Rabah Abdul Khalek: rabah.khalek@gmail.com
+- Valerio Bertone: valerio.bertone@cern.ch
+- Emanuele R. Nocera: enocera@ed.ac.uk