tetration 0.1.1

Tetration tensor file format: Rust library (tetration) and tet CLI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

#!/usr/bin/env python3
"""Unified CLI for fixture generation and large-format benchmarks."""

from __future__ import annotations

import argparse
import os
import sys

from benchmark.constants import DEFAULT_FORMATS, FormatName
from benchmark.dispatch import run_benchmark
from generate.dispatch import GENERATE_TARGETS, run_target


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="tetration fixture generation and large-format benchmarks",
    )
    sub = parser.add_subparsers(dest="command", required=True)

    gen = sub.add_parser(
        "generate",
        help="generate HDF5 / NetCDF / Zarr fixtures",
        description="Generate small (tracked) and large (gitignored) fixture tensors.",
    )
    gen.add_argument(
        "target",
        nargs="?",
        choices=GENERATE_TARGETS,
        default="small",
        help=(
            "small: tracked baseline + groups/cf/zarr; "
            "large: ~20 GiB total across h5/nc/zarr (untracked); "
            "large-*: one ~6.67 GiB file for that format (untracked); "
            "extra-large-*: one 20 GiB file for that format (untracked); "
            "all: small + large suite only"
        ),
    )
    gen.add_argument(
        "-q",
        "--quiet",
        action="store_true",
        help="no tqdm bars or status lines",
    )

    bench = sub.add_parser(
        "bench",
        help="benchmark native source ops vs `.tet` query",
        description=(
            "For each tier/format: generate once, convert once, then time tier-A/B "
            "scalar ops on source (when comparable) and `.tet`."
        ),
    )
    bench.add_argument(
        "formats",
        nargs="*",
        choices=DEFAULT_FORMATS,
        metavar="format",
        help="formats to bench (default: h5 netcdf zarr)",
    )
    bench.add_argument(
        "--ops",
        nargs="*",
        metavar="OP",
        help="comma-separated ops (default: mean,sum,min,max,count,std,var)",
    )
    bench.add_argument(
        "--skip-ops",
        action="store_true",
        help="time convert only (skip source and .tet ops)",
    )
    bench.add_argument(
        "--skip-mean",
        action="store_true",
        help=argparse.SUPPRESS,
    )
    bench.add_argument(
        "--skip-query",
        action="store_true",
        help=argparse.SUPPRESS,
    )
    bench.add_argument(
        "--jobs",
        type=int,
        default=int(os.environ.get("BENCH_JOBS", "0")),
        help="tet convert --jobs (0 = auto: host parallelism, max 64)",
    )
    bench.add_argument(
        "--run-id",
        metavar="ID",
        help="archive under bench_results/runs/ID/ (default: <git>_<UTC timestamp>)",
    )
    bench.add_argument(
        "--no-clobber",
        action="store_true",
        help="fail if --run-id directory already exists",
    )

    return parser


def main(argv: list[str] | None = None) -> int:
    args = _build_parser().parse_args(argv)
    if args.command == "generate":
        run_target(args.target, quiet=args.quiet)
        return 0
    if args.command == "bench":
        skip_ops = args.skip_ops or args.skip_mean or args.skip_query
        formats: list[FormatName] = list(args.formats or DEFAULT_FORMATS)
        return run_benchmark(
            formats=formats,
            ops=args.ops,
            skip_ops=skip_ops,
            jobs=args.jobs,
            run_id=args.run_id,
            no_clobber=args.no_clobber,
        )
    return 1


def main_generate(argv: list[str] | None = None) -> int:
    """Backward-compatible entry for `generate-fixtures`."""
    return main(["generate", *(argv if argv is not None else sys.argv[1:])])


def main_bench(argv: list[str] | None = None) -> int:
    """Backward-compatible entry for `bench-large`."""
    return main(["bench", *(argv if argv is not None else sys.argv[1:])])


if __name__ == "__main__":
    sys.exit(main())