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

Wheels are provided for common platforms and Python versions. If installing
from source, note that ibm2ieee includes a C extension, so you'll need the
appropriate compiler on your system to be able to install.

ibm2ieee requires Python >= 3.6.


License
-------

(C) Copyright 2018-2022 Enthought, Inc., Austin, TX
All rights reserved.

This software is provided without warranty under the terms of the BSD
license included in LICENSE.txt and may be redistributed only under
the conditions described in the aforementioned license. The license
is also available online at http://www.enthought.com/licenses/BSD.txt

Thanks for using Enthought open source!
