.. _performance:

Performance
===========

Binary Data Format
------------------

TimezoneFinder uses an optimized binary format based on FlatBuffers for storing and accessing timezone data. This format provides several performance advantages:

* **Zero-Copy Access**: FlatBuffers allows accessing serialized data without unpacking or parsing
* **Spatial Indexing**: H3 hexagonal grid system efficiently narrows down polygon candidates
* **Optimized Data Layout**: Compact storage with direct access to relevant data structures

For detailed information about the data format in use, see :doc:`data_format`.


C extension
-----------

During installation ``timezonefinder`` automatically tries to compile a C extension with an implementation of the time critical point in polygon check algorithm.
In order for this to work, a Clang compiler has to be installed.

.. note::

    If compilation fails (due to e.g. missing C compiler or broken ``cffi`` installation) ``timezonefinder`` will silently fall back to a pure Python implementation (~400x slower, cf. :ref:`speed test results <speed-tests>` below).


For testing if the compiled C implementation of the point in polygon algorithm is being used:

.. code-block:: python

    TimezoneFinder.using_clang_pip()  # returns True or False



Numba
-----

Some of the utility function (cf. ``utils.py``) can be JIT compiled automatically by installing the optional dependency ``numba``:

.. code-block:: console

    pip install timezonefinder[numba]


It is highly recommended to install ``Numba`` for increased performance when the C extensions cannot be used (e.g. C compiler is not present at build time).


.. note::

    If Numba can be imported, the JIT compiled Python version of the point in polygon check algorithm will be used instead of the C alternative as it is even faster (cf. :ref:`speed test results <speed-tests>` below).



For testing if Numba is being used to JIT compile helper functions:


.. code-block:: python

    TimezoneFinder.using_numba()  # returns True or False



In memory mode
--------------

To speed up the computations at the cost of memory consumption and initialisation time, pass ``in_memory=True`` during initialisation.
This causes all binary files to be read into memory.

.. code-block:: python

    tf = TimezoneFinder(in_memory=True)



.. _speed-tests:

Benchmark Results
-----------------

.. note::

   All performance reports are generated automatically and may vary based on hardware configuration and dataset version.




Timezone Finding
~~~~~~~~~~~~~~~~

See :doc:`benchmark_results_timezonefinding` for a comprehensive performance comparison between all timezone finding functions, auto-generated by ``scripts/check_speed_timezone_finding.py``



Point in Polygon Checks
~~~~~~~~~~~~~~~~~~~~~~~

See :doc:`benchmark_results_polygon` for detailed point-in-polygon algorithm performance comparison between C and Python implementations, auto-generated by ``scripts/check_speed_inside_polygon.py``


Initialization Time
~~~~~~~~~~~~~~~~~~~

See :doc:`benchmark_results_initialization` for detailed TimezoneFinder initialization performance comparison across different classes and modes, auto-generated by ``scripts/check_speed_initialisation.py``