Skip to content

Tack 0.3.0

Choose a tag to compare

@berkgeveci berkgeveci released this 07 Oct 19:59
· 1449 commits to main since this release
9331df0

The headline: the kernel language grew the vocabulary that simulation and
graphics code reaches for, found by porting 50 Taichi, Warp and
awesome-taichi programs and checking each against a NumPy reference on
every backend. Vectors work wherever scalars do, small matrices and
masks are values, kernels can be methods and return a value, atomics
return the old value, and constants, tack.math and tack.random cover
what the ports carried themselves. The same work found and fixed wrong
results that 0.2.0 shipped with, most importantly a Metal compiler fault
that dropped field updates inside loops, and a vector assignment that
read its own partly overwritten target on every backend; see Kernels
that now compute different results
and Fixes.

Validated on Linux (CPU, CUDA on an RTX 4060 Ti, HIP on an MI210 and an
MI300X, Level Zero on an Intel Max 1100) and macOS (CPU and Metal on an
M1 Max), together with the 57 example checks in tack-examples.

Added

Vectors and matrices

  • Vectors in the places a scalar works. The math builtins (min, max,
    abs, floor, sqrt, pow, ...) and the casts (int, float,
    tack.f32, ...) apply to each component, with a scalar argument
    repeated: min(max(v, -1.0), 1.0), int(floor(p)). A conditional
    expression selects whole vectors on one condition. x, y, z and
    w name the first four components, to read (v.x, vf[i].y) and to
    assign (v.x = a, v.y += a). A component of a vector field element
    can be stored directly: vf[i][c] = a, vf[i][c] += a, vf[i].y = a.
    vf[i] += vec and vf[i] *= scalar update an element in place. A
    vector indexes a field one dimension per component: grid[cell] is
    grid[cell[0], cell[1]]. All of these used to fail IR verification
    with "expected expr node", or with an AttributeError for the
    augmented store. Vectors of different widths in one operation, a
    component name past the width, and a vector combined into a scalar
    target are rejected at lowering with the source position.
  • tack.Matrix: small fixed-size matrices, up to 4×4, scalarized like
    vectors. tack.Matrix.field(n, m, dtype, shape) allocates a field of
    them. In kernels, tack.Matrix([[a, b], [c, d]]), rows given as
    vectors, and tack.Matrix.identity(n) build one; @ multiplies
    matrices and vectors, with +, -, *, / entry by entry;
    transpose(), trace(), and for 2×2 and 3×3 determinant() and
    inverse(); A[i, j] reads and writes entries; u.outer_product(v)
    makes one from two vectors. Matrices pass through device functions,
    tuple assignment, conditional expressions, field stores and atomics as
    vectors do. See Matrices in the User's Guide.
  • A list of scalars in a kernel or device function is a vector:
    pos[i] = [x, y] is pos[i] = tack.Vector([x, y]), wherever a vector
    is accepted. It was rejected as "unsupported List". An empty list, a
    list of lists (write tack.Matrix), a list as an assignment target and
    a loop over a list are still rejected.
  • Vector components by runtime index: vec[k] reads and vec[k] = x /
    vec[k] += x write the component a loop variable or field value
    selects, through a chain of selects; past the last component a read
    gives the last component and a write does nothing. vf[i][c] and
    f(x)[c] index a vector-valued expression without naming it first.
    These used to fail IR verification with "expected expr node". A literal
    index out of range, and a subscript of a scalar value, are rejected at
    lowering with the source position.
  • Elementwise comparison: v > 0.0, lo <= v <= hi, a == b on vectors
    and matrices give a mask, a vector of 0/1 per component; and,
    or and not act per component on masks; any(mask) and all(mask)
    reduce one; tack.select(mask, a, b) picks per component, with scalar
    masks and scalar arms broadcast. A mask as an if or while condition
    is rejected with the hint to reduce it.
  • min and max take two or more values, as in Python
    (min(a, b, c)), and vectors have the reductions v.sum(), v.min()
    and v.max() over their components. v.normalized(eps) divides by
    norm() + eps.
  • v.norm(eps) is sqrt(v.norm_sqr() + eps), for a length that must not
    be zero. It was "norm() takes no arguments".
  • A device function can return vectors among several values:
    return distance, normal, color, unpacked with
    d, n, c = closest_hit(...). Only scalars could be returned together;
    a vector slot was never bound and lowering failed on its name.
  • Tuple assignment to field elements and vector components:
    x[i], v[i] = p, q (whole vectors included), a swap such as
    a[i], b[i] = b[i], a[i], and lo[i], hi[i] = f(...) for a device
    function that returns two values. The whole right side is evaluated
    first and the targets are then assigned from left to right, so
    a[i], i = x, j stores at the old i. Only plain names were accepted
    as targets.
  • Vector fields exchange data with NumPy one row per vector:
    from_numpy accepts (*shape, n) as well as the flat storage shape,
    and to_numpy(vectors=True) returns (*shape, n). Plain to_numpy()
    still returns the flat array.
  • fill takes one element's value for a vector or matrix field:
    colors.fill([1.0, 1.0, 1.0]). A scalar still sets every component.

