Merge pull request #85 from adf-python/fix/docs/hot-fix

エージェントとサーバーの起動についてとクラスタリングの可視化

Author: shima004

docs/source/download/cluster_plot.zip

@@ -287,6 +287,10 @@ class KMeansPPClustering(Clustering):
         return col_ind
 ```
 
+k-means++の実装は、scikit-learnの`KMeans`クラスを使用しています。`KMeans`クラスは、`n_clusters`で指定したクラスター数によって地図上のオブジェクトをクラスタリングします。クラスタリング結果は、`labels_`属性に格納されます。また、`cluster_centers_`属性には各クラスターの中心座標が格納されます。
+
+hungarianアルゴリズムの実装は、scipyの`linear_sum_assignment`関数を使用しています。`linear_sum_assignment`関数は、コスト行列を引数として受け取り、最適な割り当てを行います。
+
 次に、作成したモジュールを登録します。`config/module.yaml` を以下のように編集してください。
 
 ```yaml
@@ -298,4 +302,55 @@ SampleHumanDetector:
   Clustering: src.<your_team_name>.module.algorithm.k_means_pp_clustering.KMeansPPClustering
 ```
 
-シミュレーションサーバーを起動して、エージェントを起動してください。エージェントが起動すると、標準出力にクラスタリング結果が表示されます。
+ターミナルを2つ起動します。
+
+片方のターミナルを開き、シミュレーションサーバーを以下のコマンドで起動します：
+
+```bash
+# Terminal A
+cd WORKING_DIR/rcrs-server/scripts
+./start-comprun.sh -m ../maps/tutorial_ambulance_team_only/map -c ../maps/tutorial_ambulance_team_only/config
+```
+
+その後、別のターミナルを開き、エージェントを起動します：
+
+```bash
+# Terminal B
+cd WORKING_DIR/<your_team_name>
+python main.py
+```
+
+エージェントが起動すると、標準出力にクラスタリング結果が表示されます。
+
+```bash
+[info     ] Clustered entities: [[257, 259, 262, 263, 270, 278, 280, 297, 336, 913, 914, 915, 916, 917, 918, 919, 933, 941, 942, 943, 944, 945, 946, 947, 974, 250, 253], [349, 896, 899, 902, 934, 960, 968, 969, 970, 971, 248, 251], [258, 266, 268, 269, 274, 275, 279, 920, 921, 922, 923, 924, 925, 926, 927, 928, 929, 932, 948, 949, 950, 951, 952, 953, 954, 955, 956, 957, 958, 959, 975, 976, 254, 255], [256, 271, 273, 281, 296, 298, 314, 330, 903, 904, 905, 910, 911, 912, 935, 936, 937, 938, 939, 940, 247, 249]] [KMeansPPClustering]
+[info     ] Agent cluster indices: [([89544, 19925], 1), ([69989, 120063], 0), ([130029, 50380], 2), ([29898, 59056], 3)] [KMeansPPClustering]
+```
+
+このままだと、クラスタリング結果がわかりにくいので、クラスタリング結果を地図上に表示してみましょう。
+
+{download}`クラスターの可視化用スクリプト <./../download/cluster_plot.zip>`をダウンロードして解凍し、`main.py`の以下の部分に
+
+```python
+# クラスタリング結果
+clusters = []
+```
+
+出力の`Clustered entities: `の後ろの部分の配列をコピーして貼り付けてください。
+
+例
+
+```python
+# クラスタリング結果
+clusters = [[257, 259, 262, 263, 270, 278, 280, 297, 336, 913, 914, 915, 916, 917, 918, 919, 933, 941, 942, 943, 944, 945, 946, 947, 974, 250, 253], [349, 896, 899, 902, 934, 960, 968, 969, 970, 971, 248, 251], [258, 266, 268, 269, 274, 275, 279, 920, 921, 922, 923, 924, 925, 926, 927, 928, 929, 932, 948, 949, 950, 951, 952, 953, 954, 955, 956, 957, 958, 959, 975, 976, 254, 255], [256, 271, 273, 281, 296, 298, 314, 330, 903, 904, 905, 910, 911, 912, 935, 936, 937, 938, 939, 940, 247, 249]]
+```
+
+貼り付けたら、以下のコマンドを実行してください。
+
+```bash
+python main.py
+```
+
+以下のような画像が出力されます。
+
+![クラスタリングの画像](./../images/cluster.png)

docs/source/hands-on/clustering.md

@@ -70,13 +70,13 @@ class KMeansPPSearch(Search):
 
 ```yaml
 DefaultTacticsAmbulanceTeam:
-  Search: src.<team-name>.module.complex.k_means_pp_search.KMeansPPSearch
+  Search: src.<your_team_name>.module.complex.k_means_pp_search.KMeansPPSearch
 
 DefaultTacticsFireBrigade:
-  Search: src.<team-name>.module.complex.k_means_pp_search.KMeansPPSearch
+  Search: src.<your_team_name>.module.complex.k_means_pp_search.KMeansPPSearch
 
 DefaultTacticsPoliceForce:
-  Search: src.<team-name>.module.complex.k_means_pp_search.KMeansPPSearch
+  Search: src.<your_team_name>.module.complex.k_means_pp_search.KMeansPPSearch
 ```
 
 ## モジュールの実装
@@ -87,7 +87,7 @@ DefaultTacticsPoliceForce:
 
 ```yaml
 KMeansPPSearch:
-  Clustering: src.<team-name>.module.algorithm.k_means_pp_clustering.KMeansPPClustering
+  Clustering: src.<your_team_name>.module.algorithm.k_means_pp_clustering.KMeansPPClustering
 ```
 
 次に、`KMeansPPSearch` モジュールで `KMeansPPClustering` モジュールを呼び出せるようにします。
@@ -146,7 +146,23 @@ class KMeansPPSearch(Search):
 
 以上で、`KMeansPPClustering` モジュールを用いた `KMeansPPSearch` モジュールの実装が完了しました。
 
-実行すると、各エージェントが担当地域内からランダムに探索対象を選択し、探索を行います。
+ターミナルを2つ起動します。
+
+片方のターミナルを開き、シミュレーションサーバーを以下のコマンドで起動します：
+
+```bash
+# Terminal A
+cd WORKING_DIR/rcrs-server/scripts
+./start-comprun.sh -m ../maps/tutorial_ambulance_team_only/map -c ../maps/tutorial_ambulance_team_only/config
+```
+
+その後、別のターミナルを開き、エージェントを起動します：
+
+```bash
+# Terminal B
+cd WORKING_DIR/<your_team_name>
+python main.py
+```
 
 ## モジュールの改善
 
@@ -172,13 +188,13 @@ class KMeansPPSearch(Search):
 ### 探索対象がステップごとに変わってしまう問題
 
 ```{admonition} 方針のヒント
-:class: tip dropdown
+:class: hint dropdown
 
 一度選択した探索対象に到達するまで、探索対象を変更しないようにする
 ```
 
 ```{admonition} プログラム例
-:class: tip dropdown
+:class: hint dropdown
 
 ````python
     def calculate(self) -> Search:
@@ -212,13 +228,13 @@ class KMeansPPSearch(Search):
 ### すでに探索したエンティティを再度探索対象として選択してしまう問題
 
 ```{admonition} 方針のヒント
-:class: tip dropdown
+:class: hint dropdown
 
 すでに探索したエンティティを何かしらの方法で記録し、再度探索対象として選択しないようにする
 ```
 
 ```{admonition} プログラム例
-:class: tip dropdown
+:class: hint dropdown
 
 ````python
     def __init__(
@@ -287,13 +303,13 @@ class KMeansPPSearch(Search):
 ### 近くに未探索のエンティティがあるのに、遠くのエンティティを探索対象として選択してしまう
 
 ```{admonition} 方針のヒント
-:class: tip dropdown
+:class: hint dropdown
 
 エンティティ間の距離を計算し、もっとも近いエンティティを探索対象として選択する
 ```
 
 ```{admonition} プログラム例
-:class: tip dropdown
+:class: hint dropdown
 
 ````python
     def calculate(self) -> Search:

docs/source/hands-on/search.md

@@ -1,4 +1,5 @@
 # 環境構築
+
 adf-core-pythonをインストールするには以下の必要条件が必要です。
 既にお使いのPCにインストールされている場合は再度インストールする必要はありません。
 
@@ -17,6 +18,7 @@ adf-core-pythonをインストールするには以下の必要条件が必要
 [Linuxでの必要条件のインストール方法](./linux/install.md)
 
 ## シミュレーションサーバーのインストール
