First round of updates

Author: Sebastien Wertz

docs/.gitignore

@@ -0,0 +1,2 @@
+*.pyc
+*.*~

docs/getting-started.md

@@ -40,7 +40,8 @@ The following options are available when configuring the build (when running `cm
    * `-DBOOST_ROOT=(path)`: Use specific Boost version (path to its install directory)
    * `-DTESTS=ON`: Also compile the test executables
    * `-DEXAMPLES=OFF`: Do not compile the example executables
-
+   * `-DPYTHON_BINDINGS=ON|OFF` (`OFF` by default). Builds python bindings for MoMEMta. Requires python and boost::python.
+   * `-DDEBUG_TIMING=ON|OFF` (`OFF` by default). If `ON`, a summary of how long each module ran is printed at the end of the integration. Can be useful to see which module to optimize.
 
 ## Usage: Lua & MoMEMta
 
@@ -50,23 +51,22 @@ Computing weights in your analysis code is then a matter of only a few lines of
 
 ```cpp
 #include <momemta/ConfigurationReader.h>
-#include <momemta/Logging.h>
 #include <momemta/MoMEMta.h>
-#include <momemta/Utils.h>
+#include <momemta/Types.h>
 
 int main(int argc, char** argv) {
 
     ConfigurationReader configuration("tt_fullyleptonic.lua");
     MoMEMta weight(configuration.freeze());
 
-    LorentzVector p3(16.17, -13.79, -3.43, 21.53);
-    LorentzVector p4(-55.79, -111.59, -122.14, 174.66);
-    LorentzVector p5(-18.90, 10.09, -0.60, 21.43);
-    LorentzVector p6(71.39, 96.01, -77.25, 142.50);
+    momemta::Particle electron { "electron", LorentzVector(16.17, -13.79, -3.43, 21.53), -11 };
+    momemta::Particle bjet1 { "bjet1", LorentzVector(-55.79, -111.59, -122.14, 174.66), 5 };
+    momemta::Particle bjet2 { "bjet2", LorentzVector(-18.90, 10.09, -0.60, 21.43), -5 };
+    momemta::Particle muon { "muon", LorentzVector(71.39, 96.01, -77.25, 142.50), 13 };
 
-    std::vector<std::pair<double, double>> weights = weight.computeWeights({p3, p4, p5, p6});
+    std::vector<std::pair<double, double>> weights = weight.computeWeights( { electron, muon, bjet1, bjet2 } );
 
-    std::cout << "Result: " << weights.back().first << " +- " << weights.back().second;
+    std::cout << "Result: " << weights.at(0).first << " +- " << weights.at(0).second;
 
     return 0;
 }
@@ -82,10 +82,10 @@ We ship a few example configuration files, along with short scripts computing a
 ./WW_fullyleptonic.exe
 ```
 
-A set of more comprehensive examples on how to run MoMEMta can be found in our [Tutorials repository](https://github.com/MoMEMta/Tutorials). Each of these examples includes a matrix element generated by our exporter, a ROOT file containing a few events, a Lua configuration file and a small source code showing how to compute weights for the events in the sample.
+A set of more comprehensive examples on how to run MoMEMta can be found in our [Tutorials repository](https://github.com/MoMEMta/Tutorials). Each of these examples includes a matrix element generated by our [exporter](https://github.com/MoMEMta/MoMEMta-MaGMEE) (see below), a ROOT file containing a few events, a Lua configuration file and a small source code showing how to compute weights for the events in the sample.
 
 ## Matrix elements
 
 MoMEMta includes matrix elements for a few processes, but you might soon want to compute weights for other processes. It is possible to include matrix elements for any process by using our [Matrix Element Exporter](https://github.com/MoMEMta/MoMEMta-MaGMEE), a plugin for [MadGraph5_aMC@NLO](https://launchpad.net/mg5amcnlo) (MG5). The plugin takes a leading-order matrix element generated by MG5 and exports it in a format suitable for use in MoMEMta. More information on how to use the plugin and the resulting matrix elements is provided in the plugin’s [README file](https://github.com/MoMEMta/MoMEMta-MaGMEE/blob/master/README.md). 
 
-Support for other matrix element generators is planned for futures releases.
+Support for other matrix element generators is planned for futures releases, however nothing prevents plugging in any code returning the matrix element provided it is wrapped properly for MoMEMta.

docs/in-depth/calling-momemta.md

@@ -1,13 +1,15 @@
 In MoMEMta, the integration is defined by linking modules together in a Lua script. MoMEMta is shipped with a set of modules covering the most common needs and whose parameters, inputs and outputs are documented [here](https://momemta.github.io/MoMEMta/dev/group__modules.html). For more information on how to write the configuration file, see [here](configuration-file.md).
 
-> *A module is just a C++ class deriving from the `Module` virtual class. How to write a new module and make it available for the calculation is described (here).*
+> *A module is just a C++ class deriving from the `Module` virtual class.*
+
+[//]: # ( How to write a new module and make it available for the calculation is described (here). )
 
 Once the configuration file is defined, it can be loaded by MoMEMta’s configuration reader:
 ```cpp
 ConfigurationReader my_reader("relative_path_to_lua_file.lua");
 ```
 
-At this point, the user might wish to modify some parameters defined in the file from the code itself:
+At this point, the user might wish to modify some parameters defined in the file from the code itself (see also [here](configuration-file#parameters)):
 ```cpp
 configuration.getGlobalParameters().set("top_mass", 173.);
 ```
@@ -18,21 +20,26 @@ Configuration my_config = my_reader.freeze();
 MoMEMta weight(my_config);
 ```
 
-> *MoMEMta is instantiated using a `Configuration` object, describing a fixed configuration: parameters cannot be modified at this stage. Parameters can be changed in the ConfigurationReader, and a new `MoMEMta` instance must then be constructed by calling `ConfigurationReader::freeze()` again.*
+> *MoMEMta is instantiated using a `Configuration` object, describing a fixed configuration: parameters cannot be modified at this stage, the execution flow of the computation is fully fixed. Parameters can be changed in the ConfigurationReader, and a new `MoMEMta` instance must then be constructed by calling `ConfigurationReader::freeze()` again.*
 
-The weight can finally be computed by calling the computeWeights() method of the MoMEMta object, passing the observed particles as a set of LorentzVectors:
+The weight can finally be computed by calling the computeWeights() method of the MoMEMta object, passing the observed particles as arguments:
 
 ```cpp
-LorentzVector p1, p2, p3, p4, met;
-std::vector<std::pair<double, double>> weights = weight.computeWeights({p1, p2, p3, p4}, met);
+ROOT::Math::LorentzVector<ROOT::Math::PxPyPzE4D<double>> p1, p2, met;
+momemta::Particle part1 { "part1", p1, 0 };
+momemta::Particle part2 { "part2", p2, 0 };
+std::vector<std::pair<double, double>> weights = weight.computeWeights({part1, part2}, met);
 ```
+> *The `momemta::Particle` type consists of tree parts: a name (string) allowing to identify the particle in the configuration file, a 4-vector object, and a type (int). The type is not used by MoMEMta but can help the user configure the computation. It could be a PDG ID code, or any other code defined by the user.*
+
+> *The MET is an optional argument (defaults to a null vector)*
 
-> *The MET is an optional argument*
+> *MoMEMta provides the useful typedef `LorentzVector` for Lorentz Vectors in the file `momemta/Types.h`*
 
-> *The LorentzVectors are expected to be expressed in the `PxPyPzE<double>` basis*
+> **Note**: MoMEMta checks that your inputs are physical, i.e. have non-negative energy and mass. Due e.g. to machine precision issues, it is possible your inputs have slightly negative masses without you noticing it. However, MoMEMta can produce nonsensical output or even crash in this case (*garbage in, garbage out*). It's up to the user to correct the inputs in those cases.
 
-The function starts the Monte-Carlo integration: the integrand function is called a large number of times, each time passing as input a phase-space point vector (where the length of the vector is the dimensionality of the integrated phase-space) with elements lying between 0 and 1, and returning as output the integrated function evaluated on this point.
+The function `computeWeights()` starts the Monte-Carlo integration: the integrand function is called a large number of times, each time passing as input a phase-space point vector (where the length of the vector is the dimensionality of the integrated phase-space) with elements lying between 0 and 1, and returning as output the integrated function evaluated on this point.
 
-`computeWeights()` returns a vector of pairs (weight, uncertainty) (at the moment, this vector only has one entry) which can then be stored by the user.
+`computeWeights()` returns a vector of pairs (weight, uncertainty). In most cases, this vector will contain only one entry, but MoMEMta allows the possibility to define *vector* integrands, i.e. integrate multi-valued functions, and return a weight and uncertainty for each component.
 
-> *The phase-space points are associated with a weight, given that they are not distributed uniformly in the phase-space, but according to the importance function defined by Vegas. In most use cases this weight is not needed by the user since Cuba automatically takes it into account when computing the integral, however it can still be retrieved through the `cuba::ps_weight` input tag (see [here](configuration-file.md#defaults)).*
+[//]: # (> *The phase-space points are associated with a weight, given that they are not distributed uniformly in the phase-space, but according to the importance function defined by Vegas. In most use cases this weight is not needed by the user since Cuba automatically takes it into account when computing the integral, however it can still be retrieved through the `cuba::ps_weight` input tag (see [here](configuration-file.md#defaults)).*)

docs/in-depth/configuration-file.md

@@ -1,8 +1,9 @@
 # The configuration file
 
-## Configuring modules
+## Configure modules
 
-Declaring a module named `karl` of type `Gaussian` in Lua is simple:
+Different *types* of modules are available on MoMEMta, each designed to perform a specific task. 
+Declaring an instance of a module named `karl` of type `Gaussian` in Lua is simple:
 
 ```
 Gaussian.karl = {}
@@ -23,11 +24,11 @@ Gaussian.friedrich = {
 }
 ```
 
-A **parameter** can be an integer (eg.: `2`), a floating point number, (eg.: `172.5`, `13000.` - note the decimal point *must* be present), a boolean (`true` or `false`) or a string (eg.: `hello`). Parameters might have default values and be optional, or be mandatory.
+A **parameter** is strongly typed and can be an integer (eg.: `2`), a floating point number, (eg.: `172.5`, `13000.` - note the decimal point *must* be present), a boolean (`true` or `false`) or a string (eg.: `hello`). Parameters might have default values and be optional, or be mandatory.
 
 An **input** is set through a so-called "**input tag**" of the form `other_module::its_output[/i]`, where `other_module` is the name of another module responsible for producing the quantity `its_output`, and `/i` has to be used when the produced quantity in question is a vector and only a specific entry of that vector is needed as input. 
 
-Some modules expect **vectors** of input tags, where the order of the entries may or nor matter. Vectors in Lua are easily declared:
+Some modules expect **vectors** of input tags, where the order of the entries may or may not matter. Vectors in Lua are easily declared:
 
 ```Lua
 -- Take first and third entry of vector output `output` of module `that_module`
@@ -42,30 +43,108 @@ my_inputs = { temp_vector[1], temp_vector[3] }
 ```
 **NB**: The indexing of Lua vectors or input tags starts at **1, not 0**.
 
-When declared, a module tells MoMEMta how many dimensions it adds to the integration (for instance, adding a transfer function on the energy of a jet means integrating over the energy of the corresponding parton). If a module adds a dimension, it also means it requires a component of the phase-space point to be specified as input (see below). MoMEMta keeps track of the total number of dimensions needed for the integration. 
+The use of some modules requires adding a dimension to the volume that is being integrated over. In other words, those modules need a component of the phase-space point to be specified as input. This is done using the function `add_dimension()`, which returns an input tag linking to a component of the phase-space point, and notifies MoMEMta to add an integration dimension.
 
-The order in which the modules are declared in the script does not matter: MoMEMta automatically executes the module in an order such that inputs are always well-defined (obviously, circular dependencies are forbidden). By default, modules whose outputs are not used by any other module, and modules whose inputs are not produced by any other modules are not executed.
+The order in which the modules are declared in the script does not matter: MoMEMta automatically executes the modules in an order such that inputs are always well-defined (obviously, circular dependencies are forbidden). By default, modules whose outputs are not used by any other module, and modules whose inputs are not produced by any other modules are not executed.
 
-## Default inputs, outputs and parameters <a name=defaults></a> 
+A full list of modules available out-of-the-box, along with documentation about the modules' inputs, outputs and parameters, is available at MoMEMta's [technical documentation](https://momemta.github.io/MoMEMta/dev/group__modules.html).
 
-Some inputs and outputs are not defined by any module *per se* but are used by MoMEMta to pass and retrieve important quantities:
+## Declare input particles
 
-Inputs:
+Particles passed as input to the `computeWeights()` function (see [Calling MoMEMta](calling-momemta)) can be linked with the modules by registering them in the Lua configuration. For instance, for a particle declared in C++ as `momemta::Particle m_part1 { "part1", p1, 0 }`, one would do:
+```Lua
+local l_part1 = declare_input("part1") -- Pass as argument the name string of m_part1
+```
+The Lua object `l_part1` now contains the input tag needed to access the particle's 4-vector. For instance, defining a transfer function on the energy of `part1` can be done as:
+```Lua
+GaussianTransferFunctionOnEnergy.tf_part1 = {
+  ps_point = add_dimension(), -- A transfer function integrates over a variable (the particle's energy), so we need a new dimension in the integrated volume
+  reco_particle = l_part1.reco_p4, -- Pass the input tag corresponding to the experimentally reconstructed 4-vector of the particle, passed to 'computeWeights()'
+  sigma = 0.10 -- Take 10% resolution on the energy
+}
+```
+Since the transfer function integrates over the particle's energy, it generates new values for its energy. This defines a new, 'parton'-level 4-vector for `part1`, which can now be passed e.g. to a matrix element. In this example, the parton-level 4-vector can be accessed directly through the `tf_part1::output` input tag. It is also possible to register it with the `l_part1` object:
+```Lua
+l_part1.set_gen_p4("tf_part1::output")
+```
+When declaring further modules, instead of using `tf_part1::output`, it is now possible to use `l_part1.gen_p4` to access the parton-level 4-vector, i.e. these are equivalent:
+```Lua
+P4Printer.printer1 = { input = "tf_part1::output" }
+P4Printer.printer2 = { input = l_part1.gen_p4 }
+```
 
-* `input::particles`: Vector of LorentzVectors passed as argument to `computeWeights()`
+Finally, the missing transverse energy 4-vector (passed optionally to `computeWeights()`) can either be accessed directly through the `met::p4` input tag, or declared as a Lua object as above:
+```Lua
+local met = declare_input("met")
+```
 
-* `input::met`: LorentzVector of the observed MET (optional argument to `computeWeights()`)
+## Declare the integrand
 
-* `cuba::ps_points`: Vector of doubles between 0 and 1. Phase-space point, ie. set of random numbers launched by Cuba to perform the integration. The length of the vector is the total number of integration dimensions declared by the modules. Instead of manually specifying the `cuba::ps_points/i` input tags, it is possible to use to `getpspoint()` function (which automatically increases “i” each time it is called).
+When the integration is fully configured, i.e. all the final module defining the integrand value is defined, the integrand has to be registered with MoMEMta to be able to compute the integral. 
+For instance, if the module called `final_module` with output `output` defines the integrand, one has to call:
+```Lua
+integrand("final_module::output")
+```
 
-* `cuba::ps_weight`: (double) Weight associated with the phase-space point
+It is possible in MoMEMta to integrate multi-valued functions (caution: is only efficient if the components of the function are not too different). For two components, the integrand would then be declared as:
+```Lua
+integrand("final_module_1::output", "final_module_2::output")
+```
 
-Outputs:
+## Define parameters <a name="parameters"></a>
 
-* `integrands`: Vector of doubles. This is the value taken to be the integrand, returned to Cuba to compute the integral. Exactly **one** declared module **must** produce this quantity.
+In MoMEMta, once the `ConfigurationReader` has been "frozen" to give a `Configuration` object, it is not possible anymore to modify anything in the integration. However, some parameters can be modified in the `ConfigurationReader` from the C++ code (allowing e.g. to carry out mass scans easily). In order to do that, the parameters have to be put in the `parameters` table in Lua:
+```Lua
+parameters = {
+  my_mass = 173.,
+  my_width = 2.5
+}
+```
+These parameters can then be linked with the modules' parameters using the `parameter()` Lua function:
+```Lua
+BreitWignerGenerator.m_prop = {
+  ps_point = add_dimension(),
+  mass = parameter('my_mass'), -- Access the value through the "parameter" function, allowing it to be modified from the C++ code
+  width = parameter.my_width -- Access the value as a regular Lua table. It will NOT be possible to modify it later on
+}
+```
+Changing `my_mass` from C++ before freezing the configuration is now possible using `ConfigurationReader::getGlobalParameters()`, see [calling momemta](calling-momemta).
 
-Parameters:
+## Configure the integration algorithm
 
-* `cuba`
+The integration algorithm can be configured from within Lua using the `cuba` table, for instance:
+```Lua
+cuba = {
+  integration_algorithm = "divonne", -- default is "vegas"
+  relative_accuracy = 0.01
+}
+```
+Four different integration algorithms are available, and each has several parameters than can be tweaked to adjust the precision and convergence speed of the calculations. 
+For a full list of the available methods and corresponding options, please consult the documentation of the numerical integration library used in MoMEMta: Cuba[^1].
+
+The integration parameters can be changed from the C++ in a manner similar to the parameters in the previous section, using the method `ConfigurationReader::getCubaConfiguration()`.
+
+## Pass arguments to the configuration
+
+Once the `ConfigurationReader` has parsed the Lua configuration file, it is not possible anymore to change the resulting computation flow (the only changes possible are the above parameters). 
+It is however possible to pass arguments from C++ to the Lua script when it is read by the `ConfigurationReader`, to influence its execution. 
+
+Defining the arguments in C++:
+```cpp
+ParameterSet lua_parameters;
+lua_parameters.set("text1", "hello, world!");
+lua_parameters.set("text2", "always look on the bright side of life!");
+lua_parameters.set("question", true);
+ConfigurationReader configuration("example.lua", lua_parameters);
+```
+Makes them available in Lua, i.e.:
+```Lua
+if question then
+  print(test1)
+else
+  print(test2)
+end
+```
+Would print "hello, world!".
 
-* `parameters`
+[^1]: [T. Hahn, *"Cuba - a library for multidimensional numerical integration"*](https://arxiv.org/abs/hep-ph/0404043)