Constants, math and random numbers

  • tack.constant(value, dtype=None): a named constant that kernels and
    device functions may read from the scope that defines them.
    DT = tack.constant(0.01) at module level lets a kernel write DT; it
    reads as the literal, and stays an ordinary Python number for host
    code. Kernels still capture nothing else: a plain module-level value
    raises NameError as before, and the message now names
    tack.constant. With a dtype the constant is typed, so
    tack.constant(747796405, tack.u32) multiplies in wrapping u32
    arithmetic (a plain literal there promotes to i64) and
    tack.constant(0.1, tack.f64) is the exact double. math.pi, math.e
    and math.tau can be written in kernels.
  • Vector and matrix constants: tack.constant((0.5, 0.5, 0.0)) is the
    vector with those components in a kernel, tack.constant(((1, 0), (0, 1)))
    the matrix with those rows, typed per component as scalar constants
    are. On the host they index, iterate and convert to NumPy arrays.
  • sinh, cosh and tanh as math builtins, on every backend.
  • tack.math: fract, mix, clamp, saturate, smoothstep, step,
    sign, length, distance and normalize as device functions with
    GLSL's definitions, on scalars and vectors alike.
  • tack.random: random numbers in kernels from a counter-based generator
    with explicit state. seed(index, stream), then u, state = uniform(state), normal, direction2, direction3; NumPy mirrors
    (np_uniform, ...) draw exactly the same values, and uniform and the
    states are bit-identical on every backend. The example ports' rng
    module, adopted.

Kernels, loops and atomics

  • A kernel may end in return expr, with a return annotation naming the
    type (-> tack.f32, -> float, -> int); the call returns that value
    as a Python number. It is computed after the launch by a one-thread
    epilogue kernel that stores it into a hidden field, so it may read
    fields, arguments, constants and locals bound outside the loop, not a
    local the loop assigns. A return anywhere else is still rejected.
  • An atomic is an expression as well as a statement: slot = tack.atomic_add(counter, 0, 1) is the element's value just before the
    update, on every backend and for every supported type, which is how
    threads claim unique slots and append to a shared list. On a vector
    field with a vector value it is the vector of the components' old
    values. Barriers remain statement-only.
  • Atomics take an index per dimension: tack.atomic_add(grid, (i, j), v),
    where a vector supplies one index per component
    (tack.atomic_add(grid, cell, v)). On a vector field a vector value
    updates every component of the element. Multi-dimensional and vector
    targets previously needed hand-linearized indices, and a tuple index
    failed IR verification.
  • tack.ndrange takes (start, end) pairs as well as sizes:
    for i, j in tack.ndrange((1, n - 1), (1, m - 1)) visits the interior
    of a grid. An empty or reversed pair runs no iterations.
  • One element of a field can be read from host code: f[i], f[i, j],
    f[None], giving a Python number or, for a vector or matrix field, a
    NumPy array. Writing an element, slicing and iterating are refused with
    a message pointing at from_numpy, fill and to_numpy. On CPU and
    Metal the read is a slice of unified memory; on CUDA, HIP and Level
    Zero it is a copy of just the element.

Data-oriented classes

  • A kernel can be a method of a @tack.data_oriented class:
    @tack.kernel def step(self, dt) is called as grid.step(0.1), and the
    object is a template like any other argument. It failed with "expects 1
    arguments, got 0". tack.inspect takes the bound form too.
  • A @tack.func under @staticmethod in a data-oriented class is called
    through self like the other methods. It was not found.
  • A @tack.data_oriented object can hold a @tack.func as an instance
    attribute and call it from its methods or from a kernel
    (self.smoothing = cubic, then self.smoothing(r, h)). Which function
    the attribute holds is part of the kernel's specialization.

