Skip to content

Releases

Tack 0.7.0

Choose a tag to compare

@berkgeveci berkgeveci released this 06 Nov 21:28
b2068f6

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_broadcast and segment_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=True sums each
    segment in element order, as reduce_by_key does. Empty segments take
    empty= (0, NaN for a mean, or the type's extremes for min and max), or
    keep their output with empty="keep"; vectors reduce componentwise; debug
    mode checks the offsets.
  • advect(..., neighbors=True) and streamlines(..., 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:
    VTKPythonAlgorithmBase subclasses that sit in a VTK pipeline beside VTK's
    own, (reader >> Contour(field="pressure", value=0.5))(). Contour,
    SlicePlane, Clip, Threshold, ExtractSurface, Tetrahedralize,
    SurfaceNormals, ConnectedComponents and Streamlines make a dataset;
    Gradients, Elevation and CellQuality add arrays to a shallow copy of
    their input; GhostCells, GenerateGlobalIds and MergePieces take every
    piece of a vtkPartitionedDataSet together, and the others run each piece.
    Parameters are properties; an exception is VTK's error and is kept as the
    algorithm's error. CPU only for now.
  • vtk_to_dataset(..., copy=False) and dataset_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=None keeps 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 a vtkPartitionedDataSet through ghost cells,
    contours and MergePieces; streamlines.
  • integrator="rk45" on advect and streamlines: steps that adapt to the
    flow, as VTK's vtkStreamTracer with its RK45 (Cash-Karp, vtkRungeKutta45)
    and its rules. step_size is the first step; a step whose error estimate
    passes tolerance (a distance, 1e-6 by default) is tried again smaller, its
    first stage kept; each step taken proposes the next, between min_step and
    max_step (a fiftieth of step_size and 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_length on advect and streamlines, 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
    against vtkGradientFilter, 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 for H1),
    equispaced ones (VTK's Lagrange cells) or, for L2, Gauss-Legendre ones
    (MFEM's default for L2). H1 holds p - 1 values per edge, (p - 1)^2
    per quad face and (p - 1)^d per 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; L2 keeps each cell's
    (p + 1)^d values. interpolate, project, probe, gradients and
    curved geometry of any order work on them; polynomials of degree p come
    back exactly.
  • subdivide(data, level): curved or high-order cells as linear sub-cells on
    each cell's lattice of level steps, 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 H1 from order 3 and L2 from 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 MFEM GridFunction, the same DOFs in MFEM's numbering.
  • VTK's Lagrange cells: vtk_to_dataset reads a grid of
    VTK_LAGRANGE_CURVE, _QUADRILATERAL or _HEXAHEDRON cells of one order
    p as 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, slice and slice_plane take subdivision=: 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=1 cuts 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, and contour and slice on sub-cells, keep ghost marks: a
    sub-cell takes its parent's, and a lattice point i...
Read more

Tack 0.6.1

Choose a tag to compare

@berkgeveci berkgeveci released this 29 Oct 01:09
db8a102

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

Choose a tag to compare

@berkgeveci berkgeveci released this 28 Oct 18:32
e13e67d

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
    about density bins a cell, every bin a leaf, as Viskores'
    CellLocatorUniformBins and VTK's vtkStaticCellLocator bin 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, advect and streamlines take it as locator=. 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
    vtkStaticCleanUnstructuredGrid and Viskores' CleanGrid merge them.
    Points at most tolerance apart 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_ids numbers 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)
    and entropy over 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
    through carry, keep_marks or drop_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 in validate.py.
  • tolerance= on generate_global_ids, ghost_cells and merge_pieces
    (VTK's vtkGenerateGlobalIds has 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 with merge_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.carry and its maps (td.Same,
    td.Take, td.Pieces, td.Interpolate), td.keep_marks and
    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) and td.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.py keeps six such
    rewrites equal to the built-ins, every part of the result. td.carry is
    now the function; the module is still tack.dataset.carry for
    from ... import.
  • td.streamlines(..., step_unit="length"): steps of a fixed arc length
    along the velocity's direction, as VTK's vtkStreamTracer steps by
    default, with steps * step_size the longest path and time still 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 with tack.communication: collectives,
    exchanges, a ghost Plan that makes a diffusion over blocks give the
    whole line's bits, Routing points to the block that holds them, and
    sort_by_key. Its examples run in validate.py and, unchanged but for
    the world, under mpiexec. 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, every tack.dataset algorithm 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 under tack.dataset or tack.interop could be rendered.
  • A prototype NVIDIA Warp backend (tack.device("warp"), the warp
    extra): kernels lower to generated @wp.kernel source 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, no tack.inspect
    (Backend.supports_inspect). Its arrays are wp.arrays. CI's warp
    job runs it and the interop on Warp's CPU device.
  • tack.interop.warp: from_warp/to_warp share arrays both ways (Warp's
    vector and matrix types as Tack's), and from_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
    (an AMRDataSet of 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
    vtkImplicitBoolean does (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's vtkPolyDataNormals without
    splitting (matched to it on spheres, scrambled windings, curved quads and
    polygons). A surface no winding makes consiste...
Read more

Tack 0.5.0

Choose a tag to compare

@berkgeveci berkgeveci released this 22 Oct 16:09
335479d

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 the ThreadPoolExecutor there, 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_class that defines __getitem__,
    __setitem__ and __len__ as @tack.func methods is indexed in kernels
    as an array is: obj[i], obj[i] = v, obj[i] += v (the index evaluated
    once) and len(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
    as obj.shape[k] with a literal k; 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.arrays into tack-core and are indexable objects: any
    kernel takes them as it takes a stored array, a[k] and len(a), not
    only through a dataset field. Breaking: import them from
    tack.arrays; tack.dataset no 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 have sum, min, max and
    mean with 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, Strided or
    Permutation lands in the array it wraps (a permutation's is a scatter),
    Components(x, y, z) writes each component to its own array, and
    Concatenate and ExtractComponent write 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 with dtype=tack.mat2()...) whose components are
    existing arrays of scalars, without copying, so data that arrives one
    array per component (another library's tensors through from_dlpack,
    a device pointer through array_from_ptr, on the CPU or a GPU) is a
    tack.Array as it is. layout="soa" on empty, zeros, ones,
    full, array, asarray and the *_like constructors (which keep a
    prototype's layout) makes new ones; a.layout is "aos" or "soa"
    and a.components gives 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, and copyto and
    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
    for tack (help(tack) said nothing: the docstring followed code).
  • NumPy-style arrays. tack.Array is 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
    and array_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); shape counts elements and a.numpy()
    gives (*shape, 3). Data moves with a.numpy() or np.asarray(a),
    await a.numpy_async(), tack.copyto(a, host) (strict, as
    np.copyto: the host values have a.numpy()'s shape or broadcast to
    it) and a.fill(value). Arrays also have ndim, nbytes and
    reshape(*shape) with one -1.
  • asyncio waits: await tack.sync_async() and await 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 awaited sync_async, and not once under tack.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's to_numpy, read_range and 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's hipStreamSynchronize holds 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_DIR chooses the directory (by default the
    platform's per-user cache directory) and TACK_CACHE=off turns it off;
    tack.cache.configure() does either from Python. For MPI jobs on a
    shared file system, python -m tack.cache pack gathers 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) or TACK_DEBUG=1 checks 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
    IndexError naming 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, and pytest -n auto for the whole suite across processes
    (pytest-xdist is in the dev extra): 4:30 ...
Read more

Tack 0.4.0

Choose a tag to compare

@berkgeveci berkgeveci released this 17 Oct 00:34
c690d2d

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 (in tack-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 (H1 of 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,
      project between 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_each and per-shape views.
    • Interop: tack.interop.vtk converts whole datasets with VTK, and
      tack.interop.mfem reads MFEM meshes and grid functions.
  • What the algorithms promise. They check field ownership before
    dispatch, including empty inputs, and reject locators built for another
    dataset. dot and cross require matching dtypes, as composite does;
    use Cast for 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. statistics sums 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_class object may hold others as attributes, to any
    depth: self.base.get(k) in a method, obj.base.step in 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_class object: for c in cells:.
    The class declares the attributes the loop runs through as
    __tack_iterate__, one to three names, fastest first. One makes c an
    integer over range; two or three make c the vector of indices over
    an ndrange, which as the parallel loop launches in its own shape. The
    object's methods take c as 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_scan and inclusive_scan take total=False to 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.
  • argsort and sort_by_key take 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_oriented is now @tack.device_class, a name for what it
    does: its objects can be kernel arguments, and kernels specialize on
    their class. @tack.data_oriented remains as an alias, so existing
    code (and code written for Taichi) runs unchanged.

  • The first visualization worklets moved to tack.deprecated, superseded
    by tack.data (see Added):

    • flying_edges, compute_normals, cell_to_point and amr_blanking
      are now under tack.deprecated.algorithms;
    • the finite-element helpers in tack.fe are now tack.deprecated.fe.

    They still import from their new places. tack.algorithms no longer
    re-exports them and now holds the compute primitives alone (scans,
    sorts, copies). Change from 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.py and
      examples/37_insitu_pipeline.py pass the contour's own device fields
      to the renderer;
    • tack-vis/31_multiblock_flying_edges.py is now
      31_multiblock_contour.py, one contour per block;
    • the tack.fe examples moved to tack-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.

  • 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: the nvidia-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_nonzero and dot in
    tack.algorithms no 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 as Field.sum() and Field.max() do, so the
    field-reduction contract applies. f64 data is now summed in f64:
    var of 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 mean var takes of
    integer data (four equal i64 values of 2^62 had a variance of 2e37).
    var returns a Python float, not NumPy's float32, and absmax
    propagates a NaN.

  • On GPUs, a floating-point exclusive_scan or inclusive_scan combines
    lanes in tree order, so it can differ from np.cumsum in 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
    f64 x, a = 0.1; y = x * a uses 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-bit neg or abs, 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_class object 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.zeros on Metal takes the new buffer as Metal cleared it. It used
    to fill it on the...

Read more

Tack 0.3.0

Choose a tag to compare

@berkgeveci berkgeveci released this 07 Oct 19:59
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 reduc...
Read more