Skip to content
Cross-project library for converting IBM-format hexadecimal floating-point to IEEE format binary floating-point.
Python C
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ibm2ieee
.gitignore
.travis.yml
CHANGES
LICENSE
MANIFEST.in
README.rst
appveyor.yml
pyproject.toml
setup.py

README.rst

The ibm2ieee package provides NumPy universal functions ("ufuncs") for converting IBM single-precision and double-precision hexadecimal floats to the IEEE 754-format floats used by Python and NumPy on almost all current platforms.

Features

  • Fast: 200-400 million values converted per second on a typical modern machine, assuming normal inputs.
  • Correct: converted results are correctly rounded, according to the default IEEE 754 round-ties-to-even rounding mode. Corner cases (overflow, underflow, subnormal results, signed zeros, non-normalised input) are all handled correctly. Where the rounded converted value is out of range for the target type, an appropriately-signed infinity is returned.
  • Handles both single-precision and double-precision input and output formats.

Portability note: the conversion functions provided in this module assume that numpy.float32 and numpy.float64 are based on the standard IEEE 754 binary32 and binary64 floating-point formats. This is true on the overwhelming majority of current platforms, but is not guaranteed by the relevant language standards.

Usage

The package provides two functions:

  • ibm2float32 converts IBM single- or double-precision data to IEEE 754 single-precision values, in numpy.float32 format.
  • ibm2float64 converts IBM single- or double-precision data to IEEE 754 double-precision values, in numpy.float64 format.

For both functions, IBM single-precision input data must be represented using the numpy.uint32 dtype, while IBM double-precision inputs must be represented using numpy.uint64.

Both functions assume that the IBM data have been converted to NumPy integer format in such a way that the most significant bits of the floating-point number become the most significant bits of the integer values. So when decoding byte data representing IBM hexadecimal floating-point numbers, it's important to take the endianness of the byte data into account. See the Examples section below for an example of converting big-endian byte data.

Examples

>>> import numpy
>>> from ibm2ieee import ibm2float32, ibm2float64
>>> ibm2float32(numpy.uint32(0xc1180000))
-1.5
>>> type(ibm2float32(numpy.uint32(0xc1180000)))
<class 'numpy.float32'>
>>> ibm2float32(numpy.uint64(0x413243f6a8885a31))
3.1415927
>>> ibm2float32(numpy.uint32(0x61100000))
inf
>>> ibm2float64(numpy.uint32(0xc1180000))
-1.5
>>> ibm2float64(numpy.uint64(0x413243f6a8885a31))
3.141592653589793
>>> ibm2float64(numpy.uint32(0x61100000))
3.402823669209385e+38
>>> input_array = numpy.arange(
        0x40fffffe, 0x41000002, dtype=numpy.uint32).reshape(2, 2)
>>> input_array
array([[1090519038, 1090519039],
       [1090519040, 1090519041]], dtype=uint32)
>>> ibm2float64(input_array)
array([[9.99999881e-01, 9.99999940e-01],
       [0.00000000e+00, 9.53674316e-07]])

When converting byte data read from a file, it's important to know the endianness of that data (which is frequently big-endian in historical data files using IBM hex floating-point). Here's an example of converting IBM single-precision data stored in big-endian form to numpy.float32. Note the use of the '>u4' dtype when converting the bytestring to a NumPy uint32 array. For little-endian input data, you would use '<u4' instead.

>>> input_data = b'\xc12C\xf7\xc1\x19!\xfb\x00\x00\x00\x00A\x19!\xfbA2C\xf7'
>>> input_as_uint32 = numpy.frombuffer(input_data, dtype='>u4')
>>> input_as_uint32
array([3241296887, 3239649787,          0, 1092166139, 1093813239],
      dtype=uint32)
>>> ibm2float32(input_as_uint32)
array([-3.141593, -1.570796,  0.      ,  1.570796,  3.141593],
      dtype=float32)

Notes on the formats

The IBM single-precision format has a precision of 6 hexadecimal digits, which in practice translates to a precision of 21-24 bits, depending on the binade that the relevant value belongs to. IEEE 754 single-precision has a precision of 24 bits. So all not-too-small, not-too-large IBM single-precision values can be translated to IEEE 754 single-precision values with no loss of precision. However, the IBM single precision range is larger than the corresponding IEEE 754 range, so extreme IBM single-precision values may overflow to infinity, underflow to zero, or be rounded to a subnormal value when converted to IEEE 754 single-precision.

For double-precision conversions, the tradeoff works the other way: the IBM double-precision format has an effective precision of 53-56 bits, while IEEE 754 double-precision has 53-bit precision. So most IBM values will be rounded when converted to IEEE 754. However, the IEEE 754 double-precision range is larger than that of IBM double-precision, so there's no danger of overflow, underflow, or reduced-precision subnormal results when converting IBM double-precision to IEEE 754 double-precision.

Every IBM single-precision value can be exactly represented in IEEE 754 double-precision, so if you want a lossless representation of IBM single-precision data, use ibm2float64.

Note that the IBM formats do not allow representations of special values like infinities and NaNs. However, signed zeros are representable, and the sign of a zero is preserved under all conversions.

Installation

The latest release of ibm2ieee is available from the Python Package Index, at https://pypi.org/project/ibm2ieee. It can be installed with pip in the usual way:

pip install ibm2ieee

Note that it includes a C extension, so you'll need a compiler on your system to be able to install.

License

The ibm2ieee package is copyright (c) 2018, Enthought, Inc.

The ibm2ieee package is licensed under a standard BSD 3-clause License. See the LICENSE file for details.

You can’t perform that action at this time.