fp-stability: per-instance disambiguation of fypp-expanded hotspots (Tier 2)

dd_line attributes to .fpp source lines, but a #:for/#:def expansion collapses many generated computations onto one line, so a macro-ambiguous hotspot cannot be pinned to a single runtime instance. This adds an opt-in precision path that resolves it.

Mechanism (validated against gfortran+Verrou): a new build flag --fp-precision-lines strips the fypp line markers from each generated .f90 so the compiler attributes every expanded instance to a distinct physical line, emitting a .linemap.json sidecar mapping each line back to (.fpp file, line, instance). Marker renumbering was tried first but hit gfortran's DWARF line-number ceiling (~300k) and 700-line shadow runs; stripping avoids both and survives the cpp #if layer.

fp-stability gains --precision-sim-binary: for the most flagrant macro-ambiguous hotspot, each expanded instance is perturbed alone (Verrou --source) on the precision binary and ranked, naming the responsible instance and showing its concrete generated code. The strip is gated to the simulation target only (pre/post run on CPU).

Validated end-to-end: m_weno.fpp:238 (3 #:for instances) resolved to instance #0 = s_cb(i+3)-s_cb(i+1). toolchain/mfc/fp_precision_lines.py is pure + TDD'd (12 tests); normal build path is byte-identical and unaffected.

Author: sbryngelson

CMakeLists.txt

@@ -31,6 +31,7 @@ option(MFC_DOCUMENTATION "Build documentation"                               OFF
 option(MFC_ALL           "Build everything"                                  OFF)
 option(MFC_SINGLE_PRECISION "Build single precision"                         OFF)
 option(MFC_MIXED_PRECISION "Build mixed precision"                           OFF)
+option(MFC_FP_PRECISION_LINES "Strip fypp markers for per-instance fp-stability attribution" OFF)
 
 if (MFC_ALL)
     set(MFC_PRE_PROCESS   ON FORCE)
@@ -433,8 +434,24 @@ macro(HANDLE_SOURCES target useCommon)
         cmake_path(GET fpp FILENAME fpp_filename)
         set(f90 "${CMAKE_BINARY_DIR}/fypp/${target}/${fpp_filename}.f90")
 
+        # In a precision-lines build, Fypp writes a marked intermediate that is
+        # then stripped of its line markers (so each expanded instance compiles
+        # to a distinct physical line) before compilation; the strip step emits a
+        # .linemap.json sidecar.  Otherwise Fypp writes ${f90} directly.  Only the
+        # simulation target is analyzed by fp-stability, so pre/post_process are
+        # always built normally.
+        set(_precision_lines OFF)
+        if (MFC_FP_PRECISION_LINES AND "${target}" STREQUAL "simulation")
+            set(_precision_lines ON)
+        endif()
+        if (_precision_lines)
+            set(f90_out "${CMAKE_BINARY_DIR}/fypp/${target}/${fpp_filename}.marked.f90")
+        else()
+            set(f90_out "${f90}")
+        endif()
+
         add_custom_command(
-            OUTPUT   ${f90}
+            OUTPUT   ${f90_out}
             COMMAND  ${FYPP_EXE} -m re
                                  -I "${CMAKE_BINARY_DIR}/include/${target}"
                                  -I "${${target}_DIR}/include"
@@ -450,12 +467,25 @@ macro(HANDLE_SOURCES target useCommon)
 								 --line-length=999
 		 						 --line-numbering-mode=nocontlines
                                  ${FYPP_GCOV_OPTS}
-                                 "${fpp}" "${f90}"
+                                 "${fpp}" "${f90_out}"
             DEPENDS  "${fpp};${${target}_incs}"
             COMMENT  "Preprocessing (Fypp) ${fpp_filename}"
             VERBATIM
         )
 
+        if (_precision_lines)
+            add_custom_command(
+                OUTPUT   ${f90}
+                COMMAND  ${Python3_EXECUTABLE}
+                         "${CMAKE_SOURCE_DIR}/toolchain/mfc/fp_precision_lines.py"
+                         "${f90_out}" "${f90}"
+                         "${CMAKE_BINARY_DIR}/fypp/${target}/${fpp_filename}.linemap.json"
+                DEPENDS  "${f90_out};${CMAKE_SOURCE_DIR}/toolchain/mfc/fp_precision_lines.py"
+                COMMENT  "Stripping markers (fp-precision-lines) ${fpp_filename}"
+                VERBATIM
+            )
+        endif()
+
         list(APPEND ${target}_SRCs ${f90})
     endforeach()
 endmacro()

toolchain/mfc/build.py

@@ -421,6 +421,7 @@ def configure(self, case: Case):
             flags.append(f"-DMFC_GCov={'ON' if ARG('gcov') else 'OFF'}")
             flags.append(f"-DMFC_Unified={'ON' if ARG('unified') else 'OFF'}")
             flags.append(f"-DMFC_Fastmath={'ON' if ARG('fastmath') else 'OFF'}")
+            flags.append(f"-DMFC_FP_PRECISION_LINES={'ON' if ARG('fp_precision_lines') else 'OFF'}")
 
         command = ["cmake"] + flags + ["-S", cmake_dirpath, "-B", build_dirpath]
 

toolchain/mfc/cli/commands.py

@@ -141,6 +141,13 @@
             default=False,
             dest="deps_only",
         ),
+        Argument(
+            name="fp-precision-lines",
+            help="(fp-stability) Strip fypp line markers so each expanded instance gets a distinct line; emits sidecars for per-instance attribution.",
+            action=ArgAction.STORE_TRUE,
+            default=False,
+            dest="fp_precision_lines",
+        ),
     ],
     examples=[
         Example("./mfc.sh build", "Build all default targets (CPU)"),
@@ -938,6 +945,13 @@
             default=None,
             metavar="PATH",
         ),
