Skip to content

Commit

Permalink
Merge pull request #255 from pfeinsper/vitepress_docs
Browse files Browse the repository at this point in the history 
Vitepress docs
  • Loading branch information
@RicardoRibeiroRodrigues
RicardoRibeiroRodrigues authored Jun 14, 2024
2 parents c21bdc0 + 43e945a commit 0212cf0
Show file tree
Hide file tree
Showing 21 changed files with 767 additions and 177 deletions.
25 changes: 16 additions & 9 deletions docs/.vitepress/config.mts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ export default defineConfig({
{ text: 'Reward', link: '/Documentation/docsSearch#reward' },
{ text: 'Termination & Truncation', link: '/Documentation/docsSearch#termination-truncation' },
{ text: 'Info', link: '/Documentation/docsSearch#info' },
{ text: 'Stay Updated', link: '/Documentation/docsSearch#stay-updated' },
{ text: 'How to Cite This Work', link: '/Documentation/docsSearch#how-to-cite-this-work' },
{ text: 'License', link: '/Documentation/docsSearch#license' },
]
Expand All @@ -68,16 +69,23 @@ export default defineConfig({
{ text: 'Reward', link: '/Documentation/docsCoverage#reward' },
{ text: 'Termination & Truncation', link: '/Documentation/docsCoverage#termination-truncation' },
{ text: 'Info', link: '/Documentation/docsCoverage#info' },
{ text: 'Stay Updated', link: '/Documentation/docsCoverage#stay-updated' },
{ text: 'License', link: '/Documentation/docsCoverage#license' },
]
},
// {
// collapsed: false,
// text: 'Algorithms',
// items: [
// { text: 'Documentation Under Construction', link: '/Documentation/docsAlgorithms#build' },
// ]
// }
{
collapsed: false,
text: 'Algorithms',
items: [
{ text: 'About', link: '/Documentation/docsAlgorithms#about' },
{ text: 'Algorithms Implemented', link: '/Documentation/docsAlgorithms#algorithms-implemented' },
{ text: 'Hypotheses', link: '/Documentation/docsAlgorithms#hypotheses' },
{ text: 'Test Configurations', link: '/Documentation/docsAlgorithms#test-configurations' },
{ text: 'How to run', link: '/Documentation/docsAlgorithms#how-to-run' },
{ text: 'Stay Updated', link: '/Documentation/docsAlgorithms#stay-updated' },
{ text: 'License', link: '/Documentation/docsAlgorithms#license' },
]
}
],
"/QuickStart/": [{
collapsed: false,
Expand All @@ -92,8 +100,7 @@ export default defineConfig({
collapsed: false,
text: 'Our Story',
items: [
{ text: 'Our Story Coming Soon!', link: '/OurStory/ourStory#our-story-coming-soon!' },
{ text: 'Stay Updated', link: '/OurStory/ourStory#stay-updated' },
{ text: 'The Beginning of Our Story', link: '/OurStory/ourStory#the-beginning-of-our-story' },
]
},],
},
Expand Down
439 changes: 428 additions & 11 deletions docs/Documentation/docsAlgorithms.md
View file

Large diffs are not rendered by default.

68 changes: 39 additions & 29 deletions docs/Documentation/docsCoverage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,23 +10,17 @@ The **Coverage Environment** is our second training environment, building on the
<em>Fig 1: Representation of the environment in the Coverage Environment.</em>
</p>


<!-- ### Outcome -->

<!-- | If target is found | If target is not found |
:-------------------------:|:-------------------------:
| ![](https://raw.githubusercontent.com/PFE-Embraer/drone-swarm-search/main/docs/public/pics/victory_render.png) | ![](https://raw.github.com/PFE-Embraer/drone-swarm-search/main/docs/public/pics/fail_render.png) |
-->

## Quick Start

::: warning Warning
The DSSE project requires Python version 3.10.5 or higher.

The installation of GDAL (requirement for using opendrift) may need the installation of the following packages
To install [GDAL](https://gdal.org/) (a requirement for using OpenDrift), you may need to install the following packages:
```sh
sudo apt-get install -y libgdal-dev gdal-bin
sudo apt install -y libgdal-dev gdal-bin
```

For Windows, Microsoft Visual C++ 14.0 or greater is required for building.
:::

::: tip Tip
Expand Down Expand Up @@ -91,18 +85,23 @@ We incorporated 8 actions in this environment to enable the use of agents traine
:::

### Inputs
| Inputs | Possible Values | Default Values |
| ------------- | ------------- | ------------- |
| `render_mode` | `"ansi" or "human"` | `"ansi"` |
| `render_grid` | `bool` | `True` |
| `render_gradient` | `bool` | `True` |
| `timestep_limit` | `int` | `100` |
| `disaster_position` | `(float, float)` | `(-24.04, -46.17)` |
| `drone_amount` | `int` | `1` |
| `drone_speed` | `int` | `10` |
| `drone_probability_of_detection`| `float` | `1.0` |
| `pre_render_time` | `int` | `10` |
| `prob_matrix_path` | `string` | `None` |
| Inputs | Possible Values | Default Values |
| ------------- | ------------- | ------------- |
| `render_mode` | `"ansi" or "human"` | `"ansi"` |
| `render_grid` | `bool` | `True` |
| `render_gradient` | `bool` | `True` |
| `timestep_limit` | `int` | `100` |
| `disaster_position` | `(float, float)` | `(-24.04, -46.17)` |
| `drone_amount` | `int` | `1` |
| `drone_speed` | `int` | `10` |
| `drone_probability_of_detection` | `float` | `1.0` |
| `pre_render_time` | `int` | `10` |
| `prob_matrix_path` | `string` | `None` |
| `particle_amount` | `int` | `50,000` |
| `particle_radius` | `int` | `800` |
| `num_particle_to_filter_as_noise` | `int` | `1` |
| `start_time` | `datetime` | `None` |
| `grid_cell_size` | `int` | `130` |

- **`render_mode`**:

Expand All @@ -127,6 +126,16 @@ We incorporated 8 actions in this environment to enable the use of agents traine

- **`prob_matrix_path`**: This **string** parameter allows the user to specify the path to file of a already simulated probability matrix. The file should be a `.npy` file containing a probability matrix. If this parameter is not specified, the environment will generate a new probability matrix.

- **`particle_amount`**: This **int** parameter allows the user to customize the number of particles used in the `Lagrangian particle model` used to create the probability matrix.

- **`particle_radius`**: This **int** parameter allows the user to `customize` the radius that the particles are randomly placed at the start of the Lagrangian particle model simulation.

- **`num_particle_to_filter_as_noise`**: This **int** parameter allows the user to modify the number of particles in each cell that are filtered to zero. (e.g. if the number of value is `1`, cells with only 1 particle in the end of simulation will be filtered to 0).

- **`start_time`**: This **datetime** parameter allows the user to specify the `start time` of the simulation. If not specified, the simulation will start at the current time.

- **`grid_cell_size`**: This **int** parameter allows the user to specify the `size of the grid` cells in meters. The default value is 130 meters.

## Built in Functions

### `env.reset`:
Expand Down Expand Up @@ -265,19 +274,16 @@ The reward returns a dictionary with the drones names as keys and their respectf

The rewards values goes as follows:

- **`Default Action`**: Every action receives a baseline reward of `0`.
- **`Leaving the Grid`**: A penalty of `-10` is applied if a drone leaves the grid boundaries.
- **`Exceeding Time Limit`**: A penalty of `-100` is imposed if the drone does not locate all the cells before the timestep_limit is exceeded.
- **`Collision`**: If drones collide, each involved drone receives a penalty of `-10`.
- **`Searching a Cell`**: The reward for searching a cell is proportional to the probability p of the cell being searched, denoted as `10 + (1 / (timestep)) * prob_matrix * 1_000`.
- **`complete the serching`**: If all cells are searched, the reward is `100`.
- **`Default Action`**: Every action receives a baseline reward of `-0.2`.
- **`Searching a Cell`**: The reward for searching a cell is proportional to the probability p of the cell being searched, denoted as `1 + (1 - Ts / Ts_limit) * p * n_cells`, being `n_cells` the number of cells with probability greater than 0, Ts being the terminal timestep and Ts_limit the limit of timesteps.
- **`Complete the searching`**: If all cells are searched, the reward is `n_cells + n_cells * (1 - Ts / Ts_limit)`.

### Termination & Truncation

The termination and truncation variables return a dictionary with all drones as keys and boolean as values. By default, these values are set to `False` and will switch to `True` under any of the following conditions:

- **`Collision`**: If two or more drones collide.
- **`Time Limit Exceeded`**: If the simulation's timestep exceeds the `timestep_limit`.
- **`Done searching all cells`**: If the agents have searched all cells with probability > 0.

#### For example, the dictionary might look like this:

Expand Down Expand Up @@ -350,5 +356,9 @@ The `env.save_matrix()` method is not only convenient for saving the probability

`env.close()` will simply close the render window. Not a necessary function but may be used.

## Stay Updated

We appreciate your patience and interest in our work. If you have any questions or need immediate assistance regarding our `Coverage Environment`, please do not hesitate to contact us via our [GitHub Issues page](https://github.com/pfeinsper/drone-swarm-search/issues).

## License
This documentation is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT). See the LICENSE file for more details.
22 changes: 11 additions & 11 deletions docs/Documentation/docsSearch.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,6 @@ while not done:


## General Info

| Import | `from DSSE import DroneSwarmSearch` |
| ------------------ | -------------------------------------------------- |
| Action Space | Discrete (9) |
Expand All @@ -83,7 +82,6 @@ while not done:
| Observation Space | `{droneN: ((x, y), probability_matrix)}` |

### Action Space

| Value | Meaning |
| ----- | ---------------------- |
| 0 | Move Left |
Expand All @@ -100,6 +98,7 @@ while not done:
| Inputs | Possible Values | Default Values |
| ------------- | ------------- | ------------- |
| `grid_size` | `int(N)` | `20` |
| `cell_size` | `int(N)` | `130` |
| `render_mode` | `"ansi" or "human"` | `"ansi"` |
| `render_grid` | `bool` | `False` |
| `render_gradient` | `bool` | `True` |
Expand All @@ -114,7 +113,9 @@ while not done:
| `probability_of_detection`| `float` | `1.0` |
| `pre_render_time` | `int` | `0` |

- **`grid_size`**: Defines the area in which the search will happen. It should always be an integer greater than one.
- **`grid_size`**: Integer value that defines the area in which the search will happen. It should always be an integer greater than one.

- **`cell_size`**: Integer value that defines the size of each cell, in meters..

- **`render_mode`**:

Expand Down Expand Up @@ -274,22 +275,17 @@ An output example can be seen below.

### Reward

The reward returns a dictionary with the drones names as keys and their respectful rewards as values. For example `{'drone0': 1, 'drone1': 89.0, 'drone2': 1}`
The reward returns a dictionary with the drones names as keys and their respectful rewards as values. For example `{'drone0': 1.0, 'drone1': 0.0, 'drone2': 1.0}`

The rewards values goes as follows:

- **`Default Action`**: Every action receives a baseline reward of `0.1`.
- **`Leaving the Grid`**: A penalty of `-200` is applied if a drone leaves the grid boundaries.
- **`Exceeding Time Limit`**: A penalty of `-200` is imposed if the drone does not locate the person before the timestep_limit is exceeded.
- **`Collision`**: If drones collide, each involved drone receives a penalty of `-200`.
- **`Searching a Cell`**: The reward for searching a cell is proportional to the probability p of the cell being searched, denoted as `[0:p]`.
- **`Finding the Person`**: If a drone successfully locates the person within a cell, the reward is `200 + 200 * ((1 - timestep) / timestep_limit)`, encouraging faster discovery.
- **`Default Action`**: Every action receives a baseline reward of `0.0`.
- **`Finding the Person`**: If a drone successfully locates the person within a cell, the reward is `1 + 1 * (1 - timestep / timestep_limit)`, encouraging faster discovery.

### Termination & Truncation

The termination and truncation variables return a dictionary with all drones as keys and boolean as values. By default, these values are set to `False` and will switch to `True` under any of the following conditions:

- **`Collision`**: If two or more drones collide.
- **`Time Limit Exceeded`**: If the simulation's timestep exceeds the `timestep_limit`.
- **`All PIWs Found`**: If all Persons in Water (PIWs) have been successfully located.

Expand Down Expand Up @@ -345,5 +341,9 @@ If you use this package, please consider citing it with this piece of BibTeX:
}
```

## Stay Updated

We appreciate your patience and interest in our work. If you have any questions or need immediate assistance regarding our `Search Environment`, please do not hesitate to contact us via our [GitHub Issues page](https://github.com/pfeinsper/drone-swarm-search/issues).

## License
This documentation is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT). See the LICENSE file for more details.
Loading

0 comments on commit 0212cf0

Please sign in to comment.