Package sim2net.mobility
¶
This package provides a collection of mobility model classes.
Mobility models ([LNR04], [CBD02]) are designed to describe the movement pattern of mobile nodes, and how their location, velocity and acceleration change over time. Since mobility patterns may play a significant role in determining the protocol performance, it is desirable for mobility models to emulate the movement pattern of targeted real life applications in a reasonable way.
The literature categorises mobility models as being either entity or group models. Entity models are used as a tool to model the behaviour of individual mobile nodes, treated as autonomous, independent entities. On the other hand, the key assumption behind the group models is that individual nodes influence each other’s movement to some degree. Therefore, group models have become helpful in simulating the motion patterns of a group as a whole.
[LNR04]  Guolong Lin, Guevara Noubir, Rajmohan Rajamaran. Mobility Models for AdHoc Network Simulation. In Proceedings of the 23rd Conference of the IEEE Communications Society (INFOCOM 2004), pp. 463473. Hong Kong, March 2004. 
[CBD02]  (1, 2) Tracy Camp, Jeff Boleng, Vanessa Davies. A Survey of Mobility Models for AdHoc Network Research. In Wireless Communications Mobile Computing. Special Issue on Mobile Ad Hoc Networking: Research, Trends and Applications, vol. 2(5), 483–502. John Wiley & Sons, 2002. 
Package modules:
Module sim2net.mobility._mobility
¶
Contains an abstract class that should be implemented by all mobility model classes.

class
sim2net.mobility._mobility.
Mobility
(name)¶ Bases:
object
This class is an abstract class that should be implemented by all mobility model classes.
 Parameters:
 name (str): a name of the implemented mobility model.

get_current_position
(node_id, node_speed, node_coordinates)¶ Calculates and returns a node’s position at the current simulation step in accordance with the implemented mobility model. It is assumed that this method is called at each step of the simulation.
 Parameters:
 node_id (int): an identifier of the node;
 node_speed: an object representing the node’s speed;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.
 Returns:
 A tuple containing current values of the node’s horizontal and vertical coordinates.
 Raises:
 NotImplementedError: this method is an abstract method.

logger
¶ (Property) A logger object of the
logging.Logger
class with an appropriate channel name.See also

random_generator
¶ (Property) An object representing the
sim2net.utility.randomness._Randomness
pseudorandom number generator.
Module sim2net.mobility.gauss_markov
¶
This module provides an implementation of the GaussMarkov mobility model.
In the GaussMarkov mobility model ([LH99]), motion of a single node is modelled in the form of a GaussMarkov stochastic process. At the beginning, each node is assigned with an initial speed and direction, as well as mean values of these parameters. Then, at set intervals of time (e.g. simulation steps), a new speed and direction are calculated for each node, which follow the new course until the next time step. This is repeated through the duration of the simulation. The new speed (\(v\)) and direction (\(d\)), at time interval \(n\), are evaluated in the following manner:
 \(v_n=\alpha\times v_{n1}+(1\alpha)\times\overline{v}+\sqrt{(1\alpha^2)}\times v_x\),
 \(d_n=\alpha\times d_{n1}+(1\alpha)\times\overline{d}+\sqrt{(1\alpha^2)}\times d_x\);
where:
 \(0\leqslant\alpha\leqslant 1\) is a tuning parameter used to vary the randomness;
 \(\overline{v}\) is constant representing the mean value of speed;
 \(\overline{d}\) is constant representing the mean value of direction;
 \(v_x\) and \(d_x\) are random variables from a normal (Gaussian) distribution.
Consequently, at time interval \(n\), node’s horizontal (\(x\)) and vertical (\(y\)) coordinates in the simulation area are given by the following equations:
 \(x_n=x_{n1}+v_{n1}\times\cos d_{n1}\);
 \(y_n=y_{n1}+v_{n1}\times\sin d_{n1}\).
It is worth to note that when \(\alpha\) is equal to \(1\), movement becomes predictable, losing all randomness. On the other hand, if \(\alpha\) is equal to \(0\), the model becomes memoryless: the new speed and direction are based completely upon the mean speed and direction constants (\(\overline{v}\) and \(\overline{d}\)) and the Gaussian random variables (\(v_x\) and \(d_x\)).
[LH99]  Ben Liang, Zygmunt J. Haas. Predictive DistanceBased Mobility Management for PCS Networks. In Proceedings of the 18th Annual Joint Conference of the IEEE Computer and Communications Societies (INFOCOM 1999), pp. 1377–1384, vol. 3. New York, NY, United States, March 1999. 

