max-div 0.0.3__py3-none-any.whl

max_div/benchmark/__init__.py

@@ -0,0 +1 @@
+from .sample_int import benchmark_sample_int

max_div/benchmark/sample_int.py

@@ -0,0 +1,85 @@
+import math
+
+import numpy as np
+
+from max_div.internal.benchmarking import BenchmarkResult, benchmark
+from max_div.internal.compat import is_numba_installed
+from max_div.sampling.discrete import sample_int
+
+
+def benchmark_sample_int(turbo: bool = False) -> None:
+    """
+    Benchmarks the `sample_int` function from `max_div.sampling.discrete`.
+
+    Different scenarios are tested:
+
+     * with & without replacement
+     * uniform & non-uniform sampling
+     * `use_numba` True and False
+     * different sizes of (`n`, `k`):
+        * (10, 1), (100, 1), (1000, 1), (5000, 1), (10000, 1)
+        * (10000, 10), (10000, 100), (10000, 1000), (10000, 5000), (10000, 10000)
+
+    :param turbo: If `True`, a much shorter (but less reliable) benchmark is run; intended for testing purposes.
+    """
+
+    if not is_numba_installed():
+        print("====================================================================================")
+        print("   WARNING: Numba is not installed!!!")
+        print("====================================================================================")
+
+    print("Benchmarking `sample_int`...")
+    print()
+    print("".ljust(30) + "use_numba=False".rjust(25) + "use_numba=True".rjust(25))
+
+    for replace, use_p, desc in [
+        (True, False, "with replacement, uniform"),
+        (False, False, "without replacement, uniform"),
+        (True, True, "with replacement, non-uniform"),
+        (False, True, "without replacement, non-uniform"),
+    ]:
+        print(desc.upper())
+
+        for n, k in [
+            (10, 1),
+            (100, 1),
+            (1000, 1),
+            (5000, 1),
+            (10000, 1),
+            (10000, 10),
+            (10000, 100),
+            (10000, 1000),
+            (10000, 5000),
+            (10000, 10000),
+        ]:
+            size_str = f"{k:<6_} out of {n:<6_}"
+
+            results: list[BenchmarkResult] = []
+            for use_numba in [False, True]:
+                if use_p:
+                    p = np.random.rand(n)
+                    p /= p.sum()
+                else:
+                    p = None
+
+                def func_to_benchmark():
+                    sample_int(n=n, k=k, replace=replace, p=p, use_numba=use_numba)
+
+                results.append(
+                    benchmark(
+                        f=func_to_benchmark,
+                        t_per_run=0.001 if turbo else 0.1,
+                        n_warmup=3 if turbo else 10,
+                        n_benchmark=3 if turbo else 30,
+                        silent=True,
+                    )
+                )
+
+            print(
+                (" " * 4)
+                + size_str.ljust(26)
+                + results[0].t_sec_with_uncertainty_str.rjust(25)
+                + results[1].t_sec_with_uncertainty_str.rjust(25)
+            )
+
+        print()

max_div/internal/benchmarking/__init__.py

@@ -0,0 +1,2 @@
+from ._micro_benchmark import BenchmarkResult, benchmark
+from ._timer import Timer

max_div/internal/benchmarking/_micro_benchmark.py

