Repository navigation
Tack 0.3.0
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,zand
wname 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] += vecandvf[i] *= scalarupdate 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 anAttributeErrorfor 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, andtack.Matrix.identity(n)build one;@multiplies
matrices and vectors, with+,-,*,/entry by entry;
transpose(),trace(), and for 2×2 and 3×3determinant()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]ispos[i] = tack.Vector([x, y]), wherever a vector
is accepted. It was rejected as "unsupported List". An empty list, a
list of lists (writetack.Matrix), a list as an assignment target and
a loop over a list are still rejected. - Vector components by runtime index:
vec[k]reads andvec[k] = x/
vec[k] += xwrite 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 == bon vectors
and matrices give a mask, a vector of0/1per component;and,
orandnotact per component on masks;any(mask)andall(mask)
reduce one;tack.select(mask, a, b)picks per component, with scalar
masks and scalar arms broadcast. A mask as aniforwhilecondition
is rejected with the hint to reduce it. minandmaxtake two or more values, as in Python
(min(a, b, c)), and vectors have the reductionsv.sum(),v.min()
andv.max()over their components.v.normalized(eps)divides by
norm() + eps.v.norm(eps)issqrt(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], andlo[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, jstores at the oldi. Only plain names were accepted
as targets. - Vector fields exchange data with NumPy one row per vector:
from_numpyaccepts(*shape, n)as well as the flat storage shape,
andto_numpy(vectors=True)returns(*shape, n). Plainto_numpy()
still returns the flat array. filltakes 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 writeDT; it
reads as the literal, and stays an ordinary Python number for host
code. Kernels still capture nothing else: a plain module-level value
raisesNameErroras 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
andmath.taucan 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,coshandtanhas math builtins, on every backend.tack.math:fract,mix,clamp,saturate,smoothstep,step,
sign,length,distanceandnormalizeas 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), thenu, state = uniform(state),normal,direction2,direction3; NumPy mirrors
(np_uniform, ...) draw exactly the same values, anduniformand 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.ndrangetakes(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 atfrom_numpy,fillandto_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_orientedclass:
@tack.kernel def step(self, dt)is called asgrid.step(0.1), and the
object is a template like any other argument. It failed with "expects 1
arguments, got 0".tack.inspecttakes the bound form too. - A
@tack.funcunder@staticmethodin a data-oriented class is called
throughselflike the other methods. It was not found. - A
@tack.data_orientedobject can hold a@tack.funcas an instance
attribute and call it from its methods or from a kernel
(self.smoothing = cubic, thenself.smoothing(r, h)). Which function
the attribute holds is part of the kernel's specialization.
Algorithms
tack.algorithms.argsort,sort_by_key,gather,uniqueand
reduce_by_key: a stable radix sort fori32/u32/i64/u64keys
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.algorithmsstatistics (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.0names elementi, as a load ofvf[i]does, and as
vf[i] *= 2.0does. It wrote the single component at flat indexi. -
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 raisesTypeErrorwith 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 orprint. 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 raisesUnsupportedSyntaxErrornaming the kernel or
device function and the source position. - A vector stored where it does not fit:
s[i] = vecinto a field of
scalars or a local array, andvf[i] = vecinto a field of vectors of
another width. Both wrote components at offsets computed from the
value's width, over whatever was there. - Reading a
forloop's variable after its loop, before the name is
assigned again, raisesNameErrorat lowering with the read's position,
on every backend. CPU raised aNameErrorfrom codegen and the GPU
backends failed to compile when the name had no other binding; when it
did (d = 100beforefor 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] += 1left
totalatstart + x[n - 1]: Apple's compiler readtotal[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;whileloops 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_orientedclass inherits its bases'
@tack.funcmethods 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): ...thend = ...)
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_orientedtemplate'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.funcgiven a vector field now loads whole vectors from it:
return vf[i]inside the function lowered to a single scalar load, so
a kernel doingout[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_measuredfailed 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
Texture3Doffers; 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 asv.xyorv.yzw
(writetack.Vector([v.y, v.z, v.w])), and automatic differentiation. - Windows has not been revalidated.
- HIP leaks one hipRTC program object per compiled variant.
hiprtcDestroyProgramsegfaults 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/ceilrestore the sign of zero withcopysign, and narrow signed
negation andabsare 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.