driver.py

import argparse
import random
import datetime as _dt
import json
import os
import platform
import re
import socket
import subprocess
import sys
import time
import uuid
from typing import Optional, Tuple

# Sort options / filter size file structure
SORT_FILE_SECTION_SEPARATOR = "--------<3---------"
# Section indexes within a sort options file split by SORT_FILE_SECTION_SEPARATOR.
SECTION_INDEX_SORT_OPTIONS = 0
SECTION_INDEX_FILTER_SIZES = 1
SECTION_INDEX_POS_QUERIES = 2

# SortSpec: (sort_kind, l2, l3, bfkind). When parsed from --help, l2/l3/bfkind are None.
SortSpec = Tuple[str, Optional[str], Optional[str], Optional[str]]

r_count = 0
count = -1

def bv_size(n: int) -> int:
    return n * 16


def num_entries_from_filter_size(filter_size: int) -> int:
    # Each entry uses 16 bytes in the filter.
    return filter_size // 16


def query_size(n: int) -> int:
    return n * 16


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Run sortbloom sweeps and capture JSONL output"
    )
    parser.add_argument(
        "--experiment",
        type=str,
        default="",
        help="Custom note for the current experiment",
    )
    parser.add_argument(
        "--out-dir", type=str, default="results", help="Output directory (must exist)"
    )
    parser.add_argument(
        "--low-bits", type=int, default=21, help="Inclusive low end of n_bits range"
    )
    parser.add_argument(
        "--high-bits", type=int, default=27, help="Inclusive high end of n_bits range"
    )
    parser.add_argument(
        "--binary",
        type=str,
        default="./target/release/sortbloom",
        help="Path to the sortbloom binary",
    )
    parser.add_argument(
        "--hasher",
        type=str,
        required=True,
        help=(
            "Comma-separated list of hasher kinds to run (e.g. "
            "'fast,mod,rangemapping'). Each will be paired with all --sort variants "
            "parsed from the binary help output."
        ),
    )
    parser.add_argument(
        "--sort-options-file",
        type=str,
        default=None,
        help=(
            "Optional path to a file listing sort variants (one per line) to use "
            "instead of parsing them from the binary help output."
        ),
    )
    parser.add_argument(
        "--run-count",
        type=int,
        default=1,
        help="Number of times to repeat the experiment sweep (default: 1).",
    )
    return parser.parse_args()


def build_latest_or_exit() -> None:
    # Ensure the latest binary is built before running experiments
    print("Ensuring latest build via `make`...")
    try:
        rc = subprocess.call(["make"])  # inherit stdout/stderr for visibility
    except FileNotFoundError:
        print("ERROR: `make` not found in PATH. Please install make.", file=sys.stderr)
        sys.exit(7)
    except Exception as e:
        print(f"ERROR: Failed to invoke make: {e}", file=sys.stderr)
        sys.exit(7)
    if rc != 0:
        print(f"ERROR: `make` failed with exit code {rc}. Aborting.", file=sys.stderr)
        sys.exit(rc)


def set_cpu_freq(level) -> None:
    low = "1.2G"
    high = "4.3G"
    governer = "powersave"
    if level == "max":
        governer = "performance"
        low = "4.1G"

    # Ensure the latest binary is built before running experiments
    print("Setting CPU freq to be max")
    try:
        rc = subprocess.call(
            [
                "sudo",
                "cpupower",
                "frequency-set",
                "-g",
                governer,
                "--min",
                low,
                "--max",
                high,
            ]
        )  # inherit stdout/stderr for visibility
        rc = subprocess.call(
            ["sudo", "cpupower", "frequency-info"]
        )  # inherit stdout/stderr for visibility
    except Exception as e:
        print(f"ERROR: Failed to invoke make: {e}", file=sys.stderr)
        sys.exit(7)


def ensure_out_dir(path: str) -> None:
    if not os.path.isdir(path):
        print(f"ERROR: Output directory does not exist: {path}", file=sys.stderr)
        sys.exit(1)