+        Argument(
+            name="precision-sim-binary",
+            help="Path to a simulation binary built with --fp-precision-lines. When given, macro-ambiguous hotspots are disambiguated to the individual fypp-expanded instance.",
+            default=None,
+            dest="precision_sim_binary",
+            metavar="PATH",
+        ),
         Argument(
             name="samples",
             short="N",

toolchain/mfc/fp_precision_lines.py

@@ -0,0 +1,123 @@
+"""FP-stability precision-lines transform (Tier 2).
+
+A fypp #:for/#:def expansion emits many generated computations that all carry
+the same cpp line marker (`# N "file.fpp"`), so DWARF — and therefore Verrou —
+collapse every expanded instance onto one .fpp line.  This transform removes the
+fypp line markers from a generated .f90 so the compiler attributes each statement
+to the generated file's own physical line (which *is* distinct per expanded
+instance), and records a sidecar mapping each surviving physical line back to
+(file, original .fpp line, instance index).  Genuine cpp directives
+(#if/#define/#endif/...) are preserved so conditional compilation is unchanged.
+
+When the stripped .f90 is compiled, Verrou attributes — and fp-stability ranks
+and isolates via --source — per expanded instance rather than per source line.
+Used only by a dedicated precision build (MFC_FP_PRECISION_LINES); the normal
+build is unaffected.  The mechanism (stripped markers -> instance-distinct
+physical-line attribution -> per-instance Verrou --source isolation, surviving
+the cpp #if layer) is validated against gfortran + Verrou.
+"""
+
+import json
+import os
+import re
+
+# A fypp line marker: "# <number> "<file>"" possibly with trailing flags.  A cpp
+# conditional/define directive (#if, #define, #endif, ...) has a word, not a
+# number, after the '#', so the two are unambiguous.
+_FYPP_MARKER = re.compile(r'^#\s+(\d+)\s+"([^"]+)"')
+# Any other preprocessor directive line (kept, but it is not a .fpp source line,
+# so it neither consumes a source-line increment nor gets a sidecar entry).
+_CPP_DIRECTIVE = re.compile(r"^\s*#")
+
+
+def strip_markers(lines: list) -> tuple:
+    """Strip fypp line markers; return (output_lines, sidecar).
+
+    sidecar maps each 1-based physical output line number to
+    {"file", "line", "instance"}: the .fpp file, the .fpp line that physical
+    line came from (auto-incremented within a marker region), and how many times
+    that marker's (file, line) had been seen before (0 = first/real occurrence,
+    >=1 = an expanded instance).
+    """
+    seen = {}
+    out = []
+    sidecar = {}
+    cur_file = None
+    cur_line = None
+    cur_instance = None
+    for raw in lines:
+        m = _FYPP_MARKER.match(raw)
+        if m:
+            cur_file = m.group(2)
+            cur_line = int(m.group(1))
+            cur_instance = seen.get((cur_file, cur_line), 0)
+            seen[(cur_file, cur_line)] = cur_instance + 1
+            continue  # drop the marker line
+        out.append(raw)
+        if cur_file is None or _CPP_DIRECTIVE.match(raw):
+            # cpp directives are kept verbatim but are not .fpp source lines
+            continue
+        sidecar[len(out)] = {"file": cur_file, "line": cur_line, "instance": cur_instance}
+        cur_line += 1  # subsequent physical source lines map to the next .fpp line
+    return out, sidecar
+
+
+def transform_file(in_path: str, out_path: str, sidecar_path: str) -> int:
+    """Strip a generated .f90 to its precision-lines variant.
+
+    Reads in_path, writes the marker-stripped source to out_path and the sidecar
+    JSON to sidecar_path.  Returns the number of mapped physical lines.
+    """
+    with open(in_path) as fh:
+        lines = fh.readlines()
+    out, sidecar = strip_markers(lines)
+    with open(out_path, "w") as fh:
+        fh.writelines(out)
+    with open(sidecar_path, "w") as fh:
+        json.dump({str(k): v for k, v in sidecar.items()}, fh)
+    return len(sidecar)
+
+
+# --- consumption side (Tier 2): locating and querying the sidecars ---
+
+
+def sidecar_dir_for_binary(sim_bin: str) -> str:
+    """Map a precision simulation binary path to its sidecar directory.
+
+    .../build/install/<hash>/bin/simulation -> .../build/staging/<hash>/fypp/simulation
+    """
+    bin_dir = os.path.dirname(os.path.abspath(sim_bin))  # .../install/<hash>/bin
+    hash_dir = os.path.dirname(bin_dir)  # .../install/<hash>
+    cfg_hash = os.path.basename(hash_dir)
+    build_root = os.path.dirname(os.path.dirname(hash_dir))  # .../build
+    return os.path.join(build_root, "staging", cfg_hash, "fypp", "simulation")
+
+
+def sidecar_path(sidecar_dir: str, fpp_file: str) -> str:
+    """Sidecar JSON path for a .fpp file: <dir>/<basename>.linemap.json."""
+    return os.path.join(sidecar_dir, os.path.basename(fpp_file) + ".linemap.json")
+
+
+def load_sidecar(path: str) -> dict:
+    """Load a sidecar JSON into {physical_line:int -> {file, line, instance}}."""
+    if not os.path.isfile(path):
+        return {}
+    with open(path) as fh:
+        raw = json.load(fh)
+    return {int(k): v for k, v in raw.items()}
+
+
+def instances_of(sidecar: dict, fpp_file: str, fpp_line: int) -> list:
+    """Return [(physical_line, instance), ...] (sorted by physical line) for every
+    expanded instance of fpp_file:fpp_line, matched by basename."""
+    base = os.path.basename(fpp_file)
+    hits = [(physline, entry["instance"]) for physline, entry in sidecar.items() if os.path.basename(entry["file"]) == base and entry["line"] == fpp_line]
+    return sorted(hits)
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) != 4:
+        sys.exit("usage: fp_precision_lines.py <in.f90> <out.f90> <sidecar.json>")
+    transform_file(sys.argv[1], sys.argv[2], sys.argv[3])

