Add native Apple Silicon Metal support - #413

1. Scope

This change extends mumax³ from NVIDIA CUDA hosts to native Apple Silicon Macs running macOS 14 or later. Linux and Windows continue to select the existing CUDA implementation. Intel Macs are not included.

2. Technical implementation

The build selects the backend through darwin/arm64 build tags. Metal Shading Language kernels and Go launch wrappers implement the existing CUDA kernel contracts. An Objective C++ runtime bridge maps allocation, copies, ordered command submission, synchronization, and kernel launches to Metal and Apple unified memory. MPSGraph provides real to complex and complex to real FFT operations with the packed layout used by cuFFT. Ten round Philox4x32 with Box Muller generation provides thermal noise on Metal. Runtime shader compilation allows the build to work with Apple Command Line Tools without CUDA or the full Xcode application.

3. Physics engine

No physical equation, material term, energy expression, solver, integrator, or upstream regression input is changed. The .mx3 language, high level Go model, physical parameters, and output formats remain common to both backends. The existing CUDA source remains selected on non Apple hosts.

The Metal backend preserves the single precision numerical model and the FFT data layout used by the demagnetizing field convolution. Parallel reduction order can change the final floating point bits. Metal thermal simulations use Philox while CUDA uses the cuRAND XORWOW sequence, so equal seeds are reproducible within Metal but select different sample sequences across backends. Thermal correctness is therefore tested statistically rather than by matching individual random samples.

4. Validation

All 15 runnable simulations from the official mumax³ examples page completed on Apple M4 Metal with 15 passes, zero failures, 96 OVF files, 1,118 table lines, and no empty artifact or NaN or Inf table value. The exact inputs, execution logs, outputs, provenance, and GPL attribution are recorded in the official examples result.

The nonthermal physics cohort passed 15 of 15 unchanged upstream tests and 103 of 103 original assertions, giving 100.000 percent conformance within the upstream tolerances. Ten average magnetization vectors produced 99.9923 percent mean normalized L2 agreement, 99.9984 percent median agreement, and 99.9415 percent minimum agreement with the embedded upstream references. All 19 zero tolerance assertions matched exactly. The method and individual values are recorded in the physics validation result.

This PR branch also passed the Metal generator and shader checks, all Go tests with the cache disabled, the macOS installer build and Metal initialization test, validation of all 176 upstream .mx3 files, and a fresh execution of the same 15 nonthermal physics tests with 15 passes.

5. Installation

The README adds one Apple Silicon section containing both the automated fresh Mac installer and the separate manual dependency, clone, build, path, and verification procedure.

6. Author

My name is Taewoo Park and I am an undergraduate physics student at the Korea Advanced Institute of Science and Technology (KAIST) and a research intern at the KAIST Ultrafast Spin Dynamics Laboratory (USDL), led by Prof. Kab-Jin Kim.

Contact: ptw151125@kaist.ac.kr