Skip to content

Commit 9a86923

Browse files
Saurav AgarwalSaurav Agarwal
Saurav Agarwal
authored and
Saurav Agarwal
committed
Add docs
1 parent 26519c9 commit 9a86923

37 files changed

+1536
-854
lines changed

cppsrc/core/include/CoverageControl/algorithms/lloyd_local_sensor_global_comm.h renamed to cppsrc/core/include/CoverageControl/algorithms/centralized_cvt.h

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,25 @@
1-
/**
2-
* The coverage control algorithm uses Lloyd's algorithm on accumulated local map of individual robots, i.e., a robot has knowledge only about the regions it has visited.
3-
* Communication radius is not considered
1+
/*!
2+
* This file is part of the CoverageControl library
3+
*
4+
* The coverage control algorithm uses centralized Centroidal Voronoi Tessellation (CVT) or Lloyd's algorithm on accumulated local map of individual robots, i.e., a robot has knowledge only about the regions it has visited.
5+
* Communication radius is not considered.
46
* The algorithm is online---it takes localized actions based on the current robot positions.
5-
**/
7+
*
8+
* @author Saurav Agarwal
9+
* @contact [email protected], [email protected]
10+
* Repository: https://github.com/KumarRobotics/CoverageControl
11+
*
12+
* The CoverageControl library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
13+
*
14+
* DISCLAIMER OF WARRANTIES: THE SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE OR OF NON-INFRINGEMENT. YOU BEAR ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE OR HARDWARE.
15+
*
16+
* SUPPORT AND MAINTENANCE: No support, installation, or training is provided.
17+
*
18+
* You should have received a copy of the GNU General Public License along with CoverageControl library. If not, see <https://www.gnu.org/licenses/>.
19+
*/
620

7-
#ifndef COVERAGECONTROL_ALGORITHMS_LLOYD_LOCAL_SENSOR_GLOBAL_COMM_H_
8-
#define COVERAGECONTROL_ALGORITHMS_LLOYD_LOCAL_SENSOR_GLOBAL_COMM_H_
21+
#ifndef COVERAGECONTROL_ALGORITHMS_CENTRALIZED_CVT_H_
22+
#define COVERAGECONTROL_ALGORITHMS_CENTRALIZED_CVT_H_
923

1024
#include <vector>
1125
#include <fstream>
@@ -22,7 +36,12 @@
2236