+
 次にRoboCup Rescue Simulationのシミュレーションサーバーをインストールします。
 
 ```{note}
@@ -48,3 +50,7 @@ cd scripts
 
 上記のように何個かのウィンドウが表示されたら成功です。
 コマンドラインで `Ctrl + C`  (MacOSの場合は `Command + C` )  を押すとシミュレーションサーバーが終了します。
+
+```{warning}
+シミュレーションサーバーを停止させたあとは、プロセスが残ってしまう場合があるので`./kill.sh` を実行してください。
+```

docs/source/images/cluster.png

@@ -17,6 +17,11 @@ Your agent team name: my-agent
 Creating a new agent team with name: my-agent
 ```
 
+```{note}
+エージェントチーム名は、エージェントのディレクトリ名として使用されます。
+以後、エージェントチーム名を `<your_team_name>` として参照します。
+```
+
 入力後、下記のようなエージェントのテンプレートがカレントディレクトリに作成されます。
 
 ```bash
@@ -55,7 +60,7 @@ cd WORKING_DIR/rcrs-server/scripts
 
 ```bash
 # Terminal B
-cd WORKING_DIR/my-agent
+cd WORKING_DIR/<your_team_name>
 python main.py
 ```
 

docs/source/install/environment/environment.md

@@ -107,9 +107,20 @@ DefaultTacticsFireBrigade:
   HumanDetector: src.<your_team_name>.module.complex.fire_brigade_human_detector.FireBrigadeHumanDetector
 ```
 
-シミュレーションサーバーを起動し、エージェントを実行してみましょう。
+ターミナルを2つ起動します。
+
+片方のターミナルを開き、シミュレーションサーバーを以下のコマンドで起動します：
+
+```bash
+# Terminal A
+cd WORKING_DIR/rcrs-server/scripts
+./start-comprun.sh -m ../maps/tutorial_fire_brigade_only/map -c ../maps/tutorial_fire_brigade_only/config
+```
+
+その後、別のターミナルを開き、エージェントを起動します：
 
 ```bash
+# Terminal B
 cd WORKING_DIR/<your_team_name>
 python main.py
 ```
@@ -151,13 +162,13 @@ RRS上のエンティティは下図のように `Entity` を継承したクラ
 - `entity` が市民であるかどうかを判定する
 
 ```python
-isinstance(entity, Civilian)
+is_civilian: bool = isinstance(entity, Civilian)
 ```
 
 - エンティティIDを取得する
 
 ```python
-entity.get_id()
+entity_id: EntityID = entity.get_id()
 ```
 
 - 市民が生きているかどうかを判定する
@@ -185,19 +196,19 @@ if buriedness is None or buriedness <= 0:
 - エンティティIDからエンティティを取得する
 
 ```python
-self._world_info.get_entity(entity_id)
+entity: Entity = self._world_info.get_entity(entity_id)
 ```
 
 - 指定したクラスのエンティティを全て取得する
 
 ```python
-self._world_info.get_entities_by_type([Building, Road])
+entities: list[Entity] = self._world_info.get_entities_by_type([Building, Road])
 ```
 
 - エージェントの位置から指定したエンティティまでの距離を取得する
 
 ```python
-self._world_info.get_distance(me, civilian.get_id())
+distance: float = self._world_info.get_distance(me, civilian.get_id())
 ```
 
 [詳細はこちら](../../adf_core_python.core.agent.info.rst)
@@ -211,7 +222,7 @@ self._world_info.get_distance(me, civilian.get_id())
 - 自分自身のエンティティIDを取得する
 
 ```python
-self._agent_info.get_entity_id()
+my_entity_id: EntityID = self._agent_info.get_entity_id()
 ```
 
 [詳細はこちら](../../adf_core_python.core.agent.info.rst)
@@ -305,9 +316,20 @@ class SampleHumanDetector(HumanDetector):
         return self._result
 ```
 
-シミュレーションサーバーを起動し、エージェントを実行してみましょう。
+ターミナルを2つ起動します。
+
+片方のターミナルを開き、シミュレーションサーバーを以下のコマンドで起動します：
+
+```bash
+# Terminal A
+cd WORKING_DIR/rcrs-server/scripts
+./start-comprun.sh -m ../maps/tutorial_fire_brigade_only/map -c ../maps/tutorial_fire_brigade_only/config
+```
+
+その後、別のターミナルを開き、エージェントを起動します：
 
 ```bash
+# Terminal B
 cd WORKING_DIR/<your_team_name>
 python main.py
 ```

docs/source/tutorial/agent/agent.md

@@ -4,7 +4,7 @@
 
 ```bash
 .
-└── <team-name>
+└── <your_team_name>
     └── config
         ├── development.json
         ├── launcher.yaml