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.
Package modules:
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
).
- time: a simulation time object of the
- 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()
anddeliver_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
).
- time: a simulation time object of the
-
_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
).
- 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:
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).
- environment: a dictionary that contains objects, which form
the network environment for simulations (see
-
_Network__application
()¶ Executes the simulation application at each operative node at the current simulation step.
See also
-
_Network__communication
()¶ Performs packets propagation in the network at the current simulation step.
See also
-
_Network__failure
()¶ Computes node failures at the current simulation step.
See also
-
_Network__move
()¶ Calculates new positions of the simulated nodes at the current simulation step.
See also
-
_Network__neighborhood
()¶ Calculates neighboring nodes at the current simulation step.
See also
-
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
-
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
-
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()
, andsim2net._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:
- node_id (int): an identifier of the node;
- send_message: a sending method in the
sim2net._network.Network
class; - receive_message: a receiving method in the
sim2net._network.Network
class.
-
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
()¶
-