Accelerate 2D advection-diffusion and add CPU/GPU performance benchmarks

README.md

@@ -69,6 +69,39 @@ where `s` is the concentration of a passive scalar quantity, `D` is a molecular
 coefficient, and `v` is a prescribed velocity field.  This repository's 2D-advection-diffusion
 [program](./example/2D-advection-diffusion.F90), for example, demonstrates how to advance the
 above equation in time using a Runge-Kutta scheme.
+It accepts `--solver workspace|operators`, `--cells`, `--steps`, `--dt`, and
+`--order` flags for benchmarking; without arguments it retains the 51×51,
+500-step, `dt=1e-4` regression case, and when `--cells` changes without `--dt`
+the default time step is scaled by the square of the grid refinement factor.
+Use `--benchmark` for the 257×257, 30000-step preset, `--no-csv` to suppress
+CSV output on large runs, `--dump-input <path>` to write the native FADV2D1 raw
+input snapshot before warmup/timing, and `--dump-final-raw <path>` for binary
+final-field output.  The tracked comparison helper lives at
+[`example/scripts/compare_2d_fields.py`](./example/scripts/compare_2d_fields.py).
+For GPU benchmarking, compile with `-DFORMAL_ENABLE_GPU_BENCHMARK`, pass
+`--gpu-profile`, and set `LFORTRAN_GPU_PROFILE=1` to collect Metal telemetry
+through the runtime snapshot shim.
+
+The native C + Metal reference benchmark is kept outside FPM's automatic
+example discovery under
+[`benchmarks/2d-advection-metal`](./benchmarks/2d-advection-metal).  It does
+not add an Objective-C `main` to the ordinary Formal examples or tests.
+After building LFortran with Pixi, run the native reference or the actual
+Formal GPU example through its wrappers:
+```bash
+export LFORTRAN_ROOT=/path/to/lfortran
+bash benchmarks/2d-advection-metal/run.sh
+# or:
+FA_ALLOW_METAL=1 bash benchmarks/2d-advection-metal/run_formal.sh
+```
+The native wrapper defaults to a CPU smoke case; the Formal wrapper defaults
+to the 2048 x 2048, 1000-step GPU case. Both Metal entry points require an
+Apple Silicon Mac and explicit `FA_ALLOW_METAL=1` permission. See the benchmark
+README for the exact provenance, source guard, and reproducibility contract.
+The optional benchmark wrappers provision their own locked FPM 0.13.0
+environment from `benchmarks/pixi.toml`, reuse the selected LFortran
+checkout's managed tools, and select the real macOS SDK compiler after Pixi
+activation. Ordinary FPM users and the compiler support matrix are unchanged.
 
 ### Other example programs
 See this repository's [example](./example) subdirectory for additional demonstrations of

benchmarks/.gitignore

@@ -0,0 +1 @@
+/.pixi/

benchmarks/2d-advection-metal/.gitignore

@@ -0,0 +1,6 @@
+/build/
+*.bin
+*.csv
+*.dSYM/
+*.fadv2d
+*.log

benchmarks/2d-advection-metal/LFortran-NOTICE.txt

@@ -0,0 +1,45 @@
+The files formal_advection.m and formal_advection.metal are derived from
+the LFortran repository, commit 3d4c7941c5a153adb996ed62309225e871c06d9b,
+under the following BSD 3-Clause terms.
+
+Copyright (c) 2019-2020, Triad National Security, LLC. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+The LFortran source repository also contains the following government-rights
+notice:
+
+This program was produced under U.S. Government contract
+89233218CNA000001 for Los Alamos National Laboratory (LANL), which is
+operated by Triad National Security, LLC for the U.S. Department of
+Energy/National Nuclear Security Administration. All rights in the program
+are reserved by Triad National Security, LLC, and the U.S. Department of
+Energy/National Nuclear Security Administration. The Government is granted
+for itself and others acting on its behalf a nonexclusive, paid-up,
+irrevocable worldwide license in this material to reproduce, prepare
+derivative works, distribute copies to the public, perform publicly and
+display publicly, and to permit others to do so.