warp-eval

Warp の評価

目的

既存のコードベースにある限定された接点について、NVIDIA Warp でどのように動作するかを再現可能な根拠に基づいて評価します。事実を報告し、判断はユーザーに委ねます。

最初の行で評価対象の選択肢として Warp を明記し、採用を推奨しないことを示します。また、性能改善の依頼を、実験の許可として扱ってはいけません。

測定を伴う評価では、warp-evaluation-report/ を作成します。ここには、レポート、個別に適用できる解決策ごとの差分、ドライバー、生の結果を含めます。本番コードは決して変更しません。測定を伴う作業に入る前に終了した場合、ディレクトリは作成しません。

厳守事項

これらのルールは、ローカルでの判断より優先されます。

1. デフォルトの評価対象は、レイテンシー、スループット、ピークメモリまたは保持メモリです。 保守性、使いやすさ、パッケージング、拡張性、自動微分、新機能は、ユーザーが明示した場合にのみ評価します。それ以外の場合は、メリットではなく制約またはコストとして報告します。
2. 正しさは必須条件です。 現行実装にバグがある、またはその契約が不明確な場合、独立したオラクルが存在するか、契約が明確になるまで比較を中止します。対応方法を提案せず、欠陥を報告します。
3. ソースコードの形状や別のワークロードから、削減効果を予測してはいけません。 実体化されたメモリは、ソースコードをコンパイラーが融合する可能性ではなく、プロファイラーまたはアロケーターの根拠に基づいて報告します。
4. 「Warp で記述できる」は仮説であり、機会が実証されたことにはなりません。
5. ゲートは厳密に判定し、近似や類推で適用してはいけません。 定義にある条件がすべて確認された場合にのみ、ゲートを適用します。ゲート D には、NVIDIA GPU 上で CUDA を使用して実行することが確認された、保守されている実装が必要です。高速なネイティブ CPU ライブラリはベースラインであり、ゲート D には該当しません。
6. すべての主張に、観察された事実、測定値、仮説、不明のいずれかを明記します。
7. カーネルではなく、ユーザーに見える処理段階を計測します。 実際のプロセス実行条件における Warp の初回インポート、初期化、JIT を含め、転送、起動、Python の起動ループ、構造体の構築・再フィット、割り当て、変換、検証、圧縮、同期を計測します。各コストとエンドツーエンドの差を報告します。
8. 明示的な許可なしに測定を行ってはいけません。 ステージ 1 の後は停止し、プロファイリング、環境変更、プロトタイピング、ベンチマーク、GPU の使用を行う前に許可を求めます。
9. 許可された測定作業には Warp が含まれます。 プロファイリングでゲートが適用されない場合でも、プロジェクト内の最も有力なベースライン、最小限の Warp プロトタイプ、エンドツーエンド比較まで続けます。Warp が対象外の場合は、プロファイリング前に停止します。
10. 環境に関する意図を推測してはいけません。 NVIDIA へのデプロイと、オプションのコンパイル済み依存関係の所有は、製品上の判断事項です。明示された制約がある場合にのみ中止します。それ以外の場合は一度だけ質問し、停止します（AWAITING INTENT）。
11. Warp の測定は CUDA のみで行い、同期します。 NVIDIA CUDA デバイスを明示的に解決し、CPU への解決とディスパッチのみの計測は破棄します。
12. 採用の選択肢を推奨したり、順位付けしたりしてはいけません。 接点と実行条件ごとに、事実、測定値、仮説、不明点を報告します。
13. レポートの作成をもって終了します。 展開や本番コードの編集は行いません。

要件

静的なスクリーニングには、対象リポジトリと、明示された製品上の制約が必要です。測定作業にはさらに、明示的な許可、NVIDIA CUDA GPU、対象プロジェクトの依存関係、代表的なワークロードが必要です。

制限事項

