Scripts for a compiler matrix

data/compiler_sweeps/tier1_base_raja_hip_compilers.txt

@@ -0,0 +1,5 @@
+# build_script mpi_version rocm_version gpu_arch
+toss4_cray-mpich_amdclang.sh 9.0.1 6.3.1 gfx942
+toss4_cray-mpich_amdclang.sh 9.0.1 6.4.3 gfx942
+toss4_cray-mpich_amdclang.sh 9.0.1 7.2.1 gfx942
+

data/compiler_sweeps/tier1_base_raja_hip_repro.txt

@@ -0,0 +1,24 @@
+Compiler matrix input:
+  data/compiler_sweeps/tier1_base_raja_hip_compilers.txt
+
+Kernel lists:
+  data/compiler_sweeps/tier1_main_kernels.txt
+  data/compiler_sweeps/tier1_diff_range_kernels.txt
+
+Run from the repository root.
+
+Main Tier 1 kernels:
+  scripts/lc-builds/run_compiler_matrix.sh from-list data/compiler_sweeps/tier1_base_raja_hip_compilers.txt --run-cmd "srun -N1 -n4 --" --throughput --base-mem 100000 --factors "1 4 16 32 64 128 256 512 1024 1500 2048 3000 4000" --kernel-file data/compiler_sweeps/tier1_main_kernels.txt -- --variants Base_HIP RAJA_HIP --npasses 3 --npasses-combiners Average Minimum Maximum --outdir compiler_sweep_runs/tier1_base_raja_hip
+
+Tier 1 special-range kernels:
+  scripts/lc-builds/run_compiler_matrix.sh from-list data/compiler_sweeps/tier1_base_raja_hip_compilers.txt --run-cmd "srun -N1 -n4 --" --throughput --base-mem 100000 --factors "32 64 128 256 512 1024 1500 2048 3000 4000 5000 6000" --kernel-file data/compiler_sweeps/tier1_diff_range_kernels.txt -- --variants Base_HIP RAJA_HIP --npasses 3 --npasses-combiners Average Minimum Maximum --outdir compiler_sweep_runs/tier1_base_raja_hip
+
+Generate plots from the produced kernel-run-data CSV files:
+  python3 scripts/build_compiler_matrix.py --root-dir . --output-dir compiler-matrix-output/tier1_base_raja_hip --no-fixed-plots
+
+Notes:
+  - The Tier 1 kernel split and factor ranges match RAJAPerf-Benchmark/2026-FCR/scripts/run_tier_mi300a.sh.
+  - The runs above keep only Base_HIP and RAJA_HIP.
+  - The sample ``srun -N1 -n4 --`` prefix uses 1 node and 4 MPI ranks; change
+    it to match the launcher settings required by your allocation if needed.
+  - Output CSV files land under each build directory in compiler_sweep_runs/tier1_base_raja_hip/.

data/compiler_sweeps/tier1_diff_range_kernels.txt

@@ -0,0 +1,3 @@
+# Tier 1 kernels with special factor ranges from RAJAPerf-Benchmark/2026-FCR/scripts/run_tier_mi300a.sh
+FEMSWEEP
+MASS3DEA

data/compiler_sweeps/tier1_main_kernels.txt

@@ -0,0 +1,9 @@
+# Tier 1 kernels from RAJAPerf-Benchmark/2026-FCR/scripts/run_tier_mi300a.sh
+DIFFUSION3DPA
+EDGE3D
+ENERGY
+INTSC_HEXRECT
+MASS3DPA_ATOMIC
+MASSVEC3DPA
+NODAL_ACCUMULATION_3D
+VOL3D

docs/sphinx/user_guide/run.rst

@@ -106,7 +106,7 @@ a summary of command-line arguments it was given if the input contains
 something that the code does not know how to parse. For example, running the
 command::
 
-  $ ./bin/raja-perf.exe --dry-run -k DAXPY Foo
+  $ ./bin/raja-perf.exe --dryrun -k DAXPY Foo
 
 will report the following in the screen output::
 
@@ -130,6 +130,44 @@ in the Suite.
           screen output, hopefully making it easy for users to correct
           erroneous usage, such as mis-spelled option names.
 
+.. _compiler-matrix-label:
+
+=========================
+Compiler matrix workflow
+=========================
+
+For compiler sweeps, use ``scripts/lc-builds/run_compiler_matrix.sh`` rather
+than invoking a single build script by hand. The matrix driver reads a compiler
+list file, sources the selected build script for each line, builds each
+configuration, and then runs the Suite with the launcher command you provide
+via ``--run-cmd``.
+
+A typical invocation looks like::
+
+  $ ./scripts/lc-builds/run_compiler_matrix.sh toss4_amdclang.sh compiler_list.txt \
+      --run-cmd "srun -N1 -n1 -c 64 --" --kernel-file kernels.txt -- --dryrun
+
+The trailing ``--`` in ``--run-cmd`` is part of the launcher prefix. It tells
+``srun`` to stop parsing its own options so the matrix script can append
+``./bin/raja-perf.exe`` and the RAJAPerf run arguments after it.
+
+The compiler list file contains one build configuration per non-comment line.
+If you pass ``from-list`` as the build-script argument, the first token on each
+line names the build script and the remaining tokens are passed to that script.
+
+The generated ``*-kernel-run-data.csv`` files can then be merged and plotted
+with the processing scripts in ``scripts/`` such as
+``scripts/build_compiler_matrix.py`` where it will generate corresponding plots.
+
+By default the script writes its outputs under ``./compiler-matrix-output``.
+Throughput plots are placed under ``./compiler-matrix-output/throughput-plots``.
+For example, the ``VOL3D`` throughput plot can be embedded with:
+
+.. figure:: ../_static/compiler-comparison-output/throughput-plots/Apps_VOL3D_Mean_flops_gigaFLOP_per_sec_throughput.pdf
+   :alt: VOL3D throughput plot
+
+   VOL3D throughput plot.
+
 .. _run_mpi-label:
 
 ==================