Package sim2net

This package provides modules for the sim2net simulator.

The sim2net.simulator.Sim2Net class is the main entry point for conducting simulations, and the sim2net.application.Application abstract class defines the interface for simulation applications.

Module sim2net._version

This package provides version information for the project.

The project’s version number has the following form: X.Y.Z, where:

  • X – is a major version number,
  • Y – is a minor version number,
  • Z – is a maintenance version number.

Each number is increased by one at a time. When one of the numbers is increased, the less significant numbers are reset to zero in the following way:

  • if there are backwards incompatible changes then the major number is incremented and the minor and maintenance numbers are reset to zero;
  • if there are new features (additions) implemented then the minor number is incremented and the maintenance number is reset to zero;
  • if there are only implementation detail changes or bug fixes then the maintenance number is incremented (and there are no resets).
sim2net._version.get_version()

Returns the current version number as a string.

sim2net._version.project_information()

Returns the project information in the form of its name, short name, and the current version number as a string.

Module sim2net._time

Supplies time-related functionality for simulations.

In this module the following terminology is used:

Simulation step, \(s\):
takes successive discrete values stating from 0 before each simulation iteration.
Simulation time, \(t_s\):
keeps track of the current time for the system being simulated; it advances to the next value in accordance with a given simulation frequency before each simulation iteration.
Simulation frequency, \(f_s\):
a constant that describes the relationship between the simulation step and the simulation time in the following manner: \(t_s=\frac{s}{f_s}\).
Simulation period, \(T_s\):
a constant such that: \(T_s=\frac{1}{f_s}\).
class sim2net._time.Time

Bases: object

This class provides time abstractions for simulations.

Class Time keeps track of simulation steps and time in accordance with a given simulation frequency value.

Warning

The class must be set up by calling the setup() method.

setup(simulation_frequency=1)

Initializes time abstractions for simulations.

Parameters:
  • simulation_frequency (int): a value of the simulation frequency (greater than 0).
Raises:
  • ValueError: raised when a given value of the simulation frequency is less or equal to 0.

Examples:

>>> clock = Time()
>>> clock.setup()
>>> clock.tick()
(0, 0.0)
>>> clock.tick()
(1, 1.0)
>>> clock.tick()
(2, 2.0)
>>> clock.simulation_period
1.0

>>> clock = Time()
>>> clock.setup(4)
>>> clock.tick()
(0, 0.0)
>>> clock.tick()
(1, 0.25)
>>> clock.tick()
(2, 0.5)
>>> clock.tick()
(3, 0.75)
>>> clock.tick()
(4, 1.0)
>>> clock.simulation_period
0.25
simulation_frequency

(Property) The simulation frequency of type int.

simulation_period

(Property) The simulation period of type float.

simulation_step

(Property) The current simulation step value of type int.

simulation_time

(Property) The current simulation time value of type float.

tick()

Advances the simulation step and time values.

Returns:
A tuple of two values: the current simulation step (int) and the current simulation time (float).

Note

The first call to this method will always returns (0, 0.0).

Module sim2net._channel

Provides an implementation of bidirectional communication channels for nodes in the simulated network.

The channels transmit packets that transport application messages between neighboring nodes. Each packet has its own identifier that is unique under the same sender, and can be received only by these nodes that are neighbors of the sender for the duration of the packet transmission according to the wireless signal propagation model used (see: sim2net.propagation). Potential packet losses are determined on the basis of the given model (see: sim2net.packet_loss), and transmission time of each packet is uniformly randomized in range \((0, t_{max}]\), where \(t_{max}\) is the given maximum transmission time in the simulation time units (see: sim2net._time).

class sim2net._channel.Channel(time, packet_loss, node_id, maximum_transmission_time)

Bases: sim2net._channel._Output, sim2net._channel._Input

This class implements bidirectional communication channels for each node in the simulated network.

The class has no members and inherits all its methods from two classes: _Input and _Output.

Application message passing is implemented here as follows. First, a message is sent locally by the _Output.send_message() method. Then, it is transmitted in a packet to neighboring nodes by the _Output.transmit_packets() method. If the transmission is successful, the packet leaves the output channel by calling the _Output.deliver_packet() method and will be transferred to receiving nodes by calling the _Input.capture_packet() methods. Finally, the message can be received by the application by calling the _Input.receive_message() method.

Parameters:
  • time: a simulation time object of the sim2net._time.Time class;
  • packet_loss: an object representing the packet loss model (see sim2net.packet_loss);
  • node_id (int): an identifier of the node;
  • maximum_transmission_time (float): maximum message transmission time between neighboring nodes in the simulation time units (see: sim2net._time).
Raises:
  • ValueError: raised when the given value of the time or packet_loss parameter is None; or when the given value of the node_id or maximum_transmission_time parameter is less than zero.
class sim2net._channel._Input(node_id)

Bases: object

This class implements input channels for nodes in the simulated network.

Parameters:
  • node_id (int): an identifier of the node for which the input channel is created.
capture_packet(packet)

Captures packets transmitted by neighboring nodes.

Parameters:
  • packet (tuple): a packet to capture represented by a tuple that contains the packet’s identifier and transported application message, which is also a tuple containing an identifier of the sender and the message.
receive_message()

Returns a received application message.

Returns:
None value if there is no message at the current simulation step, or a tuple that contains an identifier of the sender and the received application message.
class sim2net._channel._Output(time, packet_loss, node_id, maximum_transmission_time)