• Warp の CPU カーネルはシリアルであり、このスキルの評価対象外です。 「代わりに CPU で実行する」は、パフォーマンス上の代替策にはなりません。
• メッシュおよびジオメトリのクエリは、公開 API が float64 でも float32/int32 で計算します。 絶対誤差は座標の大きさに応じて増加します。
• Warp はセマンティック バージョニングに従いません。 機能リリースによって API が破壊的に変更されることがあり、保守されるのは最新の機能系列のみです。非推奨化はおよそ 4 回の月次リリースにわたって進みます。
• latest のドキュメントはリリース済みのバージョンではなく、開発中の内容を反映しています。 対象プロジェクト独自の Warp バージョンに固定してください。指定されていない場合は、現在の安定版を使い、どのバージョンかを明記してください。
• カーネル専用の組み込み関数は Python から解決できません — そのリリースに存在していても、hasattr(wp, "mesh_query_point") は False になります。組み込み関数が存在しないと結論づける前に、スタブファイルまたは該当バージョンのドキュメントを確認してください。
• enable_backward=False（カーネル、モジュール、またはグローバル設定）は随伴コード生成を無効にします。シームを通じた微分が不要な場合は、コンパイルコストを測定する前に設定してください。

出力形式

状態	到達条件	レポートディレクトリ
ABORT	評価対象のシームが提示されたスコープを満たせないことを、いずれかのゲートが確定した場合	測定を行っていない場合は不要。それ以外の場合は、すでに収集した証拠を保持します
AWAITING INTENT	環境に関するゲートで、ユーザーしか把握していない事実が判明した場合	不要 — 質問は 1 つとし、どちらの回答の場合も具体的に示します
AWAITING AUTHORIZATION	ステージ 1 で候補パターンが残った場合	不要 — 初期所見とスコープ／リソースの概要を提示します
INCOMPLETE	承認済みの作業で、スコープに沿った評価に必要な代表的な証拠を取得できない場合	必要 — 収集した証拠を保持し、不足している成果物を 1 つ明記します
レポートを納品済み	承認済みの作業で測定を行った場合、またはレポートディレクトリの作成後に作業を停止した場合	必要 — シームおよびレジームごとの事実を記載し、不足している証拠を明示します

早期終了には、次の形式をそのまま使用してください。 ABORT — Gate <letter>: <cited fact>; <why the scoped Warp evaluation cannot proceed>. 推奨する代替案を挙げないでください。 報告ルール： references/evidence-and-reporting.md。 納品するディレクトリは、テンプレートの固定順序に従います。スキーマと来歴、承認と評価状態、ステージの調査結果、シーム／レジームごとの B<n> 証拠セクション、注意事項、環境／再現手順の順です。solutions/、benchmarks/、results/ には、リンクされたすべての成果物を含めてください。

例

ゲートによる終了： ABORT — Gate A: deployment.md requires one implementation with AMD, Apple and NVIDIA parity; a Warp-specific path cannot satisfy this scope.

候補が残った場合： シームとパターンを示し、推論した事実には仮定のラベルを付け、ゲートに該当する事実がないことを明記してください。プロファイル／ベースライン／Warp のプロトタイプ／ベンチマークの範囲とコストを概説したうえで、 references/authorization-checkpoint.md にある、意図と承認に関する別々の質問をしてください。

入力

必須： 対象リポジトリ、および候補となるシームを伴うパフォーマンス、メモリ、またはスケールの問題。任意： 明示的なデプロイ／パッケージング制約、既存のプロファイルやログ、代表的なデータセット、合格基準。プロンプトの制約はリポジトリのポリシー／設定より優先され、既存のログはその次に優先されます。ユーザーによる訂正は推論より優先されます。明示された事実や測定値の代わりに、仮定を用いてはいけません。

利用可能なスクリプト

スクリプト	用途	引数
scripts/driver-template.py	ボトルネックごとに 1 回コピーし、ワークロードとバリアントを定義します	プレースホルダーを編集してから、コピーしたドライバーを実行します
scripts/measure.py	ドライバーからインポートして、同期タイミング、メモリ、分離ケースを測定します	Python API。直接実行しないでください
scripts/validate_report_schema.py	納品するレポートと証拠へのリンクを検証します	<report-directory>

対応している場合は、run_script("scripts/validate_report_schema.py", args=["warp-evaluation-report"]) を使用してください。それ以外の場合は、Python でスクリプトを実行し、レポートディレクトリを渡してください。

トラブルシューティング

