The simulators.utils library

The Utils library

simulators.utils.checksum(msg)[source]

Computes the checksum of a string message.

Parameters:: msg (str) – the message of which the checksum will be calculated and returned
Returns:: the checksum of the given string message
Return type:: chr

>>> checksum('fooo')
'L'

simulators.utils.binary_complement(bin_string, mask='')[source]

Returns the binary complement of bin_string, with bits masked by mask.

Parameters:

bin_string (str) – the binary_string of which the binary complement will be calculated
mask (str) – a binary string that will act as mask allowing to complement only bin_string’s digits corresponding to mask’s ones, leaving the bin_string’s digits corresponding to mask’s zeros as they are

Returns:

the binary complement of the given bin_string

Return type:

str

>>> binary_complement('11010110')
'00101001'

>>> binary_complement('10110', '10111')
'00001'

simulators.utils.twos_to_int(binary_string)[source]

Returns the two’s complement of binary_string.

Parameters:: binary_string (str) – the string containing only zeros and ones. It is mandatory to pad this value to the desired bits length before passing it to the method in order to avoid representation errors.
Returns:: the two’s complement of the given binary_string, as an integer
Return type:: int

>>> twos_to_int('11111011')
-5

>>> binary_string = '111'
>>> twos_to_int(binary_string)
-1
>>> binary_string = binary_string.zfill(8)
>>> binary_string
'00000111'
>>> twos_to_int(binary_string)
7

simulators.utils.int_to_twos(val, n_bytes=4)[source]

Returns the two’s complement of the given integer as a string of zeroes and ones with len = 8*n_bytes.

Parameters:

val (int) – the signed integer to be returned as binary string in two’s complement
n_bytes (int) – the number of total bytes to use for the given signed integer conversion to two’s complement

Returns:

the two’s complement of val, as a binary string

Return type:

str

>>> int_to_twos(5)
'00000000000000000000000000000101'

>>> int_to_twos(5, 2)
'0000000000000101'

>>> int_to_twos(-1625)
'11111111111111111111100110100111'

>>> int_to_twos(-1625, 2)
'1111100110100111'

>>> int_to_twos(4294967295)
Traceback (most recent call last):
    ...
ValueError: 4294967295 out of range (-2147483648, 2147483647).

simulators.utils.binary_to_bytes(binary_string, little_endian=True)[source]

Converts a binary string in a string of bytes.

Parameters:

binary_string (str) – the original binary string that has to be converted to a byte string
little_endian (bool) – boolean indicating whether the returned string should be formatted with little endian or big endian notation

Returns:

the bytestring representation of binary_string

Return type:

str

>>> binary_to_bytes('0110100001100101011011000110110001101111', False)
b'hello'

simulators.utils.bytes_to_int(byte_string, little_endian=True)[source]

Converts a string of bytes to an integer (like C atoi function).

Parameters:

byte_string (bytes) – the signed integer represented as bytes
little_endian (bool) – boolean indicating whether the byte_string param was received with little endian or big endian notation

Returns:

the value of byte_string, converted to signed integer

Return type:

int

>>> bytes_to_int(b'hello', False)
448378203247

simulators.utils.bytes_to_binary(byte_string, little_endian=True)[source]

Converts a string of bytes to a binary string.

Parameters:

byte_string (str) – the byte string to be converted to binary
little_endian (bool) – boolean indicating whether the byte_string param was received with little endian or big endian notation

Returns:

the binary representation of byte_string

Return type:

str

>>> bytes_to_binary(b'hi', little_endian=False)
'0110100001101001'

simulators.utils.bytes_to_uint(byte_string, little_endian=True)[source]

Converts a string of bytes to an unsigned integer.

Parameters:

byte_string (str) – the unsigned integer represented as bytes
little_endian – boolean indicating whether the byte_string param was received with little endian or big endian notation

Little_endian:

bool

Returns:

the value of byte_string, converted to unsigned integer

Return type:

int

>>> bytes_to_uint(b'hi', little_endian=False)
26729

simulators.utils.real_to_binary(num, precision=1)[source]

Returns the binary representation of a floating-point number (IEEE 754 standard). A single-precision format description can be found here: https://en.wikipedia.org/wiki/Single-precision_floating-point_format A double-precision format description can be found here: https://en.wikipedia.org/wiki/Double-precision_floating-point_format.

Parameters:

num (float) – the floating-point number to be converted
precision (int) – integer indicating whether the floating-point precision to be adopted should be single (1) or double (2)

Returns:

the binary string of the given floating-point value

Return type:

str

>>> real_to_binary(619.34000405413)
'01000100000110101101010111000011'

>>> real_to_binary(619.34000405413, 2)
'0100000010000011010110101011100001010100000010111010011111110111'

>>> real_to_binary(0.56734, 1)
'00111111000100010011110100110010'

simulators.utils.real_to_bytes(num, precision=1, little_endian=True)[source]

Returns the bytestring representation of a floating-point number (IEEE 754 standard).

Parameters:

num (float) – the floating-point number to be converted
precision (int) – integer indicating whether the floating-point precision to be adopted should be single (1) or double (2)
little_endian (bool) – boolean indicating whether the byte string should be returned with little endian or big endian notation

