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 は 1 つのレポートです。

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 は 1 つのグラフです。

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 位置にある 1 つの値です。

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 は 1 つの失敗した検証です。

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 は 1 つの実装について、ある種類の結果の件数を数えます。

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")
}