本書は日本語を正本とし、英語は参照用の補助訳とする。 解釈に差異がある場合は日本語版を優先する。
This document uses Japanese as the authoritative version. The English text is provided as a supporting reference translation. If any discrepancy exists, the Japanese version takes precedence.
本書では、CX_FRAMEWORK.md の読み方のルールに従う。
特に、本書では以下を区別して読むことが重要である。
- 必須要件: 追跡しなければならない情報、満たさなければならない接続条件、Benchkit が責任を持つべき事項。
- 原則: shell-first、ポータル中心、責務分離のような設計原則。
- 将来拡張: 申請フォーム、自動 PR、AI 駆動最適化、MCP 連携などの拡張方向。
This document follows the reading conventions defined in CX_FRAMEWORK.md.
In particular, it is important here to distinguish:
- mandatory requirements: information that must be tracked, connection conditions that must be satisfied, and responsibilities that Benchkit must own.
- principles: design principles such as shell-first, portal-centered interaction, and separation of responsibilities.
- future extensions: directions such as request forms, automatic PR generation, AI-driven optimization, and MCP integration.
Benchkit は、CX基盤を構成する中核ソフトウェアであり、 継続的ベンチマーク、継続的推定、継続的フィードバックを実用的に回すための基盤ソフトウェア兼ポータルである。
Benchkit は特に以下を担う。
- ベンチマーク実行定義を保持する
- CI/CD による継続実行を生成する
- 結果および推定結果を正規化する
- ベンチマーク結果・推定結果・使用量を表示する
- 将来の申請、承認、最適化、AI 指示ワークフローへの接続点を提供する
Benchkit is a core software component of the CX Platform and serves as both infrastructure and portal for practical continuous benchmarking, continuous estimation, and continuous feedback.
Benchkit is responsible in particular for:
- holding benchmark execution definitions
- generating continuous execution through CI/CD
- normalizing benchmark and estimation outputs
- presenting benchmark results, estimation results, and usage
- providing integration points for future request, approval, optimization, and AI instruction workflows
本書は、CX_FRAMEWORK.md および CX_PLATFORM.md を受けて、Benchkit 自体の責務・構成・接続点を定義する下位仕様である。
本書は、Benchkit の外にある外部サービス、外部ツール、実システムを前提とするが、
それらの内部仕様そのものではなく、Benchkit から見た責務境界と接続要件を記述する。
主要用語は CX_FRAMEWORK.md の用語集に従う。
This document is a lower-level specification derived from CX_FRAMEWORK.md and CX_PLATFORM.md, defining Benchkit’s own responsibilities, structure, and integration points.
It assumes the existence of external services, external tools, and real systems outside Benchkit, but describes not their internal semantics themselves, rather the responsibility boundaries and integration requirements as seen from Benchkit.
Core terminology follows the glossary in CX_FRAMEWORK.md.
Benchkit は CX基盤の中で、実行・結果管理・ポータルの中核を担う。
Benchkit 自体の外側には、以下が存在しうる。
- GitHub / GitLab などの外部サービス
- GitLab Runner / Jacamar CI などの実行接続機構
- 実システムおよびスケジューラ
- Benchpark, Spack, Ramble などの外部ツール
- 将来の推定モデルサービス
- 将来の AI サービス
Within the CX Platform, Benchkit is the core for execution, result management, and portal functions.
Outside Benchkit itself may exist:
- external services such as GitHub and GitLab
- execution integration mechanisms such as GitLab Runner and Jacamar CI
- real systems and schedulers
- external tools such as Benchpark, Spack, and Ramble
- future estimation-model services
- future AI services
Benchkit の下層実行基盤は shell-first である。
アプリ開発者や HPC 利用者が、普段の実行運用に近い形で build.sh や run.sh を記述・理解・保守できることを重視する。
抽象化は必要であるが、Python による過度な隠蔽や依存の増加によって参入障壁を高めることは避ける。
The lower execution layer of Benchkit is shell-first.
It prioritizes allowing application developers and HPC users to write, understand, and maintain build.sh and run.sh in a style close to their normal operational practice.
Abstraction is necessary, but Benchkit avoids raising the barrier to entry through excessive Python-based concealment or dependency growth.
Benchkit の上層利用体験は、ポータル中心の利用体験を基本とする。 利用者は可能な限りスパコンへ直接ログインすることなく、 結果参照、推定確認、使用量確認、将来の条件変更申請や AI 指示を行えることを目指す。
The upper user experience of Benchkit is based on portal-centered interaction. Users should, as much as possible, be able to inspect results, estimation outputs, usage, and future request or AI workflows without directly logging into supercomputers.
Benchkit は、アプリ固有差分、システム固有差分、CI 生成、結果正規化、可視化の責務を分離する。
Benchkit separates responsibilities among application-specific differences, system-specific differences, CI generation, result normalization, and visualization.
Benchkit は、単一の計測ツールや単一の推定方式に固定されないことを基本とする。 Benchkit 自身が担うべきなのは、特定手法を埋め込むことよりも、異なる計測方式や推定方式を受け入れ、保存し、表示し、比較できる共通ルールを提供することである。
したがって Benchkit は、推定アルゴリズムそのもの、区間分類の完全な体系、区間ごとの複合推定の内部構成、補助アーティファクトの内部フォーマットまでは固定しない。 それらは推定パッケージ開発者または外部ツール側が定義し、Benchkit はその識別情報、入出力の取り決め、適用可能性、保存形式、表示に必要な共通面を扱う。
そのため Benchkit は、少なくとも概念上、以下を分離して扱えることが望ましい。
- benchmark 結果そのもの
- 推定入力となる追加計測情報
- 推定モデル識別情報
- 推定結果の標準形式
Benchkit should avoid being fixed to any single measurement tool or estimation method. Its role is not primarily to embed one specific method, but to provide common rules that can accept, store, present, and compare different measurement and estimation approaches.
For that reason, Benchkit should preferably be able to separate at least:
- benchmark results themselves
- additional measurement data used as estimation input
- estimation-model identification information
- the standard form of estimation results
Benchkit は以下を責務として持つ。
- アプリごとのベンチマーク実行定義を保持すること
- system ごとの実行条件と queue 情報を参照して CI ジョブを生成すること
run.shの出力を標準化された Result JSON へ正規化すること- 推定結果を標準化された Estimate JSON として扱うこと
weakscalingを最小経路としつつ、より詳細な推定経路も受け入れられること- Web ポータルとして結果、推定、使用量を提示すること
- 将来の申請・承認・自動 PR・AI 最適化との接続点を提供すること
Benchkit is responsible for:
- holding per-application benchmark execution definitions
- generating CI jobs using system-specific execution and queue information
- normalizing
run.shoutput into standardized Result JSON - handling estimation output as standardized Estimate JSON
- accommodating both
weakscaling-based minimum paths and more detailed estimation paths - presenting results, estimation outputs, and usage through a web portal
- providing integration points for future request, approval, auto-PR, and AI optimization workflows
Benchkit は以下を単独では責務としない。
- 外部 CI サービス自身の管理
- 実システムそのものの管理
- スケジューラ自身の内部仕様
- 外部ツール自身の内部仕様
- 人間の承認を要する重要判断の代替
ただし、これらが Benchkit に無関係という意味ではない。 Benchkit は接続条件、前提条件、入力出力条件を明示的に扱う必要がある。
Benchkit is not solely responsible for:
- administering external CI services themselves
- administering real systems themselves
- the internal semantics of schedulers
- the internal semantics of external tools
- replacing critical human approvals
However, this does not mean they are irrelevant to Benchkit. Benchkit must explicitly handle their integration conditions, assumptions, and input/output contracts.
Benchkit は概ね以下の論理構成を持つ。
アプリごとの実装層である。 各アプリは原則として以下を持つ。
build.shrun.shlist.csv- 必要に応じて
estimate.sh
ここでは、ソース取得、ビルド、実行、FOM 抽出などのアプリ固有処理を定義する。
This is the per-application implementation layer. Each application normally contains:
build.shrun.shlist.csv- optionally
estimate.sh
This layer defines application-specific behavior such as source acquisition, build, execution, and FOM extraction.
Benchkit の共通実行基盤である。 ここでは主に以下を担う。
- 共通関数
- CI ジョブ生成
- 結果正規化
- タイミング情報収集
- 送信支援
bk_functions.sh のような共通関数は、shell-first を維持しながら定型処理を吸収する中核である。
This is the shared execution foundation of Benchkit. It mainly provides:
- common functions
- CI job generation
- result normalization
- timing collection
- sending support
Common shell functions such as those in bk_functions.sh are central to absorbing repeated patterns while preserving the shell-first approach.
Benchkit の system / queue 定義層である。
主な役割:
system.csvに system 固有・拠点固有の実行設定を持つqueue.csvに scheduler template を持つ- app 側の
list.csvから system 固有事情を切り離す
system.csv は system 名、mode、runner tag、queue、queue_group などの正本である。
project account、allocation、budget owner などの活動・課題枠に依存する値は、system の恒久的性質ではないため、OSS repo の system.csv や queue.csv には固定しない。
This is the system and queue definition layer.
Main roles:
system.csvholds system-specific and site-specific execution settingsqueue.csvholds scheduler templates- system-specific concerns are separated from app-side
list.csv
system.csv is the source of truth for items such as system name, mode, runner tag, queue, and queue_group.
Activity-specific project accounts, allocations, and budget owners are not stable system properties and must not be fixed in the OSS system.csv or queue.csv.
Benchkit のポータル層である。
主な役割:
- CX Portal のホームを主入口として持つこと
- 結果一覧
- 結果詳細
- 比較可能性の保持と、将来の比較表示への備え
- 推定結果表示
- 推定結果詳細（current / future breakdown を含む）
- 利用可能システム表示
- 使用量表示
- 登録済み run 設定と shell 側の system 分岐に基づく app / system coverage 表示
- 登録済み system / queue / system_info に対する軽い configuration checks
- 管理者向け execution profile 表示
- 管理者向け manual / scheduled / event trigger 管理
- 結果品質サマリ表示（一覧・詳細・latest-result current-state summary・source tracking current-state を含む）
- 認証・権限制御
- 将来の申請・承認ワークフローへの接続点
Execution profile は、対象活動における実行 profile である。対象 app / exp / system、system 単位の allocation project ID、有効状態、承認状態、有効期間を site-local に管理する。account や project ID などの実値を OSS repo に載せず、CX Portal の admin 管理情報として SQLite registry に保持する。manual / scheduled / event trigger は profile とは別の trigger definition として管理し、必要な profile に紐づける。scheduler ごとの具体的な投入書式は、Portal ではなく Benchkit の CI 生成層で扱う。
This is the portal layer of Benchkit.
Main roles:
- a CX Portal home page as the main entry point
- result listing
- result detail pages
- preservation of comparability and room for future comparison views
- estimation result views
- estimation detail views with current/future breakdown visibility
- available-system views
- usage views
- application/system coverage views derived from registered run settings and shell-side system branches
- lightweight configuration checks for registered system, queue, and system-info definitions
- admin-facing execution profile views
- admin-facing manual, scheduled, and event trigger management
- result-quality summaries, including list/detail presentation, latest-result current-state summaries, and source-tracking current-state visibility
- authentication and authorization
- future integration points for request and approval workflows
Execution profiles are operational execution records for a target activity. They define the target app / exp / system scope, system-specific allocation project ID, enabled state, approval state, and validity period as site-local data. Concrete account or project ID values are stored in the CX Portal admin SQLite registry instead of being committed to the OSS repository. Manual, scheduled, and event triggers are managed as separate trigger definitions linked to the relevant profile. Scheduler-specific submit formatting belongs to the Benchkit CI generation layer, not to Portal profile records.
Benchkit は少なくとも以下のデータを中心に扱う。
- 実行条件
- ベンチマーク結果
- 推定結果
- 使用量情報
- ソース出自情報
- ベンチマーク入力出自情報
Benchkit mainly handles at least the following data:
- execution conditions
- benchmark results
- estimation results
- usage information
- source provenance
- benchmark input provenance
実行条件は主に app 側の list.csv と system 側の system.csv により構成される。
list.csv: app ごとの実験条件マトリクスsystem.csv: system ごとの実行ポリシー・runner・queue 情報
Execution conditions are mainly formed by app-side list.csv and system-side system.csv.
list.csv: application-specific execution matrixsystem.csv: system-specific execution policy, runner, and queue information
ベンチマーク結果は、run.sh の出力を result.sh により Result JSON へ正規化したものである。
結果には少なくとも以下を含みうる。
- FOM
- FOM version
- Exp
- section / overlap 情報
- pipeline timing
- source_info
- input_info
- 実行環境メタデータ
pipeline_timing.queue_time は、Result JSON に報告された queue timing であり、
必ずしも scheduler 側の実待ち時間を表すとは限らない。
現在の共通 timing 収集で scheduler 待ち時間を測定できない場合は、
queue_time_source に not_measured を入れる。
site runner や scheduler log などから投入時刻と開始時刻を明示的に取得できる場合は、
任意の scheduler_queue_time と scheduler_queue_time_source を追加し、
reported queue timing とは別の値として扱う。
CI_JOB_STARTED_AT と benchmark script 内の run_start の差から得る値は、
厳密な scheduler 記録の submit/start 差ではないが、GitLab job が runner に拾われてから
benchmark script が開始するまでの job queue time として読める。
この場合は scheduler_queue_time_source に gitlab_job_started_at を入れる。
1つの run job が複数の FOM block を出して複数の Result JSON を作る場合も、
各 Result JSON は同じ job-level pipeline timing を持つ。
これにより Portal の condition-level 表示は
Exp / node_count / numproc_node / nthreads / FOM_version ごとに timing を参照できる。
pipeline_timing.run_time_scope はこの粒度を示し、現在の共通収集では job である。
同じ job に profiler 実行が含まれる場合は、pipeline_timing.profiled_run_included
を true にできる。これは profiler artifact が個々の Result JSON に付くこととは別の
job-level timing marker であり、通常実行の baseline timing と混同しない。
Benchmark results are produced by normalizing run.sh output into Result JSON through result.sh.
They may include at least:
- FOM
- FOM version
- Exp
- section / overlap information
- pipeline timing
- source_info
- input_info
- execution-environment metadata
pipeline_timing.queue_time is the queue timing reported in Result JSON, and
does not necessarily represent scheduler-side wait time. When common timing
collection cannot measure scheduler wait, queue_time_source should be
not_measured. If a site runner or scheduler log can explicitly provide submit
and start timestamps, optional scheduler_queue_time and
scheduler_queue_time_source fields may be attached and should be treated as a
separate measurement from reported queue timing.
When the value is derived from CI_JOB_STARTED_AT and the in-script run_start
timestamp, it is not a scheduler-recorded submit/start delta, but it can be
read as job queue time from GitLab job pickup to benchmark script start. In that
case, scheduler_queue_time_source should be gitlab_job_started_at.
When one run job emits multiple FOM blocks and produces multiple Result JSON
files, each Result JSON carries the same job-level pipeline timing. This lets
Portal condition-level views read timing per
Exp / node_count / numproc_node / nthreads / FOM_version row.
pipeline_timing.run_time_scope identifies that granularity; the current common
collector uses job. When the same job includes a profiler run,
pipeline_timing.profiled_run_included may be set to true. This is a
job-level timing marker, separate from attaching a profiler artifact to an
individual Result JSON, and should not be mixed into unprofiled baseline timing.
Benchkit は、少なくとも最上位アプリケーションのソース出自情報を追跡できなければならない。 特に、最上位アプリケーションの commit hash は必須追跡項目とする。
これは、AI 駆動の開発・最適化において、branch 上で細かく commit が進み、 tag や公式 version が付与されない段階でも性能評価・推定・最適化ループが進行することを想定するためである。
Benchkit が最低限追跡すべき項目は以下である。
- 最上位アプリケーションの source repository
- 最上位アプリケーションの branch または tag/ref 名
- 最上位アプリケーションの commit hash
- ref の種類と、実際に解決された commit hash
- 必要に応じて source URL
- 補助情報としての version や tag
例:
最上位アプリケーションが GitHub 上の qws であれば、main ブランチや指定 tag/ref のどの commit hash から得られた結果かを追跡できなければならない。
また、ポータル上では /results/usage を通じて、各 app / system の最新 result を基準に source tracking の current-state を確認できることが望ましい。
ここでは source_status、source_type、source_reference、不足している source field を軽く見られる形が自然である。
一方で、依存パッケージやビルド環境全体の完全な provenance 追跡は、現時点では Benchkit の必須責務とはしない。 この領域は、Benchpark、Ramble、Spack などの外部ツールが本来強みを持つ領域であり、 国際協力および役割分担の観点からも、それらに委ねることを基本方針とする。
ただし、将来的に CX 基盤全体として依存関係 provenance をより広く扱う必要が生じた場合には、 Benchkit はそれら外部ツールと接続する接続点として拡張されうる。
Benchkit must be able to track source provenance for at least the top-level application. In particular, the commit hash of the top-level application is a mandatory tracked item.
This is required because AI-driven development and optimization may advance through many commits on a branch, even before tags or official versions are created, while benchmarking, estimation, and optimization loops are already running.
At minimum, Benchkit should track:
- the source repository of the top-level application
- the branch or tag/ref name of the top-level application
- the commit hash of the top-level application
- the ref kind and the resolved commit hash actually used
- the source URL when needed
- version or tag information as supporting metadata
Example:
If the top-level application is qws on GitHub, Benchkit must be able to trace which commit hash on the main branch or specified tag/ref produced the result.
It is also desirable for the portal to expose source-tracking current state through /results/usage, based on the latest result for each application/system pair.
A lightweight view of source_status, source_type, source_reference, and missing source fields is a natural form for that visibility.
By contrast, complete provenance tracking for dependency packages and the full build environment is not currently a mandatory responsibility of Benchkit. That area is a natural strength of external tools such as Benchpark, Ramble, and Spack, and from the perspective of international collaboration and role sharing, it should generally be delegated to them.
However, if the broader CX Platform later requires wider dependency provenance support, Benchkit may be extended as an integration point for those external tools.
Benchkit は、pre-staged input、restart、学習済みモデル、公開 archive など、ベンチマーク実行に使った入力の出自情報を任意の input_info として保持できることが望ましい。
これは top-level app source を表す source_info とは別の補助情報であり、source_info に app source と benchmark input を混在させすぎない。
input_info は最初の段階では任意項目であり、存在しない result を ingest failure として扱わない。
一方、app が Benchkit の入力metadata helper または対応する受け渡し形式で input metadata を渡す場合、Benchkit はそれを JSON object として検証し、Result JSON の top-level input_info に添付できる。
input_info には少なくとも次のような情報を置けることが望ましい。
- dataset identity
- dataset version または revision
- input kind
- manifest digest または content digest
- 生成 recipe または取得 recipe
- source URL または archive reference
- self-contained な runtime parameters
- 検証状態
入力が top-level app repository 内に含まれ、その repository の source_info.resolved_commit で固定される場合は、別の manifest や content digest を必須にしない。
この場合、source_info が実際に使った app source と repo 内 input の両方の固定点になる。
input_info は省略してもよく、Portal や review で dataset 名を見せたい場合だけ、kind: "repo-local-input"、source: "source_info"、repo_relative_path、verification_status: "covered_by_source_commit" などの補助情報を持たせてよい。
入力が別の input repository や archive から来る場合は、input_info 側に source URL、ref、resolved commit または digest、取得/生成 recipe を置く。
この場合も、入力が記録済み source commit で固定されるなら verification_status: "source_commit" として Covered に分類できる。
入力が実ファイルではなく、command / arguments / parameters だけで完全に表せる場合は、kind: "runtime-parameters" または kind: "inline-parameters"、source: "inline"、arguments または parameters、verification_status: "self_contained" を使える。
同じ job から複数 result が出る場合は、result_exp などの result scope を添えて、各 result と対応する入力指定を明示してよい。
site-local path は所在情報であり、長期的な input identity ではない。 巨大データや共同研究由来データを site-local shared storage に置くことは許容されるが、Result provenance では path より dataset identity、recipe、manifest、digest を優先する。 public surface では、必要がない限り detailed local path を表示しない。
Benchkit should preferably be able to retain provenance for benchmark inputs such as pre-staged inputs, restarts, trained models, and public archives as optional input_info.
This is auxiliary information separate from source_info, which represents the top-level application source; app source and benchmark input should not be mixed too heavily into one object.
At the initial stage, input_info is optional, and results without it are not treated as ingest failures.
When an application passes input metadata through the Benchkit input metadata helper or a supported handoff format, Benchkit can validate it as a JSON object and attach it to the top-level input_info field in Result JSON.
input_info should preferably be able to include information such as:
- dataset identity
- dataset version or revision
- input kind
- manifest digest or content digest
- generation or acquisition recipe
- source URL or archive reference
- self-contained runtime parameters
- verification status
When the input is already stored in the top-level application repository and is fixed by source_info.resolved_commit, a separate manifest or content digest is not mandatory.
In that case, source_info is the fixed point for both the application source and the repository-local input actually used.
input_info may be omitted, or it may carry lightweight helper fields such as kind: "repo-local-input", source: "source_info", repo_relative_path, and verification_status: "covered_by_source_commit" when the dataset name should be visible in the Portal or during review.
When the input comes from a separate input repository or archive, input_info should carry the source URL, ref, resolved commit or digest, and acquisition or generation recipe.
If the input is fixed by a recorded source commit, it may use verification_status: "source_commit" and be classified as Covered.
When the input is not a file and can be fully represented by command arguments or parameters, input_info may use kind: "runtime-parameters" or kind: "inline-parameters", source: "inline", arguments or parameters, and verification_status: "self_contained".
When one job emits multiple results, a result scope such as result_exp may be attached so each Result JSON is evaluated against the matching input declaration.
A site-local path is location information, not a durable input identity. Large datasets and collaboration-derived inputs may still be staged on site-local shared storage, but Result provenance should prefer dataset identity, recipe, manifest, and digest over paths. Detailed local paths should not be exposed on the public surface unless they are necessary.
Benchkit は、公開可能な Result JSON から public-only reuse packet を生成できることが望ましい。 これは raw Result JSON の代替ではなく、AI agent や人間が再利用可否を判断しやすいように、公開できる evidence だけを Markdown と machine-readable manifest へ投影するものである。
Public reuse packet の対象は、少なくとも次の条件を満たす result に限定する。
- result 自体が public surface で閲覧可能である
source_infoが public access confirmed な Git URL、ref、resolved commit を持つinput_infoが public access confirmed な input source commit、archive digest、DOI、または public source commit で固定される repo-local input を示す
URL 文字列だけでは public access confirmed と見なさない。
未確認の source/input URL は public reuse packet では非公開扱いにする。
public access の確認は CI pipeline や公開前監査で実施し、Portal 表示時には外部到達性を確認しない。
現在は github.com と gitlab.com の repository URL を provider API で匿名確認した場合だけ public_access_check として扱う。
Public reuse packet には、benchmark condition、FOM、source commit、public input binding、build-cache digest、profile artifact reference、estimation package binding など、公開可能な再利用情報だけを入れる。 raw Result JSON、local path、allocation detail、operator-only environment detail、非公開 input/source は含めない。 同じ内容は JSON manifest としても取得でき、Markdown packet はこの manifest の人間・AI向け表現とする。 Portal の Evidence Snapshot では、latest result の packet status と、既に利用可能な latest public reuse packet を分けて表示してよい。これにより、最新 result が追加の public input binding を待っている場合でも、過去の eligible result から reuse packet を取得できる。
Benchkit should preferably be able to generate public-only reuse packets from publishable Result JSON records. This is not a replacement for raw Result JSON; it is a public evidence projection that helps humans and AI agents decide how a benchmark result can be reused.
A public reuse packet should be limited to results that satisfy at least:
- the result itself is visible on the public surface
source_inforecords a public-access-confirmed Git URL, ref, and resolved commitinput_inforecords a public-access-confirmed input source commit, archive digest, DOI, or repository-local input fixed by a public source commit
A URL string alone is not treated as public-access confirmed.
Unconfirmed source/input URLs are treated as non-public for public reuse packets.
Public-access checks should run in a CI pipeline or publication review step, not during Portal page rendering.
Currently, only github.com and gitlab.com repository URLs confirmed through anonymous provider APIs are treated as public_access_check evidence.
The packet should include only public reuse information such as benchmark condition, FOM, source commit, public input binding, build-cache digests, profile artifact references, and estimation package bindings. It must not include raw Result JSON, local paths, allocation details, operator-only environment details, or non-public input/source information. The same projection may be exposed as a JSON manifest, with the Markdown packet acting as the human- and AI-friendly rendering of that manifest. In the Portal Evidence Snapshot, the latest result packet status may be shown separately from the latest available public reuse packet. This keeps older eligible packets discoverable even when the newest result still needs public input binding.
推定結果は、実測結果やモデルに基づいて生成される Estimate JSON である。
Benchkit は、weakscaling を最小経路とする推定結果と、より詳細な推定結果の両方を扱えることが望ましい。
また、推定方式や計測方式の違いを将来的に比較できるよう、推定結果には方式識別のための拡張余地を持たせるべきである。
Estimation results are Estimate JSON records generated from measured results and estimation models.
Benchkit should preferably be able to handle both weakscaling-based minimum estimation outputs and more detailed estimation outputs.
It should also preserve room for method-identification metadata so that different measurement and estimation approaches can be compared in the future.
さらに、Benchkit は少なくとも次の 2 種類の出自情報を保持できることが望ましい。
- 各推定側の参照ベンチマークの出自情報
- 保存対象としての推定結果そのものの出自情報
It should also preserve both:
- side-specific reference benchmark provenance
- estimate-result provenance as a stored object
さらに Benchkit は、intra_system_scaling_model と cross_system_projection_model の両方を扱え、各 system 側で必要に応じてそれらを使い分けられることが望ましい。
In addition, Benchkit should preferably be able to handle both intra_system_scaling_model and cross_system_projection_model, and use them as needed on each system side.
Benchkit の典型的な実行フローは以下である。
- app ごとに
programs/<code>/list.csvが実験条件を定義する system.csvとqueue.csvが system 側条件を与えるmatrix_generate.shが CI ジョブを生成するbuild.shとrun.shが対象 system で実行されるrun.shはbk_emit_resultなどを通じて結果行を出力するresult.shが Result JSON を生成する- 結果が result_server へ送られ、一覧・current-state 表示・集計に使われ、将来の比較にも備えて保持される
The typical execution flow in Benchkit is:
programs/<code>/list.csvdefines execution conditions for each appsystem.csvandqueue.csvprovide system-side conditionsmatrix_generate.shgenerates CI jobsbuild.shandrun.shexecute on the target systemrun.shemits result lines through helpers such asbk_emit_resultresult.shgenerates Result JSON- results are sent to result_server for listing, current-state presentation, and aggregation, while being preserved for future comparison
Benchkit は実システムを直接管理しないが、 runner、Jacamar CI、scheduler、module 環境、共有ストレージなどの実行条件を接続可能な形で定義しなければならない。
そのため、拠点接続では少なくとも以下を扱う必要がある。
- system 名
- runner tag
- build/run の実行責任主体
- queue および submit template
- job 完了判定
- stdout/stderr/結果回収方法
- module 環境
- MPI ランチャ
- 実行アカウントと予算主体
例:
RC_GH200、RC_DGXSP、RC_GENOA、RC_FX700 では、runner tag、queue、module load、MPI 実行方法、結果回収先が定義されていて、CI からその条件で実行できなければならない。
Benchkit does not directly manage real systems, but it must define runners, Jacamar CI, scheduler behavior, module environments, shared storage, and similar execution conditions in an integrable form.
Therefore, site integration must handle at least:
- system name
- runner tag
- ownership for build/run execution
- queue and submit template
- job completion rules
- stdout/stderr/result collection method
- module environment
- MPI launcher
- execution account and budget owner
Example:
For RC_GH200, RC_DGXSP, RC_GENOA, and RC_FX700, the runner tag, queue, module loading, MPI launch method, and result collection destination must be defined so that CI can execute under those conditions.
Benchkit は将来的に以下へ拡張されうる。
- app 追加申請フォーム
- 実験条件変更申請フォーム
- 承認付き自動 PR 生成
- 推定条件変更ワークフロー
- AI 駆動最適化ワークフロー
- Benchkit から Benchpark 定義を生成する支援
- MCP サーバとしての公開
これらは Benchkit を CX基盤の中核ポータルへ発展させる方向である。
Benchkit may be extended in the future with:
- app onboarding request forms
- execution-condition change request forms
- approval-based automatic PR generation
- estimation-condition update workflows
- AI-driven optimization workflows
- support for generating Benchpark definitions from Benchkit data
- exposure as an MCP server
These extensions move Benchkit toward the role of the central portal of the CX Platform.
利用者にとって Benchkit は、単なる実行スクリプト集ではなく、 スパコンへ逐一ログインすることなく性能データを扱うための窓口である。
利用者は Benchkit を通じて、少なくとも以下を行えることが望ましい。
- ベンチマーク結果の確認
- 推定結果の確認
- 使用量の確認
- 小さな実験条件変更の要求
- 小さな推定条件変更の要求
- 将来的には AI への指示
From the user perspective, Benchkit is not just a collection of execution scripts. It is the main interface for working with performance data without repeatedly logging into supercomputers.
Users should ideally be able to use Benchkit to:
- inspect benchmark results
- inspect estimation results
- inspect usage
- request small execution-condition changes
- request small estimation-condition changes
- eventually issue instructions to AI-based workflows
本仕様は以下と整合する。
- CX_FRAMEWORK.md
- CX_PLATFORM.md
- ESTIMATION_SPEC.md
- ESTIMATE_JSON_SPEC.md
- ESTIMATION_INPUT_ACQUISITION_SPEC.md
- ESTIMATION_PACKAGE_SPEC.md
- ESTIMATION_PACKAGE_METADATA_SPEC.md
- ESTIMATION_PACKAGE_SHELL_API_SPEC.md
- REESTIMATION_SPEC.md
- RESULT_STORAGE_DESIGN.md
- AUDIT_LOG_SPEC.md
This specification is aligned with: