A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
position-allocator.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2007 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef POSITION_ALLOCATOR_H
9#define POSITION_ALLOCATOR_H
10
11#include "ns3/object.h"
12#include "ns3/random-variable-stream.h"
13#include "ns3/vector.h"
14
15namespace ns3
16{
17
18/**
19 * @ingroup mobility
20 * @brief Allocate a set of positions. The allocation strategy is implemented in subclasses.
21 *
22 * This is a pure abstract base class.
23 */
25{
26 public:
27 /**
28 * Register this type with the TypeId system.
29 * @return the object TypeId
30 */
31 static TypeId GetTypeId();
33 ~PositionAllocator() override;
34 /**
35 * @return the next chosen position.
36 *
37 * This method _must_ be implement in subclasses.
38 */
39 virtual Vector GetNext() const = 0;
40 /**
41 * Assign a fixed random variable stream number to the random variables
42 * used by this model. Return the number of streams (possibly zero) that
43 * have been assigned.
44 *
45 * This method _must_ be implement in subclasses.
46 *
47 * @param stream first stream index to use
48 * @return the number of stream indices assigned by this model
49 */
50 virtual int64_t AssignStreams(int64_t stream) = 0;
51};
52
53/**
54 * @ingroup mobility
55 * @brief Allocate positions from a deterministic list specified by the user.
56 *
57 * The first call to ListPositionAllocator::GetNext will return the
58 * first element of the list, the second call, the second element, and so on.
59 */
61{
62 public:
63 /**
64 * Register this type with the TypeId system.
65 * @return the object TypeId
66 */
67 static TypeId GetTypeId();
69
70 /**
71 * @brief Add a position to the list of positions
72 * @param v the position to append at the end of the list of positions to return from GetNext.
73 */
74 void Add(Vector v);
75
76 /**
77 * @brief Add the positions listed in a file.
78 * The file should be a simple text file, with one position per line,
79 * either X and Y, or X, Y and Z, in meters. The delimiter can
80 * be any character, such as ',' or '\\t'; the default is a comma ','.
81 *
82 * The file is read using CsvReader, which explains how comments
83 * and whitespace are handled.
84 *
85 * @param [in] filePath The path to the input file.
86 * @param [in] defaultZ The default Z value to use when reading files
87 * with only X and Y positions.
88 * @param [in] delimiter The delimiter character; see CsvReader.
89 */
90 void Add(const std::string filePath, double defaultZ = 0, char delimiter = ',');
91
92 /**
93 * Return the number of positions stored. Note that this will not change
94 * based on calling GetNext(), as the number of positions is not altered
95 * by calling GetNext ().
96 *
97 * @return the number of positions stored
98 */
99 uint32_t GetSize() const;
100 Vector GetNext() const override;
101 int64_t AssignStreams(int64_t stream) override;
102
103 private:
104 std::vector<Vector> m_positions; //!< vector of positions
105 mutable std::vector<Vector>::const_iterator m_current; //!< vector iterator
106};
107
108/**
109 * @ingroup mobility
110 * @brief Allocate positions on a rectangular 2d grid.
111 */
113{
114 public:
115 /**
116 * Register this type with the TypeId system.
117 * @return the object TypeId
118 */
119 static TypeId GetTypeId();
120
121 /**
122 * Determine whether positions are allocated row first or column first.
123 */
125 {
126 /**
127 * In row-first mode, positions are allocated on the first row until
128 * N positions have been allocated. Then, the second row located a yMin + yDelta
129 * is used to allocate positions.
130 */
132 /**
133 * In column-first mode, positions are allocated on the first column until
134 * N positions have been allocated. Then, the second column located a xMin + xDelta
135 * is used to allocate positions.
136 */
138 };
139
141
142 /**
143 * @param xMin the x coordinate where layout will start.
144 */
145 void SetMinX(double xMin);
146 /**
147 * @param yMin the y coordinate where layout will start
148 */
149 void SetMinY(double yMin);
150 /**
151 * @param z the Z coordinate of all the positions allocated
152 */
153 void SetZ(double z);
154 /**
155 * @param deltaX the x interval between two x-consecutive positions.
156 */
157 void SetDeltaX(double deltaX);
158 /**
159 * @param deltaY the y interval between two y-consecutive positions.
160 */
161 void SetDeltaY(double deltaY);
162 /**
163 * @param n the number of positions allocated on each row (or each column)
164 * before switching to the next column (or row).
165 */
166 void SetN(uint32_t n);
167 /**
168 * @param layoutType the type of layout to use (row first or column first).
169 */
170 void SetLayoutType(LayoutType layoutType);
171
172 /**
173 * @return the x coordinate of the first allocated position.
174 */
175 double GetMinX() const;
176 /**
177 * @return the y coordinate of the first allocated position.
178 */
179 double GetMinY() const;
180 /**
181 * @return the x interval between two consecutive x-positions.
182 */
183 double GetDeltaX() const;
184 /**
185 * @return the y interval between two consecutive y-positions.
186 */
187 double GetDeltaY() const;
188 /**
189 * @return the number of positions to allocate on each row or each column.
190 */
191 uint32_t GetN() const;
192 /**
193 * @return the currently-selected layout type.
194 */
195 LayoutType GetLayoutType() const;
196
197 Vector GetNext() const override;
198 int64_t AssignStreams(int64_t stream) override;
199
200 private:
201 mutable uint32_t m_current; //!< currently position
202 LayoutType m_layoutType; //!< currently selected layout type
203 double m_xMin; //!< minimum boundary on x positions
204 double m_yMin; //!< minimum boundary on y positions
205 double m_z; //!< z coordinate of all the positions generated
206 uint32_t m_n; //!< number of positions to allocate on each row or column
207 double m_deltaX; //!< x interval between two consecutive x positions
208 double m_deltaY; //!< y interval between two consecutive y positions
209};
210
211/**
212 * @ingroup mobility
213 * @brief Allocate random positions within a rectangle according to a pair of random variables.
214 */
216{
217 public:
218 /**
219 * Register this type with the TypeId system.
220 * @return the object TypeId
221 */
222 static TypeId GetTypeId();
225
226 /**
227 * @brief Set the random variable stream object that generates x-positions
228 * @param x pointer to a RandomVariableStream object
229 */
231 /**
232 * @brief Set the random variable stream object that generates y-positions
233 * @param y pointer to a RandomVariableStream object
234 */
236 /**
237 * @param z the Z coordinate of all the positions allocated
238 */
239 void SetZ(double z);
240
241 Vector GetNext() const override;
242 int64_t AssignStreams(int64_t stream) override;
243
244 private:
245 Ptr<RandomVariableStream> m_x; //!< pointer to x's random variable stream
246 Ptr<RandomVariableStream> m_y; //!< pointer to y's random variable stream
247 double m_z; //!< z coordinate of all the positions generated
248};
249
250/**
251 * @ingroup mobility
252 * @brief Allocate random positions within a 3D box according to a set of three random variables.
253 */
255{
256 public:
257 /**
258 * Register this type with the TypeId system.
259 * @return the object TypeId
260 */
261 static TypeId GetTypeId();
264
265 /**
266 * @brief Set the random variable stream object that generates x-positions
267 * @param x pointer to a RandomVariableStream object
268 */
270 /**
271 * @brief Set the random variable stream object that generates y-positions
272 * @param y pointer to a RandomVariableStream object
273 */
275 /**
276 * @brief Set the random variable stream object that generates z-positions
277 * @param z pointer to a RandomVariableStream object
278 */
280
281 Vector GetNext() const override;
282 int64_t AssignStreams(int64_t stream) override;
283
284 private:
285 Ptr<RandomVariableStream> m_x; //!< pointer to x's random variable stream
286 Ptr<RandomVariableStream> m_y; //!< pointer to y's random variable stream
287 Ptr<RandomVariableStream> m_z; //!< pointer to z's random variable stream
288};
289
290/**
291 * @ingroup mobility
292 * @brief Allocate random positions within a disc according to
293 * a given distribution for the polar coordinates of each node
294 * with respect to the provided center of the disc.
295 *
296 * @note With the default uniform distribution over \f$2 \pi\f$ in \c theta and a
297 * uniform distribution for \c rho this position allocator will *not*
298 * uniformly populate the disc. The radial distribution will be proportional
299 * to \f$\frac{1}{r^2}\f$.
300 *
301 * To get a uniform distribution over a circle use the UniformDiscPositionAllocator.
302 */
304{
305 public:
306 /**
307 * Register this type with the TypeId system.
308 * @return the object TypeId
309 */
310 static TypeId GetTypeId();
313
314 /**
315 * @brief Set the random variable that generates position angle, in radians.
316 * @param theta Random variable that represents the angle in radians of a position in a random
317 * disc.
318 */
320 /**
321 * @brief Set the random variable that generates position radius, in meters
322 * @param rho Random variable that represents the radius of a position, in meters, in a random
323 * disc.
324 */
326 /**
327 * @param x the X coordinate of the center of the disc
328 */
329 void SetX(double x);
330 /**
331 * @param y the Y coordinate of the center of the disc
332 */
333 void SetY(double y);
334 /**
335 * @param z the Z coordinate of all the positions allocated
336 */
337 void SetZ(double z);
338
339 Vector GetNext() const override;
340 int64_t AssignStreams(int64_t stream) override;
341
342 private:
343 Ptr<RandomVariableStream> m_theta; //!< pointer to theta's random variable stream
344 Ptr<RandomVariableStream> m_rho; //!< pointer to rho's random variable stream
345 double m_x; //!< x coordinate of center of disc
346 double m_y; //!< y coordinate of center of disc
347 double m_z; //!< z coordinate of the disc
348};
349
350/**
351 * @ingroup mobility
352 * @brief Allocate the positions uniformly (with constant density) randomly within a disc.
353 *
354 * UniformDiscPositionAllocator allocates the positions randomly within a disc \f$ D \f$ lying on
355 * the plane \f$ z\f$ and having center at coordinates \f$ (x,y,z) \f$ and radius \f$ \rho \f$. The
356 * random positions are chosen such that, for any subset \f$ S \subset D \f$, the expected value of
357 * the fraction of points which fall into \f$ S \subset D \f$ corresponds to \f$ \frac{|S|}{|D|}
358 * \f$, i.e., to the ratio of the area of the subset to the area of the whole disc.
359 *
360 * @note using UniformDiscPositionAllocator is not equivalent to using
361 * a RandomDiscPositionAllocator with a uniformly-distributed radius,
362 * since doing that would result in a point distribution which is
363 * more dense towards the center of the disc.
364 */
366{
367 public:
368 /**
369 * Register this type with the TypeId system.
370 * @return the object TypeId
371 */
372 static TypeId GetTypeId();
375
376 /**
377 * @param rho the value of the radius of the disc
378 */
379 void SetRho(double rho);
380
381 /**
382 * @param x the X coordinate of the center of the disc
383 */
384 void SetX(double x);
385
386 /**
387 * @param y the Y coordinate of the center of the disc
388 */
389 void SetY(double y);
390
391 /**
392 * @param z the Z coordinate of all the positions allocated
393 */
394 void SetZ(double z);
395
396 Vector GetNext() const override;
397 int64_t AssignStreams(int64_t stream) override;
398
399 private:
400 Ptr<UniformRandomVariable> m_rv; //!< pointer to uniform random variable
401 double m_rho; //!< value of the radius of the disc
402 double m_x; //!< x coordinate of center of disc
403 double m_y; //!< y coordinate of center of disc
404 double m_z; //!< z coordinate of the disc
405};
406
407} // namespace ns3
408
409#endif /* RANDOM_POSITION_H */
Allocate positions on a rectangular 2d grid.
double m_deltaX
x interval between two consecutive x positions
double m_deltaY
y interval between two consecutive y positions
LayoutType
Determine whether positions are allocated row first or column first.
@ COLUMN_FIRST
In column-first mode, positions are allocated on the first column until N positions have been allocat...
@ ROW_FIRST
In row-first mode, positions are allocated on the first row until N positions have been allocated.
int64_t AssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
uint32_t m_current
currently position
double m_yMin
minimum boundary on y positions
Vector GetNext() const override
double m_z
z coordinate of all the positions generated
LayoutType m_layoutType
currently selected layout type
double m_xMin
minimum boundary on x positions
uint32_t m_n
number of positions to allocate on each row or column
static TypeId GetTypeId()
Register this type with the TypeId system.
void SetLayoutType(LayoutType layoutType)
Allocate positions from a deterministic list specified by the user.
int64_t AssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
void Add(Vector v)
Add a position to the list of positions.
uint32_t GetSize() const
Return the number of positions stored.
static TypeId GetTypeId()
Register this type with the TypeId system.
std::vector< Vector >::const_iterator m_current
vector iterator
Vector GetNext() const override
std::vector< Vector > m_positions
vector of positions
A base class which provides memory management and object aggregation.
Definition object.h:78
Allocate a set of positions.
virtual int64_t AssignStreams(int64_t stream)=0
Assign a fixed random variable stream number to the random variables used by this model.
static TypeId GetTypeId()
Register this type with the TypeId system.
virtual Vector GetNext() const =0
Smart pointer class similar to boost::intrusive_ptr.
Allocate random positions within a 3D box according to a set of three random variables.
void SetZ(Ptr< RandomVariableStream > z)
Set the random variable stream object that generates z-positions.
Ptr< RandomVariableStream > m_x
pointer to x's random variable stream
Ptr< RandomVariableStream > m_y
pointer to y's random variable stream
void SetX(Ptr< RandomVariableStream > x)
Set the random variable stream object that generates x-positions.
int64_t AssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
void SetY(Ptr< RandomVariableStream > y)
Set the random variable stream object that generates y-positions.
static TypeId GetTypeId()
Register this type with the TypeId system.
Ptr< RandomVariableStream > m_z
pointer to z's random variable stream
Allocate random positions within a disc according to a given distribution for the polar coordinates o...
double m_y
y coordinate of center of disc
Ptr< RandomVariableStream > m_rho
pointer to rho's random variable stream
static TypeId GetTypeId()
Register this type with the TypeId system.
void SetRho(Ptr< RandomVariableStream > rho)
Set the random variable that generates position radius, in meters.
double m_x
x coordinate of center of disc
void SetTheta(Ptr< RandomVariableStream > theta)
Set the random variable that generates position angle, in radians.
int64_t AssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
Ptr< RandomVariableStream > m_theta
pointer to theta's random variable stream
double m_z
z coordinate of the disc
Allocate random positions within a rectangle according to a pair of random variables.
int64_t AssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
Ptr< RandomVariableStream > m_y
pointer to y's random variable stream
Ptr< RandomVariableStream > m_x
pointer to x's random variable stream
void SetY(Ptr< RandomVariableStream > y)
Set the random variable stream object that generates y-positions.
static TypeId GetTypeId()
Register this type with the TypeId system.
void SetX(Ptr< RandomVariableStream > x)
Set the random variable stream object that generates x-positions.
double m_z
z coordinate of all the positions generated
a unique identifier for an interface.
Definition type-id.h:48
Allocate the positions uniformly (with constant density) randomly within a disc.
static TypeId GetTypeId()
Register this type with the TypeId system.
int64_t AssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
double m_rho
value of the radius of the disc
double m_x
x coordinate of center of disc
double m_y
y coordinate of center of disc
Ptr< UniformRandomVariable > m_rv
pointer to uniform random variable
double m_z
z coordinate of the disc
Every class exported by the ns3 library is enclosed in the ns3 namespace.