perf_support API

Luna-Flow/linear-algebra/perf_support 是基准测试子系统的共享库。它持有基准用例注册表，加载或重新生成输入 fixture，准备 @mutable 输入，并运行单个用例、返回结果的校验和。perf 和 perf_runner 都构建在它之上。

源码：src/perf_support。基准测试方法见 perf_support 设计和 bench/README.md。

类型

Case

Case 是一个基准用例的元数据。

pub struct Case {
  id : String
  operation : String
  family : String
  workload_tier : String
  structure : String
  timing_scope : String
  input_layout : String
  mutation_policy : String
  size_tier : String
  cost_model : String
  rows : Int
  cols : Int
  rhs_cols : Int
}

operation 取 mul、mul_vec、determinant、inverse、rank、reduce_row_elimination、cholesky_decomposition、eigen、power_method 之一。其他字符串字段对工作负载进行分类（例如 structure = "dense"、mutation_policy = "reusable_input" 或 "scratch_per_sample"），以便报告按成因对结果分组。

PreparedCase

PreparedCase 是输入已加载为 @mutable 值的用例。

pub struct PreparedCase {
  case_item : Case
  matrix_a : @mutable.Matrix[Double]
  matrix_b : @mutable.Matrix[Double]
  vector_b : @mutable.Vector[Double]
}

注册表

cases

cases 是所有已注册用例的列表，由 bench/datasets/manifest.json 生成。

pub let cases : Array[Case]

dataset_version

dataset_version 标识 fixture 格式；版本不同的 fixture 文件会被拒绝。

pub let dataset_version : String

case_names, sample_case_names

case_names() 返回所有用例 id；sample_case_names() 为每种操作返回一个有代表性的基线用例，优先选择中等规模。

pub fn case_names() -> Array[String]
pub fn sample_case_names() -> Array[String]

find_case, find_prepared_case

按 id 查找用例，可选地准备其输入。

pub fn find_case(String) -> Case?
pub fn find_prepared_case(String) -> PreparedCase?

准备

prepare_case, prepare_case_from_fixture

prepare_case(c) 加载 bench/datasets/cases/<id>.json；prepare_case_from_fixture(c, path) 加载给定文件。

pub fn prepare_case(Case) -> PreparedCase
pub fn prepare_case_from_fixture(Case, String) -> PreparedCase

缺失的 fixture 文件会根据用例的种子确定性地重新生成并写入该路径。若 fixture 的版本、id、元数据或形状与用例不符，程序中止。

clone_prepared_case

clone_prepared_case(p) 深拷贝输入，用于会修改输入的用例。

pub fn clone_prepared_case(PreparedCase) -> PreparedCase

执行

run_prepared_case_inplace

run_prepared_case_inplace(p, scratch) 运行一次该用例的操作并返回结果的校验和。当 scratch = true 时，会先复制输入。

pub fn run_prepared_case_inplace(PreparedCase, Bool) -> UInt64

这些操作调用 @mutable 的非受检方法（unchecked_matmul、unchecked_determinant 等）；power_method 以 80 次迭代运行。None 结果映射为固定的哨兵校验和。

run_prepared_case_once, run_case_once

run_prepared_case_once(p) 依据用例自身的修改策略选择 scratch；run_case_once(c) 从默认 fixture 路径准备并运行。

pub fn run_prepared_case_once(PreparedCase) -> UInt64
pub fn run_case_once(Case) -> UInt64

case_diagnostic_payload

case_diagnostic_payload(c, checksum) 渲染一条包含用例元数据和校验和的单行 JSON 记录，供报告脚本使用。

pub fn case_diagnostic_payload(Case, UInt64) -> String

示例

let c = @perf_support.find_case("mul_baseline_dense_64").unwrap()
let checksum = @perf_support.run_case_once(c)
println(@perf_support.case_diagnostic_payload(c, checksum))