Source code for naginterfaces.​library.​ieee

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 27.1 `ieee` Chapter.

``ieee`` - IEEE Arithmetic

This module provides functions to handle various aspects of IEEE floating-point arithmetic behaviour.

Functionality Index
-------------------

Create a floating-point infinity: :meth:`create_infinity`

Create a floating-point NaN (Not a Number): :meth:`create_nan`

Determine whether a floating-point number is finite: :meth:`is_finite`

Determine whether a floating-point number is NaN (Not a Number): :meth:`is_nan`

Get current behaviour of floating-point exceptions: :meth:`get_exception_mode`

Set behaviour of floating-point exceptions: :meth:`set_exception_mode`

For full information please refer to the NAG Library document

https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/x07/x07intro.html
"""

# NAG Copyright 2017-2021.

[docs]def is_finite(x): r""" ``is_finite`` determines whether a floating-point number is finite. .. _x07aa-py2-py-doc: For full information please refer to the NAG Library document for x07aa https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/x07/x07aaf.html .. _x07aa-py2-py-parameters: **Parameters** **x** : float The number whose status is to be determined. **Returns** **finite** : bool :math:`\textit{ifinite} = 1` if and only if :math:`\mathrm{x}` is finite, and :math:`\textit{ifinite} = 0` otherwise. .. _x07aa-py2-py-notes: **Notes** ``is_finite`` returns :math:`\mathbf{True}` if and only if :math:`\mathrm{x}` is finite, and returns :math:`\mathbf{False}` otherwise. .. _x07aa-py2-py-references: **References** IEEE, 2008, `Standard for Floating-Point Arithmetic` (IEEE Standard 754-2008), IEEE, New York. """ raise NotImplementedError
[docs]def is_nan(x): r""" ``is_nan`` determines whether a floating-point number is a NaN (Not A Number). .. _x07ab-py2-py-doc: For full information please refer to the NAG Library document for x07ab https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/x07/x07abf.html .. _x07ab-py2-py-parameters: **Parameters** **x** : float The number whose status is to be determined. **Returns** **isnan** : bool :math:`\textit{iisnan} = 1` if and only if :math:`\mathrm{x}` is a NaN, and :math:`\textit{isnan} = 0` otherwise. .. _x07ab-py2-py-notes: **Notes** ``is_nan`` returns :math:`\mathbf{True}` if and only if :math:`\mathrm{x}` is a NaN, and returns :math:`\mathbf{False}` otherwise. .. _x07ab-py2-py-references: **References** IEEE, 2008, `Standard for Floating-Point Arithmetic` (IEEE Standard 754-2008), IEEE, New York. """ raise NotImplementedError
[docs]def create_infinity(isign): r""" ``create_infinity`` creates a signed infinite value. .. _x07ba-py2-py-doc: For full information please refer to the NAG Library document for x07ba https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/x07/x07baf.html .. _x07ba-py2-py-parameters: **Parameters** **isign** : int Determines the sign of the infinity to be created. If :math:`\mathrm{isign}` is greater than or equal to :math:`0`, a positive infinity is returned, otherwise a negative infinity is returned. **Returns** **x** : float The required infinite value. .. _x07ba-py2-py-notes: **Notes** ``create_infinity`` sets :math:`\mathrm{x}` to be positive or negative infinity. .. _x07ba-py2-py-references: **References** IEEE, 2008, `Standard for Floating-Point Arithmetic` (IEEE Standard 754-2008), IEEE, New York. """ raise NotImplementedError
[docs]def create_nan(quiet): r""" ``create_nan`` creates a NaN (Not A Number). .. _x07bb-py2-py-doc: For full information please refer to the NAG Library document for x07bb https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/x07/x07bbf.html .. _x07bb-py2-py-parameters: **Parameters** **quiet** : int Determines whether a quiet or a signalling NaN is to be created. If :math:`\mathrm{quiet} = 1`, the returned NaN is quiet, otherwise it is signalling. See reference IEEE (2008) for the distinction between the two kinds. **Returns** **x** : float The required NaN value. .. _x07bb-py2-py-notes: **Notes** ``create_nan`` sets :math:`\mathrm{x}` to be a quiet or a signalling NaN (Not A Number). .. _x07bb-py2-py-references: **References** IEEE, 2008, `Standard for Floating-Point Arithmetic` (IEEE Standard 754-2008), IEEE, New York. """ raise NotImplementedError
[docs]def get_exception_mode(): r""" ``get_exception_mode`` gets the current IEEE exception halting mode. .. _x07ca-py2-py-doc: For full information please refer to the NAG Library document for x07ca https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/x07/x07caf.html **Returns** **exceptionmode** : int, ndarray, shape :math:`\left(3\right)` Each of the three elements of :math:`\mathrm{exceptionmode}` is set to :math:`1` if the corresponding condition will raise an exception, and is set to :math:`0` otherwise. :math:`\mathrm{exceptionmode}[0]` concerns floating-point overflow, :math:`\mathrm{exceptionmode}[1]` concerns floating-point division by zero, and :math:`\mathrm{exceptionmode}[2]` concerns floating-point invalid operation. .. _x07ca-py2-py-notes: **Notes** ``get_exception_mode`` gets the current IEEE exception halting mode for the three common exceptions: overflow, divide-by-zero and invalid operation. .. _x07ca-py2-py-references: **References** IEEE, 2008, `Standard for Floating-Point Arithmetic` (IEEE Standard 754-2008), IEEE, New York. """ raise NotImplementedError
[docs]def set_exception_mode(exceptionmode): r""" ``set_exception_mode`` sets the current IEEE exception halting mode. .. _x07cb-py2-py-doc: For full information please refer to the NAG Library document for x07cb https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/x07/x07cbf.html .. _x07cb-py2-py-parameters: **Parameters** **exceptionmode** : int, array-like, shape :math:`\left(3\right)` Each of the three elements of :math:`\mathrm{exceptionmode}` must contain any nonzero value if the corresponding condition should raise an exception, and contain :math:`0` otherwise. :math:`\mathrm{exceptionmode}[0]` concerns floating-point overflow, :math:`\mathrm{exceptionmode}[1]` concerns floating-point division by zero, and :math:`\mathrm{exceptionmode}[2]` concerns floating-point invalid operation. .. _x07cb-py2-py-notes: **Notes** ``set_exception_mode`` sets the current IEEE exception halting mode for the three common exceptions: overflow, divide-by-zero and invalid operation. .. _x07cb-py2-py-references: **References** IEEE, 2008, `Standard for Floating-Point Arithmetic` (IEEE Standard 754-2008), IEEE, New York. """ raise NotImplementedError