Skip to content

Commit

Permalink
Merge pull request #43 from MAPF-Competition/develop
Browse files Browse the repository at this point in the history 
Release Version 1.1.3
  • Loading branch information
@nobodyczcz
nobodyczcz authored Oct 27, 2023
2 parents 9552289 + e812fa4 commit fbe6cd0
Show file tree
Hide file tree
Showing 27 changed files with 382 additions and 273 deletions.
18 changes: 18 additions & 0 deletions Changelog.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,23 @@
# Changelog

Version 1.1.3 - 2023-10-24
----------------------------
Added:
- Add Working_with_Preprocessed_Data.md to explain how you can work with your preprocessed data.
- Add Debug_and_Visualiser_Your_Planner.md to explain how you can use the JSON output to debug and visualise with PlanViz

Changed:
- Additional option `OutputScreen` in the input argument, which allows you to choose the level of details of the output JSON file.
- Readme, Parepare_Your_Planner, and compile.sh suggests running the start-kit under repo root directory.
- Simplified duplicated output appears in couts and log files
- Updated documentation (add more descriptions regarding the coordination system in Prepare_Your_Planner.md)
- Updated documentation (add corresponding descriptions of `OutputScreen` in Input_Output_Format.md)
- Terminate all processes when the main process (the simulation) is terminated.

Fixed:
- Fixed issue with running start-kit under repo root directory python cannot find compiled MAPF module for importing.
- Fixed issue with missing fie_storage_path for pybind.

Version 1.1.2 - 2023-08-29
----------------------------
Fixed:
Expand Down
71 changes: 71 additions & 0 deletions Debug_and_Visualise_Your_Planner.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Debug and Visualise Your Planner
The output file provides some related information to help you design and debug your planner.
Begin by familiarizing yourself with the structure of the output JSON file. Please refer to the [Input_Output_Format.md](./Input_Output_Format.md).

## Debug your planner using Output File
To debug your planners, there are some properties that can help you to learn how your planner coordinate the robots. Here are some suggestions that you might be interested to look at:
1. Check for Validity: Inspect the `errors` and `AllValid` properties to identify and address any invalid actions.
2. Review Paths: Study the `plannerPaths` and `actualPaths` results to check whether your planner behaves consistently with your expectations or not.
3. Analyze Planner Times: Look at the `plannerTimes` property to understand the time taken by your planner during each planning episode. Investigate further if you notice significant deviations from expected planning times.
4. Other ways: you can also compare your performance and design a better planner by simply looking at the `numTaskFinished` results and analysing the tasks finished by `events` and `tasks`.

