パラメータ調整

このガイドでは、kazunoko のイベント読み込みパラメータの意味と最適な調整方法を説明します。

---

パラメータの種類

kazunoko で調整可能なパラメータは以下の 3 つです。

パラメータ	役割	デフォルト	範囲
poll_count	バッファをスキャンする回数	10	1 ～ 65535
event_timeout	イベント受信のタイムアウト時間	5.0 秒	0.1 ～ 300 秒
threshold	イベント検出の感度	チャネル依存	0 ～ 4095

---

poll_count（ポーリング数）

意味

poll_count は、デバイスのメモリバッファを何回スキャンするかを指定します。

イベント読み込みの流れ：

PC が READ コマンド送信
  ↓
デバイスがメモリバッファをスキャン
  ↓ poll_count 回繰り返す
  ↓
データを集約して返送

poll_count の影響

poll_count	特性
小さい (100-1000)	✓ 高速 だが ✗ イベント取りこぼし
中程度 (10000-50000)	✓ バランス型（推奨）
大きい (65535)	✓ 確実 だが ✗ 遅い

選択基準

目的: 高速読み込み → poll_count を小さくする（1000-5000）
目的: 確実な読 込み → poll_count を大きくする（50000-65535）
目的: バランス → 中程度の値（10000-50000）

実験で最適値を探す

# 異なる poll_count での成功率を比較
for poll_count in 1000 10000 50000 65535; do
  echo "=== poll_count=$poll_count ==="
  success=0
  total=10

  for run in $(seq 1 $total); do
    count=$(uv run kazunoko read 100 --poll-count $poll_count | wc -l)
    if [ $count -eq 100 ]; then
      success=$((success + 1))
    fi
  done

  echo "Success rate: $(( success * 100 / total ))%"
  echo
done

出力例:

=== poll_count=1000 ===
Success rate: 70%   (高速だが不安定)

=== poll_count=10000 ===
Success rate: 95%   (バランス)

=== poll_count=50000 ===
Success rate: 100%  (確実だが遅い)

=== poll_count=65535 ===
Success rate: 100%  (最も確実だが最も遅い)

推奨設定

用途別:

# スクリーニング実験（高速が重要）
uv run kazunoko read 1000 --poll-count 1000

# 標準的な測定
uv run kazunoko read 10000 --poll-count 50000

# 長時間測定（確実性重視）
uv run kazunoko read 100000 --poll-count 65535

---

event_timeout（イベントタイムアウト）

意味

event_timeout は、1 つのイベント受信を待つ最大時間です。

READ コマンド送信
  ↓
イベント待機開始
  ↓ event_timeout 秒まで待つ
  ↓
- タイムアウト内にイベント到着 → 返送
- タイムアウト超過 → スキップ

event_timeout の影響

event_timeout	特性
短い (0.1-1.0 秒)	✓ 高速 だが ✗ スキップが多い
標準 (5.0 秒)	✓ バランス型（推奨）
長い (10.0-30.0 秒)	✓ スキップ少ない だが ✗ 遅い

選択基準

イベント検出が確実 → タイムアウトを短縮（1-3 秒）
標準的な測定環境 → デフォルト（5.0 秒）
ミューオンが少ない環境 → タイムアウト延長（10-30 秒）

イベント検出の可能性を計算

タイムアウト内にイベントが到着する確率を見積もります。

タイムアウト時間内のイベント到着確率 ≈ 既知の事象検出率 × タイムアウト時間

例：
事象検出率 = 1 イベント / 10 秒
タイムアウト = 5 秒の場合
→ 到着確率 ≈ 50%（不足）

タイムアウト = 10 秒の場合
→ 到着確率 ≈ 100%（十分）

実験で最適値を探す

# 異なる event_timeout でのスキップ率を比較
for timeout in 1.0 2.0 5.0 10.0; do
  echo "=== event_timeout=$timeout ==="
  uv run kazunoko read 100 --event-timeout $timeout | wc -l
  echo
done

出力例:

=== event_timeout=1.0 ===
67      (スキップが多い)

=== event_timeout=2.0 ===
82      (やや多い)

=== event_timeout=5.0 ===
95      (標準)

=== event_timeout=10.0 ===
100     (確実)

推奨設定

用途別:

# 高速測定（スキップ許容）
uv run kazunoko read 100 --event-timeout 1.0

# 標準的な測定
uv run kazunoko read 100 --event-timeout 5.0

# 長時間測定（確実性重視）
uv run kazunoko read 100 --event-timeout 10.0

# ミューオンが少ない環境
uv run kazunoko read 100 --event-timeout 30.0

---

Threshold（スレッショルド値）

意味

threshold は、ミューオン検出の感度を設定します。

センサーの信号強度

スレッショルド値より上 → イベント検出 ✓
スレッショルド値より下 → ノイズとして除外 ✗

スレッショルド値の影響

スレッショルド	特性
低い (100-200)	✓ イベント多い だが ✗ ノイズも増加
標準 (250-320)	✓ バランス型（推奨）
高い (350-500)	✓ ノイズ少ない だが ✗ イベント検出減

スレッショルド値の目安

Ch1: 250-300   （推奨: 280）
Ch2: 300-350   （推奨: 320）
Ch3: 270-320   （推奨: 290）

※ デバイスやセンサーによって異なる

スレッショルドスキャン（最適値探索）

異なるスレッショルド値でのイベント数を測定します。

# 5 ステップでスキャン
for threshold in 200 250 300 350 400; do
  echo "Threshold: $threshold"
  count=$(uv run kazunoko measure "1:$threshold;2:$threshold;3:$threshold" 100 | wc -l)
  echo "Events: $count"
  echo
