22. Mobility¶

The mobility support in ns-3 includes:

a set of mobility models which are used to track and maintain the current cartesian position and speed of an object.
a “course change notifier” trace source which can be used to register listeners to the course changes of a mobility model
a number of helper classes which are used to place nodes and setup mobility models (including parsers for some mobility definition formats).

22.1. Model Description¶

The source code for mobility lives in the directory src/mobility.

22.1.1. Design¶

The design includes mobility models, position allocators, and helper functions.

In ns-3, MobilityModel` objects track the evolution of position with respect to a (cartesian) coordinate system. The mobility model is typically aggregated to an ns3::Node object and queried using GetObject<MobilityModel> (). The base class ns3::MobilityModel is subclassed for different motion behaviors.

The initial position of objects is typically set with a PositionAllocator. These types of objects will lay out the position on a notional canvas. Once the simulation starts, the position allocator may no longer be used, or it may be used to pick future mobility “waypoints” for such mobility models.

Most users interact with the mobility system using mobility helper classes. The MobilityHelper combines a mobility model and position allocator, and can be used with a node container to install a similar mobility capability on a set of nodes.

We first describe the coordinate system and issues surrounding multiple coordinate systems.

22.1.1.1. Coordinate system¶

There are many possible coordinate systems and possible translations between them. Currently, ns-3 provides support for the Cartesian, Geocentric Cartesian, and Geographic coordinate systems, which are defined as:

Cartesian coordinates: They represent a point in 3D space using the set of coordinates (x,y,z). This is the default coordinate system in ns-3, and it is the most suitable for simulation scenarios whose size is in the order of a few km.
- Topocentric coordinates: Cartesian coordinates where a specific reference point on the Earth’s surface, such as lat-lon, for the origin is given. This coordinate system is useful for converting to and from Geocentric/Geographic coordinates.
- Geocentric Cartesian coordinates: Cartesian coordinate system where the origin is fixed in the Earth’s center of mass. The implementation follows the description in Sec. 6.3 of 38811.
Geographic coordinates: They represent a point in 3D space by assuming it is located on the surface or in the orbit of the Earth. Positions are uniquely described by three values: latitude, longitude and altitude. The latter reference is the Earth’s surface.

At the moment, the geocentric Cartesian coordinates are adopted by the GeocentricConstantPositionMobilityModel only. This class implements the Get/SetPosition methods, which leverage the GeographicPosition class to offer conversions to and from Cartesian coordinates. Additionally, users can set the position of a node by its geographical coordinates via the methods Get/SetGeographicPosition.

22.1.1.2. Coordinates¶

The base class for a coordinate is called ns3::Vector. While positions are normally described as coordinates and not vectors in the literature, it is possible to reuse the same data structure to represent position (x,y,z) and velocity (magnitude and direction from the current position). ns-3 uses class Vector for both.

There are also some additional related structures used to support mobility models.

Rectangle
Box
Waypoint

22.1.1.3. MobilityModel¶

Describe base class

GetPosition ()
Position and Velocity attributes
GetDistanceFrom ()
CourseChangeNotification

22.1.1.4. MobilityModel Subclasses¶

ConstantPosition
ConstantVelocity
ConstantAcceleration
GaussMarkov
Hierarchical
RandomDirection2D
RandomWalk2D
RandomWaypoint
SteadyStateRandomWaypoint
Waypoint
GeocentricConstantPosition

22.1.1.5. PositionAllocator¶

Position allocators usually used only at beginning, to lay out the nodes initial position. However, some mobility models (e.g. RandomWaypoint) will use a position allocator to pick new waypoints.

ListPositionAllocator
GridPositionAllocator
RandomRectanglePositionAllocator
RandomBoxPositionAllocator
RandomDiscPositionAllocator
UniformDiscPositionAllocator

22.1.1.6. Helper¶

A special mobility helper is provided that is mainly aimed at supporting the installation of mobility to a Node container (when using containers at the helper API level). The MobilityHelper class encapsulates a MobilityModel factory object and a PositionAllocator used for initial node layout.

Group mobility is also configurable via a GroupMobilityHelper object. Group mobility reuses the HierarchicalMobilityModel allowing one to define a reference (parent) mobility model and child (member) mobility models, with the position being the vector sum of the two mobility model positions (i.e., the child position is defined as an offset to the parent position). In the GroupMobilityHelper, the parent mobility model is not associated with any node, and is used as the parent mobility model for all (distinct) child mobility models. The reference point group mobility model [Camp2002] is the basis for this ns-3 model.

22.1.1.7. ns-2 MobilityHelper¶

The ns-2 mobility format is a widely used mobility trace format. The documentation is available at: http://www.isi.edu/nsnam/ns/doc/node172.html

Valid trace files use the following ns-2 statements:

$node set X_ x1
$node set Y_ y1
$node set Z_ z1
$ns at $time $node setdest x2 y2 speed
$ns at $time $node set X_ x1
$ns at $time $node set Y_ Y1
$ns at $time $node set Z_ Z1

In the above, the initial positions are set using the set statements. Also, this set can be specified for a future time, such as in the last three statements above.

The command setdest instructs the simulation to start moving the specified node towards the coordinate (x2, y2) at the specified time. Note that the node may never get to the destination, but will proceed towards the destination at the specified speed until it either reaches the destination (where it will pause), is set to a new position (via set), or sent on another course change (via setdest).

Note that in ns-3, movement along the Z dimension is not supported.

Some examples of external tools that can export in this format include:

BonnMotion
- Installation instructions and
- Documentation for using BonnMotion with ns-3
SUMO
TraNS
ns-2 setdest utility

A special Ns2MobilityHelper object can be used to parse these files and convert the statements into ns-3 mobility events. The underlying ConstantVelocityMobilityModel is used to model these movements.

See below for additional usage instructions on this helper.

22.1.2. Scope and Limitations¶

Cartesian, geocentric cartesian, and geographic coordinates are presently supported

22.1.3. References¶

Camp2002(1,2): T. Camp, J. Boleng, V. Davies. “A survey of mobility models for ad hoc network research”, in Wireless Communications and Mobile Computing, 2002: vol. 2, pp. 2483-2502.

38811: 3GPP. 2018. TR 38.811, Study on New Radio (NR) to support non-terrestrial networks, V15.4.0. (2020-09).

22.2. Usage¶

Most ns-3 program authors typically interact with the mobility system only at configuration time. However, various ns-3 objects interact with mobility objects repeatedly during runtime, such as a propagation model trying to determine the path loss between two mobile nodes.

22.2.1. Helper¶

A typical usage pattern can be found in the third.cc program in the tutorial.

First, the user instantiates a MobilityHelper object and sets some Attributes controlling the “position allocator” functionality.

MobilityHelper mobility;

mobility.SetPositionAllocator("ns3::GridPositionAllocator",
  "MinX", DoubleValue(0.0),
  "MinY", DoubleValue(0.0),
  "DeltaX", DoubleValue(5.0),
  "DeltaY", DoubleValue(10.0),
  "GridWidth", UintegerValue(3),
  "LayoutType", StringValue("RowFirst"));

This code tells the mobility helper to use a two-dimensional grid to initially place the nodes. The first argument is an ns-3 TypeId specifying the type of mobility model; the remaining attribute/value pairs configure this position allocator.

Next, the user typically sets the MobilityModel subclass; e.g.:

mobility.SetMobilityModel("ns3::RandomWalk2dMobilityModel",
  "Bounds", RectangleValue(Rectangle(-50, 50, -50, 50)));

Once the helper is configured, it is typically passed a container, such as:

mobility.Install(wifiStaNodes);

A MobilityHelper object may be reconfigured and reused for different NodeContainers during the configuration of an ns-3 scenario.

22.2.2. Ns2MobilityHelper¶

Two example programs are provided demonstrating the use of the ns-2 mobility helper:

ns2-mobility-trace.cc
bonnmotion-ns2-example.cc

22.2.2.1. ns2-mobility-trace¶

The ns2-mobility-trace.cc program is an example of loading an ns-2 trace file that specifies the movements of two nodes over 100 seconds of simulation time. It is paired with the file default.ns_movements.

The program behaves as follows:

a Ns2MobilityHelper object is created, with the specified trace file.
A log file is created, using the log file name argument.
A node container is created with the number of nodes specified in the command line. For this particular trace file, specify the value 2 for this argument.
the Install() method of Ns2MobilityHelper to set mobility to nodes. At this moment, the file is read line by line, and the movement is scheduled in the simulator.
A callback is configured, so each time a node changes its course a log message is printed.

The example prints out messages generated by each read line from the ns2 movement trace file. For each line, it shows if the line is correct, or of it has errors and in this case it will be ignored.

Example usage:

$ ./ns3 run "ns2-mobility-trace \
--traceFile=src/mobility/examples/default.ns_movements \
--nodeNum=2 \
--duration=100.0 \
--logFile=ns2-mob.log"

Sample log file output:

+0.0ns POS: x=150, y=93.986, z=0; VEL:0, y=50.4038, z=0
+0.0ns POS: x=195.418, y=150, z=0; VEL:50.1186, y=0, z=0
+104727357.0ns POS: x=200.667, y=150, z=0; VEL:50.1239, y=0, z=0
+204480076.0ns POS: x=205.667, y=150, z=0; VEL:0, y=0, z=0

22.2.2.2. bonnmotion-ns2-example¶

The bonnmotion-ns2-example.cc program, which models the movement of a single mobile node for 1000 seconds of simulation time, has a few associated files:

bonnmotion.ns_movements is the ns-2-formatted mobility trace
bonnmotion.params is a BonnMotion-generated file with some metadata about the mobility trace
bonnmotion.ns_params is another BonnMotion-generated file with ns-2-related metadata.

Neither of the latter two files is used by ns-3, although they are generated as part of the BonnMotion process to output ns-2-compatible traces.

The program bonnmotion-ns2-example.cc will output the following to stdout:

At 0.00 node 0: Position(329.82, 66.06, 0.00);   Speed(0.53, -0.22, 0.00)
At 100.00 node 0: Position(378.38, 45.59, 0.00);   Speed(0.00, 0.00, 0.00)
At 200.00 node 0: Position(304.52, 123.66, 0.00);   Speed(-0.92, 0.97, 0.00)
At 300.00 node 0: Position(274.16, 131.67, 0.00);   Speed(-0.53, -0.46, 0.00)
At 400.00 node 0: Position(202.11, 123.60, 0.00);   Speed(-0.98, 0.35, 0.00)
At 500.00 node 0: Position(104.60, 158.95, 0.00);   Speed(-0.98, 0.35, 0.00)
At 600.00 node 0: Position(31.92, 183.87, 0.00);   Speed(0.76, -0.51, 0.00)
At 700.00 node 0: Position(107.99, 132.43, 0.00);   Speed(0.76, -0.51, 0.00)
At 800.00 node 0: Position(184.06, 80.98, 0.00);   Speed(0.76, -0.51, 0.00)
At 900.00 node 0: Position(250.08, 41.76, 0.00);   Speed(0.60, -0.05, 0.00)

The motion of the mobile node is sampled every 100 seconds, and its position and speed are printed out. This output may be compared to the output of a similar ns-2 program (found in the ns-2 tcl/ex/ directory of ns-2) running from the same mobility trace.

The next file is generated from ns-2 (users will have to download and install ns-2 and run this Tcl program to see this output). The output of the ns-2 bonnmotion-example.tcl program is shown below for comparison (file bonnmotion-example.tr):

M 0.00000 0 (329.82, 66.06, 0.00), (378.38, 45.59), 0.57
M 100.00000 0 (378.38, 45.59, 0.00), (378.38, 45.59), 0.57
M 119.37150 0 (378.38, 45.59, 0.00), (286.69, 142.52), 1.33
M 200.00000 0 (304.52, 123.66, 0.00), (286.69, 142.52), 1.33
M 276.35353 0 (286.69, 142.52, 0.00), (246.32, 107.57), 0.70
M 300.00000 0 (274.16, 131.67, 0.00), (246.32, 107.57), 0.70
M 354.65589 0 (246.32, 107.57, 0.00), (27.38, 186.94), 1.04
M 400.00000 0 (202.11, 123.60, 0.00), (27.38, 186.94), 1.04
M 500.00000 0 (104.60, 158.95, 0.00), (27.38, 186.94), 1.04
M 594.03719 0 (27.38, 186.94, 0.00), (241.02, 42.45), 0.92
M 600.00000 0 (31.92, 183.87, 0.00), (241.02, 42.45), 0.92
M 700.00000 0 (107.99, 132.43, 0.00), (241.02, 42.45), 0.92
M 800.00000 0 (184.06, 80.98, 0.00), (241.02, 42.45), 0.92
M 884.77399 0 (241.02, 42.45, 0.00), (309.59, 37.22), 0.60
M 900.00000 0 (250.08, 41.76, 0.00), (309.59, 37.22), 0.60

The output formatting is slightly different, and the course change times are additionally plotted, but it can be seen that the position vectors are the same between the two traces at intervals of 100 seconds.

The mobility computations performed on the ns-2 trace file are slightly different in ns-2 and ns-3, and floating-point arithmetic is used, so there is a chance that the position in ns-2 may be slightly different than the respective position when using the trace file in ns-3.

22.2.3. Use of Random Variables¶

A typical use case is to evaluate protocols on a mobile topology that involves some randomness in the motion or initial position allocation. To obtain random motion and positioning that is not affected by the configuration of the rest of the scenario, it is recommended to use the “AssignStreams” facility of the random number system.

Class MobilityModel and class PositionAllocator both have public API to assign streams to underlying random variables:

/**
 * Assign a fixed random variable stream number to the random variables
 * used by this model. Return the number of streams (possibly zero) that
 * have been assigned.
 *
 * \param stream first stream index to use
 * \return the number of stream indices assigned by this model
 */
int64_t AssignStreams(int64_t stream);

The class MobilityHelper also provides this API. The typical usage pattern when using the helper is:

int64_t streamIndex = /*some positive integer */
MobilityHelper mobility;
... (configure mobility)
mobility.Install(wifiStaNodes);
int64_t streamsUsed = mobility.AssignStreams(wifiStaNodes, streamIndex);

If AssignStreams is called before Install, it will not have any effect.

22.2.4. Advanced Usage¶

A number of external tools can be used to generate traces read by the Ns2MobilityHelper.

22.2.4.1. ns-2 scengen¶

TBD

22.2.5. Examples¶

main-random-topology.cc
main-random-walk.cc
main-grid-topology.cc
ns2-mobility-trace.cc
ns2-bonnmotion.cc

22.2.5.1. reference-point-group-mobility-example.cc¶

The reference point group mobility model ([Camp2002]) is demonstrated in the example program reference-point-group-mobility-example.cc. This example runs a short simulation that illustrates a parent WaypointMobilityModel traversing a rectangular course within a bounding box, and three member nodes independently execute a two-dimensional random walk around the parent position, within a small bounding box. The example illustrates configuration using the GroupMobilityHelper and manual configuration without a helper; the configuration option is selectable by command-line argument.

The example outputs two mobility trace files, a course change trace and a time-series trace of node position. The latter trace file can be parsed by a Bash script (reference-point-group-mobility-animate.sh) to create PNG images at one-second intervals, which can then be combined using an image processing program such as ImageMagick to form a basic animated gif of the mobility. The example and animation program files have further instructions on how to run them.

22.3. Validation¶

TBD