Package sim2net.utility

This package contains miscellaneous utility modules and classes.

Module sim2net.utility.logger

Provides functions which implement an event logging system with the use of the logging module from the standard library.

class sim2net.utility.logger.Sim2NetFormatter(time=None)

Bases: logging.Formatter

Implements a custom logging.Formatter that can also log simulation steps and time (see: sim2net._time).

Parameters:
  • time: a simulation time object of the sim2net._time.Time class to log simulation steps and time.
format(record)

Formats the specified record as text and adds the current simulations step and time if the time object is present.

sim2net.utility.logger.__channel_string(channel)

Returns a logging channel string for a given string.

sim2net.utility.logger.create_logger(time=None, level=None, handler=None, formatter=None)

Creates and configures a logger for the main logging channel.

If no handler is passed, the sim2net.utility.logger.Sim2NetFormatter formatter is used.

Parameters:
  • time: a simulation time object of the sim2net._time.Time class to log simulation steps and time;
  • level: a logging level that will be set to the logger (and its handler if the handler is not passed as an argument); the level can be passed as a string or a logging module’s level;
  • handler: an object representing the handler to be used with the logger (see logging.handlers in the standard library);
  • formatter: an object representing the log format to be used with the logger’s handler (see logging.Formatter class in the standard library).
Returns:
A logging.Logger object for a newly created logger.
sim2net.utility.logger.get_logger(channel=None)

Returns a logger object. Multiple calls to this function with the same channel string will return the same object.

Parameters:
  • channel (str): a string that represents a logging channel.
Returns:
A logging.Logger object for the given logging channel or the main channel logger if channel argument is None.

Examples:

>>> main_channel_logger = logger.create_logger()
>>> main_channel_logger = logger.get_logger()
>>> new_channel_logger = logger.get_logger('my_channel')

Module sim2net.utility.randomness

Provides a pseudo-random number generator.

class sim2net.utility.randomness._Randomness

Bases: object

This class provides a pseudo-random number generator with the use of the random module from the standard library that produces a sequence of numbers that meet certain statistical requirements for randomness.

get_state()

Returns an object capturing the current internal state of the generator.

This object can be passed to set_state() to restore the state.

normal(mikro, sigma)

Returns a random floating point number with the normal (i.e. Gaussian) distribution.

Parameters:
  • mikro (float): a value of the mean to be used by the generator;
  • sigma (float): a value of the standard deviation to be used by the generator.
random_order(sequence)

Shuffles the given sequence in place.

set_state(generator_state)

Sets a new internal state of the generator.

The state can be obtained from a call to get_state() method.

Parameters:
  • generator_state: an internal state of the generator to set.
Raises:
  • ValueError: raised when a given value of the generator_state parameter is None.
uniform(begin, end)

Returns a random floating point number \(N\) such that \(begin\leqslant N\leqslant end\) for \(begin\leqslant end\) and \(end\leqslant N\leqslant begin\) for \(end < begin\).

sim2net.utility.randomness.get_random_generator()

Returns an object representing the _Randomness pseudo-random number generator. Multiple calls to this function will return the same object.

Module sim2net.utility.validation

Contains a collection of source code validation functions.

sim2net.utility.validation.check_argument_type(function, parameter, expected_type, argument, logger=None)

Checks whether a given argument is of a given type and raises an exception or reports a log message if the argument’s type is inappropriate.

Checks whether a value of the argument parameter is of the expected_type type. If not, it raises an exception (if logger object is None) or reports a log message (if logger object is passed) indicating an inappropriate type of the parameter parameter in the function function (or method).

Parameters:
  • function (str): a name of the function which argument is to be checked;
  • parameter (str): a name of the parameter which argument is to be checked;
  • expected_type: an expected type of the argument parameter;
  • argument: a value of the argument that is to be checked;
  • logger (logging.Logger): a logger object that will be used to write the log message.
Raises:
  • TypeError: raised when the value of argument is not of the expected_type type and logger object is not passed.

Example:

>>> check_argument_type('function_name', 'parameter_name', str, 'argument')