v1.4.0 (2025-10-29)

v1.4.0 (2025-10-29)#

このリリースは、Spec 021（Threshold Scan Sampler）の大規模リファクタリングを完了した重要なアップデートです。 パラレル・シリアルスキャンの統合、CSV監査ログの強化、ロギング機能の改善により、より堅牢で保守性の高いシステムを実現しました。

✨ v1.4.0 での改善点#

このマイルストーンは、以下を実現します。

  • Threshold Scan Sampler 統合: serial() と parallel() の共通インターフェース化によるコード統一

  • CSV監査ログ強化: attempts フィールド追加により詳細な実行履歴を記録

  • ロギング機能拡張: モジュール・関数・行番号の位置情報を含むデバッグログ

  • エラーハンドリング向上: 割り込み処理対応とエラーマネジメントの強化

  • CLI 最適化: 非推奨オプション削除と SamplerOptions への統一

  • アーキテクチャ整理: 不要な Scanner モジュール削除と API 整理

🎯 User Story 1 - Threshold Writer の強化#

新機能: 包括的なデバッグログと位置情報#

  • ロガー設定の拡張: ログフォーマットにモジュール、関数、行番号を追加

    # 従来:
# INFO: Threshold write succeeded

# v1.4.0:
# INFO [haniwers.v1.threshold.writer:write_threshold:142]: Threshold write succeeded

  • Debug ログの充実: Threshold Writer に包括的なロギングを実装

    • 段階前後のステータス確認

    • リトライ試行の詳細ログ

    • チャネル別の成功/失敗情報

  • 割り込み処理対応: Ctrl+C でスキャン実行中に安全に中断可能

    • スキャン途中の中断を適切にハンドル

    • 部分的な結果を CSVに保存

    • エラーサマリーを表示

CSV 監査ログの詳細化#

  • attempts フィールド追加: 各閾値操作の試行回数を記録

    timestamp,channel,threshold,status,attempts,notes
2025-10-29T10:00:00+00:00,1,280,success,1,"Write successful on first attempt"
2025-10-29T10:00:05+00:00,2,320,success,3,"Required 3 attempts due to communication error"

  • 履歴追跡機能: 何度スキャンを実行しても履歴が保持される

    • マルチラン対応で長期的な実験をサポート

    • 各実行の詳細を CSV で分析可能

🎯 User Story 2 - ThresholdScanResult モデルと Sampler 統合#

統合された結果モデル#

  • ThresholdScanResult モデル: スキャン結果を統一形式で管理

    from haniwers.v1.threshold.model import ThresholdScanResult

# スキャン実行
result = run_parallel_threshold_scan(config, device)

# 統一されたインターフェース
print(f"Success: {result.success}")
print(f"Channels: {result.scanned_channels}")
print(f"Attempts: {result.total_attempts}")
print(f"CSV files: {result.files}")

  • モデル整理: ThresholdResult → ThresholdWriteResult に名前変更

    • 書き込み結果と スキャン結果の区別を明確化

    • API の意図をより正確に表現

  • Sampler との連携: serial() と parallel() が ThresholdScanResult を返却

    • 共通インターフェースで統一的な処理が可能

    • スキャン実行後の結果処理が簡潔に

🎯 User Story 3 - CLI コマンドの整理と最適化#

SamplingOptions への統一#

  • 非推奨オプション削除: SamplingOptions と SamplerModeOptions を廃止

  • SamplerOptions への統一: 単一の統一されたオプションクラスを使用

    • ConfigLoader 統合で TOML ベースの設定が可能に

    • CLI オプションの冗長性を排除

  • SamplerConfig の対称性: 不足していたオプションを追加

    • v1.0 以来の設定パラメータの不均衡を解決

    • スキャンと測定の両方で同じ設定項目を使用可能に

serial() コマンドの簡素化#

# v1.4.0 の改善後
haniwers-v1 threshold serial \
  --thresholds "1:200;2:300;3:250" \
  --config config.toml \
  --duration 5 \
  --nsteps 10

  • 測定ループの再構成: per-sensor scanning を Sampler.run() で実装

    • チャネルごとの独立した測定制御

    • より柔軟なスキャンロジック

🧪 テスト強化#

リファクタリング後の検証#

テストスイート

状態

