From ae9125803700f6b5589c8de362f0005cc657f70e Mon Sep 17 00:00:00 2001 From: Luke Pickering Date: Mon, 7 Sep 2015 18:01:48 +0100 Subject: [PATCH] Adds in-line documentation and doxygen config file to generate autodocs. - Improves documentation in throughout the source. - Adds dox/GiBUUToStdHep.dox.cfg to build auto docs from source. - built by `make docs' or `make latex_docs'. --- GiBUUToStdHep/GiBUUToStdHep.cxx | 65 +- GiBUUToStdHep/GiBUUToStdHep_Utils.hxx | 80 +- GiBUUToStdHep/GiRooTracker.cxx | 10 +- GiBUUToStdHep/GiRooTracker.hxx | 35 +- GiBUUToStdHep/dox/GiBUUToStdHep.dox.cfg | 1519 +++++++++++++++++++++++ GiBUUToStdHep/makefile | 8 + 6 files changed, 1687 insertions(+), 30 deletions(-) create mode 100644 GiBUUToStdHep/dox/GiBUUToStdHep.dox.cfg diff --git a/GiBUUToStdHep/GiBUUToStdHep.cxx b/GiBUUToStdHep/GiBUUToStdHep.cxx index b7df972..9aee91c 100644 --- a/GiBUUToStdHep/GiBUUToStdHep.cxx +++ b/GiBUUToStdHep/GiBUUToStdHep.cxx @@ -10,21 +10,46 @@ #include "GiRooTracker.hxx" -namespace { +///Options relevant to the GiBUUToStdHep.exe executable. +namespace GiBUUToStdHepOpts { + +///The location of the input FinalEvents.dat file which was produced by GiBUU. std::string InpFName; +///\brief The neutrino species PDG. +/// +///\note Set by +/// `GiBUUToStdHep.exe ... -u xx ...' +/// Required. int nuType; +///\brief The target nuclei nucleon number, A. +/// +///\note Set by +/// `GiBUUToStdHep.exe ... -a xx ...' +/// Required. int TargetA; +///\brief The target nuclei proton number, Z. +/// +///\note Set by +/// `GiBUUToStdHep.exe ... -z xx ...' +/// Required. int TargetZ; +///\brief The maximum number of input entries to process. +/// +///\note Set by +/// `GiBUUToStdHep.exe ... -n xx ...' long MaxEntries; - +///\brief The the debugging verbosity. From 0 (quiet) --- 4 (verbose). +/// +///\note Set by +/// `GiBUUToStdHep.exe ... -v xx ...' int Verbosity = 0; } int GiBUUToStdHep(){ - std::ifstream ifs(InpFName); + std::ifstream ifs(GiBUUToStdHepOpts::InpFName); std::string line; long ctr = 0; @@ -63,7 +88,7 @@ int GiBUUToStdHep(){ isHOREv = false; } if(!(EvNum%1000)){ std::cout << "On Ev: " << EvNum << std::endl; } - if(MaxEntries == EvNum){ + if(GiBUUToStdHepOpts::MaxEntries == EvNum){ std::cout << "Finishing after " << EvNum << " entries." << std::endl; break; } @@ -71,7 +96,7 @@ int GiBUUToStdHep(){ outRooTracker->EvtNum = EvNum; //neutrino - outRooTracker->StdHepPdg[0] = nuType; + outRooTracker->StdHepPdg[0] = GiBUUToStdHepOpts::nuType; outRooTracker->StdHepStatus[0] = -1; outRooTracker->StdHepP4[0][GiRooTracker::kStdHepIdxPx] = 0; outRooTracker->StdHepP4[0][GiRooTracker::kStdHepIdxPy] = 0; @@ -79,12 +104,12 @@ int GiBUUToStdHep(){ outRooTracker->StdHepP4[0][GiRooTracker::kStdHepIdxE] = Enu; //target - outRooTracker->StdHepPdg[1] = GiBUUUtils::MakeNuclearPDG(TargetZ,TargetA); + outRooTracker->StdHepPdg[1] = GiBUUUtils::MakeNuclearPDG(GiBUUToStdHepOpts::TargetZ,GiBUUToStdHepOpts::TargetA); outRooTracker->StdHepStatus[1] = -1; outRooTracker->StdHepP4[1][GiRooTracker::kStdHepIdxPx] = 0; outRooTracker->StdHepP4[1][GiRooTracker::kStdHepIdxPy] = 0; outRooTracker->StdHepP4[1][GiRooTracker::kStdHepIdxPz] = 0; - outRooTracker->StdHepP4[1][GiRooTracker::kStdHepIdxE] = TargetA; + outRooTracker->StdHepP4[1][GiRooTracker::kStdHepIdxE] = GiBUUToStdHepOpts::TargetA; outRooTracker->StdHepN = 2; LastEvNum = EvNum; @@ -115,14 +140,14 @@ int GiBUUToStdHep(){ // << outRooTracker->GiBUU2NeutCode << std::endl; } - if(Verbosity>=1 && !outRooTracker->GiBUU2NeutCode){ + if(GiBUUToStdHepOpts::Verbosity>=1 && !outRooTracker->GiBUU2NeutCode){ // std::cout << "[WARN]: Missed a GiBUU reaction code: " << Prodid // << std::endl; } outRooTracker->StdHepN++; - if(Verbosity && (outRooTracker->StdHepPdg[outRooTracker->StdHepN-1]==0)){ + if(GiBUUToStdHepOpts::Verbosity && (outRooTracker->StdHepPdg[outRooTracker->StdHepN-1]==0)){ std::cout << "[WARN] PDG == 0\n\t" << line << std::endl; std::cout << "Copy: " << Run << " " << EvNum<< " " << ID << " " << Charge << " " << PerWeight << " " << Pos1 << " " << @@ -131,7 +156,7 @@ int GiBUUToStdHep(){ << std::endl; } - if(Verbosity>2){ + if(GiBUUToStdHepOpts::Verbosity>2){ std::cout << "Line: " << line << std::endl; std::cout << "Copy: " << Run << " " << EvNum<< " " << ID << " " << Charge << " " << PerWeight << " " << Pos1 << " " << @@ -160,7 +185,7 @@ void SetOpts(){ CLIUtils::OptSpec.emplace_back("-i", "--input-file", true, [&] (std::string const &opt) -> bool { std::cout << "\tReading GiBUU file : " << opt << std::endl; - InpFName = opt; + GiBUUToStdHepOpts::InpFName = opt; return true; }, true,[](){},""); @@ -169,7 +194,7 @@ void SetOpts(){ int vbhold; if(GiBUUUtils::str2int(vbhold,opt.c_str()) == GiBUUUtils::STRINT_SUCCESS){ std::cout << "Nu PDG: " << vbhold << std::endl; - nuType = vbhold; + GiBUUToStdHepOpts::nuType = vbhold; return true; } return false; @@ -180,7 +205,7 @@ void SetOpts(){ int vbhold; if(GiBUUUtils::str2int(vbhold,opt.c_str()) == GiBUUUtils::STRINT_SUCCESS){ std::cout << "Target A: " << vbhold << std::endl; - TargetA = vbhold; + GiBUUToStdHepOpts::TargetA = vbhold; return true; } return false; @@ -191,35 +216,35 @@ void SetOpts(){ int vbhold; if(GiBUUUtils::str2int(vbhold,opt.c_str()) == GiBUUUtils::STRINT_SUCCESS){ std::cout << "Target Z: " << vbhold << std::endl; - TargetZ = vbhold; + GiBUUToStdHepOpts::TargetZ = vbhold; return true; } return false; }, true,[](){},""); - CLIUtils::OptSpec.emplace_back("-v", "--verbosity", true, + CLIUtils::OptSpec.emplace_back("-v", "--GiBUUToStdHepOpts::verbosity", true, [&] (std::string const &opt) -> bool { int vbhold; if(GiBUUUtils::str2int(vbhold,opt.c_str()) == GiBUUUtils::STRINT_SUCCESS){ - std::cout << "Verbosity: " << vbhold << std::endl; - Verbosity = vbhold; + std::cout << "GiBUUToStdHepOpts::Verbosity: " << vbhold << std::endl; + GiBUUToStdHepOpts::Verbosity = vbhold; return true; } return false; }, false, - [&](){Verbosity = 0;}, "<0-4>{default==0}"); + [&](){GiBUUToStdHepOpts::Verbosity = 0;}, "<0-4>{default==0}"); CLIUtils::OptSpec.emplace_back("-n", "--nevs", true, [&] (std::string const &opt) -> bool { int vbhold; if(GiBUUUtils::str2int(vbhold,opt.c_str()) == GiBUUUtils::STRINT_SUCCESS){ std::cout << "Number of events: " << vbhold << std::endl; - MaxEntries = vbhold; + GiBUUToStdHepOpts::MaxEntries = vbhold; return true; } return false; }, false, - [&](){MaxEntries = -1;}, ": means all]> [default==-1]"); + [&](){GiBUUToStdHepOpts::MaxEntries = -1;}, ": means all]> [default==-1]"); } int main(int argc, char const *argv[]){ diff --git a/GiBUUToStdHep/GiBUUToStdHep_Utils.hxx b/GiBUUToStdHep/GiBUUToStdHep_Utils.hxx index 3b714d5..c8271dc 100644 --- a/GiBUUToStdHep/GiBUUToStdHep_Utils.hxx +++ b/GiBUUToStdHep/GiBUUToStdHep_Utils.hxx @@ -12,25 +12,28 @@ #include #include +///Utilities which may be helpful for processing GiBUU specific output. namespace GiBUUUtils { +///Returns the long-from PDG code for a nuclei with a given Z and A. long MakeNuclearPDG(int Z, int A); +///Return codes for GiBUUUtils::str2int enum STR2INT_ERROR { STRINT_SUCCESS, STRINT_OVERFLOW, STRINT_UNDERFLOW, STRINT_INCONVERTIBLE }; ///Converts a string to a long, checking for errors. -///See STR2INT_ERROR for error codes. STR2INT_ERROR str2int (long &i, char const *s, int base=10); ///Converts a string to a int, checking for errors. -///See STR2INT_ERROR for error codes. STR2INT_ERROR str2int (int &i, char const *s, int base=10); +///Converts an int to a std::string through std::stringstream. std::string int2str(int i); +///Sets the first N values of a numeric array-like pointer to 0. template void ClearPointer(T * &arr, size_t N){ for(size_t i = 0; i < N; ++i){ @@ -38,6 +41,7 @@ void ClearPointer(T * &arr, size_t N){ } } +///Clears a 2D C++ fixed size array. template void ClearArray2D(T (&arr)[N][M]){ for(size_t i = 0; i < N; ++i){ @@ -47,50 +51,110 @@ void ClearArray2D(T (&arr)[N][M]){ } } +///\brief Converts a GiBUU particle code, with associated particle EM charge +///information to a PDG code. +/// +/// From https://gibuu.hepforge.org/trac/wiki/ParticleIDs +///\note Returns 0 when encountering an unknown particle. +///Current codes converted: +/// - GiBUU : PDG +/// - 1 : p=2212, n=2112 +/// - 101 : pi+=211, pi0=111, pi-=-211 +/// - 901 : 11 +/// - 902 : 13 +/// - 911 : 12 +/// - 912 : 14 +/// - 999 : 22 +/// - 32 : 3122 +/// - 33 : 3222, 3212, 3112 +/// - 110 : K+=321, K0=311 int GiBUUToPDG(int GiBUUCode, double GiBUUCharge); +///\brief Converts a GiBUU interaction code to the corresponding NEUT code +///where possible. +/// +///Sometimes the NEUT code is dependent on the particle produced in the intial +///interaction. +///\note Current codes converted: +/// - 1 = QE +/// - 2-31 = res (specific number represents GiBUU particle id for resonance) +/// - 32,33 = 1pi +/// - 34 = DIS +/// - 35,36 = 2p2h +/// - 37 = 2pi +/// +///From https://gibuu.hepforge.org/trac/wiki/LesHouches int GiBUU2NeutReacCode(int GiBUUCode, int PDG); } +///Contains types and functions for adding CLI options. namespace CLIUtils { +///\brief Used to describe a CLI option. struct Option { + ///Short name for the option. + /// + ///For example `-c'. std::string ShortName; + ///Longer, alternative name for the option. + /// + ///For example `-config_file' std::string LongName; + /// std::string ValueIdent; + ///Whether an option takes a value or its presence denotes a switch. bool HasVal; + ///Whether an option is required. + /// + ///\note In this case it must take a value. bool Required; + ///Whether this option has been used. bool Used; + ///The function to call when this option is encountered. + /// + ///The value, if present is pass in to the callback. + ///\note As default arguments are not available for annonymous functions this + /// version of the callback is used for options which do not take a value. + /// In this case opt is the empty string. std::function CallBack; + ///The function to call if this option has not been 'Used'. std::function Default; + ///Default constructor; will not produce a useful Option. Option(); + ///Constructor to make a useable Option. Option(std::string shortname,std::string longname, bool hasval, std::function callback, bool required=false, std::function def=[](){}, std::string valString="Value"); + ///Checks if the given string corresponds to this option. bool IsOpt(std::string const &optname) const; friend std::ostream& operator<<(std::ostream& os, Option const &opt); }; +///Interface to adding CLI args from the entry point declaration to this module. void AddArguments(int argc, char const * argv[]); +///\brief Processes arguments added via AddArguments through options in +///CLIUtils::OptSpec. bool GetOpts(); +///Get the value of the i'th argument. std::string GetArg(size_t i); +///Get the number of arguments. size_t GetNArg(); +///The vector of added CLI options. +/// +///Use +/// CLIUtils::OptSpec.push_back(Option(...)); +///to add options. extern std::vector