Algorithms

  • tack.algorithms.argsort, sort_by_key, gather, unique and
    reduce_by_key: a stable radix sort for i32/u32/i64/u64 keys
    and segmented reductions over runs of equal keys, built from ordinary
    kernels and the scan so they run on every backend. See Sorting and
    segmented reductions
    in the User's Guide.
  • The tack.algorithms statistics (var, std, norm, absmax,
    count_nonzero, dot, histogram) accept vector fields and reduce
    over all components in storage order; they used to fail IR
    verification.

Kernels that now compute different results

  • A vector assignment whose right side reads its own target now reads
    the old components. Vectors are assigned one component at a time, and
    the right side was evaluated in between, so later components saw
    earlier ones already overwritten: v = v.normalized() (the result
    was not a unit vector), v = v.cross(w),
    v = tack.Vector([v[1], v[2], v[0]]), v += v.cross(w) and
    a[i] = a[i].cross(b[i]) all computed wrong vectors, on every backend
    and without an error. Components that could observe an earlier
    component's assignment are now evaluated first, as Python does. For a
    store to a field element that means any component that loads from a
    field, since fields may share storage. Assignments whose components
    only read their own component (v = v * 2.0, a[i] = a[i] + b[i])
    computed the right result before and still do.

  • A scalar stored to a vector field element sets every component:
    vf[i] = 0.0 names element i, as a load of vf[i] does, and as
    vf[i] *= 2.0 does. It wrote the single component at flat index i.

  • A vector field's element index is computed in 64 bits. It was narrowed
    to i32 before being scaled by the vector width, so a field of more than
    2^31 components was indexed wrongly.

Code that is now rejected

  • A multi-dimensional field indexed with the wrong number of indices.
    grid[i, j] on a three-dimensional field linearized with the sizes it
    had and silently addressed another element; so did a vector index of
    the wrong width and an atomic's index. The dispatch that binds such a
    field now raises TypeError with the source position. A single index
    is still a flat, row-major index.
  • A vector or tuple anywhere one value is required, such as a comparison
    (vf[i] < 1.0), a condition, a loop bound or print. Operations that
    do not map over a vector's components used to fail IR verification
    with "expected expr node" and a path into the lowered tree; every such
    statement now raises UnsupportedSyntaxError naming the kernel or
    device function and the source position.
  • A vector stored where it does not fit: s[i] = vec into a field of
    scalars or a local array, and vf[i] = vec into a field of vectors of
    another width. Both wrote components at offsets computed from the
    value's width, over whatever was there.
  • Reading a for loop's variable after its loop, before the name is
    assigned again, raises NameError at lowering with the read's position,
    on every backend. CPU raised a NameError from codegen and the GPU
    backends failed to compile when the name had no other binding; when it
    did (d = 100 before for d in range(4)), every backend silently read
    the outer value where Python gives the last value iterated. Copy the
    value to another name inside the loop. Sibling loops may still share a
    variable, and a loop variable may still be assigned as an ordinary local
    afterwards.

