ir_model API

Luna-Flow/mare_mark/ir_model 定义 Plot IR，即 report 根据事件构建、并渲染为 JSON、SVG 或 HTML 的可移植文档：由分类点组成的图表，以及一份包含不匹配、能力、反例和语料计数的差分报告。参见 ir_model 设计。

源码：src/ir_model/ir_model.mbt。

import {
  "Luna-Flow/mare_mark/ir_model",
}

文档

PlotDocument

PlotDocument 是一份报告。

pub struct PlotDocument {
  schema_version : @model.SchemaVersion
  run_id : String
  target : String
  plots : Array[Plot]
  differential : DifferentialReport
}
pub fn PlotDocument::new(String, String, Array[Plot], differential? : DifferentialReport) -> Self

new(run_id, target, plots) 把 schema_version 设为 SchemaVersion::V1（mmks_1）；differential 默认为 DifferentialReport::empty()。

图表

Plot

Plot 是一张图表。

pub struct Plot {
  kind : PlotKind
  title : String
  unit : String
  interval_kind : String
  points : Array[PlotPoint]
}
pub fn Plot::new(PlotKind, String, String, String, Array[PlotPoint]) -> Self

unit 标注 y 轴；interval_kind 描述这些值是什么（"raw"、"median"、某个置信水平）。

PlotPoint

PlotPoint 是某个命名系列中，位于某个分类 x 位置上的一个值。

pub struct PlotPoint {
  x : String
  y : Double
  series : String
}
pub fn PlotPoint::new(String, Double, String) -> Self

空的 series 绘制为 "value"。

PlotKind

PlotKind 选择图表的绘制与标注方式。

pub(all) enum PlotKind {
  Scaling
  RawDistribution
  BlockOrder
  Interval
  Outlier
  ChangePoint
  Heatmap
  Pareto
}

Scaling、Interval 和 ChangePoint 绘制为点，并用线连接各类别的均值；Heatmap 绘制为单元格；其他种类绘制为点。

test "a plot document" {
  let plot = @ir_model.Plot::new(
    @ir_model.PlotKind::Interval,
    "Median delta",
    "µs",
    "95% bootstrap",
    [@ir_model.PlotPoint::new("1024", -9.5, "candidate")],
  )
  let document = @ir_model.PlotDocument::new("run-7", "native", [plot])
  inspect(document.schema_version.identifier(), content="mmks_1")
  inspect(document.differential.corpus.total, content="0")
}

差分报告

DifferentialReport

DifferentialReport 汇集一次运行的正确性证据。

pub struct DifferentialReport {
  mismatches : Array[MismatchRow]
  capabilities : Array[CapabilityCell]
  counterexamples : Array[Counterexample]
  corpus : CorpusSummary
}
pub fn DifferentialReport::new(Array[MismatchRow], Array[CapabilityCell], Array[Counterexample], CorpusSummary) -> Self
pub fn DifferentialReport::empty() -> Self

empty() 没有任何行，所有语料计数为 0。

MismatchRow

MismatchRow 是一次失败的验证。

pub struct MismatchRow {
  implementation : String
  operation : String
  operands : Array[String]
  expected : String
  actual : String
  flags_diff : String
  trap : String
  fingerprint : String
  replay_command : String
}
pub fn MismatchRow::new(String, String, Array[String], String, String, String, String, String, String) -> Self

report 将 flags_diff 填为期望标志、" → " 和实际标志，各组标志以 ", " 连接。

CapabilityCell

CapabilityCell 统计某个实现某一类结果的数量。

pub struct CapabilityCell {
  implementation : String
  outcome_kind : String
  count : Int
}
pub fn CapabilityCell::new(String, String, Int) -> Self

outcome_kind 是一个 ExecutionOutcome::kind 字符串。

Counterexample

Counterexample 是一个最小化后的失败输入。

pub struct Counterexample {
  implementation : String
  minimal_input : String
  fingerprint : String
  shrink_path : Array[String]
  replay_command : String
}
pub fn Counterexample::new(String, String, String, Array[String], String) -> Self

CorpusSummary

CorpusSummary 统计验证结果。

pub struct CorpusSummary {
  total : Int
  passed : Int
  failed : Int
  unsupported : Int
  expected_difference : Int
}
pub fn CorpusSummary::new(Int, Int, Int, Int, Int) -> Self

test "a differential report" {
  let row = @ir_model.MismatchRow::new("fast", "add", ["0.1", "0.2"], "0.3", "0.30000000000000004", " → inexact", "", "sha256:…", "worker fast 3")
  let report = @ir_model.DifferentialReport::new([row], [], [], @ir_model.CorpusSummary::new(10, 9, 1, 0, 0))
  let document = @ir_model.PlotDocument::new("run-8", "js", [], differential=report)
  inspect(document.differential.mismatches[0].operation, content="add")
}