開発版ドキュメント · 0.2.3 30c2f8ba · 入門例の検証対象 0.2.3 · 版情報 · 既知の制限

GWpy 挙動互換性ポリシー#

GWexpy は、既存の GWpy API が返す既定の科学的結果を暗黙に変えることなく GWpy を拡張します。

既存の GWpy API に対応する API では、GWpy が有限の数値結果を正常に返す場合、対応する import を既定optionの GWexpy に置き換えても、数値、shapeと選択sample、軸情報、正常終了を維持しなければなりません。これらの保証から意図的に外れる場合は、GWexpy 固有の API またはoptionによる明示的な user opt-in が必要です。ただし、以下のすべてのgateを満たす名前付き・human-approvedの安全例外は除きます。内部実装を変更できるのは、科学的挙動を維持し、性能またはresourceに重大な退行を生じさせない場合だけです。

一致させる対象#

次のすべてを満たす場合に、このポリシーを適用します。

  1. 操作が既存の公開 GWpy API に対応している。

  2. 呼び出しが GWexpy 固有の opt-in ではなく既定挙動を使っている。

  3. GWpy が入力を受理し、有限の数値結果を正常に返す。

実装ではなく、観測可能な結果を比較します。

対象

必須の比較

数値結果

対応する API が公開する values と単位

選択

shape、選択sample、境界挙動

軸

t0、dt、times、span、および同等の軸情報

終了状態

GWpy で正常終了する操作を GWexpy 固有の例外に変えない

必須比較のいずれかに差異がある場合、userが明示的な GWexpy 固有 API またはoptionを選んだ場合、または差異が以下のすべての要件を満たす名前付き・human-approvedの安全例外である場合を除き、release blockerです。

名前付き安全例外#

安全例外は、GWpy の挙動を改善、再解釈、置換する一般的な許可ではありません。通常の GWpy 結果が危険である、または要求されたsample-selection domainの外側にあることを実証できる、狭く特定されたsubcaseだけで許可されます。すべての安全例外は次の条件を満たさなければなりません。

  1. 影響を受けるcaseだけにinventory markerとして記録された安定した名前。

  2. サポート対象のすべての GWpy oracle に対する直接の dual-oracle evidence。

  3. 意図的な差異に対するhuman scientific/data-model approval。

  4. 変更前後の挙動を特定するrelease-note disclosure。

  5. public API 全体より狭いscopeであり、親のerrorとその他すべての結果を維持すること。

承認済みの例外は non_intersecting_window_safety だけです。これは、親の HDF5 TimeSeriesDict.read() が成功した後、明示的なread windowと返却seriesが数学的に完全非交差であり、GWpy が要求されたsample-selection domainの外側にあるsampleだけを選択した場合に適用します。GWexpy はその非交差keyにzero-length entryを返します。親のerrorを再解釈せず、部分交差を変更せず、pad=を上書きせず、collection keyを削除せず、その他の結果も変更しません。

説明のない差異、markerのない差異、またはこの例外を当該subcaseより広げる提案は、引き続きrelease blockerです。

拡張が許される範囲#

GWexpy は、GWpy が提供しないcontainer、metadata、精度保持状態、I/O format、解析methodを追加できます。これらの追加機能は、対応する GWpy API の既定挙動から分離しなければなりません。GWexpy を import するだけでは、異なる数値semanticsへの opt-in にはなりません。

不正または矛盾した GWexpy 固有metadataは、引き続き fail closed にできます。このような不正な拡張metadataは正常な有限結果の対象外であり、明示的なvalidation testが必要です。

内部変更とresource使用量#

公開された科学的挙動が同じであれば、内部構造は変更できます。性能に影響し得るbootstrap、dispatch、I/O、数値kernel pathの変更には、riskに応じた性能・resource non-regression evidenceが必要です。maintainerがtrade-offを明示的に承認し文書化しない限り、重大な退行は変更をblockします。

文書だけの変更では、resource evidenceを該当なしと記録できます。

Review checklist#

  1. これは既存の GWpy API か。

  2. review対象のcaseで GWpy は正常な有限結果を返すか。

  3. GWpy と GWexpy の既定挙動は、値、shapeと選択sample、軸、終了挙動で一致するか。

  4. 差異がある場合、明示的な GWexpy 固有 opt-in の背後にあるか、または上記のすべてのgateを満たす名前付き・human-approvedの安全例外か。

  5. 内部変更の場合、相応の性能・resource evidenceが添付されているか。

step 4を満たさずstep 3に失敗した場合、review verdictは BLOCK です。