Write documentation for built-in timers

[suku248]

Describe the flaw
Built-in timers for different NEST phases such as network construction and simulation are included in the code base with #1778 but documentation of the timers and how they are used is lacking.

Suggest an improvement
Document

• what exactly the timers measure including the hierarchy of timers,
• how they are enabled,
• whether/when they are reset,
• that/what effects on runtime are to be expected.

Supporting materials
#1778 and #1471

Desktop/Environment

• If applicable, document systems that are known to not support the built-in timers.

Additional context

• If applicable, document differences between timers in NEST 3 and timers backported to NEST 2.20.

[terhorstd]

RST version of the table by @wschenck and @suku248:

====================================  =====================================  ===========  ===========================
Interface                             Explanation                            Basic Timer  Reset
====================================  =====================================  ===========  ===========================

biological_time                       biological time simulated since the    N/A          ResetKernel
                                      last ResetKernel

time_construction_create              time for constructing the network      YES          ResetKernel
                                      in the nest kernel, cumulative
                                      build time for creating neurons

time_construction_connect             time for constructing the network      YES          ResetKernel
                                      in the nest kernel, cumulative
                                      build time for creating connections

time_communicate_prepare              setup of presynaptic connection        YES          ResetKernel
                                      infrastructure (before actual
                                      simulation)
Within time_communicate_prepare:
timer_gather_target_data              time to communicate connection         NO           ResetKernel
                                      information from postsynaptic to
                                      presynaptic side
Within timer_gather_target_data:
timer_communicate_target_data         time for core MPI communication in     NO           ResetKernel
                                      gathering target data

time_simulate                         total time of simulation without       YES          ResetKernel,
                                      construction                                        SimluationManager::prepare

Within time_simulate:

time_update                           time for neuron update                 NO           ResetKernel,
                                                                                          SimluationManager::prepare

timer_gather_spike_data               time for complete spike exchange       NO           ResetKernel,
                                      after update phase                                  SimluationManager::prepare

Within timer_gather_spike_data:

timer_collocate_spike_data            time to collocate MPI send buffer      NO           ResetKernel,
                                      from spike register                                 SimluationManager::prepare


timer_communicate_spike_data          time for communicating spikes          NO           ResetKernel,
                                      between compute nodes                               SimluationManager::prepare

timer_deliver_spike_data              time to deliver events from the MPI    NO           ResetKernel,
                                      recv buffers to their local                         SimluationManager::prepare
                                      synaptic targets (including
                                      synaptic update, e.g. STDP
                                      synapses) and to the spike ring
                                      buffers of the corresponding
                                      postsynaptic neurons

Other measures:

local_spike_counter                   number of spikes generated on rank     N/A          ResetKernel,
                                                                                          SimluationManager::run
====================================  =====================================  ===========  ===========================

[jougs]

@suku248, @terhorstd, @jasperalbers, @jessica-mitchell: can one of you please comment on the status of this and how critical this is for releasing NEST 3.0? Thanks!