metrale_circuit/hardware/

render.rs

// SPDX-License-Identifier: MIT OR Apache-2.0

//! 2026-09-30: The Markdown of a hardware report (`kernels/circuits/plans/hw/<model>--<device>.md`)
//! and its one-line summary for the roadmap matrix.
//!
//! Owner: metrale-circuit (hardware).
//! Invariants: deterministic text (fixed decimals, sorted maps); every number names its basis in
//! the report's inputs table.

use std::collections::BTreeMap;
use std::fmt::Write as _;

use super::HwReport;
use super::gaps::GapTable;
use super::plan::NOVEL_EMITTER;
use crate::venn::Class;

/// 2026-09-30: The C values of the memory-fit table.
pub(super) const FIT_SEQS: [u64; 8] = [1, 2, 4, 8, 16, 32, 64, 128];
/// 2026-09-30: The contexts of the memory-fit table.
pub(super) const FIT_CONTEXTS: [u64; 2] = [4096, 32768];

fn gb(b: f64) -> String {
    format!("{:.2}", b / 1e9)
}

/// 2026-10-01: The label every number estimated from `r`'s constants carries when they are not
/// measured on the device's own class (a datasheet ceiling): `" (roofline projection,
/// unmeasured)"`, else nothing.
pub(super) fn projection(r: &HwReport) -> &'static str {
    if r.resolved.roofline.measured {
        ""
    } else {
        " (roofline projection, unmeasured)"
    }
}

pub(super) fn pct(x: f64) -> String {
    // 2026-09-30: `+ 0.0` turns the -0.0 an empty f64 sum yields into 0.0.
    format!("{:.1}%", 100.0 * x + 0.0)
}

fn run_name(t: &GapTable) -> String {
    format!("{} n={}", t.planned.plan.mode.name(), t.planned.plan.rows)
}

/// 2026-09-30: The report text.
pub fn render_report(r: &HwReport) -> String {
    let mut s = String::new();
    let d = &r.resolved.device;
    let _ = writeln!(s, "# {} on {} (`{}`)\n", r.model.label, d.name, d.id);
    let _ = writeln!(
        s,
        "Generated by `{}`. Do not edit: the `--check` test fails on a stale copy.\n",
        r.command
    );
    inputs(&mut s, r);
    execution(&mut s, r);
    super::tc_policy_render::section(&mut s, r);
    estimates(&mut s, r);
    super::render_routes::routes_section(&mut s, r);
    memory(&mut s, r);
    flags(&mut s, r);
    if let Some(t) = r.tables.first() {
        plan_sites(&mut s, t, r);
    }
    for t in &r.tables {
        gap_rows(&mut s, t, projection(r));
    }
    absent(&mut s, r);
    s
}

