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 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. speed test results below).

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

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:

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. speed test results below).

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

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.

tf = TimezoneFinder(in_memory=True)

Benchmark Results

Note

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

Timezone Finding

See Timezone Finding Performance Benchmark for a comprehensive performance comparison between all timezone finding functions, auto-generated by scripts/check_speed_timezone_finding.py

Point in Polygon Checks

See Point-in-Polygon Algorithm Performance Benchmark 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 TimezoneFinder Initialization Performance Benchmark for detailed TimezoneFinder initialization performance comparison across different classes and modes, auto-generated by scripts/check_speed_initialisation.py