@@ -0,0 +1,112 @@
+from dataclasses import dataclass
+from typing import Callable
+
+import numpy as np
+
+from max_div.internal.formatting import format_short_time_duration
+from max_div.internal.utils import clip
+
+from ._timer import Timer
+
+
+# =================================================================================================
+#  BenchmarkResult
+# =================================================================================================
+@dataclass(frozen=True)
+class BenchmarkResult:
+    t_sec_q_25: float
+    t_sec_q_50: float
+    t_sec_q_75: float
+
+    @property
+    def t_sec_str(self) -> str:
+        s_median = format_short_time_duration(dt_sec=self.t_sec_q_50, right_aligned=True, spaced=True, long_units=True)
+        return s_median
+
+    @property
+    def t_sec_with_uncertainty_str(self) -> str:
+        s_median = self.t_sec_str
+        s_perc = f"{50 * (self.t_sec_q_75 - self.t_sec_q_25) / self.t_sec_q_50:.1f}%"
+        return f"{s_median} ± {s_perc}"
+
+
+# =================================================================================================
+#  Main benchmarking function
+# =================================================================================================
+def benchmark(
+    f: Callable,
+    t_per_run: float = 0.1,
+    n_warmup: int = 10,
+    n_benchmark: int = 30,
+    silent: bool = False,
+) -> BenchmarkResult:
+    """
+    Adaptive micro-benchmarking function, to determine the duration/execution of the provided callable `f`.
+
+    :param f: (Callable) Function to benchmark. Should take no arguments.
+    :param t_per_run: (float, default=0.1) time in seconds we want to target per benchmarking run.
+                      # of executions/run is adjusted to meet this target.
+    :param n_warmup: (int, default=10) Number of warmup runs to perform before benchmarking.
+    :param n_benchmark: (int, default=30) Number of benchmark runs to perform.
+    :param silent: (bool, default=False) If True, suppresses any output during benchmarking.
+    :return: Median estimate of duration/execution of `f` in seconds.
+    """
+
+    # --- init --------------------------------------------
+    lst_t = []  # list of measured times per execution in seconds
+    n_executions = 1  # number of executions per run, adjusted dynamically
+    f_baseline = _baseline_fun  # baseline function to subtract overhead
+
+    if not silent:
+        print("Benchmarking: ", end="")
+
+    # --- main loop ---------------------------------------
+    for i in range(n_warmup + n_benchmark):
+        # run
+        with Timer() as timer_tot:
+            # baseline
+            with Timer() as timer_baseline:
+                for _ in range(n_executions):
+                    f_baseline()
+            t_baseline = timer_baseline.t_elapsed_sec()
+
+            # actual function
+            with Timer() as timer_f:
+                for _ in range(n_executions):
+                    f()
+            t_f = timer_f.t_elapsed_sec()
+
+        # store results of benchmark runs
+        if i >= n_warmup:
+            lst_t.append(abs(t_f - t_baseline) / n_executions)  # abs value to avoid negative times for very fast 'f'.
+            if not silent:
+                print(".", end="")
+        else:
+            if not silent:
+                print("w", end="")
+
+        # adjust n_executions
+        t_tot = timer_tot.t_elapsed_sec()
+        n_executions = round(
+            clip(
+                value=n_executions * (t_per_run / t_tot),
+                min_value=max(1.0, n_executions / 10),
+                max_value=n_executions * 10,
+            )
+        )
+
+    # --- finalize ----------------------------------------
+    q25, q50, q75 = np.percentile(lst_t, [25, 50, 75])
+    result = BenchmarkResult(t_sec_q_25=q25, t_sec_q_50=q50, t_sec_q_75=q75)
+    if not silent:
+        print(f"   {result.t_sec_with_uncertainty_str} per execution")
+
+    # --- return result -----------------------------------
+    return result
+
+
+# =================================================================================================
+#  Baseline benchmarks
+# =================================================================================================
+def _baseline_fun():
+    pass

max_div/internal/benchmarking/_timer.py

@@ -0,0 +1,35 @@
+import time
+
+
+class Timer:
+    """
+    Class acting as a context manager to measure time elapsed.  Elapsed time can be retrieved using t_elapsed().
+    """
+
+    # --- constructor -------------------------------------
+    def __init__(self):
+        self._start: float | None = None
+        self._end: float | None = None
+
+    # --- context manager ---------------------------------
+    def __enter__(self):
+        self._start = time.perf_counter_ns()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._end = time.perf_counter_ns()
+
+    # --- extract results ---------------------------------
+    def t_elapsed_nsec(self) -> float:
+        if self._start is None:
+            raise RuntimeError("Timer has not been started.")
+
+        if self._end is None:
+            # timer still running
+            return time.perf_counter_ns() - self._start
+        else:
+            # timer finished
+            return self._end - self._start
+
+    def t_elapsed_sec(self) -> float:
+        return self.t_elapsed_nsec() / 1e9