Returns:

the bytes string of the given floating-point value

Return type:

str

>>> [hex(x) for x in real_to_bytes(436.56, 1, False)]
['0x43', '0xda', '0x47', '0xae']

>>> [hex(x) for x in real_to_bytes(436.56, 2, False)]
['0x40', '0x7b', '0x48', '0xf5', '0xc2', '0x8f', '0x5c', '0x29']

simulators.utils.bytes_to_real(bytes_real, precision=1, little_endian=True)[source]

Returns the floating-point representation (IEEE 754 standard) of bytestring number.

Parameters:

bytes_real (bytes) – the floating-point number represented as bytes
precision (int) – integer indicating whether the floating-point precision to be adopted should be single (1) or double (2)
little_endian (bool) – boolean indicating whether the bytes_real param was received with little endian or big endian notation

Returns:

the floating-point value of the given bytes string

Return type:

float

>>> round(bytes_to_real(b'Dw,1', 1, False), 2)
988.69

>>> round(bytes_to_real(b'@z%}.hQ]', 2, False), 2)
418.34

simulators.utils.int_to_bytes(val, n_bytes=4, little_endian=True)[source]

Returns the bytestring representation of a given signed integer.

Parameters:

val (int) – the signed integer to be converted
n_bytes (int) – the number of bytes to fit the given unsigned integer to
little_endian (bool) – boolean indicating whether the byte string should be returned with little endian or big endian notation

Returns:

the bytes string value of the given signed integer

Return type:

str

>>> [hex(x) for x in int_to_bytes(354, little_endian=False)]
['0x0', '0x0', '0x1', '0x62']

simulators.utils.uint_to_bytes(val, n_bytes=4, little_endian=True)[source]

Returns the bytestring representation of a given unsigned integer.

Parameters:

val (int) – the unsigned integer to be converted
n_bytes (int) – the number of bytes to fit the given unsigned integer to
little_endian (bool) – boolean indicating whether the byte string should be returned with little endian or big endian notation

Returns:

the bytes string value of the given unsigned integer

Return type:

bytes

>>> [hex(x) for x in uint_to_bytes(657, little_endian=False)]
['0x0', '0x0', '0x2', '0x91']

simulators.utils.sign(number)[source]

Returns the sign (-1, 0, 1) of a given number (int or float) as an int.

Parameters:: number (int) – the number from which the sign will be extracted
Returns:: the sign multiplier of the given number
Return type:: int

>>> sign(5632)
1

>>> sign(0)
0

>>> sign(-264)
-1

simulators.utils.mjd(date=None)[source]

Returns the modified julian date (MJD) of a given datetime object. If no datetime object is given, it returns the current MJD. For more informations about modified julian date check the following link: https://core2.gsfc.nasa.gov/time/

Parameters:: date (datetime) – the object to calculate the equivalent modified julian date. If None, the current time is used.
Returns:: the modified julian date of the given date value
Return type:: float

>>> d = datetime(2018, 1, 20, 10, 30, 45, 100000)
>>> mjd(d)
58138.43802199074

simulators.utils.mjd_to_date(original_mjd_date)[source]

Returns the UTC date representation of a modified julian date one.

Parameters:: original_mjd_date (float) – a floating point number representing the modified julian date to be converted to a datetime object.
Returns:: the datetime object of the given modified julian date
Return type:: datetime

>>> mjd_to_date(58138.43802199074)
datetime.datetime(2018, 1, 20, 10, 30, 45, 100000)

simulators.utils.day_microseconds(date=None)[source]

Returns the microseconds elapsed since last midnight UTC.

Parameters:: date (datetime) – the object to calculate the total day amount of microseconds. If None, the current time is used.
Returns:: the number of microseconds elapsed since last midnight previous to given date
Return type:: int

simulators.utils.day_milliseconds(date=None)[source]

Returns the milliseconds elapsed since last midnight UTC.

Parameters:: date (datetime) – the object to calculate the total day amount of milliseconds. If None, the current time is used.
Returns:: the number of milliseconds elapsed since last midnight previous to given date
Return type:: int

simulators.utils.day_percentage(date=None)[source]

Returns the day percentage. 00:00 = 0.0, 23:59:999999 = 1.0

Parameters:: date (datetime or timedelta) – the datetime or timedelta object of which will be calculated the equivalent percentage. If None, the current datetime is used.
Returns:: the percentage of day elapsed since last midnight previous to given date
Return type:: float

simulators.utils.get_multitype_systems(path)[source]

Returns a list of .py packages containing a System class. The path in which this method looks is the same path of the module that calls this very method. It is meant to be called by a module containing a MultiTypeSystem class.

Parameters:: path (str) – the path in which the function is going to recursively look for System classes
Returns:: a list of packages containing a System class
Return type:: list

simulators.utils.list_simulators(path='/home/docs/checkouts/readthedocs.org/user_builds/discos-simulators/checkouts/latest/simulators')[source]

Returns the list of all available simulators in the package.

Parameters:: path (str) – the path in which the function will recursively look for simulators System classes
Returns:: the list of available simulators
Return type:: list