Skip to content

k4bench.labels

k4bench.labels

Human labels for the identifiers that name a benchmark run.

A run is identified by three machine strings — a detector name, an EOS sample directory (p8_ee_Zbb_ecm91) and an LCG/Spack platform triplet (x86_64-almalinux9-gcc14.2.0-opt). This module turns the latter two into something a person reads, and is the single place that knows their layouts.

It lives at the top level, and depends on nothing, because its three consumers sit in different layers and must not import each other: the e-group email and the dashboard display these labels, while the blame ranker puts them in the prompt a model judges with (:mod:k4bench.blame.rank). That last consumer is why the vocabulary below is behaviour, not styling — widening :data:_PARTICLE_LABELS changes what the model is told is being simulated, so it is versioned and tested here rather than tweaked as presentation.

Every function degrades to the raw string when a name does not match a known layout: an unrecognized future sample reads plainly instead of being guessed at and rendered as garbled physics.

PlatformLabel dataclass 

PlatformLabel(architecture: str, os: str, compiler: str, build_type: str)

A recognized platform triplet, split into the parts that mean something on their own — a caller that needs only the compiler or only the build type (an opt vs. dbg build reads differently for a codegen change) gets it from here rather than re-splitting the slug and re-deriving the layout this module already decided.

pretty_sample 

pretty_sample(sample: str) -> str

Human-readable label for an EOS sample directory name.

Covers the two naming layouts currently produced by the benchmark: single-particle guns (single_{particle}_{energy}) and generator samples ({gen}_{beams}_{process}_ecm{energy}, e.g. p8_ee_Zbb_ecm91). Anything else is returned unchanged.

Source code in k4bench/labels.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def pretty_sample(sample: str) -> str:
    """Human-readable label for an EOS sample directory name.

    Covers the two naming layouts currently produced by the benchmark:
    single-particle guns (``single_{particle}_{energy}``) and generator
    samples (``{gen}_{beams}_{process}_ecm{energy}``, e.g.
    ``p8_ee_Zbb_ecm91``). Anything else is returned unchanged.
    """
    tokens = sample.split("_")
    if (
        len(tokens) == 3 and tokens[0] == "single"
        and re.fullmatch(r"\d+(\.\d+)?(GeV|MeV|TeV)", tokens[2])
    ):
        particle = _PARTICLE_LABELS.get(tokens[1], tokens[1])
        return f"Single {particle} · {tokens[2]}"

    if len(tokens) == 4 and re.fullmatch(r"ecm\d+(\.\d+)?", tokens[3]):
        gen = _GENERATOR_LABELS.get(tokens[0], tokens[0])
        beams = _BEAM_LABELS.get(tokens[1], tokens[1])
        process = tokens[2]
        if m := _PROCESS_SPLIT_RE.match(process):
            process = f"{m.group(1)} → {m.group(2)}"
        ecm = tokens[3].removeprefix("ecm")
        if ecm.endswith(".0"):
            ecm = ecm[:-2]
        return f"{gen}: {beams} → {process} ({ecm} GeV)"

    return sample

describe_platform 

describe_platform(platform: str) -> PlatformLabel | None

platform split into its four labelled parts, or None when it does not match the {arch}-{os}{ver}-{compiler}{ver}-{type} layout, e.g. x86_64-almalinux9-gcc14.2.0-opt -> x86_64 / AlmaLinux 9 / GCC 14.2.0 / optimized.

Source code in k4bench/labels.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def describe_platform(platform: str) -> PlatformLabel | None:
    """*platform* split into its four labelled parts, or ``None`` when it does
    not match the ``{arch}-{os}{ver}-{compiler}{ver}-{type}`` layout, e.g.
    ``x86_64-almalinux9-gcc14.2.0-opt`` -> ``x86_64`` / ``AlmaLinux 9`` /
    ``GCC 14.2.0`` / ``optimized``."""
    parts = platform.split("-")
    if len(parts) != 4:
        return None
    arch, os_part, compiler_part, build = parts
    os_m = _VERSIONED_TOKEN_RE.match(os_part)
    compiler_m = _VERSIONED_TOKEN_RE.match(compiler_part)
    if not os_m or not compiler_m:
        return None
    return PlatformLabel(
        architecture=arch,
        os=f"{_OS_LABELS.get(os_m.group(1).lower(), os_m.group(1).capitalize())} "
           f"{os_m.group(2)}",
        compiler=f"{_COMPILER_LABELS.get(compiler_m.group(1).lower(), compiler_m.group(1).upper())} "
                 f"{compiler_m.group(2)}",
        build_type=_BUILD_TYPE_LABELS.get(build, build),
    )

pretty_platform 

pretty_platform(platform: str) -> str

One-line platform label, e.g. x86_64-almalinux9-gcc14.2.0-opt -> AlmaLinux 9 · GCC 14.2.0 (optimized). Falls back to the raw string for anything :func:describe_platform does not recognize.

The architecture is deliberately omitted: every run group in one report shares it, so it carries no information in a UI label. Callers that need it (the ranker's run context) use :func:describe_platform.

Source code in k4bench/labels.py 
116
117
118
119
120
121
122
123
124
125
126
127
def pretty_platform(platform: str) -> str:
    """One-line platform label, e.g. ``x86_64-almalinux9-gcc14.2.0-opt`` ->
    ``AlmaLinux 9 · GCC 14.2.0 (optimized)``. Falls back to the raw string for
    anything :func:`describe_platform` does not recognize.

    The architecture is deliberately omitted: every run group in one report
    shares it, so it carries no information in a UI label. Callers that need it
    (the ranker's run context) use :func:`describe_platform`."""
    label = describe_platform(platform)
    if label is None:
        return platform
    return f"{label.os} · {label.compiler} ({label.build_type})"