Skip to main content

read and write in engineering notation

Project description

A light-weight package used to read and write numbers in engineering format. In engineering format a number generally includes the units if available and uses SI scale factors to indicate the magnitude of the number. For example:

1ns
1.4204GHz

The pairing of a number and units is referred to as a quantity.

Shortcut Functions

Generally one uses the shortcut functions to convert numbers to and from engineering format. All of these functions take a value and units. The value may be a string or a real number. If it is a string it may be given in traditional format or in engineering format, and it may include the units. For example:

>>> from engfmt import to_quantity
>>> to_quantity('1.4204GHz')
(1420400000.0, 'Hz')

>>> from engfmt import to_eng_quantity
>>> to_eng_quantity(1420400000.0, 'Hz')
'1.4204GHz'

>>> from engfmt import to_flt_quantity
>>> to_flt_quantity(1420400000.0, 'Hz')
'1.4204e+09Hz'

>>> from engfmt import to_number
>>> to_number('1.4204GHz')
1420400000.0

>>> from engfmt import to_flt_number
>>> to_flt_number('1.4204GHz')
'1.4204e9'

>>> from engfmt import to_eng_number
>>> to_eng_number('1.4204e9Hz')
'1.4204G'

>>> from engfmt import strip_units
>>> strip_units('1.4204GHz')
'1.4204G'
>>> strip_units('1.4204e9Hz')
'1.4204e9'

Notice that the output of quanity functions always include the units and the output of number functions do not.

The output of the to_eng_number and to_eng_quantity is always rounded to the desired precision, which can be specified as an argument to these functions. This differs from the to_flt_number and to_flt_quantity functions. They attempt to retain the original format of the number if it is specified as a string. In this way it retains its original precision. The underlying assumption behind this difference is that engineering notation is generally used when communicating with people, whereas floating point notation is used when communicating with machines. People benefit from having a limited number of digits in the numbers, whereas machines benefit from have full precision numbers.

Preferences

You can adjust some of the behavior of these functions on a global basis using set_preferences:

>>> from engfmt import set_preferences
>>> set_preferences(prec=2, spacer=' ')
>>> to_eng_quantity('1.4204GHz')
'1.42 GHz'
>>> to_eng_quantity('1.4204GHz', prec=4)
'1.4204 GHz'

Specifying prec to be 4 gives 5 digits of precision (you get one more digit than the number you specify for precision). Thus, the valid range for prec is from 0 to around 12 to 14 for double precision numbers.

Passing None as a value in set_preferences returns that preference to its default value:

>>> set_preferences(prec=None, spacer=None)
>>> to_eng_quantity('1.4204GHz')
'1.4204GHz'

Quantity Class

Though rarely used, the engfmt package defines the Quantity class, which is a bit more flexible than the shortcut functions:

>>> from engfmt import Quantity
>>> h_line = Quantity('1420.405751786 MHz')

>>> str(h_line)
'1.4204GHz'

>>> float(h_line)
1420405751.786

>>> h_line.to_quantity()
(1420405751.786, 'Hz')

>>> h_line.to_eng_quantity(4)
'1.4204GHz'

>>> h_line.to_flt_quantity()
'1420.405751786e6Hz'

>>> h_line.to_number()
1420405751.786

>>> h_line.to_eng_number(4)
'1.4204G'

>>> h_line.to_flt_number()
'1420.405751786e6'

>>> h_line.strip_units()
'1420.405751786M'

>>> h_line.units()
'Hz'

>>> h_line.is_infinite()
False

>>> h_line.is_nan()
False

Physical Constants

The Quantity class also supports a small number of physical constants (you can modify the source code if you would like to add more).

Plank’s constant:

>>> plank = Quantity('h')
>>> print(str(plank))
662.61e-36J-s

Boltzmann’s constant:

>>> boltz = Quantity('k')
>>> print(str(boltz))
13.806e-24J/K

Elementary charge:

>>> q = Quantity('q')
>>> print(str(q))
160.22e-21C

Speed of light:

>>> c = Quantity('c')
>>> print(str(c))
299.79Mm/s

Zero degrees Celsius in Kelvin:

>>> zeroC = Quantity('C0')
>>> print(str(zeroC))
273.15K

Permittivity of free space:

>>> eps0 = Quantity('eps0')
>>> print(str(eps0))
8.8542pF/m

Permeability of free space:

>>> mu0 = Quantity('mu0')
>>> print(str(mu0))
1.2566uH/m

Characteristic impedance of free space:

>>> Z0 = Quantity('Z0')
>>> print(str(Z0))
376.73Ohms

String Formatting

Quantities can be passed into the string format function:

>>> print('{}'.format(h_line))
1.4204GHz

You can specify the precision as part of the format specification

>>> print('{:.6}'.format(h_line))
1.420406GHz

The ‘q’ type specifier can be used to explicitly indicate both the number and units are desired:

>>> print('{:.6q}'.format(h_line))
1.420406GHz

Alternately, ‘r’ can be used to indicate just the number is desired:

>>> print('{:r}'.format(h_line))
1.4204G

You can also use the string and floating point format type specifiers:

>>> print('{:f}'.format(h_line))
1420405751.786000

>>> print('{:e}'.format(h_line))
1.420406e+09

>>> print('{:g}'.format(h_line))
1.42041e+09

>>> print('{:s}'.format(h_line))
1.4204GHz

Exceptions

A ValueError is raised if engfmt is passed a string it cannot convert into a number:

>>> try:
...     value, units = to_quantity('xxx')
... except ValueError as err:
...     print(str(err))
xxx: not a valid number.

Text Processing

Two functions are available for converting quantities embedded within text to and from engineering notation:

>>> from engfmt import all_to_eng_fmt, all_from_eng_fmt
>>> all_to_eng_fmt('The frequency of the hydrogen line is 1420405751.786Hz.')
'The frequency of the hydrogen line is 1.4204GHz.'

>>> all_from_eng_fmt('The frequency of the hydrogen line is 1.4204GHz.')
'The frequency of the hydrogen line is 1.4204e9Hz.'

Add to Namespace

It is possible to put a collection of quantities in a text string and then use the add_to_namespace function to parse the quantities and add them to the Python namespace. For example:

add_to_namespace('''
    Fref = 156MHz  -- Reference frequency
    Kdet = 88.3uA  -- Gain of phase detector (Imax)
    Kvco = 9.07GHz/V  -- Gain of VCO
''')
print('{}\n{}\n{}'.format(Fref, Kdet, Kvco)
156MHz
88.3uA
9.07GHz/V

Any number of quantities may be given, with each quantity given on its own line. The identifier given to the left ‘=’ is the name of the variable in the local namespace that is used to hold the quantity. The text after the ‘–’ is ignored and is generally used as a description of the quantity.

Installation

Use ‘pip install engfmt’ to install. Requires Python2.7 or Python3.2 or better.

https://travis-ci.org/KenKundert/engfmt.svg?branch=master

Testing

Run ‘py.test’ to run the tests.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

engfmt-0.5.0.tar.gz (12.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page