class
sim2net.mobility.gauss_markov.
GaussMarkov
(area, time, initial_coordinates, initial_speed, **kwargs)¶ Bases:
sim2net.mobility._mobility.Mobility
This class implements the GaussMarkov mobility model, in which motion of each node is modelled in the form of a GaussMarkov stochastic process.
Note
 Due to the characteristics of this model, it is expected that each
node has assigned the normal speed distribution (see:
sim2net.speed.normal
) – the speed is used as random variable \(v_x\) when a new speed is calculated.  All direction values used in this implementation are expressed in radians.
 The
get_current_position()
method computes a position of a node at the current simulation step (see:sim2net._time
), so it is presumed that the method is called at each step of the simulation.
 Parameters:
area: an object representing the simulation area;
time: a simulation time object of the
sim2net._time.Time
class;initial_coordinates (list): initial coordinates of all nodes; each element of this parameter should be a tuple of two coordinates: horizontal and vertical (respectively) of type float;
initial_speed (float): a value of the initial speed that is assigned to each node at the beginning of the simulation;
kwargs (dict): a dictionary of (optional) keyword parameters related to the GaussMarkov mobility model; the following parameters are accepted:
 alpha (float)
The tuning parameter \(0\leqslant\alpha\leqslant 1\) used to vary the randomness of movements (default: 0.75).
 direction_deviation (float)
Constant representing the standard deviation of direction random variable \(d_x\) (it defaults to \(\frac{\pi}{2}\)).
 direction_margin (float)
Constant used to change direction mean \(\overline{d}\) to ensure that nodes do not remain near a border of the simulation area for a long period of time (it defaults to 0.15, or 15% of the simulation area width/height, and cannot be less than zero and greater than one; see:
_GaussMarkov__velocity_recalculation()
). direction_mean (float)
Constant representing mean value \(\overline{d}\) of direction (it defaults to \(\frac{\pi}{6}\)). The same value is used as mean of direction random variable \(d_x\).
 recalculation_interval (int)
Velocity (i.e. speed and direction) recalculation time interval (it defaults to the simulation frequency; see:
sim2net._time
). It determines how often, counting in simulation steps, new values of velocity are recalculated.
 Raises:
 ValueError: raised when the given value of the area, time, initial_coordinates or initial_speed parameter is None; or when the given value of the keyword parameter alpha is less than zero or greater that one; or when the given value of the (optional) keyword parameter direction_margin is less than zero or greater than one.
Example:
>>> gm = GaussMarkov(area, time, coordinates, 10.0, alpha=0.35)

_GaussMarkov__get_new_direction
()¶ Randomizes a new direction with the normal (Gaussian) distribution.
 Returns:
 (float) a newly randomized direction value.

_GaussMarkov__step_move
(node_id, node_coordinates)¶ Computes a node’s position at the current simulation step.
 Parameters:
 node_id (int): an identifier of the node;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.
 Returns:
 (tuple) current values of the node’s horizontal and vertical coordinates.

_GaussMarkov__velocity_recalculation
(node_id, node_speed, node_coordinates)¶ Recalculates a node’s velocity, i.e. its speed and direction, as a GaussMarkov stochastic process.
To ensure that a node does not remain near a border of the simulation area for a long period of time, the node is forced away from the border when it moves within certain distance of the edge. This is done by modifying mean direction \(\overline{d}\). For example, when a node is near the right border of the simulation area, the value of \(\overline{d}\) changes to 180 degrees (\(\pi\)). The distance that is used in this method is calculated as a product of the direction margin and area width or height.
 Parameters:
 node_id (int): an identifier of the node;
 node_speed: an object representing the node’s speed;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.