done

出力例:

Threshold: 200
Events: 98     (低い → イベント多い)

Threshold: 250
Events: 95

Threshold: 300
Events: 85

Threshold: 350
Events: 45

Threshold: 400
Events: 12     (高い → イベント少ない)

スレッショルド最適化ワークフロー

1. 現在のスレッショルドを確認
   uv run kazunoko status | grep threshold

2. スレッショルドスキャンを実行
   複数の値でイベント数を測定

3. 目標イベント数に対応するスレッショルドを選択
   例：100 イベント必要 → スレッショルド 280-300

4. 選択したスレッショルドで再度実験
   uv run kazunoko measure "1:280;2:300;3:290" 100

チャネル別スレッショルド調整

3 つのチャネルが異なる感度を持つ場合があります。

# チャネル別に調整
uv run kazunoko measure "1:250;2:320;3:280" 100

# または、セットコマンドで設定
uv run kazunoko threshold 1 250
uv run kazunoko threshold 2 320
uv run kazunoko threshold 3 280

---

パラメータの組み合わせ

複数のパラメータを同時に調整することで、より良い結果が得られます。

組み合わせの例

シナリオ 1: 高速測定が必要

uv run kazunoko read 1000 \
  --poll-count 1000 \
  --event-timeout 1.0

特徴: 短時間で完了
デメリット: スキップが多い可能性
推奨用途: 事前スクリーニング

シナリオ 2: 標準的な測定

uv run kazunoko measure "1:280;2:300;3:290" 10000 \
  --poll-count 50000 \
  --event-timeout 5.0

特徴: バランス型
推奨用途: 通常の測定

シナリオ 3: 確実で詳細な測定

uv run kazunoko measure "1:250;2:280;3:270" 100000 \
  --poll-count 65535 \
  --event-timeout 10.0

特徴: ほぼ完全な検出
デメリット: 時間がかかる
推奨用途: 精密な物理測定

---

パラメータ調整の手順

ステップ 1: 現在の設定を確認

uv run kazunoko status
uv run kazunoko version

ステップ 2: スレッショルドを最適化

# スレッショルドスキャンを実行
for th in 200 250 280 300 320; do
  count=$(uv run kazunoko measure "1:$th;2:$th;3:$th" 50 | wc -l)
  echo "$th: $count events"
done

# 目標イベント数に対応するスレッショルドを選択

ステップ 3: poll_count を最適化

# 選択したスレッショルドで poll_count をテスト
uv run kazunoko measure "1:280;2:300;3:290" 100 --poll-count 1000
uv run kazunoko measure "1:280;2:300;3:290" 100 --poll-count 10000
uv run kazunoko measure "1:280;2:300;3:290" 100 --poll-count 50000

# 最適な poll_count を選択

ステップ 4: event_timeout を最適化

# 選択したパラメータで event_timeout をテスト
uv run kazunoko measure "1:280;2:300;3:290" 100 \
  --poll-count 10000 \
  --event-timeout 1.0

uv run kazunoko measure "1:280;2:300;3:290" 100 \
  --poll-count 10000 \
  --event-timeout 5.0

# 最適な event_timeout を選択

ステップ 5: 本測定を実行

# 確定したパラメータで本測定
uv run kazunoko measure "1:280;2:300;3:290" 10000 \
  --poll-count 10000 \
  --event-timeout 5.0 \
  --verbose

---

パラメータ調整のトラブルシューティング

スキップが多い

原因: event_timeout が短い、スレッショルド値が高い

対応:
1. event_timeout を延長（5.0 → 10.0 秒）
2. スレッショルド値を下げる（300 → 250）
3. poll_count を増やす（1000 → 50000）

読み込みが遅い

原因: poll_count が大きい、event_timeout が長い

対応:
1. poll_count を減らす（50000 → 1000）
2. event_timeout を短縮（5.0 → 1.0 秒）
3. スレッショルド値を上げる（250 → 300）

ノイズが多い

原因: スレッショルド値が低い

対応:
1. スレッショルド値を上げる（250 → 320）
2. poll_count を増やす（検出を詳細にスキャン）

---

環境別の推奨設定

高エネルギーミューオンビーム施設

# イベント検出が確実
uv run kazunoko measure "1:280;2:300;3:290" 100000 \
  --poll-count 1000 \
  --event-timeout 0.5

地上での宇宙線測定

# 標準的なセットアップ
uv run kazunoko measure "1:280;2:300;3:290" 10000 \
  --poll-count 50000 \
  --event-timeout 5.0

ノイズが多い環境

# ノイズを除去、確実な検出
uv run kazunoko measure "1:320;2:340;3:320" 1000 \
  --poll-count 65535 \
  --event-timeout 10.0

---

パラメータ設定の記録

最適値が決定したら、ノートに記録してください。

=== 測定設定 ===
日付: 2024-12-27
場所: 実験室 A
デバイス MAC: AA:BB:CC:DD:EE:FF

Parameters:
  - threshold_ch1: 280
  - threshold_ch2: 300
  - threshold_ch3: 290
  - poll_count: 50000
  - event_timeout: 5.0

Result:
  - Events/100 requests: 95 (95% success rate)
  - Avg. time: 45 seconds

---

次のステップ

• デバッグモード - 詳細なパラメータ分析
• パフォーマンスの問題 - パラメータ調整によるパフォーマンス改善
• データ品質の確認 - パラメータ調整後のデータ検証