def next_results_path(out_dir: str) -> str:
    pattern = re.compile(r"^results-(\d+)\.jsonl$")
    existing = set()
    for name in os.listdir(out_dir):
        m = pattern.match(name)
        if m:
            existing.add(int(m.group(1)))

    # Choose the next index as (max existing) + 1, or 0 if none exist
    if existing:
        n = max(existing) + 1
    else:
        n = 0
    filename = f"results-{n:04d}.jsonl"
    return os.path.join(out_dir, filename)


def collect_git_info() -> dict:
    def run(cmd):
        return subprocess.check_output(cmd, stderr=subprocess.DEVNULL).decode().strip()

    info = {
        "current_commit_tag": None,
        "current_branch_name": None,
        "current_commit_message": None,
        "dirty": None,
    }
    # Best-effort: use describe for a tag or short SHA if no tags
    info["current_commit_tag"] = run(["git", "describe", "--tags", "--always"]) or None
    info["current_branch_name"] = (
        run(["git", "rev-parse", "--abbrev-ref", "HEAD"]) or None
    )
    info["current_commit_message"] = run(["git", "log", "-1", "--pretty=%s"]) or None
    dirty = run(["git", "status", "--porcelain"])  # non-empty => dirty
    info["dirty"] = bool(dirty)
    return info


def collect_host_info() -> dict:
    # Assume Linux, but verify and warn if not
    system = platform.system()
    if system != "Linux":
        print(f"WARNING: Non-Linux host detected: {system}", file=sys.stderr)
    hostname = socket.gethostname()
    kernel = platform.release()
    arch = platform.machine()
    cpu_model = None
    with open("/proc/cpuinfo", "r") as f:
        for line in f:
            if line.lower().startswith("model name"):
                cpu_model = line.split(":", 1)[1].strip()
                break
    return {
        "hostname": hostname,
        "os": system,
        "kernel": kernel,
        "arch": arch,
        "cpu_model": cpu_model,
    }


def _run_lscpu_keyvals() -> Optional[dict]:
    """Return lscpu output as a normalized key->value map.

    Tries JSON (-J) first.
    """
    out = subprocess.check_output(["lscpu", "-J"], stderr=subprocess.DEVNULL).decode()
    obj = json.loads(out)
    items = obj.get("lscpu") or []
    kv = {}
    for it in items:
        field = (it.get("field") or "").strip()
        data = (it.get("data") or "").strip()
        if not field:
            continue
        if field.endswith(":"):
            field = field[:-1]
        kv[field.lower()] = data
    return kv


def collect_lscpu_info() -> dict:
    """Summarize interesting CPU features and topology from lscpu.

    Includes booleans for AVX2 and AVX-512 support, a small set of topology
    numbers, vendor and virtualization hints, and min/max MHz if available.
    """
    kv = _run_lscpu_keyvals()
    if not kv:
        return {"available": False}

    # Flags/features
    flags_raw = kv.get("flags") or kv.get("features") or ""
    flags = [f.strip().lower() for f in flags_raw.split() if f.strip()]
    has_avx2 = "avx2" in flags
    avx512_list = sorted([f for f in flags if f.startswith("avx512")])
    has_avx512 = len(avx512_list) > 0

    # Helper to parse ints/floats safely from known keys
    def _as_int(key: str) -> Optional[int]:
        v = kv.get(key)
        if v is None:
            return None
        try:
            return int(str(v).split()[0])
        except Exception:
            return None

    def _as_float(key: str) -> Optional[float]:
        v = kv.get(key)
        if v is None:
            return None
        try:
            return float(str(v).split()[0])
        except Exception:
            return None

    # Topology fields (names depend on lscpu output; using lowercase keys)
    topo = {
        "cpus": _as_int("cpu(s)"),
        "threads_per_core": _as_int("thread(s) per core"),
        "cores_per_socket": _as_int("core(s) per socket"),
        "sockets": _as_int("socket(s)"),
        "numa_nodes": _as_int("numa node(s)"),
    }

    info = {
        "available": True,
        "vendor_id": kv.get("vendor id"),
        "cpu_family": kv.get("cpu family"),
        "model": kv.get("model"),
        "stepping": kv.get("stepping"),
        "virtualization": kv.get("virtualization"),
        "hypervisor_vendor": kv.get("hypervisor vendor"),
        "mhz_min": _as_float("cpu min mhz"),
        "mhz_max": _as_float("cpu max mhz"),
        "avx2": has_avx2,
        "avx512": has_avx512,
        "topology": topo,
    }

    if avx512_list:
        info["avx512_features"] = avx512_list

    # Optionally include a trimmed sample of other notable flags
    interesting = [
        "avx",
        "fma",
        "bmi1",
        "bmi2",
        "aes",
        "sha_ni",
        "sse4_2",
        "popcnt",
        "asimd",  # ARM NEON equivalent
    ]
    sample = sorted([f for f in flags if f in interesting])
    if sample:
        info["flags_sample"] = sample

    return info