max_div/internal/compat/__init__.py

@@ -0,0 +1 @@
+from ._numba import is_numba_installed, numba

max_div/internal/compat/_numba/__init__.py

@@ -0,0 +1,14 @@
+# =================================================================================================
+#  Transparant handling of original numba vs dummy numba
+# =================================================================================================
+try:
+    import numba
+except ImportError:
+    from ._dummy_numba import Numba as numba
+
+
+# =================================================================================================
+#  Helpers
+# =================================================================================================
+def is_numba_installed() -> bool:
+    return numba.__version__ != "0.0.0"

max_div/internal/compat/_numba/_dummy_numba.py

@@ -0,0 +1,94 @@
+"""
+Implements a dummy version of Numba for environments where Numba is not available.
+Main goal is that code that uses @numba.njit or numba.tuped.Dict, ... does not break and transparently falls back to standard Python.
+"""
+
+from ._helpers import dummy_decorator
+
+
+# =================================================================================================
+#  Dummy typed containers
+# =================================================================================================
+class NumbaTypedDict(dict):
+    @staticmethod
+    def empty(*args, **kwargs):
+        return dict()
+
+
+class NumbaTypedList(list):
+    @staticmethod
+    def empty_list(*args, **kwargs):
+        return list()
+
+
+# =================================================================================================
+#  Main dummy package tree
+# =================================================================================================
+class NumbaTyped:
+    # implements subset
+    Dict = NumbaTypedDict
+    List = NumbaTypedList
+
+
+class NumbaTypes:
+    # implements dummies for all members of numba.types.__all__
+    int8 = object()
+    int16 = object()
+    int32 = object()
+    int64 = object()
+    uint8 = object()
+    uint16 = object()
+    uint32 = object()
+    uint64 = object()
+    intp = object()
+    uintp = object()
+    intc = object()
+    uintc = object()
+    ssize_t = object()
+    size_t = object()
+    boolean = object()
+    float32 = object()
+    float64 = object()
+    complex64 = object()
+    complex128 = object()
+    bool_ = object()
+    byte = object()
+    char = object()
+    uchar = object()
+    short = object()
+    ushort = object()
+    int_ = object()
+    uint = object()
+    long_ = object()
+    ulong = object()
+    longlong = object()
+    ulonglong = object()
+    double = object()
+    void = object()
+    none = object()
+    b1 = object()
+    i1 = object()
+    i2 = object()
+    i4 = object()
+    i8 = object()
+    u1 = object()
+    u2 = object()
+    u4 = object()
+    u8 = object()
+    f4 = object()
+    f8 = object()
+    c8 = object()
+    c16 = object()
+    optional = object()
+    ffi_forced_object = object()
+    ffi = object()
+    deferred_type = object()
+    bool = object()
+
+
+class Numba:
+    __version__ = "0.0.0"
+    jit = dummy_decorator
+    njit = dummy_decorator
+    typed = NumbaTyped
+    types = NumbaTypes

max_div/internal/compat/_numba/_helpers.py

@@ -0,0 +1,14 @@
+from typing import Callable
+
+
+def dummy_decorator(*args, **kwargs):
+    # dummy decorator that does nothing and can be used with or without arguments
+    if len(args) == 1 and isinstance(args[0], Callable):
+        # decorator used without arguments
+        return args[0]
+    else:
+        # decorator used with arguments
+        def decorator(func):
+            return func
+
+        return decorator

max_div/internal/formatting/__init__.py

@@ -0,0 +1 @@
+from ._time_duration import format_long_time_duration, format_short_time_duration, format_time_duration

max_div/internal/formatting/_time_duration.py

