deploy: 7f8a6b4

Author: shima004

_sources/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
 ```
 

_sources/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} 方針のヒント

_sources/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

_sources/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` は、開発時に使用する設定ファイルです。

_sources/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` というモジュールを指定しています。

hands-on/clustering.html

@@ -395,11 +395,13 @@ <h2>クラスタリングモジュールの実装<a class="headerlink" href="#id
         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
             <span class="n">agent_info</span><span class="p">,</span> <span class="n">world_info</span><span class="p">,</span> <span class="n">scenario_info</span><span class="p">,</span> <span class="n">module_manager</span><span class="p">,</span> <span class="n">develop_data</span>
         <span class="p">)</span>
+        <span class="c1"># ロガーの取得</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_logger</span> <span class="o">=</span> <span class="n">get_logger</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
 
         <span class="c1"># クラスター数の設定</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_cluster_number</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span>
         <span class="k">match</span> <span class="n">agent_info</span><span class="o">.</span><span class="n">get_myself</span><span class="p">()</span><span class="o">.</span><span class="n">get_urn</span><span class="p">():</span>
+            <span class="c1"># エージェントのクラスに応じてクラスター数を設定</span>
             <span class="k">case</span> <span class="n">EntityURN</span><span class="o">.</span><span class="n">AMBULANCE_TEAM</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_cluster_number</span> <span class="o">=</span> <span class="n">scenario_info</span><span class="o">.</span><span class="n">get_value</span><span class="p">(</span>
                     <span class="n">ScenarioInfoKeys</span><span class="o">.</span><span class="n">SCENARIO_AGENTS_AT</span><span class="p">,</span>
@@ -597,6 +599,7 @@ <h2>クラスタリングモジュールの実装<a class="headerlink" href="#id
 <span class="sd">        np.ndarray</span>
 <span class="sd">            エージェントとクラスターの対応付け結果</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="c1"># エージェントの位置のリストを取得</span>
         <span class="n">agent_positions</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span>
             <span class="p">[</span>
                 <span class="p">[</span><span class="n">agent</span><span class="o">.</span><span class="n">get_x</span><span class="p">(),</span> <span class="n">agent</span><span class="o">.</span><span class="n">get_y</span><span class="p">()]</span>
@@ -605,10 +608,12 @@ <h2>クラスタリングモジュールの実装<a class="headerlink" href="#id
             <span class="p">]</span>
         <span class="p">)</span>
 
+        <span class="c1"># エージェントとクラスターの距離行列を計算</span>
         <span class="n">agent_positions</span> <span class="o">=</span> <span class="n">agent_positions</span><span class="o">.</span><span class="n">reshape</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
         <span class="n">cost_matrix</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span>
             <span class="n">agent_positions</span><span class="p">[:,</span> <span class="n">np</span><span class="o">.</span><span class="n">newaxis</span><span class="p">]</span> <span class="o">-</span> <span class="n">cluster_positions</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">2</span>
         <span class="p">)</span>
+        <span class="c1"># ハンガリアンアルゴリズムによりエージェントとクラスターの対応付けを行う</span>
         <span class="n">_</span><span class="p">,</span> <span class="n">col_ind</span> <span class="o">=</span> <span class="n">linear_sum_assignment</span><span class="p">(</span><span class="n">cost_matrix</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">col_ind</span>
 </pre></div>
@@ -643,7 +648,7 @@ <h2>クラスタリングモジュールの実装<a class="headerlink" href="#id
 </pre></div>
 </div>
 <p>このままだと、クラスタリング結果がわかりにくいので、クラスタリング結果を地図上に表示してみましょう。</p>
-<p><a class="reference download internal" download="" href="../_downloads/3a5f9008a07336d7227e96be15803593/cluster_plot.zip"><code class="xref download docutils literal notranslate"><span class="pre">クラスターの可視化用スクリプト</span></code></a>をダウンロードして解凍し、<code class="docutils literal notranslate"><span class="pre">main.py</span></code>の以下の部分に</p>
+<p><a class="reference download internal" download="" href="../_downloads/3a5f9008a07336d7227e96be15803593/cluster_plot.zip"><code class="xref download docutils literal notranslate"><span class="pre">クラスターの可視化用スクリプト</span></code></a>をダウンロードして解凍し、中の<code class="docutils literal notranslate"><span class="pre">main.py</span></code>の以下の部分に</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># クラスタリング結果</span>
 <span class="n">clusters</span> <span class="o">=</span> <span class="p">[]</span>
 </pre></div>
@@ -655,7 +660,8 @@ <h2>クラスタリングモジュールの実装<a class="headerlink" href="#id
 </pre></div>
 </div>
 <p>貼り付けたら、以下のコマンドを実行してください。</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>main.py
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt
+python<span class="w"> </span>main.py
 </pre></div>
 </div>
 <p>以下のような画像が出力されます。</p>

hands-on/search.html

@@ -453,7 +453,8 @@ <h2>モジュールの実装<a class="headerlink" href="#id5" title="Link to thi
         <span class="bp">self</span><span class="o">.</span><span class="n">register_sub_module</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_clustering</span><span class="p">)</span>
 </pre></div>
 </div>
-<p>そして、<code class="docutils literal notranslate"><span class="pre">calculate</span></code> メソッドでクラスタリングモジュールを呼び出し、探索対象を決定します。</p>
+<p>そして、<code class="docutils literal notranslate"><span class="pre">calculate</span></code> メソッドでクラスタリングモジュールを呼び出し、探索対象を決定するように変更します。</p>
+<p>以下のコードを <code class="docutils literal notranslate"><span class="pre">k_means_pp_search.py</span></code> に追記してください。</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span>    <span class="k">def</span> <span class="nf">calculate</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Search</span><span class="p">:</span>
         <span class="c1"># 自エージェントのエンティティIDを取得</span>
         <span class="n">me</span><span class="p">:</span> <span class="n">EntityID</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_agent_info</span><span class="o">.</span><span class="n">get_entity_id</span><span class="p">()</span>
@@ -467,6 +468,9 @@ <h2>モジュールの実装<a class="headerlink" href="#id5" title="Link to thi
         <span class="k">if</span> <span class="n">cluster_entity_ids</span><span class="p">:</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_result</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">cluster_entity_ids</span><span class="p">)</span>
 
+        <span class="c1"># ログ出力</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Target entity ID: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_result</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+        
         <span class="k">return</span> <span class="bp">self</span>
 </pre></div>
 </div>
@@ -508,6 +512,10 @@ <h2>課題<a class="headerlink" href="#id7" title="Link to this heading">#</a></
 <p class="admonition-title">警告</p>
 <p>ここに上げた問題以外にも、改善すべき点が存在すると思うので、それを改善していただいても構いません。</p>
 </div>
+<div class="admonition warning">
+<p class="admonition-title">警告</p>
+<p>プログラム例のプログラムにも一部問題があるので、余裕があったら修正してみてください。</p>
+</div>
 <section id="id8">
 <h3>探索対象がステップごとに変わってしまう問題<a class="headerlink" href="#id8" title="Link to this heading">#</a></h3>
 <div class="hint dropdown admonition">