fn inputs(s: &mut String, r: &HwReport) {
    let d = &r.resolved.device;
    let rf = &r.resolved.roofline;
    let chain: Vec<&str> = r
        .resolved
        .planning
        .iter()
        .map(|c| c.name.as_str())
        .collect();
    let rules = match &r.resolved.rules {
        super::class::ClassRules::Rules {
            files,
            rules,
            runtime,
        } => {
            let routes = match runtime.len() {
                0 => String::new(),
                n => format!(" and {n} runtime route{}", if n == 1 { "" } else { "s" }),
            };
            format!("{} rules{routes} from {}", rules.len(), files.join(" + "))
        }
        super::class::ClassRules::None => {
            "none: the class declares no FUSIONS.toml and inherits none, so every node is a gap"
                .into()
        }
    };
    let target = match &r.resolved.sources.target {
        Some(t) => format!("`{t}` ({} modules)", r.resolved.sources.modules.len()),
        None => format!(
            "common layer only ({} modules): kernels/{} has no `{}/{}` target",
            r.resolved.sources.modules.len(),
            d.class,
            r.model.kernel_model,
            r.model.kernel_quant
        ),
    };
    let native: Vec<String> = d.native.iter().map(|i| i.name()).collect();
    let class_set: Vec<String> = r
        .class_settings
        .iter()
        .map(|(k, v)| format!("{k}={v}"))
        .collect();
    let _ = writeln!(s, "## Inputs\n\n| | |\n|---|---|");
    let rows = [
        ("model", r.model.label.clone()),
        ("checkpoint", r.model.checkpoint.clone()),
        ("formats", r.model.precision.clone()),
        (
            "device",
            format!(
                "{} ({}, CC {}, {} SMs, {:.1} GiB {} visible, {} GB/s, L2 {}, {} KB smem/SM, cluster {}, TMEM {} KB/SM)",
                d.name,
                d.arch,
                d.compute_capability,
                d.sms,
                d.memory_bytes / (1u64 << 30) as f64,
                d.memory_type,
                d.bandwidth_gbps,
                d.l2_mb
                    .map_or_else(|| "unpublished".into(), |l| format!("{l} MB")),
                d.smem_per_sm_kb,
                d.cluster_max,
                d.tmem_per_sm_kb
            ),
        ),
        (
            "tensor cores",
            format!(
                "{} (fast path); native: {}",
                d.mma_family.name(),
                native.join(", ")
            ),
        ),
        (
            "roofline",
            format!(
                "{}: DRAM {} GB/s, BF16 {} / FP8 {} / NVFP4 {} TFLOPS; KV context {} tokens per sequence (assumption)",
                rf.basis,
                rf.roofline.dram_gbps,
                rf.roofline.bf16_tflops,
                rf.roofline.fp8_tflops,
                rf.roofline.nvfp4_tflops,
                rf.roofline.context_tokens
            ),
        ),
        ("FP4 costing", r.resolved.fp4_costing(&r.model.circuit)),
        ("class chain", chain.join(" -> ")),
        ("rules", rules),
        ("kernel sources", target),
        (
            "settings from the class",
            if class_set.is_empty() {
                "none differ from the model's source".into()
            } else {
                format!(
                    "{} (kernels/{}/HARDWARE.toml [defaults])",
                    class_set.join(" "),
                    d.class
                )
            },
        ),
    ];
    let policy: Vec<String> = r
        .policy
        .settings
        .iter()
        .map(
            |(k, v)| match r.model.policy_sources.iter().find(|(key, _)| key == k) {
                Some((_, why)) => format!("{k}={v} ({why})"),
                None => format!("{k}={v}"),
            },
        )
        .collect();
    for (k, v) in rows.into_iter().chain([(
        "policy",
        if r.model.policy_sources.is_empty() {
            format!("{} (stated by the recipe)", policy.join(" "))
        } else {
            policy.join("; ")
        },
    )]) {
        let _ = writeln!(s, "| {k} | {} |", v.replace('|', "\\|"));
    }
    let _ = writeln!(s);
}

fn execution(s: &mut String, r: &HwReport) {
    let _ = writeln!(
        s,
        "## Declared formats on this device\n\nThe checkpoint's formats are kept; this is how the device and its class's compiled kernels run them. A pair whose nodes run differently has one row per execution.\n"
    );
    let _ = writeln!(
        s,
        "| pair | weight | activation | nodes | execution |\n|---|---|---|---:|---|"
    );
    for ((pair, w, a, e), n) in &r.exec {
        let _ = writeln!(s, "| {pair} | {w} | {a} | {n} | {} |", e.describe());
    }
    let _ = writeln!(s);
}

fn estimates(s: &mut String, r: &HwReport) {
    let bw = r.resolved.roofline.roofline.dram_gbps;
    let _ = writeln!(
        s,
        "## Roofline estimates\n\nSums of per-node `max(bytes / bandwidth, FLOPs / peak)`; per-row loops are costed per row. No launch overhead: a ceiling, not a prediction.\n"
    );
    let _ = writeln!(s, "| case | time (ms) | tok/s |\n|---|---:|---:|");
    for t in &r.tables {
        let rows = t.planned.plan.rows;
        let _ = writeln!(
            s,
            "| decode C={rows} ({}){} | {:.3} | {:.1} |",
            run_name(t),
            projection(r),
            t.total_us / 1e3,
            rows as f64 / (t.total_us / 1e6)
        );
    }
    for (tokens, us) in &r.prefill {
        let _ = writeln!(
            s,
            "| prefill {}k{} | {:.1} | {:.0} |",
            tokens / 1024,
            projection(r),
            us / 1e3,
            *tokens as f64 / (us / 1e6)
        );
    }
    let floor_us = r.weight_floor / (bw * 1e3);
    let _ = writeln!(
        s,
        "\nWeight floor at C=1: {} GB read per step = {:.3} ms at {bw} GB/s{}.\n",
        gb(r.weight_floor),
        floor_us / 1e3,
        projection(r)
    );
}

