lbm-portable

A 2D D2Q9 lattice Boltzmann lid-driven cavity solver, written once in Julia with KernelAbstractions.jl, with bit-identical results on three non-NVIDIA backends:

• AMD Ryzen 7 PRO 7840U CPU (KernelAbstractions.CPU())
• AMD Radeon 780M integrated GPU (AMDGPU.jl + ROCm 6.4)
• Apple M1 7-core GPU (Metal.jl)

The same @kernel body runs unchanged on every backend; the only per-backend code is the array constructor (one line).

Companion source for the TUM SCCS Master's seminar Modern Trends in High Performance Computing (IN2107 / IN2183), Summer 2026.

Quick start

If Julia is not installed yet, install it via juliaup:

curl -fsSL https://install.julialang.org | sh
# reopen the shell (or source your shell's rc file), then check:
julia --version   # any 1.12.x matches the pinned Manifest

git clone https://github.com/HardMax71/lbm-portable-julia.git
cd lbm-portable-julia
julia --project=. -e 'using Pkg; Pkg.instantiate()'

Toolchain smoke tests (30 s each; checks each backend loads):

JULIA_NUM_THREADS=auto julia --project=. scripts/run_ka_cpu.jl   # CPU
HSA_OVERRIDE_GFX_VERSION=11.0.0 julia --project=. scripts/smoke.jl   # AMD
julia --project=. scripts/smoke_metal.jl                              # M1

AMD GPU (Debian 13 trixie, Phoenix1 / gfx1103):

./setup_amd_backend.sh                                         # one-time, ROCm 6.4
HSA_OVERRIDE_GFX_VERSION=11.0.0 julia --project=. scripts/run_ka_amd.jl

Apple M1 (macOS, Metal):

• One-time: Xcode CLT (xcode-select --install), juliaup, then julia --project=. -e 'using Pkg; Pkg.instantiate()'.
• Clone outside ~/Desktop, ~/Documents, ~/Downloads, ~/Pictures - macOS sandboxes those four folders and Julia's pwd() will fail with EPERM unless Terminal has Files-and-Folders access for them.
• Then run any scripts/*_metal.jl or scripts/metal_*.jl; output files land in data/.

Layout

src/                  CPU oracle + KA single-source kernel + JACC port
scripts/              acquire_* (run, write CSV), plot_* (read CSV, write PDF),
                      validate / benchmark / smoke / energy / pennycook
data/                 Ghia 1982 reference + per-backend measurement CSVs
figures/              paper PDFs produced by scripts/plot_*.jl
platform/             amd/, m1/: lscpu, lspci, Pkg.status(), versioninfo
setup_amd_backend.sh  Debian 13 ROCm 6.4 installer

Dependencies

Pinned in Project.toml / Manifest.toml. The major ones:

• Julia 1.12.6
• KernelAbstractions 0.9.41 (vendor-neutral kernel macros)
• AMDGPU 2.3.0 (AMD GPU backend; needs ROCm 6.x)
• Metal 1.9.3 (Apple Silicon backend; macOS only)
• JACC 1.3.1 (for the portability comparison)
• Plots, LaTeXStrings, BenchmarkTools

Project.toml resolves on every supported machine; Pkg.instantiate() fetches everything including the backend the local machine can run. Backends the local machine can NOT run (e.g. Metal on Linux) load lazily.

License

Source code: MIT (see LICENSE). Copyright (c) 2026 Maksym Azatian.

The Ghia 1982 reference data cached in data/external/ is sourced from public transcriptions; provenance and licensing notes are in data/external/README.md.