duanebyer / sidis

Event generator for polarized SIDIS with radiative corrections.

SIDIS-RC EvGen

This is an event generator for polarized semi-inclusive deep inelastic scattering (SIDIS) with QED radiative corrections, following closely work done in [1]. The project is divided into a library component sidis for calculating SIDIS cross-sections, and a binary component sidisgen for generating events.

A detailed description of the generator can be found on the arxiv.

Quick start

Generator

The sidisgen generator uses a parameter file. The allowed options are listed by sidisgen --help. As an example:

mc.num_events        10000
file.gen             gen.root
file.event           event.root
phys.sf_set          prokudin
phys.rc_method       approx
phys.soft_threshold  0.01
phys.mass_threshold  1.073249081
setup.beam           e
setup.target         p
setup.hadron         pi+
setup.beam_energy    10.6
setup.beam_pol       0
setup.target_pol     0 0 0

Then, initialize a FOAM to approximate the differential cross-section in the specified kinematic region.

sidisgen --initialize <param-file>

Finally, use the FOAM for Monte-Carlo event generation.

sidisgen --generate <param-file>

To process the resulting ROOT file, see examples/process_events.cpp.

Library

Many demonstrations of the different features of the sidis library can be found in the examples folder. To get started quickly:

#include <iostream>
#include <sidis/sidis.hpp>
#include <sidis/sf_set/prokudin.hpp>

sidis::Real const PI = sidis::PI;
sidis::Real const M_TH = sidis::MASS_P + sidis::MASS_PI_0;

int main() {
	sidis::part::Particles particles(
		sidis::part::Nucleus::P,   // Target nucleus.
		sidis::part::Lepton::E,    // Beam lepton.
		sidis::part::Hadron::PI_P, // Leading hadron.
		M_TH                       // Threshold mass of undetected part.
	);
	sidis::Real S = 2. * 10.6 * particles.M; // Kinematic variable `S = 2 p k1`.
	sidis::kin::PhaseSpace phase_space {
		0.2,      // Bjorken x.
		0.9,      // Bjorken y.
		0.3,      // Bjorken z.
		2.,       // Transverse momentum of hadron, squared.
		0.5 * PI, // Azimuthal angle of hadron.
		0.,       // Azimuthal angle of transverse target polarization.
	};
	sidis::kin::Kinematics kin(particles, S, phase_space);
	sidis::Real beam_pol = 0.;
	sidis::math::Vec3 target_pol(0., 0., 0.);
	// Compute structure functions with WW-type approximation.
	sidis::sf::set::ProkudinSfSet sf;
	sidis::Real born_xs = sidis::xs::born(kin, sf, beam_pol, target_pol);
	std::cout << "Born unpolarized cross-section is " << born_xs << std::endl;
	return 0;
}

Build

For building the generator, ROOT must be installed on your system. For building the documentation, Doxygen must be installed. For building the tests, Catch2 must be installed.

# Clone the project including submodules.
git clone https://github.com/duanebyer/sidis.git
cd sidis
git submodule init
git submodule update
# Make a build directory.
mkdir build
cd build
# Configure the build.
cmake -DCMAKE_BUILD_TYPE=Release ..
# Build.
make
# Optionally install the library and binary files to your system. Use
# `CMAKE_INSTALL_PREFIX` during the configure to choose the install location.
make install

The following CMake configuration options may be of use:

• Sidis_REAL_TYPE: The floating point type to use for all cross-section calculations. Only the standard C++ floating point types float, double, and long double are supported.
• Sidis_BUILD_TESTS: Whether to build the tests.
• Sidis_BUILD_EXAMPLES: Whether to build the examples.
• Sidis_BUILD_DOXYGEN: Whether to build the Doxygen documentation.
• Sidis_BUILD_APPS: Whether to build the sidisgen binary.
• Sidis_ENABLE_IPO: Whether to build with interprocedural optimization.

Acknowledgements

This software makes use of the following libraries:

• WW-SIDIS: Structure functions for proton using WW-type approximation [2].
• mstwpdf: Parton distribution functions for proton [3].
• ROOT: Plotting and data analysis.
• FOAM: Monte-Carlo event generation using spatial partitioning.
• cubature: Multi-dimensional numerical integration.
• GSL: Multi-dimensional Monte-Carlo integration.

References

[1] I. Akushevich and A. Ilyichev, 2019. Lowest order QED radiative effects in polarized SIDIS. Phys. Rev. D 100(3), 033005.

[2] S. Bastami, H. Avakian, A. V. Efremov, A. Kotzinian, B. U. Musch, B. Parsamyan, A. Prokudin, M. Schlegel, P. Schweitzer. Semi-inclusive deep- inelastic scattering in Wandzura-Wilczek-type approximation. J. High Energy Phys. 1906(2019), 007.

[3] A. D. Martin, W. J. Stirling, R. S. Thorne, G. Watt. Parton distributions for the LHC. Eur. Phys. J. C. 63(2009), 189-285.

sidis's Issues

Exclusive structure functions

The exclusive contribution to the cross section is not currently included. We need support for exclusive structure functions to move forward on this.

• Kinematics for exclusive events.
• Cuts for exclusive events, and extend radiative cuts to work correctly on exclusive events.
• Structure function interface ExclusiveSfSet.
• Cross section calculations using the exclusive structure functions.
• Generators for the 8-D exclusive phase space.
• Parameters for MC generation of exclusive events.

Don't export "extra" headers as part of public interface

The headers within the "sidis/extra" folder should be kept internal to the project only.

• When installing libsidis, they should not be installed.
• "sidis/extra/exception.hpp" should be moved out of the extra folder.
• Interpolation capabilities should be provided through specialized functions for creating LHAPDF, TMDLib, or CSV grids for use in user-defined TMDs/Sfs.

Running QED coupling constant

The QED coupling alpha_QED should run with Q, right now it's always kept constant.

Select kinematic variables to log to event generation output file

The user should be able to choose which kinematic variables get logged to the event generation file. Right now, only the six SIDIS phase space variables (x, y, z, pt^2, phi_h, phi) are logged. The parameter file should support a selection of kinematic variables to log. E.x.

out.file.vars = x,y,Q_sq,W_sq

num_events[4] miss match

The num_events[4] in stats does not match with what it is supposed to be as in paper

LHAPDF and TMDlib support

We should provide easy integration with external libraries for TMDs and PDFs, such as LHAPDF library and TMDlib.

• Should be enabled by a CMake configuration variable to avoid a required dependency.
• For libsidis, add new implementation of TmdSet that can load TMDs/PDFs from the system.
• For sidisgen, it should be easy to specify a desired set of TMDs and PDFs in the parameter file.
• Should be combine-able with WW-type and Gaussian approximations.

Additional targets (neutron, nuclear targets)

We should support additional targets, such as neutron and nuclear targets. Right now, users can define their own structure functions for these situations, but it would be nice if there was a simple default option.

• Neutron structure functions can be estimated from proton structure functions by interchanging valence up and down quarks.
• Nuclear structure functions can be estimated by combining proton and neutron structure functions together.
• Fermi motion and other nuclear effects should be considered.

Check that event indices are consistent everywhere

The convention is:

• 0 for total
• 1 for non-radiative
• 2 for radiative
• 3 for exclusive

This might not be followed by all parts of the code, especially the stats output in the TTree, so it should be double-checked.

Factor out certain parts of libsidis into their own libraries

We should consider whether certain libraries should be factored out of libsidis/sidisgen.

• 3,4-vectors and transformations
• Interpolation
• Parameter system
• Monte-Carlo statistics class (Stats)

Fix sf_out option to not depend on implementation-defined behaviour

The sf_out option depends on there being no padding in the SfLP struct, which could change depending on the compiler.

Asymmetry calculations

The asym namespace lets UT asymmetries be calculated efficiently. What about other kinds, like LT, LL, and so on? These should also have efficient and convenient implementations.

Change TMDSet API to reduce redundant calculations

Different structure functions (even with different polarization) will share some common TMDs between them. For Gaussian-approximated structure functions, this means that TMDs are redundantly calculated several times when computing a single cross-section.

