.. _measure:

#############
Measure tools
#############

.. contents::
    :local:
    :backlinks: none
    :depth: 2

There is a built-in function prepared to measure the time consumption of a path-finding algorithm.

The function ``measure_function`` receives a function that generates a path given a terrain.
The argument ``search_function`` must be a function that receives a terrain and returns a path.

.. code-block:: python

    from sIArena.measurements.measurements import measure_function

    def search_function(terrain: Terrain) -> Path:
        # Your path-finding algorithm here
        return path

    time = measure_function(search_function)

This function receives the following arguments:

            search_function,
            terrain: Terrain,
            iterations: int = 1,
            debug: bool = False,
            max_seconds: float = 60*5

- ``search_function``: The function that generates a path given a terrain.
- ``terrain: Terrain``: The terrain to be used in the path-finding algorithm.
- ``iterations: int = 1``: The number of times the function will be executed. The default value is 1. This is used to get the average time of the function.
- ``debug: bool = False``: If True, the function will print the time of each iteration.
- ``max_seconds: float = 60*5``: The maximum time that the function will run.

The function will fail with an exception if the path generated by the function is not correct or if the function takes more than the maximum time to run.