get_current_position
(node_id, node_speed, node_coordinates)¶ Calculates and returns a node’s position at the current simulation step in accordance with the GaussMarkov mobility model.
A distance of the route traveled by the node, between the current and previous simulation steps, is calculated as the product of the current node’s speed and the simulation period (see:
sim2net._time
module). Therefore, it is assumed that this method is called at every simulation step. Parameters:
 node_id (int): an identifier of the node;
 node_speed: an object representing the node’s speed;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.
 Returns:
 A tuple containing current values of the node’s horizontal and vertical coordinates.
 Due to the characteristics of this model, it is expected that each
node has assigned the normal speed distribution (see:
Module sim2net.mobility.nomadic_community
¶
This module provides an implementation of the Nomadic Community mobility model.
The Nomadic Community ([CBD02]) is a group mobility model, in which a group of nodes collectively moves from one destination to another. Destinations for the group are determined by the socalled reference point that is selected at random within the simulation area. Moreover, each node uses an entity mobility model to roam, within a fixed range, around the current reference point. But when the reference point changes, all nodes travel to the new area defined by new coordinates of the reference point (and its range of free roam) and then begin roaming around it. The whole process is repeated again and again until simulation ends.

class
sim2net.mobility.nomadic_community.
NomadicCommunity
(area, time, initial_coordinates, pause_time=0.0, area_factor=0.25)¶ Bases:
sim2net.mobility.random_waypoint.RandomWaypoint
,sim2net.mobility._mobility.Mobility
This class implements the Nomadic Community mobility model, in which a group of nodes travels together from one location to another.
In this implementation, coordinates of the reference point are uniformly selected at random within the simulation area once every \(x+y\times pause\_time\) simulation time units (see:
sim2net._time
module), where \(x\) is uniformly picked at random from the range \([100, 200]\), and \(y\) from the range \([1, 10]\). Nodes roam around reference points in accordance with the Random Waypoint mobility model (see:sim2net.mobility.random_waypoint
module). The width and height of the (square or rectangular) free roam area around the reference point are computed as a product of the area_factor parameter and the width and height (respectively) of the simulation area.Note
The
get_current_position()
method computes a position of a node at the current simulation step (see:sim2net._time
), so it is presumed that the method is called at each step of the simulation. Parameters:
 area: an object representing the simulation area;
 time: a simulation time object of the
sim2net._time.Time
class;  initial_coordinates (list): initial coordinates of all nodes; each element of this parameter should be a tuple of two coordinates: horizontal and vertical (respectively) of type float;
 pause_time (float): a maximum value of the pause time in
the simulation time units (default: 0.0, see also:
sim2net._time
);  area_factor (float): a factor used to determine the width and height of the free roam area around the reference point (default: 0.25).
 Raises:
 ValueError: raised when the given value of the area, time or initial_coordinates parameter is None; or when the given value of the pause_time parameter is less that zero; or when the given value of the area_factor parameter is less than zero or greater than one.
(At the beginning, nodes’ destination points are set to be equal to its initial coordinates passed by the initial_coordinates parameter.)

_NomadicCommunity__get_free_roam_area_edges
(reference_point)¶ Computes boundaries of a free roam area around a given reference point.
 Parameter:
 reference_point (tuple) containing horizontal and vertical coordinates (respectively) of the reference point.
 Returns:
 A tuple containing values of the top, right, bottom and left boundaries (respectively) in the simulation area.

_NomadicCommunity__get_new_reference_point
()¶ Uniformly randomizes new coordinates of the reference point. The vertical and horizontal coordinates are returned (respectively) as a tuple.

_NomadicCommunity__get_new_relocation_time
()¶ Randomizes and returns a new relocation time of type float, after which coordinates of the reference point will be changed.

_NomadicCommunity__reference_point_relocation
()¶ Relocates the reference point by picking its new coordinates. The relocation takes place only if all nodes are within the current area of free roam and the relocation time has expired. Otherwise, the current coordinates of the reference point are preserved.

_get_new_destination
()¶ Uniformly randomizes a new waypoint within the range of free roam and returns its coordinates as a tuple.

get_current_position
(node_id, node_speed, node_coordinates)¶ Calculates and returns a node’s position at the current simulation step in accordance with the Nomadic Community mobility model (and Random Waypoint model within the area of free roam).
A distance of the route traveled by the node, between the current and previous simulation steps, is calculated as the product of the current node’s speed and the simulation period (see:
sim2net._time
module). Therefore, it is assumed that this method is called at every simulation step. Parameters:
 node_id (int): an identifier of the node;
 node_speed: an object representing the node’s speed;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.
 Returns:
 A tuple containing current values of the node’s horizontal and vertical coordinates.
Module sim2net.mobility.random_direction
¶
This module provides an implementation of the Random Direction mobility model.
At the beginning of the simulation, with the use of the Random Direction mobility model ([RMM01]), a node first stops for some random pause time, and then randomly selects a direction in which to move. The direction is measured in degrees, and at first, the node selects a degree between 0 and 359. Next, it finds a destination point on the boundary of the simulation area in this direction of travel and moves with a constant, but randomly selected (between the minimum and maximum values), speed to its destination. Once it reaches the destination, it pauses, and then selects a new direction between 0 and 180 degree (the degree is limited because the node is already on the boundary of the simulation area). The node then identifies the destination on the boundary in this line of direction, selects a new speed, and resumes travel. The whole process is repeated again and again until simulation ends. The speed and destination of each node are chosen independently of other nodes.
[RMM01]  Elizabeth M. Royer, P. Michael MelliarSmithy, Louise E. Moser. An Analysis of the Optimum Node Density for Ad Hoc Mobile Networks. In Proceedings of the IEEE International Conference on Communications (ICC 2001), pp. 857–861, vol. 3. Helsinki, Finland, June 2001. 

class
sim2net.mobility.random_direction.
RandomDirection
(area, time, initial_coordinates, pause_time=0.0)¶ Bases:
sim2net.mobility.random_waypoint.RandomWaypoint
,sim2net.mobility._mobility.Mobility
This class implements the Random Direction mobility model, in which each node moves along straight lines from one destination point, on the boundary of the simulation area, to another.
The nodes may also have pause times when they reach their destination points, and their speeds are selected at random between the minimum and maximum speed values. (All random picks are uniformly distributed).
Note
The
get_current_position()
method computes a position of a node at the current simulation step (see:sim2net._time
), so it is presumed that the method is called at each step of the simulation.See also
 Parameters:
 area: an object representing the simulation area;
 time: a simulation time object of the
sim2net._time.Time
class;  initial_coordinates (list): initial coordinates of all nodes; each element of this parameter should be a tuple of two coordinates: horizontal and vertical (respectively) of type float;
 pause_time (float): a maximum value of the pause time in
the simulation time units (default: 0.0, see also:
sim2net._time
).
 Raises:
 ValueError: raised when the given value of the area, time or initial_coordinates parameter is None or when the given value of the pause_time parameter is less that zero.
(At the beginning, nodes’ destination points are set to be equal to its initial coordinates passed by the initial_coordinates parameter.)

_get_new_destination
()¶ Randomizes a new destination point on the boundary of the simulation area and returns its coordinates as a tuple.
Module sim2net.mobility.random_waypont
¶
This module provides an implementation of the Random Waypoint mobility model.
In this model ([JM96], [BMJ+98]), a node first stops for some random pause time. Then, the node randomly picks a point within the simulation area and starts moving toward it with a constant, but randomly selected, speed that is uniformly distributed between the minimum and maximum speed values. Upon reaching the destination point (or waypoint), the node pauses again and then moves toward a newly randomized point. (If the pause time is equal to zero, this leads to continuous mobility.) The whole process is repeated again and again until simulation ends. The speed and destination of each node are chosen independently of other nodes.
[JM96]  David B. Johnson and David A. Maltz. Dynamic Source Routing in Ad Hoc Wireless Networks. In Mobile Computing, edited by Tomasz Imielinski and Hank Korth, chapter 5, pp. 153–181. Kluwer Academic Publishers, 1996. 
[BMJ+98]  Josh Broch, David A. Maltz, David B. Johnson, YihChun Hu, Jorjeta Jetcheva. A Performance Comparison of Multihop Wireless Ad Hoc Network Routing Protocols. In Proceedings of the 4th Annual ACM/IEEE International Conference on Mobile Computing and Networking (MobiCom 1998), pp. 85–97. Dallas, Texas, United States, October 1998. 

class
sim2net.mobility.random_waypoint.
RandomWaypoint
(area, time, initial_coordinates, pause_time=0.0)¶ Bases:
sim2net.mobility._mobility.Mobility
This class implements the Random Waypoint mobility model, in which each node moves along straight lines from one waypoint to another.
The waypoints are randomly picked within the simulation area. The nodes may also have pause times when they reach waypoints, and their speeds are selected at random between the minimum and maximum speed values. (All random picks are uniformly distributed).
Note
The
get_current_position()
method computes a position of a node at the current simulation step (see:sim2net._time
), so it is presumed that the method is called at each step of the simulation. Parameters:
 area: an object representing the simulation area;
 time: a simulation time object of the
sim2net._time.Time
class;  initial_coordinates (list): initial coordinates of all nodes; each element of this parameter should be a tuple of two coordinates: horizontal and vertical (respectively) of type float;
 pause_time (float): a maximum value of the pause time in
the simulation time units (default: 0.0, see also:
sim2net._time
).
 Raises:
 ValueError: raised when the given value of the area, time or initial_coordinates parameter is None or when the given value of the pause_time parameter is less that zero.
(At the beginning, nodes’ destination points are set to be equal to its initial coordinates passed by the initial_coordinates parameter.)

_assign_new_destination
(node_id, node_speed)¶ Assigns a new destination point for a node of a given ID and picks its new speed value. (See also:
_get_new_destination()
) Parameters:
 node_id (int): an identifier of the node;
 node_speed: an object representing the node’s speed.

_assign_new_pause_time
(node_id)¶ Assigns a new pause time for a node of a given ID and returns the value. If the maximum pause time is set to 0, None value is assigned and returned.
 Parameters:
 node_id (int): an identifier of the node.
 Returns:
 (float) a newly randomized pause time.

_diagonal_trajectory
(node_id, node_coordinates, step_distance)¶ Computes the current position of a node if its trajectory is not parallel to the horizontal or vertical axis of the simulation area. (See also:
_parallel_trajectory()
.) Parameters:
 node_id (int): an identifier of the node;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.
 step_distance (float): a distance that the node has moved between the previous and current simulation step.
 Returns:
 (tuple) current values of the node’s horizontal and vertical coordinates.

_get_new_destination
()¶ Randomizes a new waypoint and returns its coordinates as a tuple.

_get_new_pause_time
()¶ Randomizes a new pause time and returns its value of type float.

_parallel_trajectory
(coordinate, destination, step_distance)¶ Computes the current position of a node when one of its coordinates is equal to the corresponding destination coordinate. In such a case, the node moves on a straight line that is parallel to the horizontal or vertical axis of the simulation area. (See also:
_diagonal_trajectory()
.) Parameters:
 coordinate (float): a value of the previous node’s coordinate that is not equal to its corresponding destination coordinate;
 destination (float): a value of the destination coordinate;
 step_distance (float): a distance that the node has moved between the previous and current simulation steps.
 Returns:
 (float) a current value of the node’s coordinate.

_pause
(node_id, node_coordinates)¶ Decreases the current value of a node’s pause time and returns the result of type float, or None if the pause time has expired.
 Parameters:
 node_id (int): an identifier of the node;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.

_step_move
(node_id, node_speed, node_coordinates)¶ Computes a node’s position at the current simulation step. If its trajectory is parallel to the horizontal or vertical axis of the simulation area, the
_steady_trajectory()
method is used, otherwise the_diagonal_trajectory()
method is used. Parameters:
 node_id (int): an identifier of the node;
 node_speed: an object representing the node’s speed;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.
 Returns:
 (tuple) current values of the node’s horizontal and vertical coordinates.

get_current_position
(node_id, node_speed, node_coordinates)¶ Calculates and returns a node’s position at the current simulation step in accordance with the Random Waypoint mobility model.
A distance of the route traveled by the node, between the current and previous simulation steps, is calculated as the product of the current node’s speed and the simulation period (see:
sim2net._time
module). Therefore, it is assumed that this method is called at every simulation step. Parameters:
 node_id (int): an identifier of the node;
 node_speed: an object representing the node’s speed;
 node_coordinates (list): values of the node’s horizontal and vertical coordinates at the previous simulation step.
 Returns:
 A tuple containing current values of the node’s horizontal and vertical coordinates.