def _read_cpu_temperature_celsius() -> Optional[float]:
    # Best-effort: try thermal zones first, then hwmon. Values are typically in millidegrees.
    def _read_temp_file(path: str) -> float | None:
        try:
            with open(path, "r") as f:
                v = f.read().strip()
            if not v:
                return None
            val = float(v)
            if val > 200:  # likely millideg
                val = val / 1000.0
            return val
        except Exception:
            return None

    # Prefer CPU/package zones
    thermal_base = "/sys/class/thermal"
    if os.path.isdir(thermal_base):
        zones = sorted(
            [z for z in os.listdir(thermal_base) if z.startswith("thermal_zone")]
        )
        candidates = []
        for z in zones:
            tpath = os.path.join(thermal_base, z, "type")
            typ = None
            try:
                with open(tpath, "r") as f:
                    typ = f.read().strip().lower()
            except Exception:
                pass
            temp = _read_temp_file(os.path.join(thermal_base, z, "temp"))
            if temp is None:
                continue
            if typ and any(k in typ for k in ("pkg", "cpu", "x86_pkg", "core")):
                return temp
            candidates.append(temp)
        if candidates:
            return max(candidates)  # best-effort

    # Fallback: hwmon
    # TODO: This fallback, as written, is bullshit. Fix this in future
    # hwmon_base = "/sys/class/hwmon"
    # if os.path.isdir(hwmon_base):
    #     temps: list[float] = []
    #     for name in os.listdir(hwmon_base):
    #         npath = os.path.join(hwmon_base, name)
    #         if not os.path.isdir(npath):
    #             continue
    #         for entry in os.listdir(npath):
    #             if entry.startswith("temp") and entry.endswith("_input"):
    #                 t = _read_temp_file(os.path.join(npath, entry))
    #                 if t is not None:
    #                     temps.append(t)
    #     if temps:
    #         return max(temps)
    return None


