Primal代码梳理01——mapf_gym.py

mapf_gym.py文件的代码实现了基于OpenAI Gym接口的、用于多智能体路径规划的环境（网格世界）。
代码包含了用于创建环境、执行动作和渲染状态的类和方法。

1 常量值

定义REWARD，分别是动作成本（ACTION_COST=-0.3）、静止成本（IDLE_COST=-.5）、到达目标时的奖励（GOAL_REWARD = 0.0）、碰撞的成本（COLLISION_REWARD = -2）、完成任务的奖励（FINISH_REWARD = 20.）和阻塞成本（BLOCKING_COST = -1.）。
opposite_actions 字典定义每个动作的相反动作。
JOINT变量定义了在评估智能体的奖励的时候是否考虑邻居智能体。如果设置为True，则智能体在评估奖励时会考虑其他邻居智能体的奖励。当前为False。
dirDict字典定义了每个动作代码对应的方向，其中键是动作代码，值是方向的二元组（x,y）。例如，动作0对应方向(0,0)（静止，无移动），动作1对应方向(0,1)（向上移动）。
actionDict字典是dirDict的逆字典，根据方向找到对应的动作代码。

2 State类

State类是多智能体系统的状态。
实现方式是使用两个2d的numpy数组。
第一个称为“state”，是地图状态。对于地图上的任意位置，该位置是静态障碍物时值为-1，位置是空的时值为0，位置上有智能体时为正整数（该智能体的id）。
第二个称为“goal”，这个数组记录智能体的目标位置。对于地图上的任意位置，该位置是某个智能体的目标位置时，该位置的值为正整数（该智能体的id）。

2.1 构造函数

__init__方法是类的构造函数。
它接收二维数组初始世界状态 world0、二维数组智能体目标 goals、是否考虑对角线移动的布尔值 diagonal 和智能体的数量 num_agents。

2.2 scanForAgents 方法

扫描初始世界状态和目标状态，以确定智能体的起始位置和目标位置。它返回包含智能体当前位置、之前的位置和目标位置的三个列表。

2.3 getPos、getPastPos 和 getGoal 方法

分别返回给定ID的智能体的当前位置、过去的位置和目标位置。

2.4 diagonalCollision方法

diagonalCollision方法检测在一个给定的状态下，移动到新位置的代理是否会与其他任何代理发生对角线冲突。
接收两个参数，分别是agent_id，待检查冲突的代理的ID；和newPos，代理尝试移动到的坐标。
如果发生冲突，它返回True；否则返回False。

2.5 moveAgent 方法

尝试移动智能体并返回状态代码。
moveAgent方法考虑了各种移动规则，包括是否出界、是否与障碍物或其他智能体发生碰撞，以及是否达到目标。
接收两个参数。第一个是direction，一个包含两个元素的元组(dx, dy)，代表想要移动的方向。另一个是agent_id，想要移动的代理的ID。

2.6 act方法

尝试执行一个动作，并返回动作是否被执行以及执行结果的状态码。
状态码说明如下。
2: action executed and left goal
1: action executed and reached goal (or stayed on)
0: action executed
-1: out of bounds
-2: collision with wall
-3: collision with robot

2.7 getDir 和 getAction 方法

通过给定的动作代码或方向，返回对应的方向或动作代码。

2.8 done 方法

检查所有智能体是否都已经达到了它们的目标位置。

3 MAPFEnv类

MAPFEnv类继承自gym.Env，是一个用于MAPF问题的环境。

3.1 init 方法

MAPFEnv类的构造函数，用于初始化环境的状态。
它设置了智能体的数量、视野大小、是否允许对角线移动、网格大小、障碍物生成概率等参数，并确定了动作空间大小。

3.2 isConnected 方法

检查给定的world0网格地图是否完全连通，即从任何一个空位置（值为0）出发，是否可以在不穿过障碍（值为-1）的情况下到达所有其他空位置。

3.3 getObstacleMap、getGoals和getPositions方法

getObstacleMap方法获取到环境中的障碍物的地图。
getGoals方法返回一个包含所有代理目标位置的列表。
getPositions方法返回一个包含所有代理当前位置的列表。

3.4 _setWorld方法

_setWorld方法用于初始化或重置环境。该方法可以接收一个存在的世界和目标位置或者创建一个新的随机环境。

3.5 _observe 方法

返回给定id的智能体的视野中的地图的观测数据，包括智能体自身位置、目标位置、其他智能体的位置、障碍物位置等。

3.6 _reset 方法

重置环境，使其回到初始状态。

3.7 _complete方法

判断所有智能体是否都已经达到了它们的目标位置。

3.8 getAstarCosts 方法

使用A*算法计算从每个网格点到目标的成本。

3.9 astar 方法

使用 A* 算法为智能体规划从当前位置到目标位置的路径。

3.10 get_blocking_reward 方法

计算给定id的智能体阻挡其他智能体到达目标的总代价，即该智能体阻挡的智能体数×BLOCKING_COST。

3.11 _step 方法

执行一个动作并更新环境状态，返回智能体视野中的新观测数据、奖励、是否完成目标、下一个有效的动作、是否在目标上、是否阻挡其他智能体以及该动作是否是有效动作。

3.12 _listNextValidActions方法

生成一个智能体在当前位置出发时的有效行动列表。

3.13 drawStar方法

drawStar方法在图形界面上绘制一个星形。

3.14 create_rectangle、create_circle方法

create_rectangle 函数用于创建一个矩形。
create_circle 函数用于创建一个圆形。

3.15 initColors方法

根据代理的数量self.num_agents，为每个agents生成独特的颜色

3.16 _render 方法

渲染当前环境状态的视觉表示。