@@ -0,0 +1,175 @@
+from typing import Literal
+
+from max_div.internal.utils import HALF_EPS
+
+
+# =================================================================================================
+#  Main entrypoints
+# =================================================================================================
+def format_time_duration(dt_sec: float, n_chars: int = 10) -> str:
+    """Format a time duration in seconds."""
+    if dt_sec < 1.0:
+        return format_short_time_duration(dt_sec, n_chars=n_chars, spaced=False, long_units=False, right_aligned=False)
+    else:
+        return format_long_time_duration(dt_sec, n_chars=n_chars)
+
+
+def format_long_time_duration(dt_sec: float, n_chars: int = 10) -> str:
+    """
+    Format a time duration that is expected to be ~1sec or larger.
+
+    The max lengths of the resulting string (n_chars) will always be exactly matched if n_chars>=5 and dt_sec<100d.
+    """
+    # --- main loop ---------------------------------------
+    result = ""
+    for precision in ["d", "h", "m", "s", "s.s", "s.ss"]:
+        # choose representation with the highest precision with length <= n_chars
+        cand = _format_long_time_duration_to_spec(dt_sec, precision)
+        if (result == "") or (len(cand) <= n_chars):
+            result = cand
+
+    # --- final result ------------------------------------
+    result = result.rjust(n_chars)  # pad with spaces on the left, if too short
+    return result
+
+
+def format_short_time_duration(
+    dt_sec: float,
+    n_chars: int = 10,
+    right_aligned: bool | None = None,
+    spaced: bool | None = None,
+    long_units: bool | None = None,
+) -> str:
+    """
+    Format a time duration that is expected to be <<1sec.  Different styling options are chosen to optimally meet
+    the given character count.
+
+    The options 'right_aligned', 'spaced', and 'long_units' are optional and, when omitted, automatically chosen
+     based on heuristics.
+
+    The requested n_chars is guaranteed to be met exactly if n_chars>=5, dt_sec<999.5 and with default styling options.
+
+    :param dt_sec: (float) Time duration in seconds.
+    :param n_chars: (int >= 5) Desired number of characters in the output
+    :param right_aligned: (bool) If True, the result is right-aligned such that values & units align vertically.
+    :param spaced: (bool) If True, a space is added between the number and the unit.
+    :param long_units: (bool) If True, long unit names are used (e.g. "nsec" instead of "ns").
+    """
+
+    # --- styling heuristics ------------------------------
+    if right_aligned is None:
+        right_aligned = n_chars > 6
+    if spaced is None:
+        spaced = n_chars > 8
+    if long_units is None:
+        long_units = n_chars > 10
+
+    # --- main loop ---------------------------------------
+    result = ""
+    for n_digits in range(n_chars - 2):
+        # choose representation with largest n_digits with length <= n_chars
+        cand = _format_short_time_duration_to_spec(dt_sec, n_digits, right_aligned, spaced, long_units)
+        if (result == "") or (len(cand) <= n_chars):
+            result = cand
+
+    # --- final result ------------------------------------
+    result = result.rjust(n_chars)  # pad with spaces on the left, if too short
+    return result
+
+
+# =================================================================================================
+#  Helpers
+# =================================================================================================
+def _format_long_time_duration_to_spec(
+    dt_sec: float, precision: str = Literal["d", "h", "m", "s", "s.s", "s.ss", "s.sss"]
+) -> str:
+    # --- rounding ----------------------------------------
+    match precision:
+        case "d":
+            round_to = 60 * 60 * 24
+        case "h":
+            round_to = 60 * 60
+        case "m":
+            round_to = 60
+        case "s":
+            round_to = 1
+        case "s.s":
+            round_to = 0.1
+        case "s.ss":
+            round_to = 0.01
+    dt_sec = round_to * round(dt_sec / round_to) * (1 + HALF_EPS)  # avoid rounding issues
+
+    # --- split in components -----------------------------
+    rem_m, s = divmod(dt_sec, 60)
+    rem_h, m = divmod(rem_m, 60)
+    d, h = divmod(rem_h, 24)
+
+    # --- construct string-valued components --------------
+    d, h, m, s = int(d), int(h), int(m), s  # convert to int where appropriate
+    match precision:
+        case "d":
+            components = [f"{d}d"]
+        case "h":
+            components = [f"{d}d", f"{h}h"]
+        case "m":
+            components = [f"{d}d", f"{h}h", f"{m}m"]
+        case "s":
+            components = [f"{d}d", f"{h}h", f"{m}m", f"{int(s)}s"]
+        case "s.s":
+            components = [f"{d}d", f"{h}h", f"{m}m", f"{s:.1f}s"]
+        case "s.ss":
+            components = [f"{d}d", f"{h}h", f"{m}m", f"{s:.2f}s"]
+
+    # prune leading zero components
+    while (len(components) > 1) and components[0].startswith("0"):
+        components.pop(0)
+
+    # --- build final result ------------------------------
+    return "".join(components)
+
+
+def _format_short_time_duration_to_spec(
+    dt_sec: float, n_digits: int, right_aligned: bool, spaced: bool, long_units: bool
+) -> str:
+    """
+    Format a time duration that is expected to be <<1sec to the given specification.
+    :param dt_sec: (float) Time duration in seconds.
+    :param n_digits: (int >= 0) Number of digits to show after the decimal point.
+    :param right_aligned: (bool) If True, the result is right-aligned such that values & units align vertically.
+    :param spaced: (bool) If True, a space is added between the number and the unit.
+    :param long_units: (bool) If True, long unit names are used (e.g. "nsec" instead of "ns").
+    :return: string representation of the time duration.
+    """
+
+    # --- init --------------------------------------------
+    if long_units:
+        c_and_unit = [
+            (1.0, "sec " if right_aligned else "s"),
+            (1e3, "msec"),
+            (1e6, "μsec"),
+            (1e9, "nsec"),
+        ]
+    else:
+        c_and_unit = [
+            (1.0, "s " if right_aligned else "s"),
+            (1e3, "ms"),
+            (1e6, "μs"),
+            (1e9, "ns"),
+        ]
+
+    # --- main loop ---------------------------------------
+    value_str, unit_str = "", ""
+    for c, unit in c_and_unit:
+        value = round(dt_sec * c, ndigits=n_digits)
+        if (value < 1000) or (value_str == ""):
+            unit_str = unit
+            if n_digits > 0:
+                value_str = f"{value:.{n_digits}f}".lstrip()
+            else:
+                value_str = str(int(value))
+
+    # --- final result ------------------------------------
+    if spaced:
+        return f"{value_str} {unit_str}"
+    else:
+        return f"{value_str}{unit_str}"

