open-standards/jouleclaw/jouleclaw-rs/crates/jouleclaw-loader-gguf/examples/energy_autotune.rs

//! Live energy-autotune: for a couple of representative matmul shapes, measure the
//! CPU (AMX) path against the GPU path **under the IOReport meter**, pick the
//! joules-minimal backend, and print the resulting tuning profile.
//!
//! Run on a QUIET box for meaningful marginal-energy figures:
//!   cargo run --release --features "rayon fabric-meter" --example energy_autotune
//!
//! The path being validated — meter → real kernels → joules-minimal selection →
//! global profile — executes regardless of box load; only the *accuracy* of the
//! µJ figures needs a quiet machine (the marginal-energy subtraction assumes a
//! stable idle draw). A backend the platform can't run for a shape reports
//! `u64::MAX` and simply never wins. A shape the meter cannot measure — the IOReport
//! counter unavailable (its CPU energy rail not advancing, among other reasons), or a
//! window that draws nothing above idle — is left untuned: nothing is recorded.

use jouleclaw_loader_gguf::energy_autotune;
use jouleclaw_loader_gguf::fabric_dispatch;

fn f32_to_bf16(v: f32) -> u16 {
    let b = v.to_bits();
    ((b + (((b >> 16) & 1) + 0x7fff)) >> 16) as u16
}

fn main() {
    // Decode (m = 1) and a prefill window (m = 256), same n×k projection — the two
    // regimes whose joules-minimal backend can genuinely differ.
    let shapes = [(1usize, 4096usize, 4096usize), (256, 4096, 4096)];

    println!("tuning {} shape(s) live on the IOReport meter…\n", shapes.len());
    for &(m, n, k) in &shapes {
        let a: Vec<f32> = (0..m * k).map(|i| ((i % 101) as f32 / 50.0) - 1.0).collect();
        let w: Vec<u8> = (0..n * k)
            .flat_map(|i| f32_to_bf16(((i % 97) as f32 / 48.0 - 1.0) * 0.1).to_le_bytes())
            .collect();

        // ~1 s per backend past the counter's update window.
        match fabric_dispatch::tune_shape_live(&a, &w, m, n, k, 1.0) {
            Some(cost) => println!(
                "  m={m:<4} n={n} k={k}  →  {:>3} wins  @ {:>10} µJ/op, {:>10} ns/op",
                cost.backend.label(),
                cost.uj,
                cost.ns
            ),
            None => println!(
                "  m={m:<4} n={n} k={k}  →  not tuned: the meter produced no figure (IOReport {:?})",
                jouleclaw_energy::ioreport_status()
            ),
        }
    }

    println!("\nglobal tuning profile (the dispatcher's lookup):");
    let snapshot = energy_autotune::global_snapshot();
    if snapshot.is_empty() {
        println!(
            "  (empty — no shape was measured; IOReport {:?})",
            jouleclaw_energy::ioreport_status()
        );
    }
    for (key, cost) in snapshot {
        println!(
            "  m_bucket={:<4} n={} k={}  →  {} ({} µJ/op)",
            key.m_bucket,
            key.n,
            key.k,
            cost.backend.label(),
            cost.uj
        );
    }
    // With the `attest` feature also on, seal the profile as a verifiable
    // autotune/1 JCR-1 receipt — the tuning decisions become an artifact, not a claim.
    #[cfg(feature = "attest")]
    {
        use ed25519_dalek::SigningKey;
        let sk = SigningKey::from_bytes(&[0x5e; 32]);
        match energy_autotune::seal_profile(&sk, "did:jouleclaw:autotune") {
            Ok(env) => println!(
                "\nsealed autotune/1 receipt: {} bytes — verifiable under the steward key",
                env.len()
            ),
            Err(e) => println!("\nseal failed: {e}"),
        }
    }

    println!(
        "\nrun the model with JOULECLAW_ENERGY_AUTOTUNE=1 to dispatch by this profile."
    );
}