swarm_engine_core/exploration/selection/
mod.rs

1//! Selection - ノード選択アルゴリズム
2//!
3//! # 設計思想: TypeAliasPolicyPattern
4//!
5//! 各 Selection アルゴリズムは独立した struct として実装され、
6//! `SelectionLogic` trait を実装する。
7//!
8//! - **ロジックの分離**: 各アルゴリズムの実装が独立
9//! - **型による制約**: Operator の型パラメータで組み合わせを制約可能
10//! - **Config 連携**: `SelectionKind` enum で Config/serde 対応
11//! - **動的切り替え**: `AnySelection` で enum dispatch による動的ディスパッチ
12//!
13//! # 統計情報
14//!
15//! Selection アルゴリズムは `SwarmStats`（collector/stats.rs）を Single Source of Truth
16//! として使用する。各メソッドは `&SwarmStats` を引数に取り、アクション統計を参照する。
17//!
18//! # モジュール構成
19//!
20//! | モジュール | 内容 |
21//! |-----------|------|
22//! | `stats` | `NodeStats`（後方互換） |
23//! | `kind` | Selection の種類（`SelectionKind` enum） |
24//! | `fifo` | FIFO 選択 |
25//! | `ucb1` | UCB1 選択 |
26//! | `greedy` | Greedy 選択 |
27//! | `thompson` | Thompson Sampling 選択 |
28//! | `any` | 動的選択ラッパー（`AnySelection`） |
29//!
30//! # 使用例
31//!
32//! ```ignore
33//! use swarm_engine_core::exploration::selection::{Fifo, Ucb1, SelectionLogic};
34//!
35//! // 静的型付け（コンパイル時に Selection が決定）
36//! let fifo = Fifo::new();
37//! let ucb1 = Ucb1::new(1.41);
38//!
39//! // 動的切り替え（実行時に Selection を変更可能）
40//! let any = AnySelection::from_kind(SelectionKind::Ucb1, 1.41);
41//! ```
42
43mod any;
44mod fifo;
45mod greedy;
46mod kind;
47mod stats;
48mod thompson;
49mod ucb1;
50
51use std::fmt::Debug;
52
53use crate::exploration::map::{GraphMap, MapNodeId, MapState};
54use crate::learn::LearnedProvider;
55use crate::online_stats::SwarmStats;
56
57// ============================================================================
58// Re-exports
59// ============================================================================
60
61// Stats (SwarmStats を使用、NodeStats は後方互換のため残す)
62pub use stats::NodeStats;
63
64// Kind
65pub use kind::SelectionKind;
66
67// Selection implementations
68pub use fifo::Fifo;
69pub use greedy::Greedy;
70pub use thompson::Thompson;
71pub use ucb1::Ucb1;
72
73// Dynamic wrapper
74pub use any::AnySelection;
75
76// ============================================================================
77// SelectionLogic trait
78// ============================================================================
79
80/// ノード選択ロジック
81///
82/// 次に探索するノードを選択する責務を持つ。
83/// SwarmStats を参照してスコアベースの選択が可能。
84///
85/// # 実装者向け
86///
87/// - `next()`: 1ノード選択（デフォルト実装あり）
88/// - `select()`: 複数ノード選択（必須）
89/// - `score()`: スコア計算（デバッグ/可視化用）
90/// - `name()`: アルゴリズム名
91pub trait SelectionLogic<N, E, S>: Send + Sync
92where
93    N: Debug + Clone,
94    E: Debug + Clone,
95    S: MapState,
96{
97    /// 次のノードを1つ選択
98    fn next(
99        &self,
100        map: &GraphMap<N, E, S>,
101        stats: &SwarmStats,
102        provider: &dyn LearnedProvider,
103    ) -> Option<MapNodeId>;
104
105    /// 次のノードを複数選択
106    fn select(
107        &self,
108        map: &GraphMap<N, E, S>,
109        count: usize,
110        stats: &SwarmStats,
111        provider: &dyn LearnedProvider,
112    ) -> Vec<MapNodeId>;
113
114    /// ノードのスコアを計算
115    fn score(
116        &self,
117        action: &str,
118        target: Option<&str>,
119        stats: &SwarmStats,
120        provider: &dyn LearnedProvider,
121    ) -> f64;
122
123    /// 名前
124    fn name(&self) -> &str;
125}
126
127// ============================================================================
128// Legacy Aliases (後方互換性)
129// ============================================================================
130
131/// FifoSelection の別名（後方互換）
132pub type FifoSelection = Fifo;
133
134/// Ucb1Selection の別名（後方互換）
135pub type Ucb1Selection = Ucb1;
136
137/// GreedySelection の別名（後方互換）
138pub type GreedySelection = Greedy;
139
140/// ThompsonSelection の別名（後方互換）
141pub type ThompsonSelection = Thompson;
swarm_engine_core/exploration/selection/mod.rs

swarm_engine_core/exploration/selection/
mod.rs
