A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
mobility-helper.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8
9#ifndef MOBILITY_HELPER_H
10#define MOBILITY_HELPER_H
11
12#include "ns3/attribute.h"
13#include "ns3/node-container.h"
14#include "ns3/object-factory.h"
15#include "ns3/output-stream-wrapper.h"
16#include "ns3/position-allocator.h"
17
18#include <vector>
19
20namespace ns3
21{
22
23class PositionAllocator;
24class MobilityModel;
25
26/**
27 * @ingroup mobility
28 * @brief Helper class used to assign positions and mobility models to nodes.
29 *
30 * MobilityHelper::Install is the most important method here.
31 */
33{
34 public:
35 /**
36 * Construct a Mobility Helper which is used to make life easier when working
37 * with mobility models.
38 */
40
41 /**
42 * Destroy a Mobility Helper
43 */
45
46 /**
47 * Set the position allocator which will be used to allocate the initial
48 * position of every node initialized during MobilityModel::Install.
49 *
50 * @param allocator allocate initial node positions
51 */
53
54 /**
55 * @tparam Ts \deduced Argument types
56 * @param type the type of mobility model to use.
57 * @param [in] args Name and AttributeValue pairs to set.
58 */
59 template <typename... Ts>
60 void SetPositionAllocator(std::string type, Ts&&... args);
61
62 /**
63 * @tparam Ts \deduced Argument types
64 * @param type the type of mobility model to use.
65 * @param [in] args Name and AttributeValue pairs to set.
66 *
67 * Calls to MobilityHelper::Install will create an instance of a matching
68 * mobility model for each node.
69 */
70 template <typename... Ts>
71 void SetMobilityModel(std::string type, Ts&&... args);
72
73 /**
74 * @param reference item to push.
75 *
76 * Push an item on the top of the stack of "reference mobility models".
77 * The input item should be a node instance to which a mobility model
78 * has already been aggregated (usually by a call to Install).
79 *
80 * If this stack is not empty when MobilityHelper::Install
81 * is called, the model from the top of the stack is used
82 * to create a ns3::HierarchicalMobilityModel to make the
83 * newly-created models define their positions relative to that
84 * of the parent mobility model.
85 *
86 * This method is typically used to create hierarchical mobility
87 * patterns and positions by starting with the large-scale mobility
88 * features, and, then, defining the smaller-scale movements relative
89 * to a few reference points in the large-scale model.
90 */
92 /**
93 * @param referenceName named item to push.
94 *
95 * Push an item on the top of the stack of "reference mobility models".
96 * The input item should be a node instance to which a mobility model
97 * has already been aggregated (usually by a call to Install).
98 *
99 * If this stack is not empty when MobilityHelper::Install
100 * is called, the model from the top of the stack is used
101 * to create a ns3::HierarchicalMobilityModel to make the
102 * newly-created models define their positions relative to that
103 * of the parent mobility model.
104 *
105 * This method is typically used to create hierarchical mobility
106 * patterns and positions by starting with the large-scale mobility
107 * features, and, then, defining the smaller-scale movements relative
108 * to a few reference points in the large-scale model.
109 */
110 void PushReferenceMobilityModel(std::string referenceName);
111 /**
112 * Remove the top item from the top of the stack of
113 * "reference mobility models".
114 */
116
117 /**
118 * @return a string which contains the TypeId of the currently-selected
119 * mobility model.
120 */
121 std::string GetMobilityModelType() const;
122
123 /**
124 * @brief "Layout" a single node according to the current position allocator type.
125 *
126 * This method creates an instance of a ns3::MobilityModel subclass (the
127 * type of which was set with MobilityHelper::SetMobilityModel), aggregates
128 * it to the provided node, and sets an initial position based on the current
129 * position allocator (set through MobilityHelper::SetPositionAllocator).
130 *
131 * @param node The node to "layout."
132 */
133 void Install(Ptr<Node> node) const;
134 /**
135 * @brief "Layout" a single node according to the current position allocator type.
136 *
137 * This method creates an instance of a ns3::MobilityModel subclass (the
138 * type of which was set with MobilityHelper::SetMobilityModel), aggregates
139 * it to the provided node, and sets an initial position based on the current
140 * position allocator (set through MobilityHelper::SetPositionAllocator).
141 *
142 * @param nodeName The name of the node to "layout."
143 */
144 void Install(std::string nodeName) const;
145
146 /**
147 * @brief Layout a collection of nodes according to the current position allocator type.
148 *
149 * For each node in the provided NodeContainer, this method creates an instance
150 * of a ns3::MobilityModel subclass (the type of which was set with
151 * MobilityHelper::SetMobilityModel), aggregates it to the node, and sets an
152 * initial position based on the current position allocator (set through
153 * MobilityHelper::SetPositionAllocator).
154 *
155 * @param container The set of nodes to layout.
156 */
157 void Install(NodeContainer container) const;
158
159 /**
160 * Perform the work of MobilityHelper::Install on _all_ nodes which
161 * exist in the simulation.
162 */
163 void InstallAll() const;
164
165 /**
166 * @param stream an output stream wrapper
167 * @param nodeid the id of the node to generate ascii output for.
168 *
169 * Enable ascii output to record course changes from the mobility model
170 * associated with the specified nodeid and dump that to the specified output
171 * stream. If the Node does not have a MobilityModel aggregated,
172 * this method will not produce any output.
173 */
174 static void EnableAscii(Ptr<OutputStreamWrapper> stream, uint32_t nodeid);
175 /**
176 * @param stream an output stream wrapper
177 * @param n node container
178 *
179 * Enable ascii output to record course changes from the mobility models
180 * associated to the the nodes in the input container and dump that to the
181 * specified output stream. Nodes that do not have a MobilityModel
182 * aggregated will not result in any output.
183 */
185 /**
186 * @param stream an output stream wrapper
187 *
188 * Enable ascii output to record course changes from the mobility models
189 * associated to every node in the system and dump that to the specified
190 * output stream. Nodes that do not have a MobilityModel aggregated
191 * will not result in any output.
192 */
193 static void EnableAsciiAll(Ptr<OutputStreamWrapper> stream);
194 /**
195 * Assign a fixed random variable stream number to the random variables
196 * used by the mobility models on these nodes. Return the number of
197 * streams (possibly zero) that have been assigned. The Install()
198 * method should have previously been called by the user.
199 *
200 * @note If the PositionAllocator used contains random variables, they
201 * will not be affected by this call to AssignStreams because they are
202 * used earlier during Install() time. If the user needs to assign a fixed
203 * stream number to a PositionAllocator used with this helper, the user
204 * should instantiate it outside of the helper, call AssignStreams() on
205 * it, and then pass the pointer of it to this helper.
206 *
207 * @param c NodeContainer of the set of nodes for which the MobilityModels
208 * should be modified to use a fixed stream
209 * @param stream first stream index to use
210 * @return the number of stream indices assigned by this helper
211 */
212 int64_t AssignStreams(NodeContainer c, int64_t stream);
213
214 /**
215 * @param n1 node 1
216 * @param n2 node 2
217 * @return the distance (squared), in meters, between two nodes
218 */
219 static double GetDistanceSquaredBetween(Ptr<Node> n1, Ptr<Node> n2);
220
221 private:
222 /**
223 * Output course change events from mobility model to output stream
224 * @param stream output stream
225 * @param mobility mobility model
226 */
228 std::vector<Ptr<MobilityModel>> m_mobilityStack; //!< Internal stack of mobility models
229 ObjectFactory m_mobility; //!< Object factory to create mobility objects
231 m_position; //!< Position allocator for use in hierarchical mobility model
232};
233
234/***************************************************************
235 * Implementation of the templates declared above.
236 ***************************************************************/
237
238template <typename... Ts>
239void
240MobilityHelper::SetPositionAllocator(std::string type, Ts&&... args)
241{
242 ObjectFactory pos(type, std::forward<Ts>(args)...);
244}
245
246template <typename... Ts>
247void
248MobilityHelper::SetMobilityModel(std::string type, Ts&&... args)
249{
250 m_mobility.SetTypeId(type);
251 m_mobility.Set(std::forward<Ts>(args)...);
252}
253
254} // namespace ns3
255
256#endif /* MOBILITY_HELPER_H */
Helper class used to assign positions and mobility models to nodes.
void PopReferenceMobilityModel()
Remove the top item from the top of the stack of "reference mobility models".
int64_t AssignStreams(NodeContainer c, int64_t stream)
Assign a fixed random variable stream number to the random variables used by the mobility models on t...
static void EnableAsciiAll(Ptr< OutputStreamWrapper > stream)
static double GetDistanceSquaredBetween(Ptr< Node > n1, Ptr< Node > n2)
void Install(Ptr< Node > node) const
"Layout" a single node according to the current position allocator type.
ObjectFactory m_mobility
Object factory to create mobility objects.
static void CourseChanged(Ptr< OutputStreamWrapper > stream, Ptr< const MobilityModel > mobility)
Output course change events from mobility model to output stream.
std::string GetMobilityModelType() const
void SetMobilityModel(std::string type, Ts &&... args)
~MobilityHelper()
Destroy a Mobility Helper.
Ptr< PositionAllocator > m_position
Position allocator for use in hierarchical mobility model.
void PushReferenceMobilityModel(Ptr< Object > reference)
void InstallAll() const
Perform the work of MobilityHelper::Install on all nodes which exist in the simulation.
MobilityHelper()
Construct a Mobility Helper which is used to make life easier when working with mobility models.
void SetPositionAllocator(Ptr< PositionAllocator > allocator)
Set the position allocator which will be used to allocate the initial position of every node initiali...
static void EnableAscii(Ptr< OutputStreamWrapper > stream, uint32_t nodeid)
std::vector< Ptr< MobilityModel > > m_mobilityStack
Internal stack of mobility models.
keep track of a set of node pointers.
Instantiate subclasses of ns3::Object.
Ptr< Object > Create() const
Create an Object instance of the configured TypeId.
void Set(const std::string &name, const AttributeValue &value, Args &&... args)
Set an attribute to be set during construction.
void SetTypeId(TypeId tid)
Set the TypeId of the Objects to be created by this factory.
Ptr< T > GetObject() const
Get a pointer to the requested aggregated Object.
Definition object.h:511
Allocate a set of positions.
Smart pointer class similar to boost::intrusive_ptr.
Every class exported by the ns3 library is enclosed in the ns3 namespace.