eng module¶

This module provides engineering-related functions including:

Handling numbers represented in engineering notation, obtaining their constituent components and converting to and from regular floats. For example:

>>> import putil.eng
>>> x = putil.eng.peng(1346, 2, True)
>>> x
'   1.35k'
>>> putil.eng.peng_float(x)
1350.0
>>> putil.eng.peng_int(x)
1
>>> putil.eng.peng_frac(x)
35
>>> str(putil.eng.peng_mant(x))
'1.35'
>>> putil.eng.peng_power(x)
EngPower(suffix='k', exp=1000.0)
>>> putil.eng.peng_suffix(x)
'k'

Pretty printing Numpy vectors. For example:

>>> from __future__ import print_function
>>> import putil.eng
>>> header = 'Vector: '
>>> data = [1e-3, 20e-6, 30e+6, 4e-12, 5.25e3, -6e-9, 70, 8, 9]
>>> print(
...     header+putil.eng.pprint_vector(
...         data,
...         width=30,
...         eng=True,
...         frac_length=1,
...         limit=True,
...         indent=len(header)
...     )
... )
Vector: [    1.0m,   20.0u,   30.0M,
                     ...
            70.0 ,    8.0 ,    9.0  ]

Formatting numbers represented in scientific notation with a greater degree of control and options than standard Python string formatting. For example:

>>> import putil.eng
>>> putil.eng.to_scientific_string(
...     number=99.999,
...     frac_length=1,
...     exp_length=2,
...     sign_always=True
... )
'+1.0E+02'

Named tuples¶

putil.eng.ENGPOWER(suffix, exp)¶: Constructor for engineering notation suffix

putil.eng.NUMCOMP(mant, exp)¶: Constructor for number components representation

Functions¶

putil.eng.no_exp(number)¶

Converts a number to a string guaranteeing that the result is not expressed in scientific notation

Parameters:	number (integer or float) – Number to convert
Return type:	string

Raises:	RuntimeError (Argument `number` is not valid)

putil.eng.peng(number, frac_length, rjust=True)¶

Converts a number to engineering notation. The absolute value of the number (if it is not exactly zero) is bounded to the interval [1E-24, 1E+24)

Parameters:	number (integer or float) – Number to convert frac_length (NonNegativeInteger) – Number of digits of fractional part rjust (boolean) – Flag that indicates whether the number is right-justified (True) or not (False)
Return type:	string

Raises:	RuntimeError (Argument `frac_length` is not valid) RuntimeError (Argument `number` is not valid) RuntimeError (Argument `rjust` is not valid)

The supported engineering suffixes are:

Exponent	Name	Suffix
1E-24	yocto	y
1E-21	zepto	z
1E-18	atto	a
1E-15	femto	f
1E-12	pico	p
1E-9	nano	n
1E-6	micro	u
1E-3	milli	m
1E+0
1E+3	kilo	k
1E+6	mega	M
1E+9	giga	G
1E+12	tera	T
1E+15	peta	P
1E+18	exa	E
1E+21	zetta	Z
1E+24	yotta	Y

For example:

>>> import putil.eng
>>> putil.eng.peng(1235.6789E3, 3, False)
'1.236M'

putil.eng.peng_float(snum)¶

Returns the floating point equivalent of a number represented in engineering notation

Parameters:	snum (EngineeringNotationNumber) – Number
Return type:	string

Raises:	RuntimeError (Argument `snum` is not valid)

For example:

>>> import putil.eng
>>> putil.eng.peng_float(putil.eng.peng(1235.6789E3, 3, False))
1236000.0

putil.eng.peng_frac(snum)¶

Returns the fractional part of a number represented in engineering notation

Parameters:	snum (EngineeringNotationNumber) – Number
Return type:	integer

Raises:	RuntimeError (Argument `snum` is not valid)

For example:

>>> import putil.eng
>>> putil.eng.peng_frac(putil.eng.peng(1235.6789E3, 3, False))
236

putil.eng.peng_int(snum)¶

Returns the integer part of a number represented in engineering notation

Parameters:	snum (EngineeringNotationNumber) – Number
Return type:	integer

Raises:	RuntimeError (Argument `snum` is not valid)

For example:

>>> import putil.eng
>>> putil.eng.peng_int(putil.eng.peng(1235.6789E3, 3, False))
1

putil.eng.peng_mant(snum)¶

Returns the mantissa of a number represented in engineering notation

Parameters:	snum (EngineeringNotationNumber) – Number
Return type:	float

Raises:	RuntimeError (Argument `snum` is not valid)

For example:

>>> import putil.eng
>>> putil.eng.peng_mant(putil.eng.peng(1235.6789E3, 3, False))
1.236

putil.eng.peng_power(snum)¶

Returns engineering suffix and floating point equivalent of the suffix when a number is represented in engineering notation. putil.eng.peng() lists the correspondence between suffix and floating point exponent.

Parameters:	snum (EngineeringNotationNumber) – Number
Return type:	named tuple in which the first item is the engineering suffix and the second item is the floating point equivalent of the suffix when the number is represented in engineering notation.

Raises:	RuntimeError (Argument `snum` is not valid)

For example:

>>> import putil.eng
>>> putil.eng.peng_power(putil.eng.peng(1235.6789E3, 3, False))
EngPower(suffix='M', exp=1000000.0)

