既知の制約#
このページは、リリース済み GWexpy 0.2.3 系列で利用者への影響が大きい制限を記録しています。以下に示す v0.2.0 で導入された境界は、後のリリースノートで明示的に更新されない限り引き続き適用されます。互換性に関する主な注意点をまとめたもので、すべての未解決 Issue を列挙したものではなく、次のリリースで制限が解消されることを約束するものでもありません。
重要
物理的に安全でメタデータを保持する結果を定義できない場合、GWexpy の契約は、裸の numpy.ndarray や astropy.units.Quantity、意味の曖昧な時刻へ黙って退行するのではなく、明示的に失敗することです。そのため、以下に示す TypeError や ValueError は、意図した安全境界である場合があります。
ここに列挙していないフォーマット別・アダプター別の対応範囲は、I/O formats と interoperability を参照してください。
開発版ドキュメントと互換性#
開発版の API ページには、0.2.3 より後の変更が含まれる場合があります。インストール済みのリリースと比較する場合は、ドキュメントのバージョンと GWpy 互換性ポリシーを参照してください。GWpy から継承した操作が成功する場合は、親の仕様を保持します。以下の処理を拒否する制限は、文書化された個別の境界に適用されるもので、GWpy の挙動を全般的に変更するものではありません。
現在の開発版の互換性に関する注意点には、継承した異種チャンネル間 CSD の単位ラベルと、無次元の信号出力が含まれます。物理的に校正したノイズ寄与の推定については、ノイズバジェットの例で出力/入力の単位を明示する方法を参照してください。これらの差異の範囲と承認は、変更履歴に記録しています。
時刻軸の厳密精度#
GWexpy v0.2.0 は、リリースの仕様で対象としているコンストラクタ、コピーとスライス、永続化、相互運用の経路で、整数の GPS ナノ秒による正確な開始時刻を保持します。ただし、すべてのサンプリング間隔と操作について、正確な有理数による時間軸を完全に定義しているわけではありません。1024 Hz や 4096 Hz などのサンプル間隔はナノ秒未満の端数を持ちますが、GWpy 互換の t0、dt、times、xindex は binary64 による近似値です。v0.2.2 以降では、このようなサンプリング間隔でのスライスや切り出しで、派生した内部の厳密時刻情報を破棄する場合があります。その場合も、親で成功する操作と、その公開時間軸を保持します。
1 ナノ秒の差や厳密な有理数サンプル境界が科学的に重要な場合、未対応の変換や永続化境界をまたいで浮動小数点時刻軸だけを権威的情報として使用しないでください。#688 で追跡しています。
SeriesMatrix の直接 NumPy ufunc#
v0.2.0 の B0 / Phase-A 契約では、意図的に SeriesMatrix.__array_ufunc__ = None を維持しています。そのため np.sqrt(matrix)、np.log(matrix)、np.exp(matrix)、np.isfinite(matrix)、np.isnan(matrix) のような直接 NumPy ufunc は、メタデータや単位を失う退行を起こす代わりに TypeError を送出します。
平方根には matrix ** 0.5 を使用してください。これは 3 種類の SeriesMatrix family で契約テストされ、B0 の情報を保持します。log、exp、isfinite、isnan については、メタデータを保持する B0 の代替経路は現在定義されていません。Quantity-left / Quantity-right の乗算を含む明示的な対応 operator は B0 の一部です。#637 と #681 を参照してください。B1 composition redesign に割り当て済みのバージョンや日付はありません。
Histogram の算術演算#
Histogram の数値算術 (+, -, *, /, **、reflected / in-place 版) と直接 NumPy ufunc routing は、意図的に TypeError で fail-closed します。bin compatibility、count / weighted / density の意味論、uncertainty propagation が定義されるまで、bin geometry と histogram metadata を保護するためです。
これは現在の安全契約であり、v0.2.0 の silent-corruption bug ではありません。既存の histogram 専用操作を使用し、bin や uncertainty metadata を意図的に捨てる場合にだけ raw value へ変換してください。安全化は #579 に記録されています。
実験 I/O における時刻解釈#
WIN/WIN32#
WIN/WIN32 の calendar field はファイルフォーマット上 timezone-naive です。現在の reader は明示的な warning を出したうえで UTC として解釈しますが、public timezone= 契約はまだありません。そのため、別の civil timezone で記録されたデータを扱うには外部情報と注意が必要です。#632 で追跡しています。
数値 CSV timestamp#
数値 CSV timestamp は従来どおり GPS 秒として解釈されます。GPS、Unix、relative timestamp を明示する time_scale= / time_unit= 契約はまだ実装されていません。数値の大きさだけから別の epoch や unit を推定しないでください。#634 で追跡しています。
Broadcast Wave timestamp#
通常の WAV 入力には、呼び出し側が epoch= を与えない限り絶対ファイル時刻はありません。BWF の OriginationDate、OriginationTime、TimeReference は timezone を特定できないため、GWexpy はまだこれらを絶対 epoch へ昇格させません。#636 で追跡しています。
GWF parallel read の対応範囲#
v0.2.0 は単一の local frame path に対して spawn-safe な parallel= read を提供します。multi-worker read は、意味論を推測する代わりに cache、URI/composite source 表現、未対応の nested execution を拒否します。multi-file streaming merge と残る peak-memory / scalability 対応は未完了です。#588 で追跡しています。
非常に大きな multi-file read では、parallel>1 が bounded-memory streaming を意味すると仮定しないでください。nproc= は引き続き parallel= の compatibility alias です。
NDScope HDF5 dataset creation option#
NDScope HDF5 writer は未対応の dataset-option 経路を fail-closed で検証しますが、v0.2.0 ではこの writer を通じた一般的な HDF5 chunking、compression、shuffle、checksum、任意の dataset-creation option の指定は提供していません。任意の writer kwargs が h5py.create_dataset() に転送されるとは仮定しないでください。#590 で追跡しています。
v0.2.0 の意図的な境界#
coupling v1 schema には
significanceを含みません。import gwexpyは lazy bootstrap を使用します。これは機能欠落ではありません。gwexpy.register_all()は full supported surface を明示的に登録し、対応する public I/O entry point は必要な handler を on demand で登録できます。将来の Field I/O、eager/advanced SegmentTable workflow、spatial geometry、mesh support、Fisher/modeling は roadmap 項目であり、v0.2.0 の regression ではありません。
regression の報告#
v0.2.0 で対応済みと文書化された挙動が、誤った値や単位、metadata/provenance の欠落、silent downgrade を生じる場合は bug として報告してください。v0.2.x の patch release は regression と correctness defect のために予約されており、新しい public API は minor release の作業です。