You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+145-4Lines changed: 145 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,9 +8,10 @@ Before start using this project you need to install the required dependencies:
8
8
9
9
1.`Python 3.11`
10
10
2.`pip`
11
-
3.`numpy`
12
-
4.`lxml`
13
-
3.`IPython` and `Jupyter Notebook` (for running Jupyter notebooks)
11
+
3.`setuptools`
12
+
4.`numpy`
13
+
5.`lxml`
14
+
6.`IPython` and `Jupyter Notebook` (for running Jupyter notebooks)
14
15
15
16
Next, you need to run this script from the root folder of this project to install it across all system:
16
17
@@ -29,7 +30,147 @@ experiments.
29
30
*`manavlib.io.tswap_io`: functions to support the setup, conversion, and processing of multi-agent pathfinding experiments to evaluate the TSWAP algorithm.
30
31
*`manavlib.utils`: various auxiliary tools. Сurrently include functions for finding paths on grids.
31
32
32
-
Examples of XML files are located in the `xml-examples` folder. You can find usage examples for the `manavlib.common.params` and `manavlib.io.xml_io` modules in the Jupyter Notebook `test/xml_io_test.ipynb`.
33
+
You can find usage examples for the `manavlib.common.params` and `manavlib.io.xml_io` modules in the Jupyter Notebook `test/xml_io_test.ipynb`.
34
+
35
+
## XML File Structure
36
+
37
+
One of the key components of this repository is a module `manavlib.io.xml_io` that allows to read experiment configurations from XML files of a special structure. It is assumed that each experiment is described by three types of files: an environment file `map.xml`, an agents/task description file `task.xml`, and an experiment/algorithm configuration file `config.xml`.
38
+
39
+
Examples of XML files are located in the `xml-examples` folder. An usage examples for `manavlib.io.xml_io` module (with custom agent, algorithm and experiment parameters) is located in the Jupyter Notebook `test/xml_io_test.ipynb`.
40
+
41
+
### Environment Description `map.xml`
42
+
43
+
The file includes a description of the environment, namely an obstacle map. Currently only static map description in grid format is supported.
44
+
45
+
#### Structure
46
+
47
+
***Root Element `<root>`**: The entire content of the XML file is wrapped inside the `<root>` element.
48
+
***Occupancy Grid Element `<occupancy_grid>`**: Defines the grid map structure and its properties. It contains metadata about the grid, such as its dimensions and cell size, as well as the grid layout itself.
49
+
***Width Element `<width>`**: Specifies the width of the grid map in the number of cells (columns).
50
+
***Height Element `<height>`**: Specifies the height of the grid map in the number of cells (rows).
51
+
***Cell Size Element `<cell_size>`**: Defines the size of each cell in the grid. This value is used for scaling and pathfinding calculations.
52
+
***Grid Element `<grid>`**: Contains the layout of the map, represented as a matrix of cells.
53
+
***Row Elements `<row>`**: Each `<row>` element represents a single row of the grid. The values within each row indicate the state of the corresponding cell: `0` represents a free cell (traversable), `1` represents an obstacle (non-traversable).
54
+
55
+
#### Example
56
+
57
+
```xml
58
+
<?xml version="1.0" ?>
59
+
<root>
60
+
<occupancy_grid>
61
+
<width>10</width>
62
+
<height>10</height>
63
+
<cell_size>1.0</cell_size>
64
+
<grid>
65
+
<row>0 0 0 0 0 0 0 0 0 0</row>
66
+
<row>0 0 0 0 0 0 0 0 0 0</row>
67
+
<row>0 0 1 1 1 1 0 0 0 0</row>
68
+
<row>0 0 0 0 0 0 0 0 0 0</row>
69
+
<row>0 0 0 0 0 0 0 0 0 0</row>
70
+
<row>0 0 0 0 0 0 0 0 0 0</row>
71
+
<row>0 0 0 0 0 0 0 0 0 0</row>
72
+
<row>0 0 0 0 0 0 0 0 0 0</row>
73
+
<row>0 0 0 0 0 0 0 0 0 0</row>
74
+
<row>0 0 0 0 0 0 0 0 0 0</row>
75
+
</grid>
76
+
</occupancy_grid>
77
+
</root>
78
+
```
79
+
80
+
### Task description `task.xml`
81
+
82
+
The file includes a task description, namely default agent configurations, initial and goal agent positions (there are two possible options to set positions: discrete and continuous) and (optionally) the configuration of each particular agent. This file defines parameters of agents such as the agent’s type, size, visibility radius, and motion parameters.
83
+
84
+
The possible agent types are defined in module `manavlib.common.params`. You can define your own agent type by creating a class in your workspace that inherits from `BaseAgentParams`.
85
+
86
+
An example of creating and reading of task file with custom agents is located in the Jupyter Notebook `test/xml_io_test.ipynb`.
87
+
88
+
#### Structure
89
+
90
+
***Root Element `<root>`**: The entire content of the XML file is wrapped inside the `<root>` element.
91
+
***Default Agent Element `<default_agent>`**: Specifies the default parameters that apply to all agents unless explicitly overridden for a particular agent. In general, the particular set of attributes is specified by the agent type, but each agent type basycally includes the following attributes:
92
+
***`model_type` (mandatory)**: The type of agent model, e.g., `diff_drive`, `holonomic`, or `base_discrete`.
93
+
***`size`**: The size (radius) of the agent.
94
+
***`r_vis`**: Visibility radius of the agent, used for determining the communication range.
95
+
* The agent configuration can include custom parameters. The following data types are supported: `str`, `int`, `float`, `bool`.
96
+
***Agents Element: `<agents>`**: Contains the list of individual agents, where `N` is the total number of agents specified by the `number` attribute.
97
+
***Agent Elements: `<agent>`**: Defines an individual agent. The attributes of the element can include:
98
+
***`id` (mandatory)**: An unique identifier for the agent.
99
+
***Initial State (`s.` prefix, mandatory)**:
100
+
***`s.x, s.y, s.th`**: The initial `x` and `y` coordinates and orientation in radians `theta` (for continuous models).
101
+
***`s.i, s.j`**: The initial row (`i`) and column (`j`) indices (for discrete models).
102
+
***Goal State (`g.` prefix, mandatory)**:
103
+
***`g.x, g.y, g.th`**: The initial `x` and `y` coordinates and orientation in radians `theta` (for continuous models).
104
+
***`g.i, g.j`**: The initial row (`i`) and column (`j`) indices (for discrete models).
105
+
***Model-Specific Parameters**: These can override the default agent parameters defined in <default_agent>, such as `model_type`, `size`, `r_vis`, etc. The following data types are supported: `str`, `int`, `float`, `bool`.
This file defines the configuration for the experiment and the algorithm used in multi-agent pathfinding tasks. It specifies both general experiment settings and the parameters of the algorithm to be applied to all agents in the experiment. Currently, only the configuration of single algorithm is supported.
137
+
138
+
The base algorithm's parameters class is defined in module `manavlib.common.params`. You need to define your own algorithm's parameters class that inherits from `BaseAlgParams`.
139
+
140
+
The class with the experiment parameters `ExperimentParams` is also defined in module `manavlib.common.params`. If it is necessary to add custom parameters of the experiment, you need to define your own class, which will globally overwrite the name `ExperimentParams`.
141
+
142
+
An example of creating and reading of config file with custom agents is located in the Jupyter Notebook `test/xml_io_test.ipynb`.
143
+
144
+
#### Structure
145
+
146
+
***Root Element `<root>`**: The entire content of the XML file is wrapped inside the `<root>` element.
147
+
***Experiment Element `<experiment>`**: Contains general settings for the experiment. It includes parameters that control the overall behavior of the simulation
148
+
***`timestep`**: Defines the duration of each discrete time step in the experiment.
149
+
***`xy_goal_tolerance`**: Defines the tolerance for reaching the goal position. Agents are considered to have reached their goal if they are within this distance
150
+
***`max_steps`**: The maximum number of time steps allowed for the experiment. If this limit is reached, the simulation terminates even if not all agents have reached their goals.
151
+
* The experiment configuration can include custom parameters. The following data types are supported: `str`, `int`, `float`, `bool`.
152
+
***Algorithm Element `<algorithm>`**: Specifies the configuration for the algorithm to be applied to all agents in the experiment. The `name` attribute defines the algorithm’s name (e.g., "example_alg"), which should match the implemented algorithm class in the code. Only one `<algorithm>` element is currently supported per configuration file, and its settings are applied uniformly to all agents.
153
+
* The parameters listed under the `<algorithm>` element are specific to the selected algorithm and are used to control its behavior during the simulation. The following data types are supported: `str`, `int`, `float`, `bool`.
0 commit comments