# 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')