• Refactor SfSet so that there are special virtual methods for calculating polarized groups of structure functions (#19).
• Make TMDs return array of flavours, instead of each flavour being calculated by a different call.
• Allow TMD results to be cached, by polarization.
• Cached TMD results used by GaussianSfSet to calculate groups of structure functions more efficiently.

Linking errors when compiling with Clang on Linux

The CMake configuration is broken for clang on linux, there are linking issues with libm and LTO.

Collinear factorization and matching

Right now, only the TMD factorization is supported. For regions of high qT/Q, it is necessary to use the collinear factorization. It would also be useful to provide matching between TMD factorization and collinear factorization for intermediate qT/Q.

• Add new interfaces (ex. CollinearPDFSet) to represent collinear PDFs/FFs.
• Write a new implementation of SfSet (ex. CollinearSfSet) that can calculate structure functions from collinear factorizations.
• Write a new implementation of SfSet that can combine a TMD factorization (TmdSfSet) with a collinear factorization (CollinearSfSet) using a matching procedure for intermediate qT/Q.

Multiple event file formats

Only ROOT file formats are supported by sidisgen currently. Other MC file formats, like HepMC, are sometimes more useful.

• Abstract over output file format.
• HepMC support.
• Plain text support.
• Make ROOT an optional dependency for sidisgen, use CMake configuration variable to enable.

Better vacuum hadron polarization calculation

The vacuum hadron polarization calculation is a bit outdated. It should be replaced with a more modern estimate.

Cross section calculation from weight norm in examples

The cross section calculation in example/process_events.cpp is weight*norm. Should be weight/norm

Multiple possible MC generator engines

Currently, a modified version of FOAM is used for the underlying Monte-Carlo generator in sidisgen. Alternate algorithms like VEGAS might perform better in certain situations. It should be possible for the user to choose which MC generator they want to use. The code almost supports this already, it just needs a little bit more work to get all the way there.

• Abstract the generator interface so that the underlying MC engine can be swapped in/out.
• Add support for three generator engines: original FOAM, modified FOAM, and VEGAS.
• Alternatively, if VEGAS just outperforms FOAM in all situations (testing needed), we'll just stick to VEGAS.

Improve numerical integration for TMDs

Currently, if Gaussian approximation is not used, the TMDs are convoluted numerically in 2D to calculate the structure functions. They are integrated out to an arbitrary upper bound. This can be improved in a few ways.

• Use a 1D convolution integration when the TMDs are spherically symmetric (which is the usual case).
• Use a change of variables so that the TMDs can be integrated all the way to infinity, instead of to a fixed upper bound.
• Relatedly, use a change of variables that estimates the TMDs as Gaussian for the numerical integration. This should substantially improve the performance of the TMD integration.
• Experiment with the numerical integration method. Right now cubature is used (I think?), but other choices might work better.

make install doesn't install MSTWPDF lib when needed

The make install command doesn't provide libmstwpdf, but it should be included for linking with libsidis.

Move structure function parser from sidisgen to libsidis

It would be useful for users of libsidis to be able to construct a structure function from a simple string description. The code to do this could be moved from sidisgen where it lives currently, to libsidis. Then call something like:

std::unique_ptr<sf::SfSet> sf = sf::create("leading prokudin");

The only issue is that sidisgen also supports loading ROOT libs to provide structure functions. This could be implemented as a fallback, in case sf::create were to fail.

Refactor the parameter system

It's very difficult to make changes to the parameter file format. A large refactor of the code for the parameter system is underway, that should make adding/removing new parameters in the future much easier.

• Check compatibility of parameters between initialization stage with generation stage.
• Use parameters to check whether two event files can be merged.
• Add hash of generator engine into the parameter files, to ensure correctness during merging and event generation.
• Test thoroughly--this is a big change.

Remove cog code generation

The code generation with cog makes the source much harder to read. It's also an awkward part of the build.

• Remove code generation from polarized structs (#19).
• Remove code generation from version headers
• Remove code generation from number-type header.