fn memory(s: &mut String, r: &HwReport) {
    let d = &r.resolved.device;
    let usable = d.memory_bytes * d.usable_fraction;
    let f = &r.footprint;
    let _ = writeln!(
        s,
        "## Memory fit\n\nUsable {} GB = {:.2} GB visible x {} ({}). Weights {} GB (embedding BF16); KV {:.0} bytes per token; recurrent state {:.1} MB per sequence. Not counted: activations, workspaces, conv windows, the CUDA context.\n",
        gb(usable),
        d.memory_bytes / 1e9,
        d.usable_fraction,
        d.usable_why,
        gb(f.weights),
        f.kv_per_token,
        f.state_per_seq / 1e6
    );
    let mut head = String::from("| C |");
    let mut rule = String::from("|---:|");
    for ctx in FIT_CONTEXTS {
        let _ = write!(head, " {}k GB | fits |", ctx / 1024);
        rule.push_str("---:|---|");
    }
    let _ = writeln!(s, "{head}\n{rule}");
    for c in FIT_SEQS {
        let mut line = format!("| {c} |");
        for ctx in FIT_CONTEXTS {
            let need = f.bytes(c, ctx);
            let _ = write!(
                line,
                " {} | {} |",
                gb(need),
                if need <= usable { "yes" } else { "no" }
            );
        }
        let _ = writeln!(s, "{line}");
    }
    let _ = writeln!(s);
    for c in [1, 128] {
        let need = f.bytes(c, FIT_CONTEXTS[0]);
        if need > usable {
            let _ = writeln!(s, "C={c} at 4k does not fit: {}.", advice(r, need, usable));
        }
    }
    let _ = writeln!(s);
}

/// 2026-09-30: What would hold `need` bytes: tensor parallelism over this device, or the
/// registry devices whose usable memory holds it.
fn advice(r: &HwReport, need: f64, usable: f64) -> String {
    let tp = (need / usable).ceil() as u64;
    let fits: Vec<&str> = r
        .others
        .iter()
        .filter(|(_, u)| *u >= need)
        .map(|(id, _)| id.as_str())
        .collect();
    let others = if fits.is_empty() {
        "no single registry device holds it".to_string()
    } else {
        format!("or one {}", fits.join(" / "))
    };
    format!(
        "needs {} GB of {} GB usable: TP={tp} on {}, {others}",
        gb(need),
        gb(usable),
        r.resolved.device.id
    )
}

fn flags(s: &mut String, r: &HwReport) {
    let _ = writeln!(
        s,
        "## Multi-row fallbacks\n\nPlan groups that loop once per row, and the engine's layer loops per sequence (`legacy` rows, KERNEL_FAMILIES.toml `[[legacy_path]]`), costed as the time the loop adds over one multi-row launch{}; the estimates above include it.\n",
        projection(r)
    );
    let mut any = false;
    for t in &r.tables {
        for f in &t.flags {
            if !any {
                let _ = writeln!(
                    s,
                    "| run | layer kind | added (ms) | share | sites | rules |\n|---|---|---:|---:|---|---|"
                );
                any = true;
            }
            let kind = f.layer_kind.map_or("prologue/epilogue", |k| k.name());
            let sites: Vec<&str> = f.sites.iter().map(String::as_str).collect();
            let rules: Vec<&str> = f.rules.iter().map(String::as_str).collect();
            let _ = writeln!(
                s,
                "| {} | {kind} | {:.3} | {} | {} | {} |",
                run_name(t),
                f.added_us / 1e3,
                pct(f.share),
                sites.join(", "),
                rules.join(", ")
            );
        }
    }
    if !any {
        let _ = writeln!(s, "None.");
    }
    let _ = writeln!(s);
}