2337
namespace CoverageControl {
2438

25-
class LloydLocalSensorGlobalComm {
39+
/*!
40+
* The coverage control algorithm uses centralized Centroidal Voronoi Tessellation (CVT) or Lloyd's algorithm on accumulated local map of individual robots, i.e., a robot has knowledge only about the regions it has visited.
41+
* Communication radius is not considered.
42+
* The algorithm is online---it takes localized actions based on the current robot positions.
43+
**/
44+
class CentralizedCVT {
2645
private:
2746
Parameters const params_;
2847
size_t num_robots_ = 0;
@@ -35,7 +54,7 @@ namespace CoverageControl {
3554
bool continue_flag_ = false;
3655

3756
public:
38-
LloydLocalSensorGlobalComm(
57+
CentralizedCVT (
3958
Parameters const &params,
4059
size_t const &num_robots,
4160
CoverageSystem &env) :
@@ -98,4 +117,4 @@ namespace CoverageControl {
98117
};
99118

100119
} /* namespace CoverageControl */
101-
#endif /* COVERAGECONTROL_ALGORITHMS_LLOYD_LOCAL_SENSOR_GLOBAL_COMM_H_ */
120+
#endif /* COVERAGECONTROL_ALGORITHMS_CENTRALIZED_CVT_H_ */

cppsrc/core/include/CoverageControl/algorithms/lloyd_global_online.h renamed to cppsrc/core/include/CoverageControl/algorithms/clairvyont_cvt.h

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,25 @@
1-
/**
2-
* The coverage control algorithm uses Lloyd's algorithm on global world IDF map, i.e., it has knowledge of the entire map.
1+
/*!
2+
* This file is part of the CoverageControl library
3+
*
4+
* The coverage control algorithm uses Centroidal Voronoi Tessellation (CVT) or Lloyd's algorithm on global world IDF map, i.e., it has knowledge of the entire map.
35
* Communication is not considered in this algorithm, i.e., all robots are assumed to be able to communicate with each other.
46
* However, the algorithm is online---it takes localized actions based on the current robot positions.
5-
**/
7+
*
8+
* @author Saurav Agarwal
9+
* @contact [email protected], [email protected]
10+
* Repository: https://github.com/KumarRobotics/CoverageControl
11+
*
12+
* The CoverageControl library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
13+
*
14+
* DISCLAIMER OF WARRANTIES: THE SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE OR OF NON-INFRINGEMENT. YOU BEAR ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE OR HARDWARE.
15+
*
16+
* SUPPORT AND MAINTENANCE: No support, installation, or training is provided.
17+
*
18+
* You should have received a copy of the GNU General Public License along with CoverageControl library. If not, see <https://www.gnu.org/licenses/>.
19+
*/
620

7-
#ifndef COVERAGECONTROL_ALGORITHMS_LLOYD_GLOBAL_ONLINE_H_
8-
#define COVERAGECONTROL_ALGORITHMS_LLOYD_GLOBAL_ONLINE_H_
21+
#ifndef COVERAGECONTROL_ALGORITHMS_CLAIRVOYANT_CVT_H_
22+
#define COVERAGECONTROL_ALGORITHMS_CLAIRVOYANT_CVT_H_
923

1024
#include <vector>
1125
#include <fstream>
@@ -20,11 +34,16 @@
2034
#include "../typedefs.h"
2135
#include "../coverage_system.h"
2236
#include "../map_utils.h"
23-
#include "lloyd_algorithms.h"
2437

2538
namespace CoverageControl {
2639

27-
class LloydGlobalOnline {
40+
/*!
41+
* Clairvoyant CVT algorithm
42+
* The algorithm has knowledge of the entire map in a centralized manner.
43+
* It uses the CVT to compute centroids of the Voronoi cells and assigns the robots to the centroids.
44+
* The algorithm is online---it takes localized actions based on the current robot positions.
45+
*/
46+
class ClairvyontCVT {
2847
private:
2948
Parameters const params_;
3049
size_t num_robots_ = 0;
@@ -37,7 +56,7 @@ namespace CoverageControl {
3756
bool continue_flag_ = false;
3857

3958
public:
40-
LloydGlobalOnline(
59+
ClairvyontCVT (
4160
Parameters const &params,
4261
size_t const &num_robots,
4362
CoverageSystem &env) :
@@ -100,4 +119,4 @@ namespace CoverageControl {
100119
};
101120

102121
} /* namespace CoverageControl */
103-
#endif /* COVERAGECONTROL_ALGORITHMS_LLOYD_GLOBAL_ONLINE_H_ */
122+
#endif /* COVERAGECONTROL_ALGORITHMS_CLAIRVOYANT_CVT_H_ */

cppsrc/core/include/CoverageControl/algorithms/lloyd_local_voronoi.h renamed to cppsrc/core/include/CoverageControl/algorithms/decentralized_cvt.h

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,26 @@
1-
/**
2-
* The coverage control algorithm uses Lloyd's algorithm on accumulated local map of individual robots, i.e., a robot has knowledge only about the regions it has visited.
1+
/*!
2+
* This file is part of the CoverageControl library
3+
*
4+
* The coverage control algorithm uses Centroidal Voronoi Tessellation (CVT) or Lloyd's algorithm on accumulated local map of individual robots, i.e., a robot has knowledge only about the regions it has visited.
35
* Communication limitations are considered in the computation of voronoi.
46
* Each robot computes the voronoi based on its local map and the positions of other robots within its communication range.
57
* The algorithm is online---it takes localized actions based on the current robot positions.
6-
**/
7-
8-
#ifndef COVERAGECONTROL_ALGORITHMS_LLOYD_LOCAL_VORONOI_H_
9-
#define COVERAGECONTROL_ALGORITHMS_LLOYD_LOCAL_VORONOI_H_
8+
*
9+
* @author Saurav Agarwal
10+
* @contact [email protected], [email protected]
11+
* Repository: https://github.com/KumarRobotics/CoverageControl
12+
*
13+
* The CoverageControl library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
14+
*
15+
* DISCLAIMER OF WARRANTIES: THE SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE OR OF NON-INFRINGEMENT. YOU BEAR ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE OR HARDWARE.
16+
*
17+
* SUPPORT AND MAINTENANCE: No support, installation, or training is provided.
18+
*
19+
* You should have received a copy of the GNU General Public License along with CoverageControl library. If not, see <https://www.gnu.org/licenses/>.
20+
*/
21+
22+
#ifndef COVERAGECONTROL_ALGORITHMS_DECENTRALIZED_CVT_H_
23+
#define COVERAGECONTROL_ALGORITHMS_DECENTRALIZED_CVT_H_
1024

1125
#include <vector>
1226
#include <fstream>
@@ -21,12 +35,16 @@
2135
#include "../typedefs.h"
2236
#include "../coverage_system.h"
2337
#include "../map_utils.h"
24-
#include "lloyd_algorithms.h"
2538
#include "../extern/lsap/Hungarian.h"
2639

2740
namespace CoverageControl {
2841

29-
class LloydLocalVoronoi {
42+
/*!
43+
* This class implements the decentralized CVT algorithm.
44+
* The algorithm uses the local map of each robot and the positions of other robots within its communication range to compute the voronoi.
45+
* The algorithm is online---it takes localized actions based on the current robot positions.
46+
*/
47+
class DecentralizedCVT {
3048
private:
3149
Parameters const params_;
3250
size_t num_robots_ = 0;
@@ -38,7 +56,7 @@ namespace CoverageControl {
3856
bool continue_flag_ = false;
3957

4058
public:
41-
LloydLocalVoronoi(
59+
DecentralizedCVT (
4260
Parameters const &params,
4361
size_t const &num_robots,
4462
CoverageSystem &env) :
@@ -138,4 +156,4 @@ namespace CoverageControl {
138156
};
139157

140158
} /* namespace CoverageControl */
141-
#endif /* COVERAGECONTROL_ALGORITHMS_LLOYD_LOCAL_VORONOI_H_ */
159+
#endif /* COVERAGECONTROL_ALGORITHMS_DECENTRALIZED_CVT_H_ */

cppsrc/core/include/CoverageControl/algorithms/lloyd_algorithms.h renamed to cppsrc/core/include/CoverageControl/algorithms/near_optimal_cvt.h

Lines changed: 27 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,26 @@
1-
/**
1+
/*!
2+
* This file is part of the CoverageControl library
3+
* Near-optimal Centroidal Voronoi Tessellation (CVT) algorithms.
4+
* The algorithm has knowledge of the entire map in a centralized manner.
5+
* It spawns random sites and iteratively moves them to the centroid of the Voronoi cell, until convergence.
6+
* Hungarian algorithm is used to assign the robots to the sites.
7+
* Out of the multiple tries, the best Voronoi is selected based on the objective function.
28
*
3-
**/
9+
* @author Saurav Agarwal
10+
* @contact [email protected], [email protected]
11+
* Repository: https://github.com/KumarRobotics/CoverageControl
12+
*
13+
* The CoverageControl library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
14+
*
15+
* DISCLAIMER OF WARRANTIES: THE SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE OR OF NON-INFRINGEMENT. YOU BEAR ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE OR HARDWARE.
16+
*
17+
* SUPPORT AND MAINTENANCE: No support, installation, or training is provided.
18+
*
19+
* You should have received a copy of the GNU General Public License along with CoverageControl library. If not, see <https://www.gnu.org/licenses/>.
20+
*/
421

5-
#ifndef COVERAGECONTROL_ALGORITHMS_LLOYD_ALGORITHMS_H_
6-
#define COVERAGECONTROL_ALGORITHMS_LLOYD_ALGORITHMS_H_
22+
#ifndef COVERAGECONTROL_ALGORITHMS_NEAR_OPTIMAL_CVT_H_
23+
#define COVERAGECONTROL_ALGORITHMS_NEAR_OPTIMAL_CVT_H_
724

825
#include <vector>
926
#include <fstream>
@@ -20,7 +37,7 @@
2037

2138
namespace CoverageControl {
2239

23-
inline auto LloydOffline(int const num_tries, int const max_iterations, int const num_sites, MapType const &map, int const map_size, double const res) {
40+
inline auto NearOptimalCVT(int const num_tries, int const max_iterations, int const num_sites, MapType const &map, int const map_size, double const res) {
2441
std::random_device rd_; //Will be used to obtain a seed for the random number engine
2542
std::mt19937 gen_;
2643
std::srand(time(NULL));
@@ -73,9 +90,9 @@ namespace CoverageControl {
7390
return all_voronoi_cells[best_vornoi_idx];
7491
}
7592

76-
inline auto LloydOffline(int const num_tries, int const max_iterations, int const num_sites, MapType const &map, int const map_size, double const res, PointVector const &positions, Voronoi &voronoi) {
93+
inline auto NearOptimalCVT(int const num_tries, int const max_iterations, int const num_sites, MapType const &map, int const map_size, double const res, PointVector const &positions, Voronoi &voronoi) {
7794

78-
voronoi = LloydOffline(num_tries, max_iterations, num_sites, map, map_size, res);
95+
voronoi = NearOptimalCVT(num_tries, max_iterations, num_sites, map, map_size, res);
7996
auto voronoi_cells = voronoi.GetVoronoiCells();
8097
std::vector <std::vector<double>> cost_matrix;
8198
cost_matrix.resize(num_sites, std::vector<double>(num_sites));
@@ -98,10 +115,10 @@ namespace CoverageControl {
98115
return goals;
99116
}
100117

101-
inline auto LloydOffline(int const num_tries, int const max_iterations, int const num_sites, MapType const &map, int const map_size, double const res, PointVector const &positions) {
118+
inline auto NearOptimalCVT(int const num_tries, int const max_iterations, int const num_sites, MapType const &map, int const map_size, double const res, PointVector const &positions) {
102119
Voronoi voronoi;
103-
return LloydOffline(num_tries, max_iterations, num_sites, map, map_size, res, positions, voronoi);
120+
return NearOptimalCVT(num_tries, max_iterations, num_sites, map, map_size, res, positions, voronoi);
104121
}
105122

106123
} /* namespace CoverageControl */
107-
#endif /* COVERAGECONTROL_ALGORITHMS_LLOYD_ALGORITHMS_H_ */
124+
#endif /* COVERAGECONTROL_ALGORITHMS_NEAR_OPTIMAL_CVT_H_ */

‎cppsrc/core/include/CoverageControl/algorithms/oracle_bang_explore_exploit.h‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,21 @@
1-
/**
1+
/*!
2+
* This file is part of the CoverageControl library
3+
*
24
* First trial of oracle with exploration and exploitation.
35
* The oracle uses complete information about the environment.
4-
**/
6+
*
7+
* @author Saurav Agarwal
8+
* @contact [email protected], [email protected]
9+
* Repository: https://github.com/KumarRobotics/CoverageControl
10+
*
11+
* The CoverageControl library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
12+
*
13+
* DISCLAIMER OF WARRANTIES: THE SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE OR OF NON-INFRINGEMENT. YOU BEAR ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE OR HARDWARE.
14+
*
15+
* SUPPORT AND MAINTENANCE: No support, installation, or training is provided.
16+
*
17+
* You should have received a copy of the GNU General Public License along with CoverageControl library. If not, see <https://www.gnu.org/licenses/>.
18+
*/
519

620
#ifndef COVERAGECONTROL_ALGORITHMS_ORACLE_BANG_EXPLORE_EXPLOIT_H_
721
#define COVERAGECONTROL_ALGORITHMS_ORACLE_BANG_EXPLORE_EXPLOIT_H_
@@ -18,7 +32,6 @@
1832
#include "../parameters.h"
1933
#include "../typedefs.h"
2034
#include "../coverage_system.h"
21-
#include "lloyd_algorithms.h"
2235
#include "../extern/lsap/Hungarian.h"
2336

2437
namespace CoverageControl {

‎cppsrc/core/include/CoverageControl/algorithms/oracle_explore_exploit.h‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,21 @@
1-
/**
1+
/*!
2+
* This file is part of the CoverageControl library
3+
*
24
* Old trial of exploration and exploitation
35
* Uses system map for exploration as well.
4-
**/
6+
*
7+
* @author Saurav Agarwal
8+
* @contact [email protected], [email protected]
9+
* Repository: https://github.com/KumarRobotics/CoverageControl
10+
*
11+
* The CoverageControl library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
12+
*
13+
* DISCLAIMER OF WARRANTIES: THE SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE OR OF NON-INFRINGEMENT. YOU BEAR ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE OR HARDWARE.
14+
*
15+
* SUPPORT AND MAINTENANCE: No support, installation, or training is provided.
16+
*
17+
* You should have received a copy of the GNU General Public License along with CoverageControl library. If not, see <https://www.gnu.org/licenses/>.
18+
*/
519

620
#ifndef COVERAGECONTROL_ALGORITHMS_ORACLE_EXPLORE_EXPLOIT_H_
721
#define COVERAGECONTROL_ALGORITHMS_ORACLE_EXPLORE_EXPLOIT_H_
@@ -15,7 +29,7 @@
1529
#include "../parameters.h"
1630
#include "../typedefs.h"
1731
#include "../coverage_system.h"
18-
#include "lloyd_algorithms.h"
32+
#include "near_optimal_cvt.h"
1933
#include "../extern/lsap/Hungarian.h"
2034

2135
namespace CoverageControl {
@@ -95,7 +109,7 @@ namespace CoverageControl {
95109
/* goals_[iRobot] = voronoi_cells_[iRobot].centroid; */
96110
/* } */
97111
robot_global_positions_ = env_.GetRobotPositions();
98-
voronoi_ = LloydOffline(params_.pLloydNumTries, params_.pLloydMaxIterations, num_robots_, oracle_map_, params_.pWorldMapSize, params_.pResolution);
112+
voronoi_ = NearOptimalCVT(params_.pLloydNumTries, params_.pLloydMaxIterations, num_robots_, oracle_map_, params_.pWorldMapSize, params_.pResolution);
99113
voronoi_cells_ = voronoi_.GetVoronoiCells();
100114
#pragma omp parallel for num_threads(num_robots_)
101115
for(size_t iRobot = 0; iRobot < num_robots_; ++iRobot) {

‎cppsrc/core/include/CoverageControl/algorithms/oracle_global_offline.h‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,23 @@
1+
/*!
2+
* This file is part of the CoverageControl library
3+
*
4+
* Global offline oracle: has complete information about the environment.
5+
* Use full communication between robots.
6+
* Tries multiple random sites for initial locations.
7+
* Uses Hungarian algorithm to assign robots to goal positions.
8+
*
9+
* @author Saurav Agarwal
10+
* @contact [email protected], [email protected]
11+
* Repository: https://github.com/KumarRobotics/CoverageControl
12+
*
13+
* The CoverageControl library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
14+
*
15+
* DISCLAIMER OF WARRANTIES: THE SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OR PURPOSE OR OF NON-INFRINGEMENT. YOU BEAR ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWARE OR HARDWARE.
16+
*
17+
* SUPPORT AND MAINTENANCE: No support, installation, or training is provided.
18+
*
19+
* You should have received a copy of the GNU General Public License along with CoverageControl library. If not, see <https://www.gnu.org/licenses/>.
20+
*/
121
/**
222
* Global offline oracle: has complete information about the environment.
323
* Use full communication between robots.
@@ -21,7 +41,7 @@
2141
#include "../typedefs.h"
2242
#include "../coverage_system.h"
2343
#include "../map_utils.h"
24-
#include "lloyd_algorithms.h"
44+
#include "near_optimal_cvt.h"
2545
#include "../extern/lsap/Hungarian.h"
2646

2747
namespace CoverageControl {
@@ -59,7 +79,7 @@ namespace CoverageControl {
5979
auto &GetVoronoi() { return voronoi_; }
6080

6181
void ComputeGoals() {
62-
goals_ = LloydOffline(params_.pLloydNumTries, params_.pLloydMaxIterations, num_robots_, env_.GetWorldIDF(), params_.pWorldMapSize, params_.pResolution, robot_global_positions_, voronoi_);
82+
goals_ = NearOptimalCVT(params_.pLloydNumTries, params_.pLloydMaxIterations, num_robots_, env_.GetWorldIDF(), params_.pWorldMapSize, params_.pResolution, robot_global_positions_, voronoi_);
6383
}
6484

6585
bool Step() {

0 commit comments

Comments
 (0)