max_div/internal/utils/__init__.py

@@ -0,0 +1,2 @@
+from ._clip import clip
+from ._precision import EPS, HALF_EPS

max_div/internal/utils/_clip.py

@@ -0,0 +1,5 @@
+def clip(value: float | int, min_value: float | int, max_value: float | int) -> float | int:
+    if min_value >= max_value:
+        return (min_value + max_value) / 2
+    else:
+        return max(min_value, min(max_value, value))

max_div/internal/utils/_precision.py

@@ -0,0 +1,5 @@
+import math
+import sys
+
+EPS = sys.float_info.epsilon  # Machine epsilon for 64-bit float (float64)
+HALF_EPS = math.sqrt(EPS)

max_div/sampling/__init__.py

@@ -0,0 +1 @@
+from .discrete import sample_int

max_div/sampling/discrete.py

@@ -0,0 +1,176 @@
+import numpy as np
+
+from max_div.internal.compat import numba
+
+
+# =================================================================================================
+#  sample_int
+# =================================================================================================
+def sample_int(
+    n: int,
+    k: int | None = None,
+    replace: bool = True,
+    p: np.ndarray[float] | None = None,
+    seed: int | None = None,
+    use_numba: bool = True,
+) -> int | np.ndarray[np.int64]:
+    """
+    Randomly sample `k` integers from range `[0, n-1]`, optionally with replacement and per-value probabilities.
+
+    Different implementation is used, depending on the case:
+
+    | `use_numba`    | `p` specified  | `replace`  | `k`  | Method Used                              | Complexity      |
+    |----------------|----------------|------------|------|------------------------------------------|-----------------|
+    |  No            | Any            | Any        | Any  | `np.random.choice`                       | depends         |
+    |  Yes           | No             | True       | Any  | `np.random.randint`, uniform sampling    | O(k)            |
+    |  Yes           | No             | False      | Any  | k-element Fisher-Yates shuffle           | O(n)            |
+    |  Yes           | Yes            | Any        | 1    | Multinomial sampling using CDF           | O(n + log(n))   |
+    |  Yes           | Yes            | True       | >1   | Multinomial sampling using CDF           | O(n + k log(n)) |
+    |  Yes           | Yes            | False      | >1   | Efraimidis-Spirakis sampling + exponential key sampling (Gumbel-Max Trick) using the Ziggurat algorithm.  | O(n) |
+
+    :param n: defines population to sample from as range [0, n-1].  `n` must be >0.
+    :param k: The number of integers to sample (>0).  `k=None` indicates a single integer sample.
+    :param replace: Whether to sample with replacement.
+    :param p: Optional 1D array of probabilities associated with each integer in the range.
+              Size must be equal to max_value + 1 and sum to 1.
+    :param seed: Optional random seed for reproducibility.
+    :param use_numba: Use the self-implemented algorithm (which is `numba`-accelerated if `numba` is installed)
+    :return: `k=None` --> single integer; `k>=1` --> (k,)-sized array with sampled integers.
+    """
+
+    # -------------------------------------------------------------------------
+    #  Don't try using numba
+    # -------------------------------------------------------------------------
+    if not use_numba:
+        # --- argument handling ---------------------------
+        if (k == 1) or (k is None):
+            replace = True  # single sample, replacement makes no difference, so we can fall back to faster methods
+
+        # --- argument validation -------------------------
+        if n < 1:
+            raise ValueError(f"n must be >=1. (here: {n})")
+        if k is not None:
+            if k < 1:
+                raise ValueError(f"k must be >=1. (here: {k})")
+            if (not replace) and (k > n):
+                raise ValueError(f"Cannot sample {k} unique values from range [0, {n}) without replacement.")
+
+        # --- sampling ------------------------------------
+        if seed is not None:
+            np.random.seed(seed)
+
+        if k is None:
+            # returns scalar
+            return np.random.choice(n, size=None, replace=replace, p=p)
+        else:
+            # returns array
+            return np.random.choice(n, size=k, replace=replace, p=p)
+
+    # -------------------------------------------------------------------------
+    #  Try using numba
+    # -------------------------------------------------------------------------
+    else:
+        # --- argument handling ---------------------------
+        k_orig = k  # remember, to know what return value we need
+        if (k == 1) or (k is None):
+            k = 1  # make sure we always have an integer for the numba function
+            replace = True  # single sample, replacement makes no difference, so we can fall back to faster methods
+        if p is None:
+            use_p = False
+            p = np.zeros(0, dtype=np.float64)  # dummy value
+        else:
+            use_p = True
+        if seed is None:
+            use_seed = False
+            seed = 42  # dummy value
+        else:
+            use_seed = True
+
+        # --- argument validation -------------------------
+        if n < 1:
+            raise ValueError(f"n must be >=1. (here: {n})")
+        if k < 1:
+            raise ValueError(f"k must be >=1. (here: {k})")
+        if (not replace) and (k > n):
+            raise ValueError(f"Cannot sample {k} unique values from range [0, {n}) without replacement.")
+        if use_p:
+            if (p.ndim != 1) or (p.size != n):
+                raise ValueError(f"p must be a 1D array of size {n}. (here: shape={p.shape})")
+
+        # --- call numba function -------------------------
+        samples = sample_int_numba(n=n, k=k, replace=replace, use_p=use_p, p=p, use_seed=use_seed, seed=seed)
+        if k_orig is None:
+            return samples[0]
+        else:
+            return samples
+
+
+@numba.njit
+def sample_int_numba(
+    n: int,
+    k: int,
+    replace: bool,
+    use_p: bool = False,
+    p: np.ndarray[float] = np.zeros(0),
+    use_seed: bool = False,
+    seed: int = 42,
+) -> np.ndarray[int]:
+    """
+    See native python version docstring.  We split the implementation into a core numba-decorated function and
+    a Python front-end, because numba-decorated functions do not allow for multiple possible return types.
+    """
+    if use_seed:
+        np.random.seed(seed)
+
+    if (k == n) and (not replace):
+        # corner case: return all elements in random order
+        population = np.arange(n, dtype=np.int64)
+        np.random.shuffle(population)
+        return population
+
+    if not use_p:
+        if replace:
+            # UNIFORM sampling with replacement
+            return np.random.choice(n, size=k)  # O(k)
+        else:
+            # UNIFORM sampling without replacement using Fisher-Yates shuffle
+            population = np.arange(n, dtype=np.int64)  # O(n)
+            for i in range(k):  # k x O(1)
+                j = np.random.randint(i, n)
+                population[i], population[j] = population[j], population[i]
+            return population[:k]  # O(k)
+    else:
+        if replace:
+            # NON-UNIFORM sampling with replacement using CDF
+            cdf = np.empty(n)  # O(n)
+            csum = 0.0
+            for i in range(n):  # n x O(1)
+                csum += p[i]
+                cdf[i] = csum
+            samples = np.empty(k, dtype=np.int64)  # O(k)
+            for i in range(k):  # k x O(log(n))
+                r = np.random.random()
+                idx = np.searchsorted(cdf, r)
+                samples[i] = idx
+            return samples
+        else:
+            # NON-UNIFORM sampling without replacement using Efraimidis-Spirakis + Exponential keys
+            # algorithm description:
+            #   Efraimidis:       select k elements corresponding to k largest values of  u_i^{1/p_i} (u_i ~ U(0,1))
+            #   Gumbel-Max Trick: select k smallest values of  -log(u_i)/p_i  (u_i ~ U(0,1))
+            #   Ziggurat:         (TODO) generate log(u_i) more efficiently, applying the Ziggurat algorithm
+            #                            to the exponential distribution, which avoids usage of transcendental
+            #                            functions for the majority of the samples.
+            keys = np.empty(n, dtype=np.float64)  # O(n)
+            u = np.random.random(n)  # O(n)
+            for i in range(n):  # n x O(1)
+                if p[i] == 0.0:
+                    keys[i] = np.inf
+                else:
+                    keys[i] = -np.log(u[i]) / p[i]
+
+            # Get indices of k smallest keys
+            if k > 1:
+                return np.argpartition(keys, k)[:k]  # O(n) average case
+            else:
+                return np.array([np.argmin(keys)])  # O(n)