• 代表的なワークロードがない場合は、対象範囲を INCOMPLETE とし、不足している成果物を明記します。データを捏造したり、Gate F を発動させたりしないでください。
• Warp が CPU に解決される、または CUDA デバイスがない場合は、その実行結果を破棄し、正確性やタイミングに関する主張を行う前に停止します。
• レポートの検証に失敗した場合は、レポートまたは参照先の成果物を修正します。スキーマエラーを決して免除しないでください。

手順

最後のステージより前の各ステージで評価を終了できます。ゲートが発動したらすぐに停止し、対象範囲の事実を変えない証拠は収集しないでください。

1. コードを読み、契約を導き出し、ゲートを確認する

• references/target-patterns.mdを使って候補とその指標を特定します。
• リポジトリからデバイス／常駐性、データ型／形状、サイズ、頻度、プロセスのライフタイム、勾配、パッケージングを導き出します。質問する前に推論してください。
• 推論した契約を1行で示し、修正を促します。不明なハードウェア、件数、サイズ、許容誤差は測定値ではなく仮定です。すべての推論は修正可能な状態に保ち、明示された事実や測定値を必要とするゲートを満たすものとして扱ってはなりません。
• プロファイリングの前に Gates A–E を確認します。代表的な証拠がすでにある場合に限り、今 Gate F を確認します。それ以外の場合はステージ2に持ち越します。各ゲートでは、references/rejection-gates.mdに記載された正確な境界のみを使用します。

Gate	発動条件
A	本番環境が CPU のみ、または NVIDIA 以外への移植性が必要だと 明示されており、許容可能な任意の CUDA パスがない
B	小規模または低頻度の呼び出しごとにホスト／デバイス境界を越える必要があり、その境界を拡大できない
C	対象領域が密なテンソル演算で、すでにチューニング済みのフレームワークまたはベンダーライブラリにマッピングされている
D	成熟した CUDA 実装がすでに契約を満たしており、パフォーマンス以外の目的が求められていない
E	明示されたポリシーが Warp の依存関係、コンパイル、キャッシュ、またはフォールバックに関する要件を妨げている
F	代表的な証拠により、どのバックエンドを使っても要求された指標への寄与率が低すぎると分かる

• Gate F は、提示されたプロファイル、構造上の上限、またはユーザーが示した数値に基づく計算など、すでに存在する代表的な証拠がある場合に限り、ステージ1で発動できます。そのような証拠がない場合、Gate F はステージ2のプロファイリングまで未確定のままです。推論値で発動させることはできません。
• Gates A と E には、明示された制約が必要です。CPU 実装、別のアクセラレーター、Warp への依存がないこと、または依存関係のリストが短いことは、何の証明にもなりません。
• A/E が未解決で、パターンが有効な場合は、任意の NVIDIA パスが許容されるか確認します。具体的には、名前付きエクストラ、ソフトインポート、既存のフォールバック、デフォルトインストールの変更なしを提示します。肯定する回答ではすべて、Warp のプロトタイプ作成とベンチマークを実施することを明示する必要があります。条件は Warp の対象範囲のみを制限します。否定または未決定の回答の場合は ABORT です。
• 別のゲートが発動している場合、リポジトリから回答が得られる場合、またはパターンに一致しない場合は質問しないでください。パターンに一致しない場合、プロファイリングは行いません。
• 候補が残った場合は、意図に関する質問をauthorization checkpoint（初期の所見、正確な対象範囲、ステージ、リソースコスト）と組み合わせてから停止します。ステージ2には、確定した意図と明示的な承認の両方が必要です。

2. 実際のアプリケーションをプロファイリングする

明示的な承認と、確定した意図の確認質問が必要です。