putil.eng.peng_suffix(snum)¶

Returns the suffix of a number represented in engineering notation

Parameters:	snum (EngineeringNotationNumber) – Number
Return type:	string

Raises:	RuntimeError (Argument `snum` is not valid)

For example:

>>> import putil.eng
>>> putil.eng.peng_suffix(putil.eng.peng(1235.6789E3, 3, False))
'M'

putil.eng.peng_suffix_math(suffix, offset)¶

Returns an engineering suffix based on a starting suffix and an offset of number of suffixes

Parameters:	suffix (EngineeringNotationSuffix) – Engineering suffix offset (integer) – Engineering suffix offset
Return type:	string

Raises:	RuntimeError (Argument `offset` is not valid) RuntimeError (Argument `suffix` is not valid) ValueError (Argument `offset` is not valid)

For example:

>>> import putil.eng
>>> putil.eng.peng_suffix_math('u', 6)
'T'

putil.eng.pprint_vector(vector, limit=False, width=None, indent=0, eng=False, frac_length=3)¶

Formats a list of numbers (vector) or a Numpy vector for printing. If the argument vector is None the string 'None' is returned

Parameters:	vector (list of integers or floats, Numpy vector or None) – Vector to pretty print or None limit (boolean) – Flag that indicates whether at most 6 vector items are printed (all vector items if its length is equal or less than 6, first and last 3 vector items if it is not) (True), or the entire vector is printed (False) width (integer or None) – Number of available characters per line. If None the vector is printed in one line indent (boolean) – Flag that indicates whether all subsequent lines after the first one are indented (True) or not (False). Only relevant if width is not None eng (boolean) – Flag that indicates whether engineering notation is used (True) or not (False) frac_length (integer) – Number of digits of fractional part (only applicable if eng is True)
Raises:	ValueError (Argument `width` is too small)
Return type:	string

For example:

>>> from __future__ import print_function
>>> import putil.eng
>>> header = 'Vector: '
>>> data = [1e-3, 20e-6, 300e+6, 4e-12, 5.25e3, -6e-9, 700, 8, 9]
>>> print(
...     header+putil.eng.pprint_vector(
...         data,
...         width=30,
...         eng=True,
...         frac_length=1,
...         limit=True,
...         indent=len(header)
...     )
... )
Vector: [    1.0m,   20.0u,  300.0M,
                     ...
           700.0 ,    8.0 ,    9.0  ]
>>> print(
...     header+putil.eng.pprint_vector(
...         data,
...         width=30,
...         eng=True,
...         frac_length=0,
...         indent=len(header)
...     )
... )
Vector: [    1m,   20u,  300M,    4p,
             5k,   -6n,  700 ,    8 ,
             9  ]
>>> print(putil.eng.pprint_vector(data, eng=True, frac_length=0))
[    1m,   20u,  300M,    4p,    5k,   -6n,  700 ,    8 ,    9  ]
>>> print(putil.eng.pprint_vector(data, limit=True))
[ 0.001, 2e-05, 300000000.0, ..., 700, 8, 9 ]

putil.eng.round_mantissa(arg, decimals=0)¶

Rounds the fractional part of a floating point number mantissa or Numpy vector of floating point numbers to a given number of digits. Integers are not altered. The mantissa used is that of the floating point number(s) when expressed in normalized scientific notation

Parameters:	arg (integer, float, Numpy vector of integers or floats, or None) – Input data decimals (integer) – Number of digits to round the fractional part of the mantissa to.
Return type:	same as arg

For example:

>>> import putil.eng
>>> putil.eng.round_mantissa(012345678E-6, 3)
12.35
>>> putil.eng.round_mantissa(5, 3)
5

putil.eng.to_scientific_string(number, frac_length=None, exp_length=None, sign_always=False)¶

Converts a number or a string representing a number to a string with the number expressed in scientific notation. Full precision is maintained if the number is represented as a string

Parameters:

number (number or string) – Number to convert
frac_length (integer or None) – Number of digits of fractional part, None indicates that the fractional part of the number should not be limited
exp_length (integer or None) – Number of digits of the exponent; the actual length of the exponent takes precedence if it is longer
sign_always (boolean) – Flag that indicates whether the sign always precedes the number for both non-negative and negative numbers (True) or only for negative numbers (False)

Return type:

string

For example:

>>> import putil.eng
>>> putil.eng.to_scientific_string(333)
'3.33E+2'
>>> putil.eng.to_scientific_string(0.00101)
'1.01E-3'
>>> putil.eng.to_scientific_string(99.999, 1, 2, True)
'+1.0E+02'

putil.eng.to_scientific_tuple(number)¶

Returns mantissa and exponent of a number when expressed in scientific notation. Full precision is maintained if the number is represented as a string

Parameters:	number (integer, float or string) – Number
Return type:	named tuple in which the first item is the mantissa (string) and the second item is the exponent (integer) of the number when expressed in scientific notation

For example:

>>> import putil.eng
>>> putil.eng.to_scientific_tuple('135.56E-8')
NumComp(mant='1.3556', exp=-6)
>>> putil.eng.to_scientific_tuple(0.0000013556)
NumComp(mant='1.3556', exp=-6)