aether-dsc 0.2.6__tar.gz → 0.2.7__tar.gz

{aether_dsc-0.2.6/aether_dsc.egg-info → aether_dsc-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-dsc
-Version: 0.2.6
+Version: 0.2.7
 Summary: aether-dsc — the sealed AETHER header payload: opaque, digest-named, no readable source in the wheel
 Author: Alessandro Masat
 License: Apache-2.0
@@ -59,6 +59,17 @@ The blob is a zlib-compressed tar — not obfuscation against a determined
 reader, just enough that `strings`/`cat` on the wheel does not hand back
 readable C++ source.
 
+## The C reference core
+
+`aether_dsc.c_core` is a pure-Python (standard library only) generator of
+plain C99 functions that reproduce, bit for bit, what aether's expression
+templates evaluate on the host: vector, matrix, quaternion and scalar
+kinds at `f64` and `f32`. `c_core.function(kind, shape=..., width=...)`
+returns one function (its name, text, `deps` and `libm`), and
+`c_core.emit(names)` writes the typedefs and functions for those names and
+everything they depend on as one block of C text. Compile it with
+`-ffp-contract=off`.
+
 ## Threading
 
 Free-threaded CPython (3.13t/3.14t) is supported: the compiled modules declare GIL-free operation and the GIL stays disabled after import. Any number of threads may call module-level functions, build, compile, plan and cache concurrently. Distinct objects may be used from distinct threads without synchronisation. One stateful object (a stream, capture, launcher, graph, composer, plan, pipeline, active set, host kernel or arg block) shared by several threads is memory-safe — its calls serialise and a consumed object raises — but the ORDER of those calls is the caller's responsibility, exactly as for a NumPy array or a CuPy stream. CUDA adds two rules of its own: a stream capture is begun, filled and ended by one thread, and while any capture is open no thread may synchronise the whole device (stream-level synchronisation is fine). GPU routes are supported on free-threaded 3.14; on 3.13t the CPU route runs.

{aether_dsc-0.2.6 → aether_dsc-0.2.7}/README.md

@@ -40,6 +40,17 @@ The blob is a zlib-compressed tar — not obfuscation against a determined
 reader, just enough that `strings`/`cat` on the wheel does not hand back
 readable C++ source.
 
+## The C reference core
+
+`aether_dsc.c_core` is a pure-Python (standard library only) generator of
+plain C99 functions that reproduce, bit for bit, what aether's expression
+templates evaluate on the host: vector, matrix, quaternion and scalar
+kinds at `f64` and `f32`. `c_core.function(kind, shape=..., width=...)`
+returns one function (its name, text, `deps` and `libm`), and
+`c_core.emit(names)` writes the typedefs and functions for those names and
+everything they depend on as one block of C text. Compile it with
+`-ffp-contract=off`.
+
 ## Threading
 
 Free-threaded CPython (3.13t/3.14t) is supported: the compiled modules declare GIL-free operation and the GIL stays disabled after import. Any number of threads may call module-level functions, build, compile, plan and cache concurrently. Distinct objects may be used from distinct threads without synchronisation. One stateful object (a stream, capture, launcher, graph, composer, plan, pipeline, active set, host kernel or arg block) shared by several threads is memory-safe — its calls serialise and a consumed object raises — but the ORDER of those calls is the caller's responsibility, exactly as for a NumPy array or a CuPy stream. CUDA adds two rules of its own: a stream capture is begun, filled and ended by one thread, and while any capture is open no thread may synchronise the whole device (stream-level synchronisation is fine). GPU routes are supported on free-threaded 3.14; on 3.13t the CPU route runs.

{aether_dsc-0.2.6 → aether_dsc-0.2.7}/aether_dsc/__init__.py

@@ -50,7 +50,7 @@ __all__ = ["Payload", "seal", "payload", "version", "PAYLOAD_DIR"]
 #: `constexpr version()`), because a sealed payload speaks for exactly one
 #: aether checkout and a version skew between the two would silently claim
 #: otherwise.
-version = "0.2.6"
+version = "0.2.7"
 __version__ = version  # the conventional spelling
 
 _PAYLOAD_CACHE: Payload | None = None

aether_dsc-0.2.7/aether_dsc/c_core.py

@@ -0,0 +1,421 @@
+# Copyright 2026 Alessandro Masat
+# SPDX-License-Identifier: Apache-2.0
+
+"""aether's C reference core: a generator of plain C99 functions.
+
+Each function reproduces, bit for bit, what aether's expression templates
+evaluate on the host (see "Bit-identity formula table" in
+docs/superpowers/specs/2026-10-16-embedded-c-target-design.md). The rules
+that make that true:
+
+* folds (dot, norm, sum) are right-nested, highest index outermost, with no
+  zero seed: ``e[N-1] + (e[N-2] + (... + e[0]))``;
+* ``x / s`` is ``r = 1/s`` once, then ``r * x_k``;
+* ``neg`` is ``x * -1``; ``norm`` is ``sqrt(ssq)`` (no hypot);
+* nothing promotes: a ``f32`` text uses the ``f``-suffixed libm and only
+  ``aether_c_f32_t`` values.
+
+Consumers: aether's gtest suite pins the corpus header minted from these
+texts against the C++ templates; hawk imports this module, requests
+functions by ``(kind, shape, width)``, resolves ``deps`` transitively and
+inlines the texts verbatim into standalone C files. The module only uses the
+standard library. Every ``function``/``struct``/``real_typedef`` result is
+memoised by name in one registry, which ``emit`` reads.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, Iterable
+
+CORE_VERSION = "aether-c/1"
+WIDTHS = ("f64", "f32")
+
+# width -> (C type, libm suffix)
+_WIDTH = {"f64": ("double", ""), "f32": ("float", "f")}
+
+
+@dataclass(frozen=True)
+class CFunction:
+    name: str
+    text: str
+    deps: tuple[str, ...]
+    libm: tuple[str, ...]
+
+
+_REGISTRY: dict[str, CFunction] = {}
+
+
+def _check_width(width: str) -> None:
+    if width not in _WIDTH:
+        raise ValueError(f"unknown width {width!r}; expected one of {WIDTHS}")
+
+
+_RANK: dict[str, int] = {}  # 0 width typedef, 1 struct typedef, 2 function
+
+
+def _memo(item: CFunction, rank: int) -> CFunction:
+    _RANK.setdefault(item.name, rank)
+    return _REGISTRY.setdefault(item.name, item)
+
+
+def real_type(width: str) -> str:
+    _check_width(width)
+    return _WIDTH[width][0]
+
+
+def _t(width: str) -> str:
+    return f"aether_c_{width}_t"
+
+
+def real_typedef(width: str) -> CFunction:
+    _check_width(width)
+    name = _t(width)
+    guard = name.upper()
+    text = f"#ifndef {guard}\n#define {guard}\ntypedef {_WIDTH[width][0]} {name};\n#endif\n"
+    return _memo(CFunction(name, text, (), ()), 0)
+
+
+def _check_shape(shape) -> None:
+    """Every extent an ``int`` (not ``bool``) >= 1; raised before anything is memoised."""
+    if not all(type(n) is int and n >= 1 for n in shape):
+        raise ValueError(f"invalid shape {shape!r}: every extent must be an int >= 1")
+
+
+def _struct_name(shape: tuple[int, ...], width: str) -> str:
+    _check_shape(shape)
+    if len(shape) == 1:
+        return f"aether_c_{width}_vec{shape[0]}_t"
+    if len(shape) == 2:
+        return f"aether_c_{width}_mat{shape[0]}x{shape[1]}_t"
+    raise ValueError(f"no struct for shape {shape!r}")
+
+
+def struct(shape: tuple[int, ...], width: str) -> CFunction:
+    shape = tuple(shape)
+    name = _struct_name(shape, width)  # validates the shape before anything is memoised
+    real = real_typedef(width)
+    if len(shape) == 1:
+        body = f"{real.name} v[{shape[0]}];"
+    else:
+        body = f"{real.name} m[{shape[0]}][{shape[1]}];"
+    guard = name.upper()
+    text = f"#ifndef {guard}\n#define {guard}\ntypedef struct {{ {body} }} {name};\n#endif\n"
+    return _memo(CFunction(name, text, (real.name,), ()), 1)
+
+
+# ---- per-family formatters; each returns (body lines, libm) ----
+# ``cells`` are the component accessors in row-major order ("v[k]" or "m[r][c]"),
+# so one formatter serves a vector kind and its matrix mirror; ``x`` names the
+# operand of a unary kind.
+
+def _fold(terms: list[str]) -> str:
+    """Right-nested, highest index outermost, no seed."""
+    if len(terms) == 1:
+        return terms[0]
+    return f"({terms[-1]} + {_fold(terms[:-1])})"
+
+
+def _cells(shape: tuple[int, ...]) -> list[str]:
+    if len(shape) == 1:
+        return [f"v[{k}]" for k in range(shape[0])]
+    return [f"m[{r}][{c}]" for r in range(shape[0]) for c in range(shape[1])]
+
+
+def _fold_kind(op: str, cells: list[str], w: str, x: str) -> tuple[list[str], tuple[str, ...]]:
+    if op == "vec_dot":
+        return [f"return {_fold([f'(a.{c} * b.{c})' for c in cells])};"], ()
+    if op == "vec_norm":
+        sq = _fold([f"({x}.{c} * {x}.{c})" for c in cells])
+        return [f"return sqrt{_WIDTH[w][1]}({sq});"], (f"sqrt{_WIDTH[w][1]}",)
+    return [f"return {_fold([f'{x}.{c}' for c in cells])};"], ()
+
+
+def _out_body(cells: list[str], exprs: list[str]) -> list[str]:
+    return [f"out.{c} = {e};" for c, e in zip(cells, exprs)]
+
+
+def _cwise_binary(kind: str, cells: list[str], w: str, x: str) -> tuple[list[str], tuple[str, ...]]:
+    s = _WIDTH[w][1]
+    if kind in _ARITH:
+        op = _ARITH[kind]
+        return _out_body(cells, [f"(a.{c} {op} b.{c})" for c in cells]), ()
+    fn = f"{_LIBM_BINARY[kind]}{s}"
+    return _out_body(cells, [f"{fn}(a.{c}, b.{c})" for c in cells]), (fn,)
+
+
+def _cwise_unary(kind: str, cells: list[str], w: str, x: str) -> tuple[list[str], tuple[str, ...]]:
+    t = _t(w)
+    if kind == "vec_neg":
+        return _out_body(cells, [f"({x}.{c} * ({t})-1.0)" for c in cells]), ()
+    if kind == "vec_rsqrt":
+        fn = f"sqrt{_WIDTH[w][1]}"
+        return _out_body(cells, [f"(({t})1.0 / {fn}({x}.{c}))" for c in cells]), (fn,)
+    fn = f"{_LIBM_UNARY[kind]}{_WIDTH[w][1]}"
+    return _out_body(cells, [f"{fn}({x}.{c})" for c in cells]), (fn,)
+
+
+def _scale(kind: str, cells: list[str], w: str, x: str) -> tuple[list[str], tuple[str, ...]]:
+    t = _t(w)
+    if kind == "vec_scale":
+        return _out_body(cells, [f"(s * a.{c})" for c in cells]), ()
+    pre = [f"const {t} r = (({t})1.0 / s);"]
+    return pre + _out_body(cells, [f"(r * a.{c})" for c in cells]), ()
+
+
+def _cross(kind: str, cells: list[str], w: str, x: str) -> tuple[list[str], tuple[str, ...]]:
+    return _out_body(cells, [
+        "((a.v[1] * b.v[2]) - (a.v[2] * b.v[1]))",
+        "((a.v[2] * b.v[0]) - (a.v[0] * b.v[2]))",
+        "((a.v[0] * b.v[1]) - (a.v[1] * b.v[0]))",
+    ]), ()
+
+
+_ARITH = {"vec_add": "+", "vec_sub": "-", "vec_mul": "*", "vec_cwise_div": "/"}
+_LIBM_BINARY = {"vec_min": "fmin", "vec_max": "fmax", "vec_pow": "pow"}
+_LIBM_UNARY = {"vec_abs": "fabs", "vec_sqrt": "sqrt", "vec_exp": "exp", "vec_log": "log",
+               "vec_sin": "sin", "vec_cos": "cos", "vec_tan": "tan", "vec_tanh": "tanh",
+               "vec_asin": "asin", "vec_acos": "acos", "vec_atan": "atan"}
+
+# kind -> (arg layout, result, body formatter); layout "fold2"/"bin"=(a,b), "un"=(a) or (m),
+# "scalar"=(a, s); result "vec" or "real". Insertion order here IS the order kinds() reports.
+_VEC_KINDS: dict[str, tuple[str, str, Callable]] = {}
+
+
+def _register(names: Iterable[str], layout: str, result: str, fmt: Callable) -> None:
+    for n in names:
+        _VEC_KINDS[n] = (layout, result, fmt)
+
+
+_register(("vec_dot",), "fold2", "real", _fold_kind)
+_register(("vec_norm", "vec_sum"), "un", "real", _fold_kind)
+_register(("vec_cross",), "fold2", "vec", _cross)
+_register(tuple(_ARITH), "fold2", "vec", _cwise_binary)
+_register(("vec_scale", "vec_div_s"), "scalar", "vec", _scale)
+_register(("vec_min", "vec_max", "vec_pow"), "fold2", "vec", _cwise_binary)
+_register(("vec_neg", "vec_abs", "vec_sqrt", "vec_rsqrt", "vec_exp", "vec_log", "vec_sin",
+           "vec_cos", "vec_tan", "vec_tanh", "vec_asin", "vec_acos", "vec_atan"),
+          "un", "vec", _cwise_unary)
+assert set(_LIBM_BINARY) | set(_ARITH) | set(_LIBM_UNARY) <= set(_VEC_KINDS)
+
+_VEC_ORDER = tuple(_VEC_KINDS)
+# matrix mirrors: every elementwise vector kind (not the folds or cross) over m[r][c]
+_MAT_CWISE = tuple("mat_" + k[4:] for k, v in _VEC_KINDS.items()
+                   if v[1] == "vec" and k != "vec_cross")
+_MAT_OTHER = ("mat_sum", "mat_mv", "mat_mm", "mat_transpose", "vec_outer")
+_QUAT = ("quat_mul", "quat_conj", "quat_recip", "quat_rotate", "quat_as_pure", "quat_as_vec3")
+_SCALARS = ("rsqrt", "sign", "clip", "remainder")
+
+
+def kinds() -> tuple[str, ...]:
+    return _VEC_ORDER + _MAT_CWISE + _MAT_OTHER + _QUAT + _SCALARS
+
+
+def _render(kind: str, shape: tuple[int, ...], width: str, ret: str, name: str,
+            params: str, body: list[str], deps: tuple[str, ...], libm: tuple[str, ...]) -> CFunction:
+    head = f"/* aether-c: {kind} {shape!r} {width} {CORE_VERSION} */\n"
+    lines = "".join(f"    {ln}\n" for ln in body)
+    text = f"{head}static inline {ret} {name}({params})\n{{\n{lines}}}\n"
+    return _memo(CFunction(name, text, deps, tuple(sorted(set(libm)))), 2)
+
+
+def _deps(width: str, *shapes: tuple[int, ...]) -> tuple[str, ...]:
+    """Width typedef first, then each struct type in order of first use."""
+    out = [real_typedef(width).name]
+    for sh in shapes:
+        n = struct(sh, width).name
+        if n not in out:
+            out.append(n)
+    return tuple(out)
+
+
+def _require_rank(kind: str, shape: tuple[int, ...], rank: int) -> None:
+    if len(shape) != rank:
+        raise ValueError(f"{kind} needs a rank-{rank} shape, got {shape!r}")
+
+
+def _vector_function(kind: str, shape: tuple[int, ...], width: str) -> CFunction:
+    """A vector kind, or (kind ``mat_*``) its elementwise matrix mirror."""
+    is_mat = kind.startswith("mat_")
+    base = "vec_" + kind[4:] if is_mat else kind
+    _require_rank(kind, shape, 2 if is_mat else 1)
+    if kind == "vec_cross" and shape != (3,):
+        raise ValueError(f"vec_cross is defined only for shape (3,), got {shape!r}")
+    layout, result, fmt = _VEC_KINDS[base]
+    t, st = _t(width), _struct_name(shape, width)
+    x = "m" if is_mat else "a"
+    body, libm = fmt(base, _cells(shape), width, x)
+    params = {"fold2": f"{st} a, {st} b", "un": f"{st} {x}", "scalar": f"{st} a, {t} s"}[layout]
+    if result == "vec":
+        body = [f"{st} out;"] + body + ["return out;"]
+    prefix = st[len(f"aether_c_{width}_"):-len("_t")]
+    name = f"aether_c_{width}_{prefix}_{kind[4:]}"
+    return _render(kind, shape, width, st if result == "vec" else t, name, params, body,
+                   _deps(width, shape), libm)
+
+
+def _matrix_function(kind: str, shape: tuple[int, ...], shape2, width: str) -> CFunction:
+    t, w = _t(width), width
+    if kind == "vec_outer":
+        _require_rank(kind, shape, 1)
+        if shape2 is None or len(shape2) != 1:
+            raise ValueError(f"vec_outer needs shape2 of rank 1, got shape={shape!r} shape2={shape2!r}")
+        out_shape = (shape[0], shape2[0])
+        ut, vt, ot = _struct_name(shape, w), _struct_name(shape2, w), _struct_name(out_shape, w)
+        body = [f"{ot} out;"] + _out_body(_cells(out_shape), [
+            f"(u.v[{r}] * v.v[{c}])" for r in range(shape[0]) for c in range(shape2[0])]) + ["return out;"]
+        name = f"aether_c_{w}_vec{shape[0]}_outer_vec{shape2[0]}"
+        return _render(kind, shape, w, ot, name, f"{ut} u, {vt} v", body,
+                       _deps(w, shape, shape2, out_shape), ())
+    _require_rank(kind, shape, 2)
+    rows, cols = shape
+    mt = _struct_name(shape, w)
+    if kind == "mat_sum":
+        terms = [f"(m.{c} * ({t})1.0)" for c in _cells(shape)]
+        return _render(kind, shape, w, t, f"aether_c_{w}_mat{rows}x{cols}_sum", f"{mt} m",
+                       [f"return {_fold(terms)};"], _deps(w, shape), ())
+    if kind == "mat_transpose":
+        out_shape = (cols, rows)
+        ot = _struct_name(out_shape, w)
+        body = [f"{ot} out;"] + _out_body(_cells(out_shape), [
+            f"m.m[{r}][{c}]" for c in range(cols) for r in range(rows)]) + ["return out;"]
+        return _render(kind, shape, w, ot, f"aether_c_{w}_mat{rows}x{cols}_transpose", f"{mt} m",
+                       body, _deps(w, shape, out_shape), ())
+    if kind == "mat_mv":
+        vt, ot = _struct_name((cols,), w), _struct_name((rows,), w)
+        body = [f"{ot} out;"] + _out_body(_cells((rows,)), [
+            _fold([f"(m.m[{r}][{c}] * v.v[{c}])" for c in range(cols)]) for r in range(rows)]) + ["return out;"]
+        return _render(kind, shape, w, ot, f"aether_c_{w}_mat{rows}x{cols}_mv", f"{mt} m, {vt} v",
+                       body, _deps(w, shape, (cols,), (rows,)), ())
+    # mat_mm
+    if shape2 is None or len(shape2) != 2 or shape2[0] != cols:
+        raise ValueError(f"mat_mm needs shape2 (K, C) with K == {cols}, got shape={shape!r} shape2={shape2!r}")
+    out_shape = (rows, shape2[1])
+    rt, ot = _struct_name(shape2, w), _struct_name(out_shape, w)
+    body = [f"{ot} out;"] + _out_body(_cells(out_shape), [
+        _fold([f"(l.m[{i}][{k}] * r.m[{k}][{j}])" for k in range(cols)])
+        for i in range(rows) for j in range(shape2[1])]) + ["return out;"]
+    name = f"aether_c_{w}_mat{rows}x{cols}_mm_mat{shape2[0]}x{shape2[1]}"
+    return _render(kind, shape, w, ot, name, f"{mt} l, {rt} r", body,
+                   _deps(w, shape, shape2, out_shape), ())
+
+
+def _quat_function(kind: str, shape, shape2, width: str) -> CFunction:
+    """Quaternions are vec4 values laid out (w, x, y, z); a 3-vector is a vec3."""
+    if shape is not None or shape2 is not None:
+        raise ValueError(f"{kind} takes no shape, got shape={shape!r} shape2={shape2!r}")
+    t, w = _t(width), width
+    q4, q3 = (4,), (3,)
+    st4, st3 = _struct_name(q4, w), _struct_name(q3, w)
+    conj = lambda k: f"(q.v[{k}] * ({t})-1.0)"
+    pre: list[str] = []
+    if kind == "quat_mul":
+        # (l_i * r_j) term indices per output component, in aether's left-to-right order
+        pairs = [[(0, 0), (1, 1), (2, 2), (3, 3)], [(0, 1), (1, 0), (2, 3), (3, 2)],
+                 [(0, 2), (1, 3), (2, 0), (3, 1)], [(0, 3), (1, 2), (2, 1), (3, 0)]]
+        signs = [("-", "-", "-"), ("+", "+", "-"), ("-", "+", "+"), ("+", "-", "+")]
+        exprs = []
+        for ps, sg in zip(pairs, signs):
+            e = f"(l.v[{ps[0][0]}] * r.v[{ps[0][1]}])"
+            for (i, j), op in zip(ps[1:], sg):
+                e = f"({e} {op} (l.v[{i}] * r.v[{j}]))"
+            exprs.append(e)
+        params, ret, shapes, cells = f"{st4} l, {st4} r", st4, (q4,), _cells(q4)
+    elif kind == "quat_conj":
+        exprs = ["q.v[0]"] + [conj(k) for k in (1, 2, 3)]
+        params, ret, shapes, cells = f"{st4} q", st4, (q4,), _cells(q4)
+    elif kind == "quat_recip":
+        ssq = _fold([f"(q.v[{k}] * q.v[{k}])" for k in range(4)])
+        pre = [f"const {t} r = (({t})1.0 / {ssq});"]
+        exprs = ["(r * q.v[0])"] + [f"(r * {conj(k)})" for k in (1, 2, 3)]
+        params, ret, shapes, cells = f"{st4} q", st4, (q4,), _cells(q4)
+    elif kind == "quat_rotate":
+        # component i uses j = i+1, k = i+2 (mod 3); u_j is q.v[j+1]
+        for i, n in enumerate("xyz"):
+            j, k = (i + 1) % 3, (i + 2) % 3
+            pre.append(f"const {t} t{n} = (({t})2.0 * ((q.v[{j + 1}] * v.v[{k}]) - (q.v[{k + 1}] * v.v[{j}])));")
+        exprs = []
+        for i in range(3):
+            j, k = (i + 1) % 3, (i + 2) % 3
+            exprs.append(f"((v.v[{i}] + (q.v[0] * t{'xyz'[i]})) + "
+                         f"((q.v[{j + 1}] * t{'xyz'[k]}) - (q.v[{k + 1}] * t{'xyz'[j]})))")
+        params, ret, shapes, cells = f"{st4} q, {st3} v", st3, (q4, q3), _cells(q3)
+    elif kind == "quat_as_pure":
+        exprs = [f"({t})0.0"] + [f"v.v[{k}]" for k in range(3)]
+        params, ret, shapes, cells = f"{st3} v", st4, (q3, q4), _cells(q4)
+    else:  # quat_as_vec3
+        exprs = [f"q.v[{k}]" for k in (1, 2, 3)]
+        params, ret, shapes, cells = f"{st4} q", st3, (q4, q3), _cells(q3)
+    body = pre + [f"{ret} out;"] + _out_body(cells, exprs) + ["return out;"]
+    return _render(kind, q4, w, ret, f"aether_c_{w}_quat_{kind[5:]}", params, body,
+                   _deps(w, *shapes), ())
+
+
+def _scalar_function(kind: str, width: str) -> CFunction:
+    t, s = _t(width), _WIDTH[width][1]
+    real = real_typedef(width)
+    sq, fm, cs = f"sqrt{s}", f"fmod{s}", f"copysign{s}"
+    if kind == "rsqrt":
+        params, body, libm = f"{t} x", [f"return (({t})1.0 / {sq}(x));"], (sq,)
+    elif kind == "sign":
+        params, libm = f"{t} x", ()
+        body = [f"return (x > ({t})0.0) ? ({t})1.0 : ((x < ({t})0.0) ? ({t})-1.0 : ({t})0.0);"]
+    elif kind == "clip":
+        params, libm = f"{t} x, {t} lo, {t} hi", ()
+        body = [f"const {t} t = ((x >= lo) || (x != x)) ? x : lo;",
+                "return ((t <= hi) || (t != t)) ? t : hi;"]
+    else:
+        params, libm = f"{t} a, {t} b", (fm, cs)
+        body = [f"{t} m = {fm}(a, b);",
+                f"if (m != ({t})0.0) {{",
+                f"    if ((b < ({t})0.0) != (m < ({t})0.0)) {{",
+                "        m += b;",
+                "    }",
+                "} else {",
+                f"    m = {cs}(({t})0.0, b);",
+                "}",
+                "return m;"]
+    return _render(kind, (), width, t, f"aether_c_{width}_{kind}", params, body, (real.name,), libm)
+
+
+def function(kind: str, *, shape=None, shape2=None, width: str = "f64") -> CFunction:
+    _check_width(width)
+    if kind in _SCALARS:
+        if shape is not None or shape2 is not None:
+            raise ValueError(f"{kind} takes no shape, got shape={shape!r} shape2={shape2!r}")
+        return _scalar_function(kind, width)
+    if kind not in kinds():
+        raise ValueError(f"unknown kind {kind!r}; known kinds: {', '.join(kinds())}")
+    if kind in _QUAT:
+        return _quat_function(kind, shape, shape2, width)
+    if shape is None:
+        raise ValueError(f"{kind} needs a shape")
+    shape = tuple(shape)
+    shape2 = None if shape2 is None else tuple(shape2)
+    _check_shape(shape)
+    if shape2 is not None:
+        _check_shape(shape2)
+        if kind not in ("mat_mm", "vec_outer"):
+            raise ValueError(f"{kind} takes no shape2, got shape2={shape2!r}")
+    if kind in _VEC_KINDS or kind in _MAT_CWISE:
+        return _vector_function(kind, shape, width)
+    return _matrix_function(kind, shape, shape2, width)
+
+
+def emit(names: Iterable[str]) -> str:
+    """The closure of ``names``: typedefs, then structs, then functions, each once."""
+    order: list[str] = []
+    seen: set[str] = set()
+
+    def visit(name: str) -> None:
+        if name in seen:
+            return
+        if name not in _REGISTRY:
+            raise KeyError(name)
+        seen.add(name)
+        for dep in _REGISTRY[name].deps:
+            visit(dep)
+        order.append(name)
+
+    for name in names:
+        visit(name)
+    order.sort(key=_RANK.__getitem__)  # stable: dependency order kept within a class
+    return "\n".join(_REGISTRY[n].text for n in order)

{aether_dsc-0.2.6 → aether_dsc-0.2.7/aether_dsc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-dsc
-Version: 0.2.6
+Version: 0.2.7
 Summary: aether-dsc — the sealed AETHER header payload: opaque, digest-named, no readable source in the wheel
 Author: Alessandro Masat
 License: Apache-2.0
@@ -59,6 +59,17 @@ The blob is a zlib-compressed tar — not obfuscation against a determined
 reader, just enough that `strings`/`cat` on the wheel does not hand back
 readable C++ source.
 
+## The C reference core
+
+`aether_dsc.c_core` is a pure-Python (standard library only) generator of
+plain C99 functions that reproduce, bit for bit, what aether's expression
+templates evaluate on the host: vector, matrix, quaternion and scalar
+kinds at `f64` and `f32`. `c_core.function(kind, shape=..., width=...)`
+returns one function (its name, text, `deps` and `libm`), and
+`c_core.emit(names)` writes the typedefs and functions for those names and
+everything they depend on as one block of C text. Compile it with
+`-ffp-contract=off`.
+
 ## Threading
 
 Free-threaded CPython (3.13t/3.14t) is supported: the compiled modules declare GIL-free operation and the GIL stays disabled after import. Any number of threads may call module-level functions, build, compile, plan and cache concurrently. Distinct objects may be used from distinct threads without synchronisation. One stateful object (a stream, capture, launcher, graph, composer, plan, pipeline, active set, host kernel or arg block) shared by several threads is memory-safe — its calls serialise and a consumed object raises — but the ORDER of those calls is the caller's responsibility, exactly as for a NumPy array or a CuPy stream. CUDA adds two rules of its own: a stream capture is begun, filled and ended by one thread, and while any capture is open no thread may synchronise the whole device (stream-level synchronisation is fine). GPU routes are supported on free-threaded 3.14; on 3.13t the CPU route runs.

{aether_dsc-0.2.6 → aether_dsc-0.2.7}/aether_dsc.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ aether_dsc/__init__.py
 aether_dsc/_core.py
 aether_dsc/_rtc_check.py
 aether_dsc/_seal_impl.py
+aether_dsc/c_core.py
 aether_dsc/payload_headers.txt
 aether_dsc/payload_headers_host.txt
 aether_dsc/seal.py
@@ -16,4 +17,5 @@ aether_dsc.egg-info/requires.txt
 aether_dsc.egg-info/top_level.txt
 aether_dsc/_payload/ee303363b05593f7617a9bbd46fd051fdba1ab5ed91498b223c1a2cd9c369790.bin
 tests/test_aether_dsc.py
+tests/test_c_core.py
 tests/test_ft_payload.py

{aether_dsc-0.2.6 → aether_dsc-0.2.7}/pyproject.toml

@@ -14,7 +14,7 @@ name = "aether-dsc"
 # aether-dsc ships a SEALED payload of that exact checkout, so a version skew
 # between the two would silently claim a payload speaks for a different
 # aether than it does.
-version = "0.2.6"
+version = "0.2.7"
 description = "aether-dsc — the sealed AETHER header payload: opaque, digest-named, no readable source in the wheel"
 readme = "README.md"
 requires-python = ">=3.9"

aether_dsc-0.2.7/tests/test_c_core.py

@@ -0,0 +1,221 @@
+# Copyright 2026 Alessandro Masat
+# SPDX-License-Identifier: Apache-2.0
+import re, subprocess, shutil, pytest
+from aether_dsc import c_core as C
+
+F64_DOT3 = ("static inline aether_c_f64_t aether_c_f64_vec3_dot(aether_c_f64_vec3_t a, aether_c_f64_vec3_t b)\n"
+            "{\n    return ((a.v[2] * b.v[2]) + ((a.v[1] * b.v[1]) + (a.v[0] * b.v[0])));\n}\n")
+
+def test_vec3_dot_is_right_nested_with_no_seed():
+    f = C.function("vec_dot", shape=(3,), width="f64")
+    assert f.name == "aether_c_f64_vec3_dot" and f.text.endswith(F64_DOT3)
+    assert f.text.startswith("/* aether-c: vec_dot (3,) f64 aether-c/1 */\n")
+    assert f.deps == ("aether_c_f64_t", "aether_c_f64_vec3_t") and f.libm == ()
+
+def test_vec3_norm_is_sqrt_of_right_nested_squares():
+    assert "return sqrt(((a.v[2] * a.v[2]) + ((a.v[1] * a.v[1]) + (a.v[0] * a.v[0]))));" in C.function("vec_norm", shape=(3,)).text
+
+def test_vec1_dot_is_one_product():
+    assert "return (a.v[0] * b.v[0]);" in C.function("vec_dot", shape=(1,)).text
+
+def test_div_s_multiplies_by_one_reciprocal():
+    t = C.function("vec_div_s", shape=(2,)).text
+    assert "const aether_c_f64_t r = ((aether_c_f64_t)1.0 / s);" in t and "out.v[1] = (r * a.v[1]);" in t
+
+def test_neg_multiplies_by_minus_one():
+    assert "out.v[0] = (a.v[0] * (aether_c_f64_t)-1.0);" in C.function("vec_neg", shape=(1,)).text
+
+def test_min_keeps_operand_order():
+    assert "out.v[0] = fmin(a.v[0], b.v[0]);" in C.function("vec_min", shape=(1,)).text
+
+def test_cross_formulas_and_shape_guard():
+    t = C.function("vec_cross", shape=(3,)).text
+    assert "out.v[0] = ((a.v[1] * b.v[2]) - (a.v[2] * b.v[1]));" in t
+    assert "out.v[1] = ((a.v[2] * b.v[0]) - (a.v[0] * b.v[2]));" in t
+    assert "out.v[2] = ((a.v[0] * b.v[1]) - (a.v[1] * b.v[0]));" in t
+    with pytest.raises(ValueError, match=r"\(4,\)"):
+        C.function("vec_cross", shape=(4,))
+
+def test_scalar_formulas():
+    assert "return ((aether_c_f64_t)1.0 / sqrt(x));" in C.function("rsqrt").text
+    assert "const aether_c_f64_t t = ((x >= lo) || (x != x)) ? x : lo;" in C.function("clip").text
+    assert "return ((t <= hi) || (t != t)) ? t : hi;" in C.function("clip").text
+    r = C.function("remainder").text
+    assert "aether_c_f64_t m = fmod(a, b);" in r and "m = copysign((aether_c_f64_t)0.0, b);" in r
+    assert C.function("remainder").libm == ("copysign", "fmod")
+
+def test_f32_never_promotes():
+    t = C.function("vec_norm", shape=(3,), width="f32").text
+    assert "sqrtf(" in t and "aether_c_f32_t" in t and "double" not in t
+    assert C.function("vec_norm", shape=(3,), width="f32").libm == ("sqrtf",)
+
+def test_struct_typedefs_are_guarded():
+    s = C.struct((3,), "f64")
+    assert s.text == "#ifndef AETHER_C_F64_VEC3_T\n#define AETHER_C_F64_VEC3_T\ntypedef struct { aether_c_f64_t v[3]; } aether_c_f64_vec3_t;\n#endif\n"
+
+MAT_SHAPES = ((2, 2), (3, 3), (4, 4), (2, 3), (3, 2), (1, 3))
+MM_PAIRS = (((2, 3), (3, 2)), ((3, 3), (3, 3)), ((2, 2), (2, 2)))
+OUTER_PAIRS = (((2,), (3,)), ((3,), (3,)))
+
+
+def _requests(width):
+    """Every (kind, kwargs) the broad tests exercise, derived from kinds()."""
+    for kind in C.kinds():
+        if kind == "vec_outer":
+            for s, s2 in OUTER_PAIRS:
+                yield kind, dict(shape=s, shape2=s2, width=width)
+        elif kind == "mat_mm":
+            for s, s2 in MM_PAIRS:
+                yield kind, dict(shape=s, shape2=s2, width=width)
+        elif kind.startswith("mat_"):
+            for s in MAT_SHAPES:
+                yield kind, dict(shape=s, width=width)
+        elif kind.startswith("quat_"):
+            yield kind, dict(width=width)
+        elif kind.startswith("vec_"):
+            for s in ((1,), (2,), (3,), (4,), (6,)):
+                if kind == "vec_cross" and s != (3,): continue
+                yield kind, dict(shape=s, width=width)
+        else:
+            yield kind, dict(width=width)
+
+def test_texts_are_deterministic_c99_and_c_plus_plus_safe():
+    for width in C.WIDTHS:
+        for kind, kw in _requests(width):
+            a, b = C.function(kind, **kw), C.function(kind, **kw)
+            assert a == b and "//" not in a.text and "static inline" in a.text
+            assert a.deps[0] == f"aether_c_{width}_t"
+
+def test_emit_orders_the_closure_typedefs_first_each_once():
+    names = [C.function("vec_norm", shape=(3,)).name, C.function("vec_dot", shape=(3,)).name]
+    text = C.emit(names)
+    assert text.index("typedef double aether_c_f64_t;") < text.index("aether_c_f64_vec3_t;") < text.index("aether_c_f64_vec3_norm(")
+    assert text.count("typedef struct { aether_c_f64_t v[3]; }") == 1
+
+@pytest.mark.skipif(shutil.which("cc") is None, reason="no C compiler")
+def test_emitted_closure_compiles_as_strict_c99(tmp_path):
+    names = [C.function(k, **kw).name for w in C.WIDTHS for k, kw in _requests(w)]
+    src = tmp_path / "t.c"
+    src.write_text("#include <math.h>\n" + C.emit(names))
+    subprocess.run(["cc", "-std=c99", "-pedantic", "-Wall", "-Wextra", "-Wconversion", "-Wsign-conversion",
+                    "-Wdouble-promotion", "-Wno-unused-function", "-Werror", "-fsyntax-only", str(src)], check=True)
+
+def test_mat2x2_sum_is_the_ones_matdot_fold():
+    t = C.function("mat_sum", shape=(2, 2)).text
+    assert "return ((m.m[1][1] * (aether_c_f64_t)1.0) + ((m.m[1][0] * (aether_c_f64_t)1.0) + ((m.m[0][1] * (aether_c_f64_t)1.0) + (m.m[0][0] * (aether_c_f64_t)1.0))));" in t
+
+def test_mat2x2_mv_row_fold():
+    t = C.function("mat_mv", shape=(2, 2)).text
+    assert "out.v[0] = ((m.m[0][1] * v.v[1]) + (m.m[0][0] * v.v[0]));" in t
+
+def test_mat1x3_mv():
+    assert "out.v[0] = ((m.m[0][2] * v.v[2]) + ((m.m[0][1] * v.v[1]) + (m.m[0][0] * v.v[0])));" in C.function("mat_mv", shape=(1, 3)).text
+
+def test_mat_mm_names_both_shapes_and_folds_over_k():
+    f = C.function("mat_mm", shape=(2, 3), shape2=(3, 2))
+    assert f.name == "aether_c_f64_mat2x3_mm_mat3x2"
+    assert "out.m[0][0] = ((l.m[0][2] * r.m[2][0]) + ((l.m[0][1] * r.m[1][0]) + (l.m[0][0] * r.m[0][0])));" in f.text
+    assert set(f.deps) >= {"aether_c_f64_mat2x3_t", "aether_c_f64_mat3x2_t", "aether_c_f64_mat2x2_t"}
+    assert f.deps[0] == "aether_c_f64_t"
+
+def test_outer_and_transpose():
+    assert "out.m[1][0] = (u.v[1] * v.v[0]);" in C.function("vec_outer", shape=(2,), shape2=(3,)).text
+    assert C.function("vec_outer", shape=(2,), shape2=(3,)).name == "aether_c_f64_vec2_outer_vec3"
+    assert "out.m[2][0] = m.m[0][2];" in C.function("mat_transpose", shape=(1, 3)).text
+
+def test_mat_cwise_mirror_the_vector_templates():
+    assert "out.m[1][0] = (s * a.m[1][0]);" in C.function("mat_scale", shape=(2, 2)).text
+    t = C.function("mat_div_s", shape=(2, 2)).text
+    assert "const aether_c_f64_t r = ((aether_c_f64_t)1.0 / s);" in t and "out.m[1][1] = (r * a.m[1][1]);" in t
+    assert "out.m[0][1] = (m.m[0][1] * (aether_c_f64_t)-1.0);" in C.function("mat_neg", shape=(1, 3)).text
+    assert "out.m[0][0] = ((aether_c_f32_t)1.0 / sqrtf(m.m[0][0]));" in C.function("mat_rsqrt", shape=(1, 1), width="f32").text
+    assert "out.m[0][0] = fmin(a.m[0][0], b.m[0][0]);" in C.function("mat_min", shape=(1, 3)).text
+    assert "out.m[0][2] = fabsf(m.m[0][2]);" in C.function("mat_abs", shape=(1, 3), width="f32").text
+    assert "out.m[0][0] = (a.m[0][0] + b.m[0][0]);" in C.function("mat_add", shape=(2, 3)).text
+
+def test_matrix_shape_errors():
+    with pytest.raises(ValueError, match=r"\(3,\)"):
+        C.function("mat_sum", shape=(3,))
+    with pytest.raises(ValueError, match=r"\(2, 3\).*\(2, 3\)"):
+        C.function("mat_mm", shape=(2, 3), shape2=(2, 3))
+    with pytest.raises(ValueError, match=r"\(2, 2\)"):
+        C.function("mat_mm", shape=(2, 2))
+    with pytest.raises(ValueError, match=r"\(2,\)"):
+        C.function("vec_outer", shape=(2,))
+
+def test_kinds_order_matrix_between_vectors_and_scalars():
+    k = C.kinds()
+    assert k.index("vec_atan") < k.index("mat_add") < k.index("mat_atan") < k.index("mat_sum") < k.index("rsqrt")
+    assert k[-4:] == ("rsqrt", "sign", "clip", "remainder") and k[-11] == "vec_outer" and k[-10:-4] == tuple(x for x in k if x.startswith("quat_"))
+    assert len(set(k)) == len(k)
+
+def test_unknown_kind_and_name():
+    with pytest.raises(ValueError, match="vec_dot"):
+        C.function("nope")
+    with pytest.raises(KeyError, match="no_such"):
+        C.emit(["no_such"])
+
+
+def test_quat_mul_hamilton_left_to_right():
+    t = C.function("quat_mul").text
+    assert "out.v[0] = ((((l.v[0] * r.v[0]) - (l.v[1] * r.v[1])) - (l.v[2] * r.v[2])) - (l.v[3] * r.v[3]));" in t
+    assert "out.v[1] = ((((l.v[0] * r.v[1]) + (l.v[1] * r.v[0])) + (l.v[2] * r.v[3])) - (l.v[3] * r.v[2]));" in t
+    assert "out.v[2] = ((((l.v[0] * r.v[2]) - (l.v[1] * r.v[3])) + (l.v[2] * r.v[0])) + (l.v[3] * r.v[1]));" in t
+    assert "out.v[3] = ((((l.v[0] * r.v[3]) + (l.v[1] * r.v[2])) - (l.v[2] * r.v[1])) + (l.v[3] * r.v[0]));" in t
+
+def test_quat_rotate_expands_as_aether_does():
+    t = C.function("quat_rotate").text
+    assert "const aether_c_f64_t tx = ((aether_c_f64_t)2.0 * ((q.v[2] * v.v[2]) - (q.v[3] * v.v[1])));" in t
+    assert "out.v[0] = ((v.v[0] + (q.v[0] * tx)) + ((q.v[2] * tz) - (q.v[3] * ty)));" in t
+
+def test_quat_recip_scales_the_conjugate_by_one_reciprocal():
+    t = C.function("quat_recip").text
+    assert "const aether_c_f64_t r = ((aether_c_f64_t)1.0 / ((q.v[3] * q.v[3]) + ((q.v[2] * q.v[2]) + ((q.v[1] * q.v[1]) + (q.v[0] * q.v[0])))));" in t
+    assert "out.v[0] = (r * q.v[0]);" in t and "out.v[1] = (r * (q.v[1] * (aether_c_f64_t)-1.0));" in t
+
+def test_quat_as_pure_and_as_vec3():
+    assert "out.v[0] = (aether_c_f64_t)0.0;" in C.function("quat_as_pure").text
+    assert "out.v[2] = q.v[3];" in C.function("quat_as_vec3").text
+
+def test_quat_names_types_deps_and_shape_rejection():
+    f = C.function("quat_rotate", width="f32")
+    assert f.name == "aether_c_f32_quat_rotate"
+    assert f.text.startswith("/* aether-c: quat_rotate (4,) f32 aether-c/1 */\n")
+    assert "static inline aether_c_f32_vec3_t aether_c_f32_quat_rotate(aether_c_f32_vec4_t q, aether_c_f32_vec3_t v)" in f.text
+    assert f.deps == ("aether_c_f32_t", "aether_c_f32_vec4_t", "aether_c_f32_vec3_t")
+    assert C.function("quat_as_pure").deps == ("aether_c_f64_t", "aether_c_f64_vec3_t", "aether_c_f64_vec4_t")
+    assert "const aether_c_f32_t r = ((aether_c_f32_t)1.0 /" in C.function("quat_recip", width="f32").text
+    with pytest.raises(ValueError):
+        C.function("quat_mul", shape=(4,))
+    with pytest.raises(ValueError):
+        C.function("quat_mul", shape2=(4,))
+
+
+_LIBM_CALL = re.compile(r"\b(sqrt|fmin|fmax|pow|fabs|exp|log|sin|cos|tan|tanh|asin|acos|atan|fmod|copysign)f?\(")
+
+def test_every_registered_name_audits_deps_libm_and_width_purity():
+    for width in C.WIDTHS:
+        for kind, kw in _requests(width):
+            f = C.function(kind, **kw)
+            for dep in f.deps:
+                C.emit([dep])  # KeyError if a dep is not registered
+            calls = set(re.findall(r"\b((?:sqrt|fmin|fmax|pow|fabs|exp|log|sin|cos|tan|tanh|asin|acos|atan|fmod|copysign)f?)\(", f.text))
+            assert set(f.libm) == calls and len(f.libm) == len(set(f.libm)), (f.name, f.libm, calls)
+            if width == "f32":
+                assert all(c.endswith("f") for c in calls), f.name
+                assert not re.search(r"\bdouble\b", f.text), f.name
+            else:
+                assert not re.search(r"\bfloat\b", f.text), f.name
+
+def test_invalid_shapes_raise_and_register_nothing():
+    before = dict(C._REGISTRY)
+    for kind, kw in (("vec_add", dict(shape=(0,))), ("vec_add", dict(shape=(-2,))),
+                     ("vec_dot", dict(shape=(0,))), ("mat_mv", dict(shape=(0, 3))),
+                     ("vec_add", dict(shape=(True,))), ("vec_add", dict(shape=(2.0,))),
+                     ("rsqrt", dict(shape=(3,))), ("clip", dict(shape2=(3,))),
+                     ("vec_add", dict(shape=(3,), shape2=(3,)))):
+        with pytest.raises(ValueError):
+            C.function(kind, **kw)
+    with pytest.raises(ValueError):
+        C.struct((0,), "f32")
+    assert C._REGISTRY == before