fn plan_sites(s: &mut String, t: &GapTable, r: &HwReport) {
    let p = &t.planned.plan;
    let c = &r.model.circuit;
    let fused = p
        .edge_states
        .iter()
        .filter(|e| matches!(e, Some(crate::fuser::EdgeState::Fused(_))))
        .count();
    let novel_groups = p
        .groups
        .iter()
        .filter(|g| g.emitter == NOVEL_EMITTER)
        .count();
    let _ = writeln!(
        s,
        "## Fused plan: {}\n\ndigest {}; {} groups, {} launches, {} fused edges, {} placeholder (novel) groups. The full plan: `met circuit plan --checkpoint {} --hardware {} --precision {} --format plan`.\n",
        run_name(t),
        p.digest,
        p.groups.len(),
        p.launches(),
        fused,
        novel_groups,
        r.model.checkpoint,
        r.resolved.device.id,
        r.model.precision_choice.name()
    );
    let mut sites: BTreeMap<(String, String, String), usize> = BTreeMap::new();
    for g in &p.groups {
        let first = &c.nodes[g.nodes[0]];
        let locals: Vec<&str> = g.nodes.iter().map(|&n| c.nodes[n].local.as_str()).collect();
        let what = if g.kernels.is_empty() {
            format!("({})", g.emitter)
        } else {
            let k: Vec<String> = g.kernels.iter().map(|k| k.to_string()).collect();
            k.join(" + ")
        };
        let key = (
            format!("{} [{}]", first.block, locals.join(",")),
            what,
            g.rule.clone(),
        );
        *sites.entry(key).or_insert(0) += 1;
    }
    for (rule, why) in &t.planned.refused {
        let _ = writeln!(s, "Rule `{rule}` left out of this plan: {why}.\n");
    }
    let _ = writeln!(s, "| site | kernels | rule | groups |\n|---|---|---|---:|");
    for ((site, what, rule), n) in sites {
        let _ = writeln!(s, "| {site} | {what} | {rule} | {n} |");
    }
    let _ = writeln!(s);
}

fn gap_rows(s: &mut String, t: &GapTable, projection: &str) {
    let _ = writeln!(
        s,
        "## Gap report: {}\n\nEstimated step {:.3} ms{projection}. Shared {} (measured on this class), shared-unmeasured {}, parameterisation {}, policy variant {}, novel {} of the step.\n",
        run_name(t),
        t.total_us / 1e3,
        pct(t.share_of(&[Class::Shared])),
        pct(t.share_of(&[Class::SharedUnmeasured])),
        pct(t.share_of(&[Class::ParameterizationOpportunity])),
        pct(t.share_of(&[Class::PolicyVariant])),
        pct(t.share_of(&[Class::Novel]))
    );
    let _ = writeln!(
        s,
        "| site | op | formats | execution | n | share | class | family | detail |\n|---|---|---|---|---:|---:|---|---|---|"
    );
    for row in &t.rows {
        let formats = row
            .formats
            .as_ref()
            .map_or_else(|| "-".to_string(), |(w, a)| format!("{w} x {a}"));
        let exec = row.exec.map_or_else(|| "-".to_string(), |e| e.describe());
        let mut detail = row.detail.clone();
        if !row.diffs.is_empty() {
            let _ = write!(detail, "; differs: {}", row.diffs.join(", "));
        }
        let _ = writeln!(
            s,
            "| {} | {} | {formats} | {exec} | {} | {} | {} | {} | {} |",
            row.site,
            row.op,
            row.count,
            pct(row.share),
            row.class.name(),
            row.family.as_deref().unwrap_or("-"),
            detail.replace('|', "\\|")
        );
    }
    let _ = writeln!(s);
}

fn absent(s: &mut String, r: &HwReport) {
    let _ = writeln!(
        s,
        "## Rule kernels this device cannot run\n\nKernels a rule under this policy names that the device's class does not provide: the port list.\n"
    );
    if r.absent.is_empty() {
        let _ = writeln!(s, "None.");
        return;
    }
    let _ = writeln!(s, "| kernel | why |\n|---|---|");
    for (k, a) in &r.absent {
        let _ = writeln!(s, "| {k} | {} |", a.describe().replace('|', "\\|"));
    }
}