Repository navigation
Releases
Tack 0.7.0
The headline: Tack's filters run inside VTK. Nearly every tack.dataset
filter is a VTK algorithm (tack.interop.vtk.algorithms), its
arguments the algorithm's parameters, taking trees of datasets, AMR
hierarchies and pieces over MPI ranks, and running on the device its
device names. Datasets cross between VTK and Tack without a copy
(copy=False): on the CPU, on Metal, and on CUDA, HIP and Level Zero with a
VTK that holds device arrays. Examples 47-53 are VTK pipelines with Tack's
filters in them, on real Exodus, OpenFOAM and AMR files. Higher orders:
bases of any order on every shape from segments to wedges, Bernstein and
serendipity spaces, HDiv and HCurl at order 1, curved geometries, and
contour, slice, clip, threshold, advection and integration of them, cut at
the field's roots; VTK's Lagrange, Bezier and quadratic cells, its
vtkCellGrid and more of MFEM, both ways, with galleries in the
Visualization Guide. Advection gains an adaptive RK45, a path length, a
terminal speed and a walk through face neighbours; tack.algorithms gains
segmented reductions and scans, the same bits on every backend. The
documentation site is rewritten around Tack's four layers, the repository
is now github.com/Kitware/tack, and tack-core is on PyPI
(pip install 'tack-core[cpu]'), with tack-vis installed from this
repository at the release tag.
Nine changes break code written for 0.6; they lead the Changed section. The
ones most programs meet: data.fields is a Fields mapping that refuses an
ambiguous name, project into Constant averages over each cell rather
than its corners, extract_surface keeps only the points its faces use, the
VTK algorithms of points, lines and surfaces give vtkPolyData, and a
kernel over cells that reads their faces or edges asks for them with
incidence=.
Validated on Linux (CPU; CUDA on an RTX 6000 Ada; HIP on two MI210s; Level
Zero on an Intel Max 1100) and macOS (CPU and Metal on an M1 Max), with
debug mode, both id widths of the dataset tests and MPI, against VTK 9.7.1,
VTK master and VTK builds holding CUDA, HIP and Level Zero arrays, together
with tack-examples' ports of production datasets. A targeted round after
the last fixes reran what they touched on every machine, and the disk cache
now settles: a second and third run of the quick tests add no entries.
Added
- Segmented operations in
tack.algorithms:segment_reduce(sum, min, max, mean),
segment_scan(inclusive and exclusive sums, running min and max),
segment_broadcastandsegment_ids, over flat values and CSR offsets,
empty segments kept -- each cell's points, each point's cells, sparse rows.
A segment of up to 256 elements is one thread's; a longer one goes by
chunks of 256, a segment over several chunks combined a level up, so one
enormous segment is a few launches, not one thread's walk. On an M1 Max's
GPU a 10M-element segment reduces in 4 ms (a thread per segment: 1.2 s), a
skewed mix of 1M short segments and one of 5M in 3.7 ms (590 ms), and 2.5M
segments of about 4 in 0.66 ms (0.59). No atomics in the arithmetic, so
float sums are the same bits on every backend;ordered=Truesums each
segment in element order, asreduce_by_keydoes. Empty segments take
empty=(0, NaN for a mean, or the type's extremes for min and max), or
keep their output withempty="keep"; vectors reduce componentwise; debug
mode checks the offsets. advect(..., neighbors=True)andstreamlines(..., neighbors=True): a stage
whose particle has left the cell it was last found in tries that cell's face
neighbours before the locator's bins, taking one, as the last cell is taken,
only where it holds the point well inside, so the paths are the bins' bit
for bit. On the CPU, streamlines on the aneurysm (8.7M tetrahedra) took 1.45
to 2.04x less time (20,000 seeds: 1116 to 546 ms) and on the ONERA M6 (46.9M
cells) 1.63 to 1.90x (16,384 seeds: 2067 to 1086 ms). About one location in
seven missed the last cell, and 43-49% (aneurysm) and 78% (M6) of the misses
were in a face neighbour. The neighbours are a table of six ids a cell
(CellLocator.cell_neighbors()), built from the faces on first use and kept
with the locator: 0.9 s and 210 MB on the aneurysm, 4.1 s and 1.1 GB on the
M6, so the walk is off by default. Pyramids, polyhedra and surfaces search
the bins as before.- Tack's filters as VTK algorithms,
tack.interop.vtk.algorithms:
VTKPythonAlgorithmBasesubclasses that sit in a VTK pipeline beside VTK's
own,(reader >> Contour(field="pressure", value=0.5))().Contour,
SlicePlane,Clip,Threshold,ExtractSurface,Tetrahedralize,
SurfaceNormals,ConnectedComponentsandStreamlinesmake a dataset;
Gradients,ElevationandCellQualityadd arrays to a shallow copy of
their input;GhostCells,GenerateGlobalIdsandMergePiecestake every
piece of avtkPartitionedDataSettogether, and the others run each piece.
Parameters are properties; an exception is VTK's error and is kept as the
algorithm'serror. CPU only for now. vtk_to_dataset(..., copy=False)anddataset_to_vtk(..., copy=False)share
memory on the CPU instead of copying: points, point and cell data, cell
types, offsets and connectivity (ids in VTK's width), ghost marks and global
ids, wherever the values are one contiguous block of the type Tack keeps
(anything that must change, such as a type, an origin, strips or polyhedra,
is copied). Shared VTK arrays become read-only Tack arrays that keep VTK's
alive, and the other way.dtype=Nonekeeps each floating-point array in
its own type. The algorithms convert this way, so a pipeline copies nothing.- Examples 47-49: a VTK pipeline with Tack's filters in it, from a VTK reader
to VTK rendering; pieces of avtkPartitionedDataSetthrough ghost cells,
contours andMergePieces; streamlines. integrator="rk45"onadvectandstreamlines: steps that adapt to the
flow, as VTK'svtkStreamTracerwith its RK45 (Cash-Karp,vtkRungeKutta45)
and its rules.step_sizeis the first step; a step whose error estimate
passestolerance(a distance, 1e-6 by default) is tried again smaller, its
first stage kept; each step taken proposes the next, betweenmin_stepand
max_step(a fiftieth ofstep_sizeand twice it by default, VTK's
ratios), in either step unit. A particle's step goes with it between a GPU's
launches (bit for bit with one launch) and from piece to piece. On a swirl
at VTK's settings, Tack's RK45 takes about half of fixed RK4's points (42-44
a path, VTK 42) and lies within 2-3e-5 of the path, VTK's within 1-2e-5.max_lengthonadvectandstreamlines, with any integrator: a path that
has gone that far stops (TERMINATE); in the length unit its last step
lands on it.- The VTK comparison harness (
benchmarks/vtk_compare) times point gradients
againstvtkGradientFilter, and the performance page says what its dashes
are: comparisons not made, not failures (VTK's Viskores filters have no cell
gradient, volume or centers; the Linux run timed VTK against Tack's CPU
alone). - Bases of any order on segments, quads, pixels, hexahedra and voxels
(tack.dataset.bases):H1(data, order=p, basis=...)from order 3 and
L2(data, order=p, basis=...)from order 2 (or on Gauss-Legendre nodes from
order 1), on Gauss-Lobatto nodes (the default, MFEM's forH1),
equispaced ones (VTK's Lagrange cells) or, forL2, Gauss-Legendre ones
(MFEM's default forL2).H1holdsp - 1values per edge,(p - 1)^2
per quad face and(p - 1)^dper cell after the points, each cell reading
a shared edge in order from its lower point id and a face in the frame of
its own row, so cells turned every way share them;L2keeps each cell's
(p + 1)^dvalues.interpolate,project,probe,gradientsand
curved geometry of any order work on them; polynomials of degreepcome
back exactly. subdivide(data, level): curved or high-order cells as linear sub-cells on
each cell's lattice oflevelsteps, fields at the lattice points (VTK's
vtkCellGridToUnstructuredGrid). A lattice point shared by cells is one
point, evaluated once, by the first cell holding it.- The MFEM interop takes
H1from order 3 andL2from order 2 on quads and
hexahedra, and curved meshes of any order on them: on Gauss-Lobatto,
Gauss-Legendre and closed uniform nodes the values are copied in Tack's
numbering, on any other basis (Bernstein) evaluated at Tack's nodes,
exactly either way.mfem_grid_function(data, field, mesh)gives a field
back as an MFEMGridFunction, the same DOFs in MFEM's numbering. - VTK's Lagrange cells:
vtk_to_datasetreads a grid of
VTK_LAGRANGE_CURVE,_QUADRILATERALor_HEXAHEDRONcells of one order
pas linear cells on their corners with the geometry and point data in
H1(order=p, basis="equispaced"), VTK's nodes;dataset_to_vtk(..., higher_order=True)writes a high-order or curved dataset of those shapes as
Lagrange cells of its largest order, each shared node one point, which VTK
evaluates as Tack does. contour,sliceandslice_planetakesubdivision=: on the tensor
shapes, a field above order 1 or a curved geometry is cut on linear
sub-cells, by default as many lattice steps as the largest order of the
field and geometry, and only the cells whose field's Bernstein
coefficients can hold the value are refined. The surface has no cracks;
its error falls as the square of the step.subdivision=1cuts the cells
linearized at their corners;tolerance=(in the field's unit, a distance
for slices) chooses the fewest steps whose estimated error is within it,
from the Bernstein coefficients' distance from the corners' interpolation.subdivide, andcontourandsliceon sub-cells, keep ghost marks: a
sub-cell takes its parent's, and a lattice point i...
Tack 0.6.1
A fix for Tack's CPU on many threads. 0.6.0 capped every fan-out's chunks
at 20 µs of estimated work, meant for a few costly elements such as
streamlines; on long ranges it cut the work into thousands of interleaved
chunks, and on Linux the threads then faulted the same huge pages of new
outputs at once. On 28 threads (an EPYC 7453) every CPU filter was 2-5x
slower than the performance page reported, behind VTK on six filters of
each mesh. 0.6.1 caps only short ranges, where the cap was meant to apply.
The performance page's Linux columns are measured again with the fix, and
its CUDA column against VTK is filled for every filter.
Fixed
- A CPU fan-out caps its chunks at about 20 µs of estimated work only on a
short range, where the pool's own chunks are at most 256 elements. On any
range the cap cut long dispatches into thousands of interleaved chunks, and
on 28 threads the workers faulted the same huge pages of new outputs at
once: threshold of 20M hexahedra took 650 ms against 200, point to cell
120 against 30, and the ONERA M6's cell locator build 5.7 s against 2.9
(4.4 s against 2.8 on 8 threads; jura, EPYC 7453). Short ranges of costly
elements, such as a few streamlines, still go one element a claim.
The performance page, with the corrected numbers: https://berkgeveci.github.io/tack/0.6/performance/
Tack 0.6.0
The headline: the dataset layer takes data in the shapes simulations write
it. Meshes in pieces, over devices and MPI ranks, through
tack.communication, a subset of DIY with Tack arrays as messages: ghost
cells and global ids, merging, probes and particles that cross pieces,
statistics over ranks, GPU-aware MPI on CUDA and HIP. Point clouds, with a
point locator, SPH, deposits, friends-of-friends halos and periodic boxes.
Block-structured AMR and octrees. Physical units on fields and parameters,
and time on datasets, with filters that stream steps. The filters are
written with public names only, so users can write their own (the
Visualization Guide's "Write a Filter" chapter). Around them: polyhedra and
polygons through probe, gradients and advection; voxelization, cell quality
and feature edges; a two-level cell locator that took the streamlines of the
ONERA M6 wing (46.9M cells) from minutes to tens of milliseconds on every
GPU, 20-33x faster than Viskores' on CUDA, each building its locator; a
prototype NVIDIA Warp backend; and a performance page against VTK and
Viskores.
Validated on Linux (CPU; CUDA on an RTX 4060 Ti and an RTX 6000 Ada; HIP on
two MI210s; Level Zero on an Intel Max 1100), macOS (CPU and Metal on an M1
Max) and Windows Server 2022 (CPU, and CUDA on a T4 in TCC mode), with debug
mode, both id widths of the dataset tests and MPI over 2 and 3 ranks,
together with tack-examples' ports, among them four production datasets (up
to 46.9M cells and 512 pieces). The dataset filters agree with VTK's at 10k
to 1M cells. Against 0.5, two known costs remain on Windows' CPU: filters
over about 10k cells are 5-22% slower on two threads, where the first
fan-out costs more than it saves, and converting a mesh from VTK is 1.2-1.6x
slower.
Added
- A performance page in the documentation: Tack's filters against VTK and
Viskores at 20M hexahedra and tetrahedra on the CPU and the GPU (an EPYC
7453 with an RTX 6000 Ada, an M1 Max with its GPU), streamlines on CUDA
against Viskores' on the ONERA M6 wing and an aneurysm, and four
production datasets against VTK. Every Tack output is checked against
VTK's before its time counts. CellLocator(data, levels=1): the cells binned on one uniform grid of
aboutdensitybins a cell, every bin a leaf, as Viskores'
CellLocatorUniformBinsand VTK'svtkStaticCellLocatorbin them; the
default,levels=2, is the two-level grid (Changed). VTK and Viskores let
the caller choose the locator too. On a small, even mesh one level searches
fewer candidates (tack-examples' fire port: 6.6 a location, against 12 for
two levels);probe,advectandstreamlinestake it aslocator=. On
a mesh graded toward a body in a far field (the ONERA M6) a few bins hold
most of the cells, and two levels are the choice. Both find the same cells
and coordinates, bit for bit.td.merge_points(data, tolerance=0): coincident points made one, as VTK's
vtkStaticCleanUnstructuredGridand Viskores'CleanGridmerge them.
Points at mosttoleranceapart join, and so do chains of them; each set
becomes its smallest point, with that point's position, point fields,
ghost marks and global id, and the cells stay the same cells on the
merged points. It is for meshes written without merging their points. A
simulation's 512 pieces store each point about 2.6 times, so matching
points across pieces numbered 16.9M of them; merged piece by piece first,
generate_global_idsnumbers 6,310,285, the merged mesh's count. Point
counts match VTK's static clean, exactly and with a tolerance.- A "Write a Filter" chapter in the Visualization Guide: five built-in
filters (point_elevation,threshold,shrink,jump,triangulate)
andentropyover pieces rewritten with public names only, each section
on what that kind of filter must keep (relative positions, the device,
implicit arrays, quantities as parameters, units of results, ghost marks
throughcarry,keep_marksordrop_marks, hidden cells, owned values
over pieces). Its program,docs/examples/data_filters.py, holds every
rewrite to the built-in in every part, and runs invalidate.py. tolerance=ongenerate_global_ids,ghost_cellsandmerge_pieces
(VTK'svtkGenerateGlobalIdshas one): points of different pieces at most
that far apart are copies, and so are chains of them, for pieces whose
copies of a shared point differ in their last bits. Points are binned into
cells a little over two tolerances wide, each sent to its own cell and the
ones its box reaches, through the same sort over the pieces as exact
matching; owners then agree along chains by exchanges between partners.
The default, 0, matches exactly as before. On a simulation's 512 pieces in
f64, merged first withmerge_points, a tolerance of 1e-12 numbers
6,310,285 points (the merged mesh's), where exact matching numbers
6,311,919, and gives VTK's ghost cell count.- What the built-in filters are written with is public, so a filter of
your own is written the same way:td.carryand its maps (td.Same,
td.Take,td.Pieces,td.Interpolate),td.keep_marksand
td.drop_marks,td.visible,td.owned_values(which takes a field's
name too),td.Set.from_flags(a selection a kernel flags, for
extract_cells) andtd.units(quantities as parameters; the units of
differences, products and SI names). On the Data Model page. An audit
that rewrote built-ins with public names only found three silent errors a
user's filter made without them: a dataset built by hand dropped the
record of lost ghost marks (reductions over pieces then counted shared
points twice), a difference of degrees Celsius kept the unit, and a
hidden cell was processed.test_public_filters.pykeeps six such
rewrites equal to the built-ins, every part of the result.td.carryis
now the function; the module is stilltack.dataset.carryfor
from ... import. td.streamlines(..., step_unit="length"): steps of a fixed arc length
along the velocity's direction, as VTK'svtkStreamTracersteps by
default, withsteps * step_sizethe longest path andtimestill the
time the particle takes (1 / |v| integrated beside the path by the same
weights). The default,"time", is unchanged. A time step sized for the
fastest speed made tiny steps where the flow is slow: the carotid port's
median step was 0.0005 long against VTK's 0.1, and GPU streamlines from
a few dozen seeds were 4-100x VTK's time. With length steps the four
streamline ports take VTK's steps, match its paths to 2e-7 (carotid
2e-4), and run in 0.16-0.57x its time on 8 CPU threads.- A Visualization Guide chapter, Communicate Between Blocks, on writing
an algorithm over pieces withtack.communication: collectives,
exchanges, a ghostPlanthat makes a diffusion over blocks give the
whole line's bits,Routingpoints to the block that holds them, and
sort_by_key. Its examples run invalidate.pyand, unchanged but for
the world, undermpiexec. The Runtime API contract gains a
Communication section: what is collective, what does not depend on how
blocks are assigned, and the errors. - Two reference pages in the Visualization Guide, generated from the
docstrings: Algorithms, everytack.datasetalgorithm by what it does,
each group with a table of what it gives, what it takes (pieces, AMR,
octrees) and its VTK and Viskores counterparts; and Data Model, the
classes, constructors and sources, and the VTK, MFEM and Warp interop.
A test fails when an exported name has no entry. The site's API pages now
see tack-vis (a Griffe extension,docs/_ext/tack_namespace.py): before,
nothing undertack.datasetortack.interopcould be rendered. - A prototype NVIDIA Warp backend (
tack.device("warp"), thewarp
extra): kernels lower to generated@wp.kernelsource from Tack's typed
IR and run on Warp's CPU or CUDA device, on its current stream, with
Tack's integer and floating-point semantics,wrap_ptr, DLPack and debug
bounds checks; workgroups on CUDA only, notack.inspect
(Backend.supports_inspect). Its arrays arewp.arrays. CI'swarp
job runs it and the interop on Warp's CPU device. tack.interop.warp:from_warp/to_warpshare arrays both ways (Warp's
vector and matrix types as Tack's), andfrom_simdata/to_simdata
exchange datasets with warp-simdata. Point clouds, curves, surface meshes,
OpenFOAM meshes and patches, CGNS sections (one shape, MIXED, NGON_n,
NFACE_n), EnSight parts, corner-point grids and FLASH axisymmetric data
(anAMRDataSetof revolved boxes, coordinates implicit) come across
without copies, CGNS's 1-based and MIXED connectivities read lazily;
other models through warp-simdata's VTK conversion.- An unstructured topology of one shape whose offsets count in steps of the
shape's points shares its connectivity as the shape's rows rather than
gathering them, so an imported mesh stays one copy through the filters.
Polyhedral, polygonal and polyline topologies keep implicit arrays as
given. - Implicit booleans:
td.Union(f, g, ...),td.Intersection(...)and
td.Difference(...)combine implicit functions as VTK's
vtkImplicitBooleandoes (the smallest value, the largest, the first's or
the rest's negated), on the device, wherever a function is taken (clip,
slice, extract_geometry, extract_points, implicit_values); held to VTK in
every implicit-function comparison. td.surface_normals(data, consistent=True): a surface's polygons wound
alike -- each connected region as its first cell, by union-find with
parities over the edges on the device -- and its unit normals on cells and,
summed and made unit, on points, as VTK'svtkPolyDataNormalswithout
splitting (matched to it on spheres, scrambled windings, curved quads and
polygons). A surface no winding makes consiste...
Tack 0.5.0
The headline: the API freeze. Arrays are NumPy-style (tack.Array is
storage; "field" means a dataset's field only), devices are values
(tack.device("cuda:1")), kernels use NumPy's and GLSL's names in place
of Taichi's, and the dataset package is tack.dataset, with one name per
operation: see the Breaking entries under Changed. Around it:
several devices of one type in one process, datasets that compute on their
own device, launches queued on every GPU backend with asyncio waits,
compiled kernels kept on disk, a debug mode that checks every array index,
a CPU thread pool compiled from LLVM IR, indexable device classes with
tack.arrays' implicit arrays in the core, and structure-of-arrays
storage. Windows works for the first time, on the CPU and on CUDA.
Validated on Linux (CPU; CUDA on an RTX 4060 Ti, an RTX 6000 Ada, an H100
and four A100s in one process; HIP on two MI210s; Level Zero on an Intel
Max 1100), macOS (CPU and Metal on an M1 Max) and Windows Server 2022 (CPU,
and CUDA on a T4), with debug mode and both id widths of the dataset tests,
together with tack-examples' 57 examples. The dataset filters agree with
VTK's at 10k to 1M cells and with Viskores' on CUDA, and run faster than
0.4.0's on the CPU and on CUDA, the backends compared. One thing is untested: memory export
(Array.export_memory) on Windows. A GPU in TCC mode, as Data Center GPUs
run on Windows Server, cannot export at all.
Added
- Windows. The whole suite passes on Windows Server 2022 on the CPU and
with CUDA (a T4), after the fixes below: the disk cache stopped writing
when Windows refused to replace an open file, and CUDA failed on a GPU
without memory pools. The CPU's fan-out takes theThreadPoolExecutorthere, as
before: the JIT-compiled pool is POSIX only, so a launch needs more work
before it is worth threading (a fan-out costs 70–130 µs on Windows
against a few on Linux). - Indexable objects. A
@tack.device_classthat defines__getitem__,
__setitem__and__len__as@tack.funcmethods is indexed in kernels
as an array is:obj[i],obj[i] = v,obj[i] += v(the index evaluated
once) andlen(obj), which may bound the parallel loop. Several indices,
obj[i, j], arrive as one vector. One kernel then takes a stored array or
any indexable object, compiled once for each. An instance tuple of
numbers,self.shape = (nx, ny), is one runtime scalar per entry, read
asobj.shape[k]with a literalk; a new shape does not recompile. A
class tuple,shape = (4, 4), is read the same way and compiled in. A
store without__setitem__, and an atomic on an indexable object, are
refused when the kernel compiles. tack.arrays: the implicit arrays (CountingArray,ConstantArray,
CartesianProduct,UniformCoordinates,Permutation,Concatenate,
View,Strided,ExtractComponent,Components,Function,
Transform,Cast,RandomUniform,RandomNormal) move from
tack.dataset.arraysinto tack-core and are indexable objects: any
kernel takes them as it takes a stored array,a[k]andlen(a), not
only through a dataset field. Breaking: import them from
tack.arrays;tack.datasetno longer re-exports them.tack.algorithms(scans, sorts,gather,unique,reduce_by_key, the
statistics,copy) take implicit arrays as inputs, read in their kernels
without storing them, and implicit arrays havesum,min,maxand
meanwith a stored array's semantics (computed into a temporary, then
reduced). An implicit array is on the device of the arrays it holds
(a.device), so these run and allocate there.- Writable implicit arrays: a kernel's store into a
View,Stridedor
Permutationlands in the array it wraps (a permutation's is a scatter),
Components(x, y, z)writes each component to its own array, and
ConcatenateandExtractComponentwrite through too. An array is
writable when what it writes through is; a store into a computed array
is refused when the kernel compiles, and a read-only stored array stays
read-only behind a wrapper. - Structure-of-arrays storage.
tack.soa(x, y, z)makes a vector array
(a matrix array withdtype=tack.mat2()...) whose components are
existing arrays of scalars, without copying, so data that arrives one
array per component (another library's tensors throughfrom_dlpack,
a device pointer througharray_from_ptr, on the CPU or a GPU) is a
tack.Arrayas it is.layout="soa"onempty,zeros,ones,
full,array,asarrayand the*_likeconstructors (which keep a
prototype's layout) makes new ones;a.layoutis"aos"or"soa"
anda.componentsgives the component arrays. Kernels index an SOA
array exactly as an interleaved one, loads, stores, components,
augmented stores and vector atomics, each component its own kernel
parameter; one kernel takes either layout, compiled once for each. On
the host it reads and writes as any vector array, andcopytoand
tack.array(a, layout=...)convert between layouts. Not available for
an SOA array: a scalar atomic at a flat component index, and export as
one buffer (DLPack,export_memory, VTK), which its components do. tack.__version__, the installed tack-core's version, and a docstring
fortack(help(tack)said nothing: the docstring followed code).- NumPy-style arrays.
tack.Arrayis backend storage;tack.dataset.Field
is a function space plus coefficients, and "field" means only that now.
Constructors take the shape first, as NumPy's do:tack.empty(shape, dtype=f32),zeros,ones,full(shape, fill_value, dtype=None),
arange([start,] stop[, step], dtype=None),empty_like,zeros_like,
ones_like,full_like,array(obj, dtype=None),asarray,concat
andarray_from_ptr(ptr, shape, dtype). Any NumPy dtype is accepted
where a dtype is (np.float32,"float32"). Python floats default to
f32 and ints to i32 (i64 if a value needs it), since f64 is not on every
backend; a NumPy array keeps its dtype. Vectors and matrices are element
types:tack.empty((n,), tack.vec3()),vec(n, dtype),mat2...mat4,
mat(rows, columns, dtype);shapecounts elements anda.numpy()
gives(*shape, 3). Data moves witha.numpy()ornp.asarray(a),
await a.numpy_async(),tack.copyto(a, host)(strict, as
np.copyto: the host values havea.numpy()'s shape or broadcast to
it) anda.fill(value). Arrays also havendim,nbytesand
reshape(*shape)with one-1. asynciowaits:await tack.sync_async()andawait a.numpy_async()wait for the device in a worker thread, so an
application's event loop (trame, Jupyter, a server) keeps running
while kernels finish; kernel calls themselves are unchanged. On CUDA
the wait is an event on the context's stream, on Metal the last
committed command buffer, on Level Zero a host-visible event signalled
by a barrier on the backend's command list, on HIP an event on the
device's stream; on the CPU, whose launches complete before returning,
the wait is inline. During a 490 ms CUDA kernel another task ran 436
times while one awaitedsync_async, and not once undertack.sync();
during a 685 ms Level Zero kernel (Intel Max 1100), 311 to 384 times;
during a 1.45 s HIP kernel (MI210), 1353 times.
Level Zero'sto_numpy,read_rangeand reductions now wait on such
an event outside the backend's lock, so another thread may launch
while one waits. Every HIP wait (tack.sync(), reads, reductions) is
on an event too, through ctypes: hip-python's wrappers hold the GIL
while the runtime waits, which stopped every other Python thread for
the length of the kernel, and ROCm'shipStreamSynchronizeholds the
stream, so a launch from another thread took the whole wait (350 ms)
and now takes 60 µs. CUDA reads wait for the stream before they copy,
for the same reason: a copy to pageable host memory waited with the
context held, and a launch from another thread took the whole wait
(910 ms on an H100), now 43 µs.- Compiled kernels are kept on disk, so a later process starts warm: the
first contour of a 21³ grid in a new process went from 445 ms (CPU) and
1.1 s (Metal) to 31 ms on an M1 Max. The lowered kernel and each
compiled variant are stored, keyed by content; an edited kernel, device
function, constant or template class, another Tack or another machine
compiles again.TACK_CACHE_DIRchooses the directory (by default the
platform's per-user cache directory) andTACK_CACHE=offturns it off;
tack.cache.configure()does either from Python. For MPI jobs on a
shared file system,python -m tack.cache packgathers a warm-up run's
entries into one bundle, which each rank reads once (or rank 0 reads and
broadcasts,tack.cache.load_bundle(comm=...)); under MPI nothing is
looked up or written per kernel. The entries take at most
TACK_CACHE_SIZE(1 GiB by default); the least recently used go first.
Every backend stores compiled code: CUDA its PTX, HIP its code objects,
Level Zero its native binary, with the SPIR-V to fall back on. Debug
mode's kernels are stored apart from the others.
See The Kernel Cache in the User's Guide. - Debug mode:
tack.set_debug(True)orTACK_DEBUG=1checks every
array index in every kernel, one dimension at a time. An
out-of-bounds access is skipped (a load gives 0) and the call raises
IndexErrornaming the access, its file and line, the index and the
extent, and how many more were skipped; an access inside a device
function names it. It runs on every backend, compiles separately from
normal kernels, and does not compile per array length. Without it,
generated code is unchanged. pytest -m quick, a module per area of the code, 80 s on four
workers, andpytest -n autofor the whole suite across processes
(pytest-xdist is in thedevextra): 4:30 ...
Tack 0.4.0
The headline: tack.data, a dataset API in tack-vis. Meshes, the
fields on them and over fifty visualization algorithms run on every
backend, and their outputs agree with VTK's on hexahedral and tetrahedral
meshes from 10k to 1M cells, and with Viskores' on CUDA. The core gained
what that work needed: queued Metal launches, workgroup scans and sorts on
GPUs, fills that stay on the device, 2D and 3D grids for ndrange, and
device classes that hold and iterate over one another. Some kernels now
compute different results: f64 kernels using float-literal locals, the
statistics in tack.algorithms, floating-point scans on GPUs (in the last
bits), and i8/i16 negation on CUDA drivers before 13.3; see Kernels that
now compute different results.
Validated on Linux (CPU; CUDA on an RTX 4060 Ti and an RTX 6000 Ada; HIP
on an MI210; Level Zero on an Intel Max 1100) and macOS (CPU and Metal on
an M1 Max), both id widths of the dataset tests, together with the 57
example checks in tack-examples.
Added
The dataset API
tack.data(intack-vis): meshes, the fields on them, and the
algorithms that work on both. It is described in the User's Guide
chapter Datasets and visualization and the Dataset API reference.- Topologies: structured grids; unstructured meshes of the linear
cells, vertex to pyramid; and polyhedra, polygons and polylines. - Fields: a field is a space (
H1of order 1 or 2,L2,Constant,
Values) and its values. The values may be an implicit array that
stores nothing, such as a grid's coordinates. - Sets: named sets of points, cells or faces, carried through
filters. - 64-bit ids wherever a mesh needs them.
- Algorithms: over fifty, among them contour (and López's on
polyhedra), slice, clip, threshold, external faces, gradients,
projectbetween spaces, the cell locator and probe, advection and
streamlines. All run on every backend. - Your own kernels see a mesh as the built-in ones do, through
for_eachand per-shape views. - Interop:
tack.interop.vtkconverts whole datasets with VTK, and
tack.interop.mfemreads MFEM meshes and grid functions.
- Topologies: structured grids; unstructured meshes of the linear
- What the algorithms promise. They check field ownership before
dispatch, including empty inputs, and reject locators built for another
dataset.dotandcrossrequire matching dtypes, ascompositedoes;
useCastfor conversion. Fractional computations convert integer
storage before arithmetic, so clipping differences do not overflow;
integer magnitude and logarithms return floating point fields.
Computation uses f64 for f64 input, otherwise f32, with the
corresponding precision limits.statisticssums integer values exactly
in f64 (to 2^53) instead of wrapping; its moments use the floating
precision. Face positions refresh after editing L2 geometry. Shrink
accepts quadratic geometry through its corner values, and probe samples
a quadratic target's points while keeping its geometry. Advection and
host-point probing preserve the source's coordinate precision.
Device classes
- A
@tack.device_classobject may hold others as attributes, to any
depth:self.base.get(k)in a method,obj.base.stepin a kernel. The
tree is one template argument. Composed objects inline to the code one
would write by hand, and a class holding itself is refused. - A kernel can loop over a
@tack.device_classobject:for c in cells:.
The class declares the attributes the loop runs through as
__tack_iterate__, one to three names, fastest first. One makescan
integer overrange; two or three makecthe vector of indices over
anndrange, which as the parallel loop launches in its own shape. The
object's methods takecas it comes, so one kernel runs over objects
that iterate differently. See Iterating an Object in the User's Guide.
Runtime and algorithms
tack.sync()waits for every launch queued on the current backend. It
is a no-op where launches complete before returning.exclusive_scanandinclusive_scantaketotal=Falseto skip the
total: nothing is read back to the host, so on Metal the scan stays
queued with whatever follows. The radix sort's passes and the dataset
algorithms that only need offsets use it; a 1M-key sort went from 10.7
to 9.4 ms on CPU and from 7.7 to 6.3 ms on Metal.argsortandsort_by_keytake more than 2^31 - 1 keys, with i64
indices beyond that count;argsort(..., index_dtype=tack.i64)asks
for them at any size.
Changed
-
@tack.data_orientedis now@tack.device_class, a name for what it
does: its objects can be kernel arguments, and kernels specialize on
their class.@tack.data_orientedremains as an alias, so existing
code (and code written for Taichi) runs unchanged. -
The first visualization worklets moved to
tack.deprecated, superseded
bytack.data(see Added):flying_edges,compute_normals,cell_to_pointandamr_blanking
are now undertack.deprecated.algorithms;- the finite-element helpers in
tack.feare nowtack.deprecated.fe.
They still import from their new places.
tack.algorithmsno longer
re-exports them and now holds the compute primitives alone (scans,
sorts, copies). Changefrom tack.algorithms.flying_edges import ...to
from tack.deprecated.algorithms.flying_edges import ..., or move to
tack.data.contour. -
The examples that used the deprecated worklets now use
tack.data:- the isosurface tutorial,
examples/32_pathtrace.pyand
examples/37_insitu_pipeline.pypass the contour's own device fields
to the renderer; tack-vis/31_multiblock_flying_edges.pyis now
31_multiblock_contour.py, one contour per block;- the
tack.feexamples moved totack-vis/examples/deprecated/and
still run in the examples sweep.
Examples that save an image write it under
results/, as the others
already did, instead of into the working directory. - the isosurface tutorial,
-
Metal launches are queued instead of waited for one by one. The host
waits when it touches field memory, reduces a field, or calls the new
tack.sync(); an error in a launch surfaces at that wait rather than
at the call. Results are unchanged. To time a Metal kernel, call
tack.sync()before reading the clock. -
The CUDA backend warns, at its first compile, when NVRTC is older than
13. NVRTC 12.0 miscompiled one of the ported examples (lattice
Boltzmann on an H100: density off by up to 1.6e-2, against 2.3e-6 with
NVRTC 13.2). The warning names the remedy: thenvidia-cuda-nvrtc
wheel for a CUDA version no newer than the driver's, which cuda-python
finds before a system toolkit.
Kernels that now compute different results
-
var,std,norm,absmax,count_nonzeroanddotin
tack.algorithmsno longer combine into a one-element f32 (or i32)
atomic accumulator. Each forms its terms in the inputs' precision --
f64 if any input is f64, otherwise f32, an integer input converted
first -- and reduces them asField.sum()andField.max()do, so the
field-reduction contract applies. f64 data is now summed in f64:
varof 1e8 + 0..999 is exact where f32 gave nonsense.count_nonzero
counts in i64 and no longer wraps past 2^31. Integer products no longer
wrap before converting, and neither does the meanvartakes of
integer data (four equal i64 values of 2^62 had a variance of 2e37).
varreturns a Python float, not NumPy's float32, andabsmax
propagates a NaN. -
On GPUs, a floating-point
exclusive_scanorinclusive_scancombines
lanes in tree order, so it can differ fromnp.cumsumin the last bits
from the ninth element on. CPU results are unchanged. -
A local assigned once, to float literals, takes the precision of what
it meets where it is read, as the literal written there would: with an
f64x,a = 0.1; y = x * auses the f64 nearest 0.1. It was an f32
local, so f64 kernels computed with the f32 rounding of the literal.
This includes literals a device function returns, such as a cell's
parametric center returned as a vector of literals, which made shape
weights f32 on f64 data. A local assigned only literals more than once,
such as the result of a device function returning literals from
several branches, takes the kernel's float precision, as a float scalar
argument does: f64 when a field is f64. f32 kernels are unchanged. -
On CUDA, negating an i8 or i16 value (
-x,abs(x)) and then widening
it keeps the wrapped result:-(-32768)in i16 widens to −32768. On
drivers before CUDA 13.3 it widened to 32768. NVIDIA's PTX assembler,
which those drivers run on Tack's PTX, drops the sign extension after a
16-bitnegorabs, on every architecture; ptxas 13.3 fixed it. The
CUDA generator now negates i8 and i16 values with a 32-bit inline-PTX
subtraction, so no 16-bit negation reaches the driver.
Performance changes users may notice
-
A kernel taking a
@tack.device_classobject no longer compiles anew
for every length of a field the object holds. The object's fields were
keyed by their full shape; they are now keyed by rank, and the
dimensions the code actually bakes in (a row stride, a length used in
arithmetic) still specialize, as they do for plain field arguments. A
contour of a 64^3 grid on Metal at an output size not seen before went
from 36 to 9 ms. The bucket sort's key template recompiled for every
size of contour, slice and clip; the dataset views likewise hold
fields of every mesh's size. -
Metal no longer waits about 0.3 ms after every launch: a contour of 100k
cells, some 76 launches, spent 26 ms waiting. It also lets Metal clear
new buffers instead of clearing them on the CPU, which was 252 of
399 ms when deriving the faces of 5M hexahedra. -
tack.zeroson Metal takes the new buffer as Metal cleared it. It used
to fill it on the...
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 reduc...