詳細

v1 ユニットテスト全体

✅ パス

Scanner モジュール削除後も回帰なし

コード品質

✅ Pass

ruff format, pre-commit OK

テストカバレッジ

✅ 80%+

CSV、ロギング、エラーハンドリング対応

削除されたレガシーテスト#

  • Old Scanner test 削除 (~568 LOC):

    • test_serial_threshold_scan.py (parallel mode テスト)

    • test_parallel_threshold_scan.py (serial mode テスト)

    • 非推奨の collect_events() API に依存するテスト

  • 理由: Sampler による統一化により不要になったレガシーテスト

    • 新しい Sampler ベースのテストで十分カバー

🔧 内部実装の改善#

API の削除と整理#

  • 削除された関数:

    • load_thresholds_from_csv(): 非推奨 API

    • run_serial_threshold_scan(): serial.py モジュール削除に伴う廃止

    • 複数の legacy scan 実行関数

  • 削除されたモジュール:

    • src/haniwers/v1/threshold/serial.py: Sampler に統合

    • src/haniwers/v1/threshold/parallel.py: Sampler に統合

    • src/haniwers/v1/helpers/scan_result.py: ScanResultWriter に統合

  • 削除された CLI:

    • scan サブコマンドモジュール: write / serial コマンドに統合

コード改善#

  • Magic Numbers の廃止: プロトコル定数とタイミング定数への置き換え

    # 従来 (threshold/writer.py):
val1 = 0b10000 + (vth >> 6)  # ヘッダビット + 上位3ビット
val2 = (vth << 2) & 0xFF      # 下位8ビット
time.sleep(0.1)               # デバイス安定化待ち
time.sleep(0.5)               # リトライ間隔

# v1.4.0:
PROTOCOL_HEADER_BIT = 0b10000
THRESHOLD_UPPER_BITS_SHIFT = 6
THRESHOLD_LOWER_BITS_SHIFT = 2
BYTE_MASK = 0xFF
DEVICE_STABILIZATION_DELAY = 0.1
RETRY_INTERVAL = 0.5

val1 = PROTOCOL_HEADER_BIT + (vth >> THRESHOLD_UPPER_BITS_SHIFT)
val2 = (vth << THRESHOLD_LOWER_BITS_SHIFT) & BYTE_MASK
time.sleep(DEVICE_STABILIZATION_DELAY)
time.sleep(RETRY_INTERVAL)

  • ログレベルの整理: 過度なデバッグログを削除

    • パフォーマンス向上

    • ログ出力の可読性向上

    • 本当に必要な情報に焦点

  • 関数名の明確化:

    • log_threshold_operation() → write_threshold_to_csv()

    • より正確な関数名で意図を表現

Sampler 統合の成果#

# v1.3.0:
from haniwers.v1.threshold.serial import run_serial_threshold_scan
from haniwers.v1.threshold.parallel import run_parallel_threshold_scan

# v1.4.0: 統一されたインターフェース
from haniwers.v1.threshold.scanner.serial import run_serial_threshold_scan
from haniwers.v1.threshold.scanner.parallel import run_parallel_threshold_scan
# どちらも同じ ThresholdScanResult を返却

📊 Spec 021 実装完了サマリー#

Phase 1-5 の達成#

  1. Phase 1 (計画): Threshold Scan Sampler 設計完了

  2. Phase 2 (実装): device.read_events() から Sampler への置き換え完了

  3. Phase 3 (統合): serial / parallel / write の統一インターフェース化完了

  4. Phase 4 (強化): CSV エクスポート、デバッグログ、エラー処理向上

  5. Phase 5 (最適化): CLI 整理、レガシー API 削除、SamplerOptions 統一

主要な統計#

  • 削除コード: ~1200 LOC (legacy scanner module)

  • 追加テスト: ~200 LOC (Sampler 統合テスト)

  • 実装期間: 2025-08-25 ～ 2025-10-29 (約 2 ヶ月)

  • コミット数: 71 commits

📦 インストール#

pip install haniwers==1.4.0

または最新版：

pip install --upgrade haniwers

🔗 関連リンク#

リリース担当: shotakaha リリース日: 2025-10-29 MR: !106 - feat(threshold): complete Sampler integration and API cleanup (021)

目次