Standalone Apple GPU experiments for anisotropic clover-Wilson inversion.
This project grew out of studying Eloy Romero's mgproton multigrid prototype
in Chroma and his SuperbBLAS work.
We credit that work for guiding the initial sparse color/spin representation
and the investigation of even/odd preconditioning, chirality-split aggregation,
Galerkin coarse operators, and Krylov solvers. MetalClover implements these
ideas with dedicated CPU and Metal kernels. The optional near-null/SVD basis
builder follows the homogeneous-solve and local-compression approach in
mgproton; the hierarchy application and memory management remain separate
implementations.
The fermion-action conventions and independent numerical references come from
Chroma and QDP++. The anisotropic
stout-smeared clover-Wilson operator follows Chroma's conventions, and the native
adapter and verification tools use Chroma/QDP++ to check the stout gauge state,
operator application, and full FP64 residuals. These checks establish agreement
with the Chroma operator; they do not establish identical hierarchy construction
or convergence behavior to mgproton. We acknowledge Eloy Romero and the
Chroma/QDP++ developers for these foundations.
The source and reproducible numerical results are in metal-bsr-prototype.
- Near-null/SVD MG on 32³×256: 4.61× warm solve speedup and original Chroma FP64 checks
- Real 32³×256 low-memory LDL clover, tuned MG timings, and native FP64 checks
- Real 24³×256 MG tuning and original Chroma FP64 validation
- Homogeneous near-null solves and SVD-compressed MG basis
- Native Chroma adapter, action conventions, and initial real-field timings
- Standalone prototype overview
Large gauge fields, generated binaries, and saved solution fields are excluded from Git; text results, input/output hashes, source, and reproduction instructions are versioned.
Build the installable Metal library with Apple Clang:
make install PREFIX=/path/to/metal-prefixAll C++ library types and routines are in MetalCloverEnv. The public header
metalclover/metalclover.h provides a C ABI usable from GCC-built Chroma,
separate full and odd-Schur solve interfaces, arrays of source/solution pointers,
and structured residual, iteration, timing and nominal operator-work results.
One context owns and reuses one hierarchy. Array solves run batched GPU tiles
(default cap 8), sharing gauge, clover and hierarchy data. The caller owns
the source and solution arrays.
See batched RHS support and
interfaces and FLOP accounting.
For distillation, each color eigenvector supplies four source-spin RHS;
num_vecs=1 therefore means four inversions.
The Chroma integration on rge/devel-datalib-reorg enables
MetalBiCGClover and MetalMGClover with --with-metal=/path/to/metal-prefix.
It implements the vector SystemSolver interface used by the SuperbBLAS
propagator/distillation measurement, including native even/odd reduction and
reconstruction. Each refinement uses the supplied original Chroma FP64
operator. See Chroma's docs/metal-clover.md for XML and the real-gauge harness.
Run make format from the repo root or metal-bsr-prototype/ to format the
.hpp, .cc, .mm, and .metal sources using the checked-in
.clang-format. This requires clang-format on PATH;
override the executable with make format CLANG_FORMAT=clang-format-23 if needed.
Use make format-check to check formatting without modifying files. CI pins
clang-format to 23.1.5, the version used to format the current sources.
GitHub Actions runs on pushes, pull requests, and
manual dispatches. It checks formatting on Ubuntu and builds all 19 standalone
Objective-C++ programs on an Apple Silicon macos-15 runner with Xcode 16.4.
It also compiles all ten Metal shader files offline using make -C metal-bsr-prototype metal-check; this does not require GPU execution.
CI covers the standalone build. Native Chroma/QDP++ adapters require a separate installation, and the real-field residual checks and performance studies require local gauge data and an Apple GPU. Those numerical runs remain separate from the hosted formatting and build checks.