• プロジェクト自身のプロファイラーと代表的なエントリポイントを使ってプロファイリングします。
• バックエンドを選ぶ前に、同期されたエンドツーエンドのステージ時間とピークメモリを測定します。どのエントリポイントをプロファイリングし、どれをゲートがスクリーニングしたかを報告します。
• さらなる測定は、ソースの見た目ではなく、観測されたコストに基づいて優先順位を付けます。
• 各測定は、実際に呼び出された公開メソッドとバリアントによって命名します。フォールバックはその公開シームの実行レジームであり、別の操作ではないため、より安価な兄弟メソッドで名前付きメソッドをスクリーニングすることはできません。
• 計測された分岐が意図したデバイス上で実行されたことを確認します。ホスト入力とデバイス入力の間でコストが変わらず、デバイス割り当てがほぼゼロである場合、ホストフォールバックが露呈します。
• 公開境界を通じて、ステージの空ステージ上限とスタブ下限を測定します。操作ごとのタイミングを差し引かないでください。
• 測定された上限が、候補が自身のメトリクスを動かせないことを証明する場合、Gate F の下で影響を受けるスコープを ABORT し、すでに収集した証拠を保持して停止します。既存の承認はこの実質性チェックをすでにカバーしています。承認を再度求めないでください。
• 代表的なカバレッジが利用できない場合 — 代表的なデータセット、実行可能なエントリポイント、本番ディストリビューションのいずれもない場合 — 欠落している単一の成果物を記録し、影響を受けるスコープを INCOMPLETE とマークして停止します。これは欠落した証拠であり、Gate F でも ABORT でもありません。でっち上げたワークロードでは実質性を証明できません。

プロトコル: references/benchmark-protocol.md。

3. 反証可能な仮説を立てる

候補ごとに記録します: ソース、ボトルネックの証拠、目的、狭いシーム、Warp が変更できるメカニズム、最強の既存手法、リスク、受け入れしきい値、最も安価な反証実験。references/target-patterns.md に対してスクリーニングし、どれも生き残らなければ、レポートを書いて停止します。

4. プロトタイプの前にコントラクトを書く

値、dtype、シェイプ、デバイス、エラー、ミューテーション、順序付け、タイ、容量/オーバーフロー、トポロジー/退化、トレランス、必要な勾配、ストリーム、所有権、エイリアシング、無効化、並行性、キャプチャ、ティアダウン、フォールバックを定義します。

• Warp の出力を見る前にトレランスを固定します。ミスマッチの後にコントラクトを弱めてはいけません。
• 提案されたシームが必要なコントラクトを満たせない場合、プロトタイピングの前に ABORT します。
• タイミングの前に事前登録します: ワークロードの来歴、コストを制御する状態変数と本番範囲、チューニングノブ、既存手法の実行間ばらつき、すべての実装に適用されるオラクル。

ハザードと敵対的チェック: references/semantic-contract.md。

5. まずベースラインを改善する

バックエンドよりアルゴリズムを優先します：（1）より優れたアルゴリズム、または出力に応じて計算量が変化するアルゴリズム； （2）チャンク化、タイリング、スパース出力、レイアウト、再マテリアライズ； （3）現行フレームワークのコンパイラーとネイティブプリミティブ； （4）プロジェクトがすでに依存しているもの — 独自のアクセラレーターバックエンド、提供されているのに無効化されている並列処理のイディオム、または既存の依存関係が公開しているものの、誰も接続していない機能； （5）そのうえで初めて、Warpを限定的に検討します。

• スコープ内の選択肢のみを比較します。改善した現行実装、現在の依存関係を通じて利用できる機能、Warpを対象としてください。無関係なライブラリは追加しないでください。
• ある方法が利用できないと判断する前に、宣言済みの依存関係に未使用のバックエンド、フラグ、バインディングがないか検索してください。
• 改善した現行実装を比較の基準として維持してください。調整不足、誤り、または漸近的に劣るベースラインとの結果では、バックエンドの比較を立証できません。

Warpのプロトタイプを始める前に、プロジェクト内で利用できる方法をすべて検証してください。

状態	その状態を主張するために必要なこと
測定済み	ベースラインと同じ境界を通じて計測されている
利用不可	利用できないことが、引用した宣言、シンボルテーブル、または存在しないフラグによって証明されている
免除	ユーザーに確認し、スキップする選択をしたこと。その言葉を記録する

機能が存在していてもバインドされていない場合、それは利用可能であり、利用不可ではありません。その機能を公開するコストが、予定しているWarpとの接続部分以下なら、まず測定してください。手順の詳細： references/baselines.md。 免除された方法はステージ6を妨げません。明示的に免除されていないすべての方法は、Warpのプロトタイプを始める前に測定するか、利用不可であることを証明する必要があります。

6. 最小単位でプロトタイプを作成する

