Metadata-Version: 2.1
Name: ibm2ieee
Version: 1.1.0
Summary: Convert IBM hexadecimal floating-point data to IEEE 754 floating-point data.
Home-page: https://github.com/enthought/ibm2ieee
Author: Enthought
Author-email: info@enthought.com
License: UNKNOWN
Description: 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.
        
        ibm2ieee requires Python >= 3.6.
        
        
        License
        -------
        
        (C) Copyright 2018-2021 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!
        
Keywords: ibm hfp ieee754 hexadecimal floating-point ufunc
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Provides-Extra: test
