数値的安定性と精度

gwexpy は、重力波データ解析で頻繁に扱われる極めて広いダイナミックレンジを持つデータを処理できるように設計されています。重力波のひずみ信号（strain）は典型的には \(10^{-21}\) のオーダーですが、中間処理では 1 に近い値を扱うこともあります。

科学的な正確性を保証し、数値的なアーティファクト（”Death Floats” や信号消失など）を防ぐため、gwexpy は堅牢な数値安定化戦略を実装しています。

主な機能

1. アダプティブ・ホワイトニング (Adaptive Whitening)

標準的なホワイトニングアルゴリズムは、ゼロ除算を防ぐために固定の正規化パラメータ（eps）を使用することがよくあります。このパラメータが大きすぎる（例: 1e-12）と、物理的に意味のある微小な信号（\(10^{-21}\) のひずみなど）が埋もれてしまう可能性があります。

問題: 単純なホワイトニングは失敗する可能性がある

from gwexpy.timeseries import TimeSeries
import numpy as np

# ❌ 悪い例: 適切な正規化なしの手動ホワイトニング
data = TimeSeries(np.random.randn(1000) * 1e-21, sample_rate=1024)
asd = data.asd()
whitened = data / asd  # 危険: ゼロに近い値での除算が発生する可能性

解決策: GWexpyのアダプティブ・ホワイトニングを使用

gwexpy は、データのスケールに合わせて正規化パラメータを自動的に調整します：

eps の自動スケーリング: 正規化フロアは入力データの分散に対して相対的に計算されます。
安全フロア: 極めて静かなデータやゼロ埋めされた領域でも特異点が発生しないよう、最小フロア（SAFE_FLOOR = 1e-50）が設定されています。

# ✅ 良い例: GWexpyの安全なホワイトニング
data = TimeSeries(np.random.randn(1000) * 1e-21, sample_rate=1024)
whitened = data.whiten(eps="auto")  # 自動的に適切な正規化を処理

2. 堅牢な独立成分分析 (Robust ICA)

ICA による分離は、数値的に安定した方法で実行されます：

内部標準化: データは FastICA アルゴリズムに渡される前に内部的に単位分散に標準化され、入力振幅に関わらず収束条件が満たされるようにします。
相対許容誤差: 収束判定の許容誤差（tolerance）は、データのスケールに対して相対的に定義されます。

3. 安全な対数スケーリング (Safe Logarithmic Scaling)

広いダイナミックレンジを持つデータ（スペクトログラムや PSD など）を可視化する際、データにゼロや極めて小さな値が含まれていると、デシベル（dB）への変換で問題が発生することがあります。

問題: アーティファクトが発生する対数スケールプロット

# ❌ 悪い例: 手動の対数変換は -inf 値を生成する可能性
asd = data.asd()
asd_db = 10 * np.log10(asd)  # 警告: ゼロに近い値で -inf が発生する可能性
plot = asd_db.plot()

解決策: GWexpyの安全なプロット機能を使用

gwexpy は「Safe Log」アプローチを採用しています：

動的フロア: データの最大値と指定されたダイナミックレンジ（デフォルト 200 dB）に基づいて、フロア値が動的に計算されます。
アーティファクトの排除: これにより -inf 値の発生を防ぎ、「無音」部分が白い穴や数値エラーとしてではなく、カラースケールの最下部として正しく描画されます。

# ✅ 良い例: GWexpyは対数スケーリングを安全に処理
asd = data.asd()
plot = asd.plot()  # 可視化のために自動的に安全な対数スケーリングを適用

4. 計算機イプシロンへの配慮

パッケージ全体で使用される数値定数（分散フロア、コヒーレンスの分母など）は、使用されている浮動小数点型（float32 vs float64）の機械精度（イプシロン）に基づいて導出されており、不要なオーバーヘッドなしに最適な精度を保証します。

ユーザーへの推奨事項

手動オフセットの回避: プロットや処理の前に、恣意的な小さな値（例: data + 1e-20）を手動で足す必要はありません。gwexpy の関数が内部で適切に処理します。
デフォルトを信頼する: whiten() や ica_fit() などの関数のデフォルトパラメータは、数値的な安全性を考慮して調整されています。可能な限り eps="auto" や tol="auto" を使用してください。
警告を確認する: 数値的に不安定な操作（例: 定数ゼロのチャンネルのホワイトニング）を行おうとした場合、gwexpy は解決策を示す有益な警告やエラーを出力します。