## Visualise your planner using Output File
We also provide a tool called [PlanViz](https://github.com/MAPF-Competition/PlanViz) for visualising your plan with the output JSON file.
PlanViz shows the animation of the actualPaths of agents in the JSON file.
While the actual paths are always valid and conflict-free, the plannerPaths might contain conflicts and invalid moves.
In such cases, PlanViz can highlight the problematic agents with red color.
You can also click each item in the error list to jump to the corresponding timestep.
Note that PlanViz does not do any validation or error checking.
Therefore, the errors it shows are those recorded in the JSON file.
If you modify the JSON file manually, the error list and agent highlighting can be inconsistent with the movement.

For more details, please refer to the [Visualiser Page](https://github.com/MAPF-Competition/PlanViz).

### Use PlanViz

Following the instruction in the [Visualiser Page](https://github.com/MAPF-Competition/PlanViz), one can start PlanViz by running the following command
```
python3 plan_viz.py --map ../example/warehouse_small.map --plan ../example/warehouse_small.json --grid --aid --static --ca
```
You will see something similar to the figure below:

![A screenshot of the PlanViz UI.](./image/UI.png)

The UI of PlanViz consists of a main canvas, which shows the visualization, and a UI panel, which users can interact with. In the main canvas, we use the following markers to represent agents and tasks:

![Markers for agents and tasks.](./image/markers.png)

We will explain the UI panel in five sections: Animation Control, Visualization Options, Timestep Selector, Error List, and Event List. For instructions on how to debug errors, see the [error list section](#errorlist).

#### Animation Control
The animation control section shows the current timestep in the visualization and provides buttons for controlling the animation. You can use `Play/Pause` to start/stop the animation and `Next/Prev` to make agents move one step forward/backward.


#### Visualization Options

The visualization option section allows users to choose what to be displayed in the main canvas:

![Different visualization options](./image/visualization_option.png)

Note that, when "Show colliding agents" is turned on, an agent will be marked as always red if it has a collision in any timestep. You can also use the drop-down list of shown tasks to select which tasks to display:
![Different options for displaying tasks.](./image/tasks_drop_down.png)

#### Timestep Selector
The timestep selector section allows users to jump to a specific timestep. Note that you need to pause PlanViz before using it.

<h4 id="errorlist">
Error List
</h4>

The error list section shows the errors (planner timeout, collisions in the planned paths, etc.) in the JSON input file. You can interact with a collision error by single or double-clicking it:

![](./image/single_click.gif)

*When "Show colliding agents" is turned off, single-clicking a conflict will mark the two colliding agents red.*

![](./image/double_click.gif)

*Double-clicking a conflict will make PlanViz jump to the specific timestep and show the collision.*
#### Event List

The event list section shows the events (assignment and completion of tasks) in the JSON input file. Single-clicking an event will make PlanViz jump to the timestep right before the event timestep.
10 changes: 6 additions & 4 deletions Input_Output_Format.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@
| --help | |
| --inputFile | String <br /> The input file describes the problem to be solved in JSON format |
| --output | String <br /> The output file describes the planner result in JSON format |
| --outputScreen | Int (=1) <br /> The level of details in the output file (=1 to show all, = 2 to show problem summary, start and actual path and =3 to show only problem summary). |
| --evaluationMode | Boolean <br /> when run in this mode the program will check the validity of the planned and executed actions in an existing plan, as specified by the --output parameter |
| --simulationTime | Int <br /> The maximum number of timesteps allowed for solving the problem, we sometimes refer to this as planning horizon |
| --planTimeLimit | Int <br /> The amount of time available for planning in each timestep, if this time limit exceeded by the planner, all robots are issued wait commands at current timestep |
| --fileStoragePath | String <br /> The folder path that your local preprocessing file locates |
| --planTimeLimit | Int <br /> The amount of time available for planning in each timestep, if this time limit is exceeded by the planner, all robots are issued wait commands at current timestep |
| --preprocessTimeLimit | Int <br /> The amount of time in seconds available for loading and precomputing auxiliary data before the problem-solving process begins |
| --logFile | String <br /> An output file that records all warnings and errors issued by the simulator in the event of invalid or incomplete actions from the planner |

Expand All @@ -19,10 +21,10 @@ All paths here is the relative path relative to the location of input JSON file
| properties | |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| mapFile | String <br /> The relative path to the file that describes the grid environment input. We use the grid map format as described in the next section (with a section link to the relevant section) |
| robotFile | String <br /> The relative path to the file that describes the start locations for robots. The first line indicates the number of robots n. The following n lines correspond to the start locations of the n robots..* |
| agentFile | String <br /> The relative path to the file that describes the start locations for robots. The first line indicates the number of robots n. The following n lines correspond to the start locations of the n robots..* |
| taskFile | String <br /> The relative path to the file that describes the locations for tasks. The first line indicates the number of tasks m. The following m lines contain single integers that correspond to the locations of the m tasks on the grid.\* |
| numTasksReveal | Int (=1) <br /> The number of tasks/errands revealed to an robot at any one time. Every time an robot finishes a task/errand a new task is revealed. By default, this is 1, which means only the next 1 task/errand is known to the robot. |
| taskAssignmentStrategy | String (=roundrobin) <br /> The strategy for assigning tasks (`greedy`,`roundrobin` or `roundrobin-fixed`). Every time an robot finished a task/errand, a task assignment strategy decides the next task assigned to the robot. `greedy` will assign the next unassgined task from task file line by line. While for `roundrobin` and `roundrobin-fixed`, tasks assignment is pre-deceided by the system using a round robin strategy, where the $i_{th}$ robot will get the $i + n_i*(team size)$ task and $n_i$ is the task counter for robot $i$, starts from 0 and growth by 1 upon a task finish. The difference between "roundrobin" and "roundrobin-fixed" is that for "roundrobin-fixed", the simulation will stop when all the tasks from the task files are finished, and for "roundrobin" the task assignment system will iteratively read the task file from the first line to simulate planning for "infinite" tasks/errands. |
| numTasksReveal | Int (=1) <br /> The number of tasks/errands revealed to a robot at any one time. Every time a robot finishes a task/errand a new task is revealed. By default, this is 1, which means only the next 1 task/errand is known to the robot. |
| taskAssignmentStrategy | String (=roundrobin) <br /> The strategy for assigning tasks (`greedy`,`roundrobin` or `roundrobin-fixed`). Every time a robot finishes a task/errand, a task assignment strategy decides the next task assigned to the robot. `greedy` will assign the next unassigned task from task file line by line. While for `roundrobin` and `roundrobin-fixed`, tasks assignment is pre-decided by the system using a round-robin strategy, where the $i_{th}$ robot will get the $i + n_i*(team size)$ task and $n_i$ is the task counter for robot $i$, starts from 0 and growth by 1 upon a task finish. The difference between "roundrobin" and "roundrobin-fixed" is that for "roundrobin-fixed", the simulation will stop when all the tasks from the task files are finished, and for "roundrobin" the task assignment system will iteratively read the task file from the first line to simulate planning for "infinite" tasks/errands. |
| teamSize | Int <br /> The number of robots in the simulation |


Expand Down
Loading

0 comments on commit fbe6cd0

Please sign in to comment.