Logging and diagnostics

Logging

Controlling printing
Error messages
Timing

Controlling printing

The following settings are used to control what is printed during initialization and event generations.

flag Print:init (default = on)
If disabled, messages (except for errors) are suppressed during initialization. In order to show only certain types of information, use the Init:showProcesses, Init:showMultipartonInteractions, Init:showChangedSettings, Init:showAllSettings, Init:showChangedParticleData, Init:showChangedResonanceData, Init:showAllParticleData, and Init:showOneParticleData settings.

flag Print:next (default = on)
If disabled, messages (except for errors) are suppressed during event generation. In order show only certain types of information, use the Next:numberCount, Next:numberShowLHA, Next:numberShowInfo, Next:numberShowProcess, and Next:numberShowEvent settings.

flag Print:quiet (default = off)
Can be set on to avoid the printing during program execution, to the largest extent possible. This is equivalent to turning off the three flags above.

Error messages

Error messages are printed through the Logger class. There are five types of error messages:

Abort: An abort message indicates a critical error that might prevent further event generation from taking place. Examples: unable to find particle database; invalid user settings; calling Pythia::next after initialization failed.
Error: An error indicates that something has gone wrong during event generation. When an error occurs in a function, it usually means that function failed to execute. It is possible that the calling function is able to recover, otherwise the event will fail to generate.
Warning: Warning messages indicate an exceptional case that the function is able to recover from. They are usually not a cause for concern, but a large number of warnings could indicate that there is something wrong with your configuration.
Info: Info messages provide information that is not an error. Example: when the parallel framework automatically detects the number of hardware threads, this number is output as an Info message.
Report: Report messages are used to provide additional details that may be relevant for debugging purposes. These messages are off by default.

In the Logger class, the abortMsg, errorMsg, warningMsg, and infoMsg methods are used to generate messages of the corresponding types. However, the standard way to output error messages is through the ABORT_MSG, ERROR_MSG, WARNING_MSG, and INFO_MSG macros. These macros expand to the corresponding methods, but automatically replaces the first argument by __METHOD_NAME__. For example, the two lines are equivalent:

infoPtr->ERROR_MSG("an error occurred");
infoPtr->errorMsg(__METHOD_NAME__, "an error occurred");

The reason macros are used this way is that there is no other easy way to automatically propagate the name of the method where the error occurred.

The following settings are used to control error logging features.

flag Print:errors (default = on)
If on, error messages are printed to the console the first time each of them occurs. Even if off, errors are still logged and displayed when calling Pythia::stat.

mode Print:verbosity (default = 2; minimum = 0; maximum = 3)
This setting determines which types of diagnostic messages are logged. Messages that don't satisfy the verbosity level will not be printed when calling Pythia::stat.
option 0 : No error messages are logged.
option 1 : Only critical abort messages are logged.
option 2 : All normal messages are logged (default).
option 3 : Also report messages are logged, and errors and warnings are printed every time they occur instead of just the first time. Useful for user-level debugging, where combining with Next:numberCount = 1 will allow easier identification of problematic events.

flag Print:useErrorStream (default = off)
By default, all logger messages are written to cout. If this flag is turned on, error messages will instead be written to cerr.

Timing

The Timer class provides a simple stopwatch that can be used to time code. The timer can be started, stopped, paused, and resumed. At construction, an optional counter can be passed which the timer class will add its elapsed time to, in milliseconds, when stopped. The following gives a small example. Not illustrated here is that whenever a timer goes out of scope, it is stopped, and if a valid counter is available, that counter is incremented. In this way, a timer does not need to be explicitly stopped in complicated return structures.

 
  // Accumulate the event generation time with tEvt, in milliseconds. 
  double tEvt = 0.; 
  // Timer per event and for everything, including initialization. 
  Timer evtTimer(Timer::WALL, &tEvt), totTimer; 
  // Start the total timer. 
  totTimer.start(); 
  Pythia pythia; 
  pythia.readString("SoftQCD:all = on"); 
  pythia.init(); 
  // Generate events. 
  for (int iEvent = 0; iEvent < nEvent; ++iEvent) { 
    // Start the event timer. 
    evtTimer.start(); 
    // Generate the event. 
    bool good = pythia.next(); 
    // Stop the event timer. 
    evtTimer.stop(); 
    if (!good) continue; 
    // Analysis code here is not included in evtTimer but is in totTimer. 
  } 
  totTimer.stop();

Timer::Timer(Timer::TimeType typeIn = Timer::CPU, double* counterPtrIn = nullptr, mutex* mutexPtrIn = nullptr)
Constructor; timing does not begin until start() is called.
argument typeIn (default = Timer::CPU) : type of time to measure. WALL is the real elapsed time, CPU is the processor time for all threads, and THREAD is the processor time for a single thread. When using THREAD the timer should only be called by that thread.
argument counterPtrIn (default = nullptr) : optional pointer to a counter. If provided, the elapsed time in milliseconds is added to *counterPtrIn every time stop() is called.
argument mutexPtrIn (default = nullptr) : if using a shared counter across threads, a single mutex pointer should be passed to all timers using the same counter to prevent race conditions.

Timer::~Timer()
Destructor which calls stop() so the optional counter is incremented if the timer is still running.

void Timer::start(bool pausedIn = false)
Resets and starts the timer.
argument pausedIn (default = off) : optionally start the timer as paused if set as true.

void Timer::pause()
Pauses the timer without clearing the accumulated time.

void Timer::resume()
Resumes the timer after pause() is called.

void Timer::stop()
Stops the timer. The elapsed time is added to the optional counter if valid.

double Timer::elapsed() const
Returns the total accumulated time in milliseconds. If the timer is running, the accumulated time up to the call is included.

template <typename T> double Timer::elapsed() const
Same as above but with the result in units of T.
argument T : the time units of type std::chrono::duration.

bool Timer::isActive() const
Returns true if the timer is currently running. A paused timer is not active.

bool Timer::isPaused() const
Returns true if the timer is paused.

Timer::TimeType Timer::timeType() const
Returns the type of time measured, Timer::WALL, Timer::CPU, or Timer::THREAD.