• 本番環境に変更を加えず、別のコピーで作業し、統合部分はデフォルトで無効にします。仮説を検証するのに必要な最小限だけをプロトタイプします。
• Warpのプロトタイプではすべて、明示的にCUDAデバイスを選択し、正確性や性能の検証に入る前に、WarpがそれをCUDAとして解決していることを確認してください。WarpのCPUバックエンドは決して実行したり、結果を報告したりしないでください。
• 関数の境界ではなく、共有データと構造のライフタイムに基づいて単位のサイズを決めます。まとめてコストを償却できる構築、再構築、クエリは、ひとつの単位です。
• 計測前に各バリアントに名前を付けます。各ソリューションは、固定したベースラインに対する独立したパッチとして保存し、問題なく適用できることと、測定結果を再現できることを証明してください。
• 計測前に、未対応のケースとオーバーフローを明らかにしてください。
• 敵対的な条件に対する契約チェックを実行し、本番規模で正確性を監査し、意図的に分岐を壊してテストが失敗することを確認してください。必須チェックにひとつでも失敗した場合、対象範囲について ABORT を返します。
• 計算負荷が高いケースや再利用の多いケースで期待外れの結果が出た場合、それを代表的な結果とみなす前に、references/target-patterns.mdにある、より強力な定式化を検討してください。素朴なカーネルひとつだけでは、Warpの可能性を判断できません。

7. 境界全体をベンチマークする

• ボトルネックごとにscripts/driver-template.pyを一度コピーし、scripts/measure.pyを通じて計測してください。タイミングやメモリー計測を独自に実装しないでください。
• Warpのカーネル起動は非同期です。計測ヘルパーは、選択したデバイスを計測対象領域の開始直前と、ウォールタイマーを停止する前の、計測対象領域内の各処理をキューに登録した後に同期する必要があります。
• ルール7に含まれるすべてのコスト、公開呼び出し、その直後の下流ステージ、現実的なサイズ、プロセスのコールド／ウォーム両方の状態を含めてください。
• 出力されたJSONからレポートの各セルをすべて転記してください。記録がない場合は not measured と記載します。
• null_testと、一度だけ発生するコストを個別および償却後の両方で報告してください。GPUの計測は排他的なデバイスロックのもとで実行してください。1.5×未満では測定上の差はありません。
• 事前に定めたエンドツーエンドの性能またはメモリー要件を満たさない接続部分と実行条件については、計測結果を保存したうえで ABORT とします。

プロトコルの全容： references/benchmark-protocol.md。

8. 証拠を要約する

• シームと実行環境ごとに、セマンティクスの結果、最も強力なベースラインの測定値、ワークロードの出所、時間、メモリ、ライフサイクル、移植性、所有権に関する事実を報告します。
• 明示された基準によってそのステータスが客観的に決まる場合に限り、pass、fail、not measured、not available、no representative data、unknown、n/a を使用します。欠落している証拠は、欠落したままにします。
• 評価対象のすべてのシームと実行環境について、エンドツーエンドの Warp 測定が含まれる場合に限り、レポートに complete と記載します。ゲートが発動した場合は aborted — <gate and scope>、代表的な証拠を得られなかった場合は incomplete — <missing evidence and scope> と記載します。収集したものはすべて保持します。現行実装のみのレポートを、完了した warp-eval として提出してはいけません。
• 測定合計の 10 % 以上を占めるすべての段階について、除外された段階も含め、ステータスと理由を一行で記した全数調査の行を作成します。
• 各ゲートは、調査全体の主な目的ではなく、その候補のパターンが限界に達する指標に照らして判定します。

9. 引き渡す

• スキーマを変更せず、 assets/warp-evaluation-report-template.md を使用します。承認とスコープを記録します。
• ボトルネックごとに表を 1 つ作成します。ベースライン、現行依存関係を使った解決策、次に Warp の順に記載し、絶対時間とピークメモリ、比率、契約のステータス、証拠の不足を含めます。
• 測定値またはその適用範囲の説明に必要な場合に限り、本文を追加します。作業用成果物は results/ に格納します。

uv run python scripts/validate_report_schema.py <report-directory>

• 最初の測定で全数調査表と表が確定した時点でバリデーターを一度実行し、提出前にもう一度実行します。すべてのエラーを修正します。
• 終了ステータスではなく、成果物からビルドとインポートを検証します。実行したドライバーそのものを納品します。その後は作業を終了します。