Fixes with no source change needed

  • The size of a local or shared array may be arithmetic on constants and
    dimensions: tack.local_array(tack.f32, MAX_HITS * 4) is folded to one
    constant when dimensions are resolved. Only a literal was, and Metal
    refused the kernel with "array size is not a constant expression".
  • Reading a zero-dimensional field to the host (f.to_numpy() for
    shape=()) crashed the process on CUDA: cuda-python does not take a
    zero-dimensional NumPy array as a host buffer. The copy now goes through
    a flat view.
  • A parallel loop may start at a negated argument: range(-n, n + 1) and
    tack.ndrange((-n, n + 1), ...) failed with "Cannot resolve loop range
    expression: IRUnaryOp", because the host evaluates the launch size and
    had no case for a unary minus.
  • Unary plus on an integer (+n) compiles on Metal, CUDA, HIP and Level
    Zero. The generators emitted a one-argument call to the two-argument
    add helper, which the device compilers rejected.
  • Metal computed wrong results, silently, for a field element updated
    in a loop.
    for k in range(n): total[0] += x[k]; counter[0] += 1 left
    total at start + x[n - 1]: Apple's compiler read total[0] once,
    before the loop. It happened when the element's address did not depend
    on the thread, the loop also stored to another field of the same type,
    and the trip count was a runtime value; while loops and f32 fields
    were affected alike. Present since field pointers moved into one
    argument buffer, so in 0.2.0. A loop that stores to a field is now
    compiled in a function of its own, which costs under 3% for the kernels
    that have one and nothing for the others.
  • A zero-dimensional scalar field, tack.field(dtype, shape=()), can be
    allocated on Metal. Its buffer zeroed the new storage with [:], which
    a zero-dimensional array rejects with "too many indices". CPU was not
    affected, nor zero-dimensional vector fields.
  • A subclass of a @tack.data_oriented class inherits its bases'
    @tack.func methods and class constants and may override them. Only
    the class's own were found, so a method calling an inherited one failed
    with "self.weight ... is neither a class constant ... nor a @tack.func
    method". A subclass without the decorator is handled the same way.
  • CPU threading on two-thread machines: one worker the scheduler took
    off its core could make a cheap kernel look expensive. The fan-out's
    per-worker median picked the slower of two workers, so a single stalled
    worker set a floor under the serial cost estimate and raised the
    kernel's threading threshold with it, until a later recheck corrected
    it. The median over an even number of workers is now the lower middle
    value. Machines with three or more threads were not affected.
  • A field of zero elements can be allocated on Metal and CUDA, as it
    already could on CPU and Level Zero. A filter that selects nothing now
    returns an empty field instead of failing to allocate it.
  • A kernel that used a name as a sequential loop's variable and later
    assigned it as a plain local (for d in range(4): ... then d = ...)
    failed to compile on Metal, CUDA, HIP and Level Zero with an undeclared
    identifier; CPU accepted it. The C-family generators now treat the loop
    header's declaration as ending with its block, so the later assignment
    declares a new local, as on CPU.
  • A field can be passed down through any number of nested device
    functions. Three or more levels failed to compile on every backend
    ("Cannot coerce float* to i32" on CPU, a pointer-to-integer error from
    the GPU compilers): copy propagation resolved one link of the chain of
    parameter copies per pass and left a local holding the field.
  • A @tack.data_oriented template's vector field attributes are now
    detected as vector fields: self.vel[i, j] in a template method, or
    obj.vel[i, j] in the kernel, lowered as a scalar field access and
    failed IR verification.
  • A @tack.func given a vector field now loads whole vectors from it:
    return vf[i] inside the function lowered to a single scalar load, so
    a kernel doing out[i] = f(vf, i) wrote one component and left the
    rest. The inliner propagated vector-variable and texture metadata to a
    function's parameters but not vector-field metadata.
  • A device function's locals bound by tuple unpacking (t, u = f(), or
    for i, j in ...) are now renamed when the function is inlined. They
    escaped renaming before, so the inlined body overwrote the caller's
    variables of the same names.

Tooling

  • test_a_stale_parallel_rate_gets_re_measured failed about one run in
    thirteen on two-thread machines and once on a CI runner: it asserted
    that two threads beat one on a bandwidth-bound kernel, which they need
    not. The scenario now uses a compute-bound kernel, so the assertion
    tests the recovery path it was written for.
  • The CPU threading tests no longer fail on two-thread machines: the
    per-worker median above was the cause, and a test that compared against
    the estimate before its own fan-out now compares against the one after.

Known limitations

  • ROCm 7.0 and 7.1 miscompile some integer code on HIP. Their device
    compiler (AMD clang 20, inside hipRTC) can evaluate a 64-bit signed
    comparison wrongly when it sits inside a long integer expression; the
    kernel returns a wrong value with no error. Tack's generated source is
    correct, and right on CUDA, as host C++ and under ROCm's clang 23. Use
    a newer ROCm where possible; on 7.0 and 7.1, check integer-heavy kernels
    against the CPU backend.
  • HIP on gfx90a (MI200) samples 3D textures in software. The device
    reports image support but refuses linear 3D filtering, which is all
    Texture3D offers; Tack detects this at init and falls back. MI300
    parts have no texture hardware and always sample in software.
  • Metal compiles a kernel whose sequential loop stores to a field in a
    function of its own
    , to avoid an Apple GPU compiler fault (see
    Fixes). The fault's mechanism is not known, so the rule is wider than
    the trigger; it costs under 3% on the kernels that take it.
  • Not in this release: struct types (use one field per member), a
    3×3 SVD (2×2 only, in the examples), swizzles such as v.xy or v.yzw
    (write tack.Vector([v.y, v.z, v.w])), and automatic differentiation.
  • Windows has not been revalidated.
  • HIP leaks one hipRTC program object per compiled variant.
    hiprtcDestroyProgram segfaults in hip-python, so Tack does not call it;
    the variant cache keeps compilations rare.
  • Level Zero relies on two workarounds for Intel driver defects: f64
    floor/ceil restore the sign of zero with copysign, and narrow signed
    negation and abs are emitted as non-inlined helpers.
  • Raster depth bias: in mixed scenes, path-traced surfaces are pushed
    back by a fixed 0.5% relative depth bias so a wireframe lying on its own
    surface is drawn; it can drop wire pixels at grazing angles.