fix: Improve documentation with additional comments and examples for clustering and search modules

Author: shima004

docs/source/hands-on/clustering.md

@@ -69,11 +69,13 @@ class KMeansPPClustering(Clustering):
         super().__init__(
             agent_info, world_info, scenario_info, module_manager, develop_data
         )
+        # ロガーの取得
         self._logger = get_logger(f"{self.__class__.__name__}")
 
         # クラスター数の設定
         self._cluster_number: int = 1
         match agent_info.get_myself().get_urn():
+            # エージェントのクラスに応じてクラスター数を設定
             case EntityURN.AMBULANCE_TEAM:
                 self._cluster_number = scenario_info.get_value(
                     ScenarioInfoKeys.SCENARIO_AGENTS_AT,
@@ -271,6 +273,7 @@ class KMeansPPClustering(Clustering):
         np.ndarray
             エージェントとクラスターの対応付け結果
         """
+        # エージェントの位置のリストを取得
         agent_positions = np.array(
             [
                 [agent.get_x(), agent.get_y()]
@@ -279,10 +282,12 @@ class KMeansPPClustering(Clustering):
             ]
         )
 
+        # エージェントとクラスターの距離行列を計算
         agent_positions = agent_positions.reshape(-1, 2)
         cost_matrix = np.linalg.norm(
             agent_positions[:, np.newaxis] - cluster_positions, axis=2
         )
+        # ハンガリアンアルゴリズムによりエージェントとクラスターの対応付けを行う
         _, col_ind = linear_sum_assignment(cost_matrix)
         return col_ind
 ```
@@ -329,7 +334,7 @@ python main.py
 
 このままだと、クラスタリング結果がわかりにくいので、クラスタリング結果を地図上に表示してみましょう。
 
-{download}`クラスターの可視化用スクリプト <./../download/cluster_plot.zip>`をダウンロードして解凍し、`main.py`の以下の部分に
+{download}`クラスターの可視化用スクリプト <./../download/cluster_plot.zip>`をダウンロードして解凍し、中の`main.py`の以下の部分に
 
 ```python
 # クラスタリング結果
@@ -348,6 +353,7 @@ clusters = [[257, 259, 262, 263, 270, 278, 280, 297, 336, 913, 914, 915, 916, 91
 貼り付けたら、以下のコマンドを実行してください。
 
 ```bash
+pip install -r requirements.txt
 python main.py
 ```
 

docs/source/hands-on/search.md

@@ -125,7 +125,9 @@ class KMeansPPSearch(Search):
         self.register_sub_module(self._clustering)
 ```
 
-そして、`calculate` メソッドでクラスタリングモジュールを呼び出し、探索対象を決定します。
+そして、`calculate` メソッドでクラスタリングモジュールを呼び出し、探索対象を決定するように変更します。
+
+以下のコードを `k_means_pp_search.py` に追記してください。
 
 ```python
     def calculate(self) -> Search:
@@ -141,6 +143,9 @@ class KMeansPPSearch(Search):
         if cluster_entity_ids:
             self._result = random.choice(cluster_entity_ids)
         
+        # ログ出力
+        self._logger.info(f"Target entity ID: {self._result}")
+        
         return self
 ```
 
@@ -185,6 +190,10 @@ python main.py
 ここに上げた問題以外にも、改善すべき点が存在すると思うので、それを改善していただいても構いません。
 ```
 
+```{warning}
+プログラム例のプログラムにも一部問題があるので、余裕があったら修正してみてください。
+```
+
 ### 探索対象がステップごとに変わってしまう問題
 
 ```{admonition} 方針のヒント

docs/source/tutorial/agent/agent_control.md

@@ -235,20 +235,19 @@ my_entity_id: EntityID = self._agent_info.get_entity_id()
 ```python
 from typing import Optional
 
-from rcrs_core.worldmodel.entityID import EntityID
-from rcrs_core.entities.civilian import Civilian
-from rcrs_core.entities.entity import Entity
-
 from adf_core_python.core.agent.develop.develop_data import DevelopData
 from adf_core_python.core.agent.info.agent_info import AgentInfo
 from adf_core_python.core.agent.info.scenario_info import ScenarioInfo
 from adf_core_python.core.agent.info.world_info import WorldInfo
 from adf_core_python.core.agent.module.module_manager import ModuleManager
 from adf_core_python.core.component.module.complex.human_detector import HumanDetector
 from adf_core_python.core.logger.logger import get_agent_logger
+from rcrs_core.entities.civilian import Civilian
+from rcrs_core.entities.entity import Entity
+from rcrs_core.worldmodel.entityID import EntityID
 
 
-class SampleHumanDetector(HumanDetector):
+class FireBrigadeHumanDetector(HumanDetector):
     def __init__(
         self,
         agent_info: AgentInfo,
@@ -271,44 +270,56 @@ class SampleHumanDetector(HumanDetector):
     def calculate(self) -> HumanDetector:
         """
         行動対象を決定する
-        
+
         Returns
         -------
             HumanDetector: 自身のインスタンス
         """
+        # 自分自身のEntityIDを取得
         me: EntityID = self._agent_info.get_entity_id()
+        # すべてのCivilianを取得
         civilians: list[Entity] = self._world_info.get_entities_of_types(
             [
                 Civilian,
             ]
         )
-        
+
+        # 最も近いCivilianを探す
         nearest_civilian: Optional[EntityID] = None
         nearest_distance: Optional[float] = None
         for civilian in civilians:
+            # civilianがCivilianクラスのインスタンスでない場合はスキップ
             if not isinstance(civilian, Civilian):
                 continue
-            
+
+            # civilianのHPが0以下の場合はすでに死んでしまっているのでスキップ
             if civilian.get_hp() <= 0:
                 continue
-            
+
+            # civilianの埋没度が0以下の場合は掘り起こす必要がないのでスキップ
             if civilian.get_buriedness() <= 0:
                 continue
-            
+
+            # 自分自身との距離を計算
             distance: float = self._world_info.get_distance(me, civilian.get_id())
-            
+
+            # 最も近いCivilianを更新
             if nearest_distance is None or distance < nearest_distance:
                 nearest_civilian = civilian.get_id()
                 nearest_distance = distance
-        
+
+        # 計算結果を格納
         self._result = nearest_civilian
 
+        # ロガーに出力
+        self._logger.info(f"Target: {self._result}")
+
         return self
 
     def get_target_entity_id(self) -> Optional[EntityID]:
         """
         行動対象のEntityIDを取得する
-        
+
         Returns
         -------
             Optional[EntityID]: 行動対象のEntityID

docs/source/tutorial/config/config.md

@@ -24,6 +24,15 @@
 読み込むモジュールのパスなどが記述されています。
 パスを指定する際は、プロジェクトの`main.py`からの相対パスで指定してください。
 
+```{admonition} 例
+:class: note
+
+```yaml
+DefaultSearch:
+    PathPlanning: src.<your_team_name>.module.complex.sample_search.SampleSearch
+    Clustering: src.<your_team_name>.module.complex.sample_search.SampleClustering
+```
+
 ### development.json
 
 `development.json` は、開発時に使用する設定ファイルです。

docs/source/tutorial/module/module.md

@@ -8,8 +8,8 @@
 
 ```yaml
 SampleSearch:
-    PathPlanning: src.my-agent.module.complex.sample_search.SampleSearch
-    Clustering: src.my-agent.module.complex.sample_search.SampleClustering
+    PathPlanning: src.<your_team_name>.module.complex.sample_search.SampleSearch
+    Clustering: src.<your_team_name>.module.complex.sample_search.SampleClustering
 ```
 
 この場合、`SampleSearch` というモジュールで使用される、`PathPlanning` と `Clustering` というモジュールを指定しています。