マジックナンバー（999/99/9.99等）の定数化と用途・設計意図の明文化

[t-uda]

概要

tda_ml モジュール内で各所にハードコードされているマジックナンバー (999.0, 99.0, 9.99 など) を全て定数化し、意味や用途ごとの意図をソースコードおよびdocstring/コメント内で明記するリファクタタスクのためのissueです。

目的

• 可読性の向上（後からコードを読んだ人が混乱しないように）
• ヒューマンエラー防止（異なる値の混同や並存を防ぐ）
• 保守容易性の向上（値の変更やポリシー決定をグローバルに行えるように）

詳細

• 以下の値をはじめとするマジックナンバーについて、用途ごとに定数名を厳密に決め、すべて定数として管理する：
  • 999.0（Wasserstein距離での空入力）
  • 99.0（Bottleneck距離での空入力）
  • 9.99（メトリクス集計での空inlier検出時）
• それぞれの値がどのような失敗ケース・意味づけで使われているかをdocstringやコメント等に明記する。
• ポリシーとして「マジックナンバー禁⽌」「必要なら値の統一を検討」も合わせて議論する。
• 関連するテスト（ユニットテスト）があれば定数へ追従させる。

関連

• PR #56
• 過去IssueやPRに類似実装・議論がないかも要調査

備考

• 定数配置は constants.py などの専用モジュールを作ることも検討
• 定数名、docstring文言は開発メンバー間で納得のいくものにする

---

#59 終了後に残っている「正則化・安定化のための微小正定数」も全て意図の明らかな定数名を割り当ててください

[koki3070]

進捗（Human Note 以外）

W-Dist センチネル（999.0 / 99.0 / 9.99）を廃止し、空予測 inlier を含め Gudhi の H₁ 1-Wasserstein（order=1, internal_p=2）に統一しました。issue 本文の「定数化」ではなく、OT 距離として数学的に定義される方針で実装しています。

変更概要

• tda_ml/persistence.py: 空点群時の早期 return（999/99/0）を削除
• tda_ml/metrics.py: empty_pred_wdist 引数と 9.99 分岐を削除し、常に compute_w_distance 経由
• tests/test_persistence.py 新規、tests/test_metrics.py 更新

ブランチ・検証

• ブランチ: fix/issue60-wdist-real-wasserstein（upstream/main 単独、Follow-up: 正則化・安定化のための ad-hoc 微小正定数の要否をPR 54〜58 マージ後に再検証する #59 とは分離）
• コミット: 29321f6
• uv run pytest → 46 passed

PR 前の注記

• 学習経路（trainer / 位相損失）は未変更のため、MCC/G-Mean の再学習検証は不要と判断
• 旧センチネル（9.99 等）との W-Dist 数値非互換あり（定義変更）。再評価・REPRODUCIBILITY.md 追記は PR / follow-up で対応予定
• issue 備考の微小正定数（persistence.py の 1e-6 等）は Follow-up: 正則化・安定化のための ad-hoc 微小正定数の要否をPR 54〜58 マージ後に再検証する #59（PR fix: issue #59 — ad-hoc 微小正定数の整理と論文外モデリング床の削除 #62）側 / follow-up 扱い

PR 作成準備済みです。