Make Numba optional with graceful fallback to pure Python #75

[diegoceccarelli]

Summary

Implements optional Numba support with graceful fallback to pure Python execution, enabling easier debugging and reduced
dependencies while maintaining full backward compatibility.

Key Changes

Configuration System

• New config.py: Global configuration for enabling/disabling Numba
• Environment variable support: RANX_USE_NUMBA=false to disable Numba
• Programmatic control: ranx.set_numba_enabled(False) API
• Public API: Exposed use_numba and set_numba_enabled in main module

Conditional Decorators (decorators.py)

• @maybe_njit: Conditional njit that falls back to identity function
• @maybe_jit: Conditional jit decorator
• maybe_prange: Falls back to regular range when Numba disabled
• create_typed_dict/list: Runtime helpers for typed collections

Metrics Refactoring

• All metric functions: Converted from @njit to @maybe_njit
• Parallel implementations: Split into Numba and NumPy versions with runtime dispatch
• Type annotations: Updated from numba.typed.List to generic list
• Import safety: Added try/except blocks around all Numba imports

Data Structures

• Conditional imports: Safe fallbacks when Numba unavailable
• Runtime type creation: Fixed helper functions to avoid compilation issues
• Backward compatibility: All existing APIs unchanged

Benefits

For Development

• Easier debugging: Pure Python stack traces when Numba disabled
• Faster iteration: No JIT compilation delays during development
• Better error messages: Clear Python exceptions vs Numba compilation errors

For Deployment

• Optional dependency: Numba can be omitted from requirements
• Simpler environments: Works in constrained environments without Numba
• Graceful degradation: Automatic fallback with performance warning

For Users

• Zero breaking changes: Existing code works unchanged
• Performance by default: Numba still enabled by default
• Flexible control: Easy runtime switching for different use cases

See also #75

[diegoceccarelli]

@AmenRa I don't intend to merge this in master just open the PR to share the code in my branch. The annoying thing is that prange needs to be compiled so it can't be resolved with a decorator. I'll think if there is a better way to implement the parallel business.

[AmenRa]

@diegoceccarelli my initial experiments with eager compilation look promising. Maybe it will also alleviate the issues you are having with the compilation as well. Also, there are noticeable speed ups for metrics computation with large Qrels / Runs (~2x).

Do you have any idea of the impact of your approach on the current implementation? I guess the decorators will have some impact on performance.

Should we consider the option of two completely separate backends?
Example:

# Use Numba backend
from ranx import Qrels, Run, evaluate

# Use Python / Numpy backend
from ranx.numpy import Qrels, Run, evaluate