Bases: object

This class implements output channels for nodes in the simulated network.

Note

Methods transmit_packets() and deliver_packet() are responsible for the transmission and delivery of packages, so it is presumed that these methods are called at each step of the simulation.

Parameters:
  • time: a simulation time object of the sim2net._time.Time class;
  • packet_loss: an object representing a packet loss model to use (see sim2net.packet_loss);
  • node_id (int): an identifier of the node for which the output channel is created;
  • maximum_transmission_time (float): maximum message transmission time between neighboring nodes in the simulation time units (see: sim2net._time).
_Output__get_transmission_neighbors(packet_id, transmission_time, neighbors)

Returns a list of neighboring nodes at the beginning of packet transmission.

Parameters:
  • packet_id (int): an identifier of the transmitted packet;
  • transmission_time (float): scheduled start time of the transmission;
  • neighbors (list): a list of identifiers of all neighboring nodes of the sender at the current simulation step.
Returns:
(list) a list of identifiers of neighboring nodes of the sender for the given packet transmission or None value if the transmission time has not yet begun.
deliver_packet()

Delivers packets to neighboring nodes.

Returns:

None value if there is no packet to deliver at the current simulation step, or a tuple that contains the packet to deliver. In such a case, the tuple has the following data:

  • an identifier of the packet to deliver of type int;
  • a tuple that contains an identifier of the sender of type int and the transported application message;
  • a list of identifiers of nodes which receive the packet.

Hint

  • It is possible that at one simulation step there will be multiple packets to deliver, so this method should be called as long until it returns None value.
  • This method requires the use of complementary method _Input.capture_packet() of input channels of all nodes receiving the packet.
send_message(message, neighbors)

Sends an application message.

Parameters:
  • message: the application message to send of any type;
  • neighbors (list): a list of identifiers of all neighboring nodes of the sender at the current simulation step.
transmit_packets(neighbors)

Transmits packets to neighboring nodes.

Parameters:
  • neighbors (list): a list of identifiers of all neighboring nodes of the sender at the current simulation step according to the wireless signal propagation model used (see: sim2net.propagation).

Module sim2net._network

This module provides an implementation of the mobile ad hoc network that is to be simulated.

The network is composed of the given number of nodes running the provided simulation application. The main method of this module, the sim2net._network.Network.step() method, is called at each simulation step and it advances the simulation by computing node failures, new positions of the nodes, performing direct communication between neighboring nodes, and executing the simulation application at each node.

Additionally, the sim2net._network._Communication class is implemented, which serves as a communication interface for the simulated nodes.

class sim2net._network.Network(environment)

Bases: object

This class implements the mobile ad hoc network that is to be simulated.

Parameters:
  • environment: a dictionary that contains objects, which form the network environment for simulations (see sim2net._network.Network.__ENVIRONMENT for the objects list).
_Network__application()

Executes the simulation application at each operative node at the current simulation step.

See also

sim2net.application

_Network__communication()

Performs packets propagation in the network at the current simulation step.

See also

sim2net._channel.Channel

_Network__failure()

Computes node failures at the current simulation step.

See also

sim2net.failure

_Network__move()

Calculates new positions of the simulated nodes at the current simulation step.

See also

sim2net.mobility

_Network__neighborhood()

Calculates neighboring nodes at the current simulation step.

See also

sim2net.propagation

communication_receive(node_id)

Receives an application message for the given node.

Parameters:
  • node_id (int): an identifier of the receiver.
Returns:
None value if there is no message at the current simulation step for the receiver, or a tuple that contains an identifier of the sender and the received application message.

See also

sim2net._network._Communication

communication_send(node_id, message)

Sends an application message.

Parameters:
  • node_id (int): an identifier of the sender;
  • message: the application message to send of any type.

Warning

This method uses the copy.deepcopy() function, and hence may be slow.

See also

sim2net._network._Communication

finalize()

Calls the sim2net.application.Application.finalize() finalization method at each node after all simulation steps.

step()

Advances the simulation by one simulation step. This method is called as many times as there is simulation steps by the sim2net.simulator.Sim2Net.run() method.

This method calls: sim2net._network.Network._Network__failure(), sim2net._network.Network._Network__move(), sim2net._network.Network._Network__neighborhood(), sim2net._network.Network._Network__communication(), sim2net._network.Network._Network__application(), and sim2net._time.Time.tick() methods.

class sim2net._network._Communication(node_id, send_message, receive_message)

Bases: object

This class implements a communication interface for the simulated nodes providing two methods for sending and receiving application messages.

Parameters:
receive()

Returns None value if there is no message at the current simulation step, or a tuple that contains an identifier of the sender and the received application message.

send(message)

Sends an application message.

Parameters:
  • message: the application message to send of any type.

Module sim2net.simulator

This module provides an interface to the simulator for the sim2net.cli command-line tool and its main entry point for conducting simulations.

class sim2net.simulator.Sim2Net(configuration, application_file)

Bases: object

This class is the main entry point for conducting simulations.

Based on the given simulation configuration and application file, the class initializes and runs the simulation.

_Sim2Net__get_application_class(application_file)
_Sim2Net__get_arguments(name, configuration)
_Sim2Net__get_element(name, configuration, environment, number=None)
_Sim2Net__get_value(name, configuration)
_Sim2Net__report_error(element, name)
run()