def _collect_cpu_cache_info() -> dict:
    # Read CPU0 cache hierarchy; sizes like '32K', '256K', '12288K' etc.
    base = "/sys/devices/system/cpu/cpu0/cache"
    raw_bytes: dict[str, int] = {}
    per_level: dict[str, dict[str, int]] = {}
    total_kb = 0
    if os.path.isdir(base):
        for idx in os.listdir(base):
            ipath = os.path.join(base, idx)
            if not os.path.isdir(ipath):
                continue
            size_path = os.path.join(ipath, "size")
            level_path = os.path.join(ipath, "level")
            typ_path = os.path.join(ipath, "type")
            try:
                with open(size_path, "r") as f:
                    s = f.read().strip().upper()  # e.g., '32K', '256K', '12M'
                with open(level_path, "r") as f:
                    level = f.read().strip()
                with open(typ_path, "r") as f:
                    ctype = (
                        f.read().strip().lower()
                    )  # 'data' | 'instruction' | 'unified'
            except Exception:
                continue

            # Parse size
            mult = 1
            if s.endswith("K"):
                mult = 1024
                sval = s[:-1]
            elif s.endswith("M"):
                mult = 1024 * 1024
                sval = s[:-1]
            else:
                sval = s
            try:
                bytes_val = int(float(sval) * mult)
            except Exception:
                continue

            key = f"L{level}_{ctype}"
            raw_bytes[key] = raw_bytes.get(key, 0) + bytes_val
            lvl = f"L{level}"
            per_level.setdefault(lvl, {})
            per_level[lvl][ctype] = per_level[lvl].get(ctype, 0) + bytes_val
            total_kb += bytes_val // 1024

    # Build raw_kb
    raw_kb = {k: v // 1024 for k, v in raw_bytes.items()}

    # Build data-focused view with fallback to unified if data missing
    data_kb: dict[str, int] = {}
    for lvl, tmap in per_level.items():
        if "data" in tmap:
            data_kb[lvl] = tmap["data"] // 1024
        elif "unified" in tmap:
            data_kb[lvl] = tmap["unified"] // 1024

    out: dict[str, object] = {"raw_kb": raw_kb, "data_kb": data_kb}
    if total_kb > 0:
        out["total_kb_cpu0"] = total_kb
    return out


def rustc_version() -> str:
    return subprocess.check_output(["rustc", "--version"]).decode().strip()


def _read_proc_stat_cpu_totals() -> tuple[int, int] | None:
    # Returns (total_time, idle_time) across all CPUs from /proc/stat
    with open("/proc/stat", "r") as f:
        first = f.readline()
    if not first.startswith("cpu "):
        return None
    parts = first.split()
    # Fields: user nice system idle iowait irq softirq steal guest guest_nice
    # We use the standard Linux utilisation formula
    vals = [int(p) for p in parts[1:11]]
    user, nice, system, idle, iowait, irq, softirq, steal, guest, guest_nice = vals
    idle_all = idle + iowait
    non_idle = user + nice + system + irq + softirq + steal
    total = idle_all + non_idle
    return total, idle_all


def _cpu_utilization_percent(sample_ms: int = 120) -> float | None:
    # Best-effort instantaneous CPU utilisation using /proc/stat delta
    t1 = _read_proc_stat_cpu_totals()
    if t1 is None:
        return None
    time.sleep(max(0.001, sample_ms / 1000.0))
    t2 = _read_proc_stat_cpu_totals()
    if t2 is None:
        return None
    totald = t2[0] - t1[0]
    idled = t2[1] - t1[1]
    if totald <= 0:
        return None
    util = (totald - idled) / totald * 100.0
    # Clamp to [0, 100]
    if util < 0:
        util = 0.0
    elif util > 100:
        util = 100.0
    return util


def _read_loadavg() -> dict:
    out = {"1m": None, "5m": None, "15m": None}
    with open("/proc/loadavg", "r") as f:
        parts = f.read().split()
    out["1m"] = float(parts[0])
    out["5m"] = float(parts[1])
    out["15m"] = float(parts[2])
    return out


def _read_meminfo() -> dict:
    # Returns memory and swap stats in kB
    info: dict[str, int] = {}
    with open("/proc/meminfo", "r") as f:
        for line in f:
            if ":" not in line:
                continue
            k, v = line.split(":", 1)
            v = v.strip()
            if v.endswith(" kB"):
                v = v[:-3].strip()
            info[k] = int(v)

    total = info.get("MemTotal")
    available = info.get("MemAvailable")
    mem_used = None
    mem_used_pct = None
    if total is not None and available is not None and total > 0:
        mem_used = total - available
        mem_used_pct = (mem_used / total) * 100.0

    swap_total = info.get("SwapTotal")
    swap_free = info.get("SwapFree")
    swap_used = None
    if swap_total is not None and swap_free is not None:
        swap_used = swap_total - swap_free

    return {
        "memory": {
            "total_kb": total,
            "available_kb": available,
            "used_kb": mem_used,
            "used_percent": mem_used_pct,
        },
        "swap": {
            "total_kb": swap_total,
            "free_kb": swap_free,
            "used_kb": swap_used,
        },
    }


def _read_disk_root() -> dict:
    st = os.statvfs("/")
    total = st.f_frsize * st.f_blocks
    free = st.f_frsize * st.f_bavail
    used = total - free
    used_pct = (used / total * 100.0) if total > 0 else None
    return {
        "total_bytes": int(total),
        "free_bytes": int(free),
        "used_bytes": int(used),
        "used_percent": used_pct,
    }


def _read_uptime_seconds() -> float | None:
    with open("/proc/uptime", "r") as f:
        return float(f.read().split()[0])


def collect_system_utilization() -> dict:
    # Aggregate best-effort utilisation snapshot
    cpu_util = _cpu_utilization_percent()
    loadavg = _read_loadavg()
    memswap = _read_meminfo()
    disk_root = _read_disk_root()
    uptime = _read_uptime_seconds()
    cpu_count = os.cpu_count()
    return {
        "cpu": {
            "util_percent": cpu_util,
            "loadavg": loadavg,
            "count": cpu_count,
        },
        "memory": memswap.get("memory"),
        "swap": memswap.get("swap"),
        "disk_root": disk_root,
        "uptime_seconds": uptime,
    }


def collect_w_output() -> str | None:
    # Keep headers for clarity; text will be JSON-escaped as needed
    return subprocess.check_output(["w"], stderr=subprocess.DEVNULL).decode()


def collect_cpu_freq_info_output() -> str | None:
    # Keep headers for clarity; text will be JSON-escaped as needed
    return subprocess.check_output(
        ["cpupower", "frequency-info"], stderr=subprocess.DEVNULL
    ).decode()


def write_run_meta(fp, experiment: str, run_count: int) -> None:
    meta = {
        "kind": "run_meta",
        "experiment": experiment,
        "run_id": str(uuid.uuid4()),
        "ts": _dt.datetime.now(_dt.timezone.utc).isoformat(),
        "git": collect_git_info(),
        "host": collect_host_info(),
        "lscpu": collect_lscpu_info(),
        "rustc_version": rustc_version(),
        "cpu_temp_c": _read_cpu_temperature_celsius(),
        "cpu_cache": _collect_cpu_cache_info(),
        "run_count": run_count,
        "w_output": collect_w_output(),
        "cpu_freq": collect_cpu_freq_info_output(),
        "system_utilization": collect_system_utilization(),
    }
    fp.write(json.dumps(meta) + "\n")
    fp.flush()


def validate_and_write_line(raw_line: str, fp) -> None:
    line = raw_line.strip()
    if not line:
        return
    try:
        obj = json.loads(line)
    except json.JSONDecodeError:
        print("WARNING: Non-JSON output from binary:", file=sys.stderr)
        print(raw_line.rstrip(), file=sys.stderr)
        return

    if not isinstance(obj, dict):
        print(type(obj), line)
        return

    # Validate keys
    allowed = {"args", "bf_results"}
    extra = set(obj.keys()) - allowed
    if extra:
        print(
            f"WARNING: Unexpected keys in JSON output: {sorted(extra)}", file=sys.stderr
        )

    # Write the original raw JSON line to preserve formatting
    fp.write(line + "\n")
    fp.flush()


def _split_sections_by_separator(lines: list[str], separator: str) -> list[list[str]]:
    """Split a list of lines into sections separated by `separator`."""
    sections: list[list[str]] = []
    current: list[str] = []
    for raw in lines:
        if separator in raw.strip():
            sections.append(current)
            current = []
        else:
            current.append(raw)
    sections.append(current)
    return sections


def read_sort_variants_from_file(path: str) -> list[SortSpec]:
    try:
        with open(path, "r") as f:
            variants: list[SortSpec] = []
            lines = f.readlines()

            sections = _split_sections_by_separator(lines, SORT_FILE_SECTION_SEPARATOR)

            assert SECTION_INDEX_SORT_OPTIONS < len(sections)

            lines_for_sorts = sections[SECTION_INDEX_SORT_OPTIONS]

            random.shuffle(lines_for_sorts)
            for raw in lines_for_sorts:
                line = raw.strip()
                if not line or line.startswith("#"):
                    continue
                # Support CSV lines: sort[,l2[,l3]]
                if "," in line:
                    parts = [p.strip() for p in line.split(",")]
                    if not parts or not parts[0]:
                        print("NO SORT VARIANT PROVIDED, SKIPPING THE ROW", line)
                        continue
                    sort = parts[0]
                    l2 = parts[1] if len(parts) > 1 and parts[1] != "" else None
                    l3 = parts[2] if len(parts) > 2 and parts[2] != "" else None
                    bfkind = parts[3] if len(parts) > 3 and parts[3] != "" else None
                    variants.append((sort, l2, l3, bfkind))
                else:
                    variants.append((line, None, None, None))
    except OSError as e:
        print(f"ERROR: Failed to read sort options file '{path}': {e}", file=sys.stderr)
        sys.exit(8)

    if not variants:
        print(
            f"ERROR: Sort options file '{path}' did not contain any variants.",
            file=sys.stderr,
        )
        sys.exit(9)
    return variants


def read_filter_sizes_from_file(path: str) -> list[int]:
    """Read filter sizes from the first section of the file.

    The file is split into sections by lines containing
    SORT_FILE_SECTION_SEPARATOR. The SECTION_INDEX_FILTER_SIZES section is
    interpreted as newline-separated scale factors for the Bloom filter size.
    Each value v is converted to bytes as:
        filter_size_bits = int(v) * 8 * 1024 * 1024
    """
    try:
        with open(path, "r") as f:
            lines = f.readlines()
    except OSError as e:
        print(
            f"ERROR: Failed to read filter sizes from file '{path}': {e}",
            file=sys.stderr,
        )
        sys.exit(8)

    # If there is no separator, there is no dedicated filter-size section.
    if not any(SORT_FILE_SECTION_SEPARATOR in raw.strip() for raw in lines):
        return []

    sections = _split_sections_by_separator(lines, SORT_FILE_SECTION_SEPARATOR)
    if len(sections) <= SECTION_INDEX_FILTER_SIZES:
        print("No explicit filter-size section; caller fallbacks to cmd")
        return []

    filter_sizes: list[int] = []
    for raw in sections[SECTION_INDEX_FILTER_SIZES]:
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        try:
            scale = int(line)
        except ValueError:
            print(
                f"WARNING: Skipping invalid filter size value '{line}' "
                f"in '{path}' (expected integer).",
                file=sys.stderr,
            )
            continue
        filter_size_bits = scale * 8 * 1024 * 1024
        filter_sizes.append(filter_size_bits)

    if not filter_sizes:
        print(
            f"WARNING: No valid filter sizes found in {SECTION_INDEX_FILTER_SIZES} section of '{path}'.",
            file=sys.stderr,
        )

    return filter_sizes


def read_pos_queries_from_file(path: str) -> list[float]:
    """Read pos-queries values from the third section of the file.

    The file is split into sections by lines containing
    SORT_FILE_SECTION_SEPARATOR. The SECTION_INDEX_POS_QUERIES section is
    interpreted as newline-separated floating-point values that are passed
    directly to the binary as --pos-queries (typically between 0 and 100).

    If the section is missing or contains no valid values, this falls back to
    [0.0] and prints a warning.
    """
    try:
        with open(path, "r") as f:
            lines = f.readlines()
    except OSError as e:
        print(
            f"ERROR: Failed to read pos-queries from file '{path}': {e}",
            file=sys.stderr,
        )
        sys.exit(8)

    sections = _split_sections_by_separator(lines, SORT_FILE_SECTION_SEPARATOR)
    if len(sections) <= SECTION_INDEX_POS_QUERIES:
        print(
            f"WARNING: No explicit pos-queries section found in '{path}'; "
            "defaulting to [0.0].",
            file=sys.stderr,
        )
        return [0.0]

    values: list[float] = []
    for raw in sections[SECTION_INDEX_POS_QUERIES]:
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        try:
            v = float(line)
        except ValueError:
            print(
                f"WARNING: Skipping invalid pos-queries value '{line}' "
                f"in '{path}' (expected float).",
                file=sys.stderr,
            )
            continue
        values.append(v)

    if not values:
        print(
            f"WARNING: No valid pos-queries values found in section "
            f"{SECTION_INDEX_POS_QUERIES} of '{path}'; defaulting to [0.0].",
            file=sys.stderr,
        )
        return [0.0]

    return values


def run_once(
    binary_path: str,
    filter_size: int,
    hasher: str,
    sort_spec: SortSpec,
    fp,
    seed: Optional[int] = None,
    pos_queries: Optional[float] = None,
) -> None:
    num_entries = num_entries_from_filter_size(filter_size)
    probe_count = query_size(num_entries)
    sort, l2, l3, bfkind = sort_spec

    cmd = [
        "setarch",
        "-R",
        binary_path,
        f"--filter-size={filter_size}",
        f"--num-entries={num_entries}",
        f"--probe-count={probe_count}",
        f"--hasher={hasher}",
        f"--sort={sort}",
    ]
    if l2 is not None:
        cmd.append(f"--l2={l2}")
    if l3 is not None:
        cmd.append(f"--l3={l3}")
    if pos_queries is not None:
        cmd.append(f"--pos-queries={pos_queries}")
    if bfkind is not None:
        cmd.append(f"--bfkind={bfkind}")
    if seed is not None:
        cmd.append(f"--seed={seed}")

    if "lds" in hasher and bfkind is not None:
        print(f"skipping because {hasher} and {bfkind} conflict")
        return
    if "lds" in hasher and "no-sort" in sort:
        print(
            f"skipping because {hasher} and {sort} conflict. Edit this file to run lds and no-sort together."
        )
        return

    print(f"Running: {' '.join(cmd)}")
    with subprocess.Popen(
        cmd,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        bufsize=1,
        universal_newlines=True,
    ) as proc:
        assert proc.stdout is not None
        for out_line in proc.stdout:
            validate_and_write_line(out_line, fp)
        rc = proc.wait()
        if rc != 0:
            # Print stderr to help debugging
            err = proc.stderr.read() if proc.stderr else ""
            print(f"ERROR: Binary exited with code {rc}", file=sys.stderr)
            if err:
                print(err, file=sys.stderr)
            sys.exit(rc)

    time.sleep(4)
    print("---")


def run_sweep(
    binary_path: str,
    low_bits: int,
    high_bits: int,
    hashers: list[str],
    sorts: list[SortSpec],
    pos_queries: float,
    fp,
    seed: Optional[int] = None,
) -> None:
    for idx_bits, n_bits in enumerate(range(low_bits, high_bits + 1)):
        # Visual separator on STDOUT to denote next experiment is about to start
        set_cpu_freq("max")
        print(f"---- bloom size {n_bits + 4} ----")
        exp_start = time.perf_counter()
        for hasher in hashers:
            for sort_spec in sorts:
                num_entries = 2**n_bits
                filter_size = bv_size(num_entries)
                run_once(
                    binary_path,
                    filter_size,
                    hasher,
                    sort_spec,
                    fp,
                    seed=seed,
                    pos_queries=pos_queries,
                )
        elapsed = time.perf_counter() - exp_start
        # Write experiment-end summary line
        n = 2**n_bits
        summary = {
            "kind": "experiment_end",
            "n_bits": n_bits,
            "filter_size": bv_size(n),
            "elapsed_seconds": elapsed,
            "end_cpu_temp_c": _read_cpu_temperature_celsius(),
            "ts": _dt.datetime.now(_dt.timezone.utc).isoformat(),
        }
        fp.write(json.dumps(summary) + "\n")
        fp.flush()
        set_cpu_freq("min")
        time.sleep(120)


def run_sweep_filter_sizes(
    binary_path: str,
    filter_sizes: list[int],
    hashers: list[str],
    sorts: list[SortSpec],
    pos_queries: float,
    fp,
    seed: Optional[int] = None,
) -> None:
    for idx, filter_size in enumerate(filter_sizes):
        exp_start = time.perf_counter()
        set_cpu_freq("max")
        print(f"---- bloom filter size {filter_size / (8 * 1024 * 1024)}MB ----")
        for hasher in hashers:
            for sort_spec in sorts:
                run_once(
                    binary_path,
                    filter_size,
                    hasher,
                    sort_spec,
                    fp,
                    seed=seed,
                    pos_queries=pos_queries,
                )
        elapsed = time.perf_counter() - exp_start
        summary = {
            "kind": "experiment_end",
            "filter_size": filter_size,
            "num_entries": num_entries_from_filter_size(filter_size),
            "elapsed_seconds": elapsed,
            "end_cpu_temp_c": _read_cpu_temperature_celsius(),
            "ts": _dt.datetime.now(_dt.timezone.utc).isoformat(),
        }
        fp.write(json.dumps(summary) + "\n")
        fp.flush()
        set_cpu_freq("min")
        global count, r_count
        if r_count != count:
            time.sleep(120)


def update_latest_symlink(out_dir: str, target_path: str) -> None:
    link_path = os.path.join(out_dir, "latest.jsonl")
    # Use a relative target inside out_dir for portability
    rel_target = os.path.basename(target_path)
    try:
        if os.path.islink(link_path) or os.path.exists(link_path):
            os.unlink(link_path)
        os.symlink(rel_target, link_path)
    except Exception as e:
        print(f"WARNING: Failed to update latest.jsonl symlink: {e}", file=sys.stderr)


def main():
    random.seed(42)
    args = parse_args()
    ensure_out_dir(args.out_dir)
    # Build the project to ensure we run the latest binary
    build_latest_or_exit()

    # Parse requested hasher kinds
    hashers = [h.strip() for h in args.hasher.split(",") if h.strip()]
    if not hashers:
        print(
            "ERROR: --hasher must specify at least one value (comma-separated).",
            file=sys.stderr,
        )
        sys.exit(6)

    if args.run_count < 1:
        print("ERROR: --run-count must be >= 1.", file=sys.stderr)
        sys.exit(10)

    out_dir = args.out_dir
    result_path = next_results_path(out_dir)
    # Open new results file and write run meta header
    with open(result_path, "w") as f:
        write_run_meta(f, args.experiment, args.run_count)

        filter_sizes: list[int] = []
        pos_queries_values: list[float] = [0.0]
        if args.sort_options_file:
            filter_sizes = read_filter_sizes_from_file(args.sort_options_file)
            if filter_sizes:
                print(
                    "Filter sizes (bytes) supplied by file '{}': {}".format(
                        args.sort_options_file,
                        ", ".join(str(sz) for sz in filter_sizes),
                    )
                )
            pos_queries_values = read_pos_queries_from_file(args.sort_options_file)
            if pos_queries_values:
                print(
                    "Pos-queries values supplied by file '{}': {}".format(
                        args.sort_options_file,
                        ", ".join(str(v) for v in pos_queries_values),
                    )
                )

        global count, r_count
        count = args.run_count * len(pos_queries_values);

        for run_idx in range(args.run_count):
            for pos_queries in pos_queries_values:
                r_count += 1
                # Every run_count, read the file again, and probably shuffle it.
                assert args.sort_options_file
                if args.sort_options_file:
                    sorts = read_sort_variants_from_file(args.sort_options_file)
                    print(
                        "Sort variants supplied by file '{}': {}".format(
                            args.sort_options_file,
                            ", ".join(s[0] for s in sorts),
                        )
                    )

                seed = None if run_idx == 0 else run_idx
                if filter_sizes:
                    run_sweep_filter_sizes(
                        args.binary,
                        filter_sizes,
                        hashers,
                        sorts,
                        pos_queries,
                        f,
                        seed=seed,
                    )
                else:
                    if args.low_bits > args.high_bits:
                        print(
                            f"ERROR: --low-bits ({args.low_bits}) must be <= --high-bits ({args.high_bits})",
                            file=sys.stderr,
                        )
                        sys.exit(2)
                    run_sweep(
                        args.binary,
                        args.low_bits,
                        args.high_bits,
                        hashers,
                        sorts,
                        pos_queries,
                        f,
                        seed=seed,
                    )

    set_cpu_freq("min")
    update_latest_symlink(out_dir, result_path)
    print("Bye!")


if __name__ == "__main__":
    main()