diff --git a/docs/source/download/cluster_plot.zip b/docs/source/download/cluster_plot.zip new file mode 100644 index 0000000..122b555 Binary files /dev/null and b/docs/source/download/cluster_plot.zip differ diff --git a/docs/source/hands-on/clustering.md b/docs/source/hands-on/clustering.md index 9e70f9a..62f842d 100644 --- a/docs/source/hands-on/clustering.md +++ b/docs/source/hands-on/clustering.md @@ -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..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/ +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) diff --git a/docs/source/hands-on/search.md b/docs/source/hands-on/search.md index 8b6ac94..293ef8b 100644 --- a/docs/source/hands-on/search.md +++ b/docs/source/hands-on/search.md @@ -70,13 +70,13 @@ class KMeansPPSearch(Search): ```yaml DefaultTacticsAmbulanceTeam: - Search: src..module.complex.k_means_pp_search.KMeansPPSearch + Search: src..module.complex.k_means_pp_search.KMeansPPSearch DefaultTacticsFireBrigade: - Search: src..module.complex.k_means_pp_search.KMeansPPSearch + Search: src..module.complex.k_means_pp_search.KMeansPPSearch DefaultTacticsPoliceForce: - Search: src..module.complex.k_means_pp_search.KMeansPPSearch + Search: src..module.complex.k_means_pp_search.KMeansPPSearch ``` ## モジュールの実装 @@ -87,7 +87,7 @@ DefaultTacticsPoliceForce: ```yaml KMeansPPSearch: - Clustering: src..module.algorithm.k_means_pp_clustering.KMeansPPClustering + Clustering: src..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/ +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: diff --git a/docs/source/images/cluster.png b/docs/source/images/cluster.png new file mode 100644 index 0000000..4e0b9fb Binary files /dev/null and b/docs/source/images/cluster.png differ diff --git a/docs/source/install/environment/environment.md b/docs/source/install/environment/environment.md index 1818228..e9cf04b 100644 --- a/docs/source/install/environment/environment.md +++ b/docs/source/install/environment/environment.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` を実行してください。 +``` diff --git a/docs/source/tutorial/agent/agent.md b/docs/source/tutorial/agent/agent.md index 853858a..45bab95 100644 --- a/docs/source/tutorial/agent/agent.md +++ b/docs/source/tutorial/agent/agent.md @@ -17,6 +17,11 @@ Your agent team name: my-agent Creating a new agent team with name: my-agent ``` +```{note} +エージェントチーム名は、エージェントのディレクトリ名として使用されます。 +以後、エージェントチーム名を `` として参照します。 +``` + 入力後、下記のようなエージェントのテンプレートがカレントディレクトリに作成されます。 ```bash @@ -55,7 +60,7 @@ cd WORKING_DIR/rcrs-server/scripts ```bash # Terminal B -cd WORKING_DIR/my-agent +cd WORKING_DIR/ python main.py ``` diff --git a/docs/source/tutorial/agent/agent_control.md b/docs/source/tutorial/agent/agent_control.md index afc3457..cc4c6f0 100644 --- a/docs/source/tutorial/agent/agent_control.md +++ b/docs/source/tutorial/agent/agent_control.md @@ -107,9 +107,20 @@ DefaultTacticsFireBrigade: HumanDetector: src..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/ 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/ python main.py ``` diff --git a/docs/source/tutorial/config/config.md b/docs/source/tutorial/config/config.md index 3257086..5f951c1 100644 --- a/docs/source/tutorial/config/config.md +++ b/docs/source/tutorial/config/config.md @@ -4,7 +4,7 @@ ```bash . -└── +└── └── config ├── development.json ├── launcher.yaml