max_div-0.0.3.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: max-div
+Version: 0.0.3
+Summary: Flexible Solver for Maximum Diversity Problems with Fairness Constraints.
+Project-URL: Documentation, https://max-div.readthedocs.io/
+Project-URL: Source, https://github.com/bertpl/max-div
+Project-URL: ChangeLog, https://github.com/bertpl/max-div/blob/develop/CHANGELOG.md
+Project-URL: Issues, https://github.com/bertpl/max-div/issues
+Project-URL: Roadmap, https://github.com/bertpl/max-div/milestones
+Author-email: Bert Pluymers <bert.pluymers@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0.0
+Provides-Extra: docs
+Requires-Dist: mkdocs-autoapi[python]>=0.4.1; extra == 'docs'
+Requires-Dist: mkdocs-include-markdown-plugin>=7.2.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
+Requires-Dist: ruff>=0.14.0; extra == 'docs'
+Provides-Extra: numba
+Requires-Dist: numba>=0.57; extra == 'numba'
+Description-Content-Type: text/markdown
+
+![shields.io-python-versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
+![genbadge-test-count](https://bertpl.github.io/max-div/version_artifacts/release/v0.0.3/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/max-div/version_artifacts/release/v0.0.3/badge-coverage.svg)
+![max-div logo](https://bertpl.github.io/max-div/version_artifacts/release/v0.0.3/splash.webp)
+
+# max-div
+Configurable Solver for Maximum Diversity Problems with Fairness Constraints.
+
+### --- ***Under Development*** ---

max_div-0.0.3.dist-info/RECORD

@@ -0,0 +1,23 @@
+max_div/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+max_div/benchmark/__init__.py,sha256=wzyPThNW4GETpkPh5yXDKTkQbJQ1ulungL2jQL8Ak2s,45
+max_div/benchmark/sample_int.py,sha256=mueD3v0tqP0zTN9Gf1LjnvrCEm0fV3zlgcE-Eh3V0vQ,2817
+max_div/internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+max_div/internal/benchmarking/__init__.py,sha256=WNjrLlGI_vkI-nZkQMPICgi67rTVole_MCc4jNe_OxI,83
+max_div/internal/benchmarking/_micro_benchmark.py,sha256=hvQxmKG72MnG9dANrLbYm8D7NsJP-2pGapl5idX_E7I,4183
+max_div/internal/benchmarking/_timer.py,sha256=gpA3KgreDTtK2QUARJKI4Ir9dTDMKW7B5GQuThRbYh8,1050
+max_div/internal/compat/__init__.py,sha256=ApHeMuO_9zlP34BnSZMRVLVyEEv1VEkGXNJzw5ddaK4,46
+max_div/internal/compat/_numba/__init__.py,sha256=fKwHEiafrYMmk_GOaOKZBb3rDU9q0sYqzi3BPPtV0A4,631
+max_div/internal/compat/_numba/_dummy_numba.py,sha256=FPguZfpQzpWRxmc4pYSGVCoPzgofsgQO_bknF_bK8aQ,2341
+max_div/internal/compat/_numba/_helpers.py,sha256=pQqAjHYbSwPos9011xpmbkJeZ5cPBUZq14qh8G6GtjQ,402
+max_div/internal/formatting/__init__.py,sha256=UMim6fo_e4JGJo7pl8FZ1nNpmStlfbGB7O49LhCZwWo,104
+max_div/internal/formatting/_time_duration.py,sha256=dO88GPZeMbxVk0YF9Zr2Y0NLCXaiW_HwTa7S-PT9e9E,6740
+max_div/internal/utils/__init__.py,sha256=Xqb7Rh9Lq6WsUK-5B9aouwWMhAh0c1a7pF0rdaP5kgo,62
+max_div/internal/utils/_clip.py,sha256=kWUCKG9uFxNvFWvThMyFdWLlzVb9cFADngpBYl5b38U,230
+max_div/internal/utils/_precision.py,sha256=3eEUdJQmXA3Q6Tg4jb3vG0RTwOBNgnc09j5ts0gcIdw,125
+max_div/sampling/__init__.py,sha256=_tsDiQNr4brsMiROQVbJFpq7Um79HV7P0ec6ChMd_iY,33
+max_div/sampling/discrete.py,sha256=VYBpeYYIUbLeuA3Ld4PTBkVwq6ziIBW0KlkJVqmqNuU,8048
+max_div-0.0.3.dist-info/METADATA,sha256=PwZtrIAsZRKs5bCVw_SzDOQpfPtCVOcDxHTvuBRrLAM,1604
+max_div-0.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+max_div-0.0.3.dist-info/entry_points.txt,sha256=EL6VQ4tIThMRtNqBtQvj2yAMBJm-7OM801VYPBsRwp4,80
+max_div-0.0.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+max_div-0.0.3.dist-info/RECORD,,

max_div-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

max_div-0.0.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+benchmark_sample_int = max_div.benchmark:benchmark_sample_int

max_div-0.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.