.. _physics-mergerTreeEvolveProfiler:

Merger Tree Evolver Profiler
============================

Class providing profilers for merger tree evolution---diagnostic objects that record timing and performance information for each ODE integration step. For each differential evolution step, a profiler receives the node being evolved, the time range, the number of function evaluations, the property values and rates, and the wall-clock CPU time. This information can be written to log files to identify bottlenecks in the galaxy formation physics or in the ODE integrator configuration.

**Default implementation:** ``mergerTreeEvolveProfilerNull``

Methods
-------

``stepDescriptor`` → ``void``
   Provide a descriptor of the current step.

   * ``type (varying_string), intent(in ) :: descriptor``

``profile`` → ``void``
   Profile a differential evolution step.

   * ``type (treeNode ), intent(in ) :: node``

   * ``double precision , intent(in ) :: time , timeStart , timeEnd , timeStep``

   * ``integer (c_size_t ), intent(in ) :: countEvaluations``

   * ``logical , intent(in ) :: interrupted``

   * ``integer (c_size_t ), intent(in ) :: propertyIndex``

   * ``type (varying_string), intent(in ) :: propertyName``

   * ``double precision , intent(in ), dimension(:) :: propertyValue , propertyRate, propertyScale, propertyError``

   * ``double precision , intent(in ) :: timeCPU``

.. _physics-mergerTreeEvolveProfilerNull:

``mergerTreeEvolveProfilerNull``
--------------------------------

A merger tree evolve profiler that does nothing.

**(Default implementation)**

.. _physics-mergerTreeEvolveProfilerSimple:

``mergerTreeEvolveProfilerSimple``
----------------------------------

A merger tree evolve profiler that collects simple data. Each step taken by the ODE evolver is then analyzed. First, a record of the size of the time step taken is recorded. Second, the property which is currently limiting the time step size (i.e. that which has the largest error over the step as judged using the same heuristics as the ODE solver uses to determine step size) is determined and a record of this is kept.

At the end of a run the accumulated data is written to the Galacticus output file, into a group named ``metaData/evolverProfiler``. A histogram of time step sizes is written to ``timeStepCount`` with bins specified in ``timeStep``---these bins can be adjusted using ``[timeStepMinimum]``, ``[timeStepMaximum]`` and ``[timeStepPointsPerDecade]``. A histogram of which properties limited step size is written to ``propertyHitCount`` with the associated property names written to ``[propertyNames]``.

**Methods**

* ``calculationReset`` — Reset memoized calculations.

**Parameters**

* ``[timeStepMinimum]`` (real; default ``1.0d-6``) — The smallest timestep to use in profiling ODE solver steps.
* ``[timeStepMaximum]`` (real; default ``1.0d+1``) — The largest timestep to use in profiling ODE solver steps.
* ``[timeStepPointsPerDecade]`` (integer; default ``3``) — The number of bins per decade of timestep to use when profiling ODE solver steps.

.. _physics-mergerTreeEvolveProfilerTinySteps:

``mergerTreeEvolveProfilerTinySteps``
-------------------------------------

A merger tree evolve profiler that monitors timestep sizes during galaxy evolution and issues warnings when steps fall below a threshold, helping to diagnose stiff ODE systems or convergence problems. The warning threshold is set by ``[timeStepTiny]`` and the minimum recorded step size is tracked via ``[timeStepMinimum]``.

**Parameters**

* ``[timeStepTiny]`` (real; default ``1.0d-9``) — The time step below which warnings will be issued.