streami

streami is an MPI- and CUDA-based, distributed-memory tool for computing streamlines and streaklines through 3D vector fields. It integrates particles via Runge-Kutta-style stepping over either structured (regular grid) or unstructured (tet/pyramid/wedge/hex mesh, via UMesh) fields, and ships both a headless command-line tool and an interactive ANARI-based editor/viewer.

Domain decomposition is done via macrocells, one per MPI rank. Particles ("rays") that leave a rank's macrocell are forwarded to the owning rank using rafi, a small ray-forwarding infrastructure library built for exactly this kind of wavefront/ray-relay pattern across ranks.

Project layout

Path	Description
streami.h / streami.cu	Core library: Context, Tracer, VecField, MacroCell, particle I/O
main.cu	Headless CLI driver (STREAMI_APP); selects between Spherical/RAW/UMesh use cases
field/	Vector field implementations: StructuredField, UMeshField, SphericalField (procedural test field)
gpu/	CUDA kernels for seeding particles and advancing them through a field
editor/	Interactive ANARI-based viewer for visualizing streamlines/streaklines alongside volume rendering
common/	Shared rendering/course infrastructure (dvr_course-common): framebuffer, pipeline, transfer functions, vec math
tools/convert_icon	Optional command-line data-wrangling tool (off by default)
submodules/rafi	Ray Forwarding Infrastructure — MPI library for forwarding "rays" (here: particles) between ranks
submodules/cuBQL	CUDA BVH/spatial query library, used for point location in unstructured meshes

Building

Requirements:

• CMake >= 3.26.5
• CUDA toolkit + a CUDA-capable GPU
• MPI
• umesh (must be findable via find_package(umesh))
• ANARI >= 0.15.0 (for the editor target)

git submodule update --init --recursive
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . -j

This produces:

• streami — the headless CLI executable
• streami_library — the core tracer as a library (linked by the editor)
• streami-editor — the interactive ANARI viewer

Optional cmdline data tools can be enabled with -DBUILD_CMDLINE_TOOLS=ON.

Running

Headless CLI (streami)

main.cu dispatches to one of three use cases (main_Spherical, main_RAW, main_UMesh — selected in code; main_UMesh is active by default). For a .umesh/.raw unstructured or voxel input:

mpirun -np <N> ./streami input.umesh \
  -gx <gx> -gy <gy> -gz <gz> \      # macrocell grid; gx*gy*gz must equal N ranks
  -numparticles 100000 \
  -numsteps 1000 \
  -stepsize 1.0 \
  -minlength 1e-3 \
  -halo 0.0

For raw voxel input (.raw), pass -dims x y z to specify the grid dimensions. Output streamlines are written per-rank as streamlinesN.obj, plus a gathered all.obj on rank 0.

Global region-of-interest seeding can be restricted with -roi x0 y0 z0 x1 y1 z1 (Cartesian box) or -spherical-roi ... (in lat/lon/radius space).

Interactive editor (streami-editor)

./streami-editor input.umesh \
  -numparticles 5 -numsteps 1000 -stepsize 0.5 -minlength 1e-3 \
  [-streaklines] [-tuberadius r] [-roi x0 y0 z0 x1 y1 z1] \
  [-dims x y z -org ox oy oz -spacing sx sy sz]   # for raw voxel input

The editor renders the traced lines as tubes alongside a volume rendering of the field using ANARI, and lets you interactively pick a region of interest in the viewer (printed back out as a -roi flag for reuse on the command line).

Contributors

• Stefan Zellmann — University of Cologne
• Milan Jaros — IT4Innovations, VSB – Technical University of Ostrava
• Andrea Paris — NVIDIA
• Ingo Wald — NVIDIA
• Tatiana von Landesberger — University of Cologne

References

If you use this software in your research, please cite:

Stefan Zellmann, Milan Jaroš, Andrea Paris, Ingo Wald, Tatiana von Landesberger. Streami: An MPI Data-Parallel Library to Compute Field Lines on GPUs. VIS 2026 Short Papers, 2026.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

SPDX-License-Identifier: Apache-2.0

Key concepts

• VecField — abstract base for anything sampleable as a 3D vector field; concrete implementations are StructuredField (regular grid), UMeshField (unstructured mesh, BVH-accelerated via cuBQL), and SphericalField (procedural, used for testing).
• MacroCell — the per-rank spatial subdomain (with optional halo region) that a VecField is decomposed into; computed via makeMacroCell() from the global world bounds, an MPI rank's position in a regular grid of ranks, and a halo width.
• Tracer — drives the integration: seeds particles, repeatedly advances them through the locally-owned field, and uses rafi to forward particles across rank boundaries until they exit the domain or reach maxSteps/minLength.