toolchain/mfc/fp_stability.py

@@ -44,6 +44,15 @@
    One run with --check-max-float=yes; reports locations where a
    double→float conversion would overflow to ±Inf.
 
+I. Per-instance disambiguation (--precision-sim-binary PATH; opt-in)
+   A fypp #:for/#:def expansion collapses many generated computations onto one
+   .fpp line, so a macro-ambiguous hotspot cannot be pinned to a single runtime
+   instance.  Given a simulation binary built with `--fp-precision-lines` (markers
+   stripped so each instance is a distinct line, plus .linemap.json sidecars), the
+   most flagrant macro-ambiguous hotspot is disambiguated: each expanded instance
+   is perturbed alone on the precision binary, ranking them to the responsible
+   instance and showing its concrete generated code.
+
 Logs are saved to fp-stability-logs/ and uploaded as CI artifacts.
 On GitHub Actions: a step summary table and ::warning:: file annotations
 are emitted automatically so failing source lines appear in the PR diff.
@@ -1149,6 +1158,67 @@ def _run_confirmation(case, verrou_bin, sim_bin, work_dir, ref_dir, dd_line_locs
     return confirmed, set_dev, ranked
 
 
+def _disambiguate_instances(case, prec_sim_bin, verrou_bin, work_dir, hotspot_file, hotspot_line):
+    """Rank the individual fypp-expanded instances of a macro-ambiguous hotspot.
+
+    Uses a precision binary (built with --fp-precision-lines) in which each
+    expanded instance of hotspot_file:hotspot_line compiles to a distinct
+    physical .f90 line.  The sidecar enumerates those physical lines; each is
+    perturbed alone (float mode, vs the precision binary's own nearest-rounding
+    reference) so the dominant instance is identified.
+
+    Returns a list of {instance, physline, dev, snippet} sorted most-flagrant
+    first (empty if no sidecar / no instrumented instances).
+    """
+    from . import fp_precision_lines as fpl
+
+    sidecar_dir = fpl.sidecar_dir_for_binary(prec_sim_bin)
+    sidecar = fpl.load_sidecar(fpl.sidecar_path(sidecar_dir, hotspot_file))
+    instances = fpl.instances_of(sidecar, hotspot_file, hotspot_line)
+    if not instances:
+        return []
+
+    prec_dir = os.path.join(work_dir, "precision")
+    ref_dir = os.path.join(prec_dir, "ref")
+    os.makedirs(ref_dir, exist_ok=True)
+    gen_path = os.path.join(prec_dir, "gen_source.txt")
+    try:
+        _run_simulation_verrou(verrou_bin, prec_sim_bin, work_dir, ref_dir, rounding_mode="nearest")
+        _run_simulation_verrou(
+            verrou_bin,
+            prec_sim_bin,
+            work_dir,
+            prec_dir,
+            rounding_mode="nearest",
+            extra_flags=[f"--gen-source={gen_path}"],
+        )
+    except MFCException:
+        return []
+    if not os.path.isfile(gen_path):
+        return []
+    with open(gen_path) as fh:
+        gen_lines = fh.readlines()
+
+    f90_file = os.path.join(sidecar_dir, os.path.basename(hotspot_file) + ".f90")
+    compare = case["compare"]
+    results = []
+    for physline, instance in instances:
+        src = _build_source_filter(gen_lines, [(f90_file, physline, physline)])
+        if not src:
+            continue  # this instance performs no instrumented FP op
+        dev = _source_perturb_dev(verrou_bin, prec_sim_bin, work_dir, ref_dir, prec_dir, src, compare, f"inst{instance:02d}")
+        results.append(
+            {
+                "instance": instance,
+                "physline": physline,
+                "dev": dev or 0.0,
+                "snippet": _read_source_line(f90_file, physline).strip(),
+            }
+        )
+    results.sort(key=lambda r: r["dev"], reverse=True)
+    return results
+
+
 def _run_case(
     case: dict,
     verrou_bin: str,
@@ -1163,6 +1233,7 @@ def _run_case(
     run_cancellation: bool,
     run_mca: bool,
     run_float_max: bool,
+    prec_sim_bin: str = None,
 ) -> dict:
     name = case["name"]
     threshold = case["threshold"]
@@ -1294,6 +1365,24 @@ def _run_case(
             except Exception as exc:
                 cons.print(f"  [bold yellow]dd_line confirmation error[/bold yellow]: {exc}")
 
+        # --- E3: per-instance disambiguation of the most flagrant macro-ambiguous hotspot ---
+        if prec_sim_bin and result["dd_line_locs"]:
+            macro_loc = next((loc for loc in result["dd_line_locs"] if loc.get("macro")), None)
+            if macro_loc:
+                cons.print(f"  [dim]disambiguating fypp instances of {macro_loc['path']}:{macro_loc['start']} (precision binary)...[/dim]")
+                try:
+                    insts = _disambiguate_instances(case, prec_sim_bin, verrou_bin, work_dir, macro_loc["path"], macro_loc["start"])
+                    macro_loc["instances"] = insts
+                    if insts and insts[0]["dev"] > 0:
+                        win = insts[0]
+                        cons.print(f"  flagrant instance: #{win['instance']} (.f90:{win['physline']}, dev={win['dev']:.3e})  {win['snippet']}")
+                    elif insts:
+                        cons.print(f"  [dim]{len(insts)} instance(s) enumerated; none perturbed measurably (hotspot inert)[/dim]")
+                    else:
+                        cons.print("  [dim]no sidecar instances found for this hotspot[/dim]")
+                except Exception as exc:
+                    cons.print(f"  [bold yellow]instance disambiguation error[/bold yellow]: {exc}")
+
         # --- F: cancellation detection ---
         if run_cancellation:
             cons.print("  [dim]cancellation detection...[/dim]")
@@ -1460,6 +1549,9 @@ def _emit_github_summary(results: list, n_samples: int):
                     tags.append(f"_{loc['macro']}-expanded, may represent multiple instances_")
                 suffix = f" — {', '.join(tags)}" if tags else ""
                 md.append(f"- `{where}`{suffix}")
+                for inst in loc.get("instances", [])[:8]:
+                    flag = " ⟵ flagrant" if inst is loc["instances"][0] and inst["dev"] > 0 else ""
+                    md.append(f"  - instance #{inst['instance']} (`.f90:{inst['physline']}`, dev={inst['dev']:.2e}){flag}: `{inst['snippet']}`")
                 snippet = _get_source_context(rel_path, start)
                 if snippet:
                     md.append("  ```fortran")
@@ -1531,6 +1623,9 @@ def fp_stability():
     run_cancellation = not ARG("no_cancellation")
     run_mca = not ARG("no_mca")
     run_float_max = not ARG("no_float_max")
+    prec_sim_bin = ARG("precision_sim_binary")
+    if prec_sim_bin and not os.path.isfile(prec_sim_bin):
+        raise MFCException(f"precision simulation binary not found: {prec_sim_bin}")
 
     log_dir = os.path.join(MFC_ROOT_DIR, "fp-stability-logs")
     os.makedirs(log_dir, exist_ok=True)
@@ -1540,6 +1635,8 @@ def fp_stability():
     cons.print(f"  verrou:      {verrou_bin}")
     cons.print(f"  simulation:  {sim_bin}")
     cons.print(f"  pre_process: {pp_bin}")
+    if prec_sim_bin:
+        cons.print(f"  precision:   {prec_sim_bin}  (per-instance disambiguation)")
     cons.print(f"  samples:     {n_samples}")
     features = []
     if run_float:
@@ -1578,6 +1675,7 @@ def fp_stability():
                 run_cancellation,
                 run_mca,
                 run_float_max,
+                prec_sim_bin,
             )
         except MFCException as exc:
             cons.print(f"  [bold red]ERROR[/bold red]: {exc}")