Page MenuHomeHEPForge
Files F8723850

No OneTemporary
Actions

View Options

diff --git a/doc/doxygen/mainpage.dox b/doc/doxygen/mainpage.dox
index 8e754d3..2d83a65 100644
--- a/doc/doxygen/mainpage.dox
+++ b/doc/doxygen/mainpage.dox
@@ -1,44 +1,225 @@
namespace HEJ { // so that doxygen links names in this namespace
/**
* @mainpage
*
* @section intro Introduction
*
* HEJ 2 is a library for all-order resummation of high-energy
* logarithms. It includes a program to add resummation to fixed-order
* events. User documentation for the program can be found <a
* href="TODO">TODO: here</a>. This documentation is instead aimed at users
* of the library itself.
*
* @section overview Overview
*
* The main functionality is contained in the HEJ namespace. Particles
* are defined via the Particle struct, which consists of the particle
* four-momentum and its identifier according to the <a
* href="http://pdg.lbl.gov/2017/reviews/rpp2017-rev-monte-carlo-numbering.pdf">
* PDG Monte Carlo numbering scheme </a>. Given a number of incoming and
* outgoing particles, the square of the resummation matrix element can
* be calculated with the help of the MatrixElement class.
*
* The EventReweighter class adds resummation to existing fixed-order
* events. Both fixed-order and resummation events are objects of the
* Event class, which are created from UnclusteredEvent objects with the
* help of a <a
* href="http://fastjet.fr/repo/doxygen-3.3.1/classfastjet_1_1JetDefinition.html">jet
* definition according to the fastjet</a> library. UnclusteredEvent
* objects can be assembled manually or converted from input events in
* the LesHouches standard, read from file with a LHEF::Reader.
*
* Events can be saved with one of the EventWriter classes. Currently,
* there is support for the Les Houches event file format with the
* LesHouchesWriter class. If HEJ 2 was installed with HepMC 2 or 3
* support, the respective format is available through the HepMCWriter
* class.
*
* Further classes of interest are the interfaces to the Mixmax and
* Ranlux64 random number generators, the PDF class to interact with <a
* href="https://lhapdf.hepforge.org/"> LHAPDF </a> and the ScaleGenerator
* and ScaleConfig classes to calculate renormalisation and factorisation
* scales for a given Event.
+ *
+ * @section example Example
+ *
+ * As an example, we show a toy program that computes the square of a
+ * matrix element in the HEJ approximation for a single event. First, we
+ * include the necessary header files:
+ * @code{.cpp}
+ * #include "HEJ/Event.hh"
+ * #include "HEJ/MatrixElement.hh"
+ * @endcode
+ * We then specify the incoming and outgoing particles. A particle
+ * has a type and four-momentum \f$(p_x, p_y, p_z, E)\f$. For instance, an
+ * incoming gluon could be defined as
+ * @code{.cpp}
+ * fastjet::PseudoJet momentum{0, 0, 308., 308.};
+ * HEJ::Particle gluon_in{HEJ::ParticleID::gluon, momentum};
+ * @endcode
+ * We collect all incoming and outgoing particles in a partonic event. Here
+ * is an example for a partonic \f$gu \to gghu\f$ event:
+ * @code{.cpp}
+ * HEJ::UnclusteredEvent partonic_event;
+ *
+ * // incoming particles
+ * partonic_event.incoming[0] = {
+ * HEJ::ParticleID::gluon,
+ * { 0., 0., 308., 308.}
+ * };
+ * partonic_event.incoming[1] = {
+ * HEJ::ParticleID::up,
+ * { 0., 0.,-164., 164.}
+ * };
+ * // outgoing particles
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::higgs,
+ * { 98., 82., 14., 180.}
+ * });
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::up,
+ * { 68.,-54., 36., 94.}
+ * });
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::gluon,
+ * {-72., 9., 48., 87.}
+ * });
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::gluon,
+ * {-94.,-37., 46., 111.}
+ * });
+ * @endcode
+ * Alternatively, we could read the event from a Les Houches event file,
+ * possibly compressed with gzip. For this, the additional header
+ * files @c HEJ/stream.hh and @c LHEF/LHEF.h have to be
+ * included.
+ * @code{.cpp}
+ * HEJ::istream in{"events.lhe.gz"};
+ * LHEF::Reader reader{in};
+ * reader.readEvent();
+ * HEJ::UnclusteredEvent partonic_event{reader.hepeup};
+ * @endcode
+ *
+ * In this specific example we will later choose a constant value for the
+ * strong coupling, so that the HEJ matrix element does not depend on the
+ * renormalisation scale. However, in a more general scenario, we will want
+ * to set a central scale:
+ * @code{.cpp}
+ * partonic_event.central.mur = 50.;
+ * @endcode
+ * It is possible to add more scales in order to perform scale variation:
+ * @code{.cpp}
+ * partonic_event.variations.resize(2);
+ * partonic_event.variations[0].mur = 25.;
+ * partonic_event.variations[1].mur = 100.;
+ * @endcode
+ *
+ * In the next step, we leverage FastJet to construct an event with
+ * clustered jets. Here, we use antikt jets with R=0.4 and transverse
+ * momenta of at least 30 GeV.
+ * @code{.cpp}
+ * const fastjet::JetDefinition jet_def{
+ * fastjet::JetAlgorithm::antikt_algorithm, 0.4
+ * };
+ * const double min_jet_pt = 30.;
+ * HEJ::Event event{partonic_event, jet_def, min_jet_pt};
+ * @endcode
+ * In order to calculate the Matrix element, we now have to fix the physics
+ * parameters. For the sake of simplicity, we assume an effective coupling
+ * of the Higgs boson to gluons in the limit of an infinite top-quark mass
+ * and a fixed value of $\alpha_s = 0.118$ for the strong coupling.
+ * @code{.cpp}
+ * const auto alpha_s = [](double /* mu_r */) { return 0.118; };
+ * HEJ::MatrixElementConfig ME_config;
+ * // whether to include corrections from the
+ * // evolution of \alpha_s in virtual corrections
+ * ME_config.log_correction = false;
+ * HEJ::MatrixElement ME{alpha_s, ME_config};
+ * @endcode
+ * If QCDLoop is installed, we can also take into account the full loop
+ * effects with finite top and bottom quark masses:
+ * @code{.cpp}
+ * HEJ::MatrixElementConfig ME_config;
+ * ME_config.Higgs_coupling.use_impact_factors = false;
+ * ME_config.Higgs_coupling.mt = 163;
+ * ME_config.Higgs_coupling.include_bottom = true;
+ * ME_config.Higgs_coupling.mb = 2.8;
+ * @endcode
+ * Finally, we can compute and print the square of the matrix element with
+ * @code{.cpp}
+ * std::cout << "HEJ ME: " << ME(event).central << '\n';
+ * @endcode
+ * In the case of scale variation, the weight associated with the scale
+ * @c event.variations[i].mur is @c ME(event).variations[i].
+ *
+ * Collecting the above pieces, we have the following program:
+ * @code{.cpp}
+ * #include "HEJ/Event.hh"
+ * #include "HEJ/MatrixElement.hh"
+ *
+ * int main(){
+ * HEJ::UnclusteredEvent partonic_event;
+ * // incoming particles
+ * partonic_event.incoming[0] = {
+ * HEJ::ParticleID::gluon,
+ * { 0., 0., 308., 308.}
+ * };
+ * partonic_event.incoming[1] = {
+ * HEJ::ParticleID::up,
+ * { 0., 0.,-164., 164.}
+ * };
+ * // outgoing particles
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::higgs,
+ * { 98., 82., 14., 180.}
+ * });
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::up,
+ * { 68.,-54., 36., 94.}
+ * });
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::gluon,
+ * {-72., 9., 48., 87.}
+ * });
+ * partonic_event.outgoing.push_back({
+ * HEJ::ParticleID::gluon,
+ * {-94.,-37., 46., 111.}
+ * });
+ *
+ * const fastjet::JetDefinition jet_def{
+ * fastjet::JetAlgorithm::antikt_algorithm, 0.4
+ * };
+ * const double min_jet_pt = 30.;
+ * HEJ::Event event{partonic_event, jet_def, min_jet_pt};
+ *
+ * const auto alpha_s = [](double /* mu_r */) { return 0.118; };
+ * HEJ::MatrixElementConfig ME_config;
+ * // whether to include corrections from the
+ * // evolution of \alpha_s in virtual corrections
+ * ME_config.log_correction = false;
+ * HEJ::MatrixElement ME{alpha_s, ME_config};
+ *
+ * std::cout
+ * << "HEJ ME: " << ME(event).central
+ * << " = tree * virtual = " << ME.tree(event).central
+ * << " * " << ME.virtual_corrections(event).central
+ * << '\n';
+ * }
+ * @endcode
+ * After saving the above code to a file @c matrix_element.cc, it
+ * can be compiled into an executable @c matrix_element with a
+ * suitable compiler. For example, with @c g++ this can be done
+ * with the command
+ * @code{.sh}
+ * g++ -o matrix_element matrix_element.cc -lHEJ -lfastjet
+ * @endcode
+ * If HEJ or any of the required libraries was installed to a
+ * non-standard location, it may be necessary to explicitly specify the
+ * paths to the required header and library files. This can be done with
+ * the @c HEJ-config executable and similar programs for the
+ * other dependencies:
+ * @code{.sh}
+ * g++ $(fastjet-config --cxxflags) $(HEJ-config --cxxflags) -o matrix_element matrix_element.cc $(HEJ-config --libs) $(fastjet-config --libs)
+ * @endcode
*/
}

File Metadata

Mime Type
text/x-diff
Expires
Mon, Jan 20, 9:48 PM (1 d, 4 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
4212734
Default Alt Text
(8 KB)

Event Timeline