Source code for naginterfaces.library.ieee
# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.3 `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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x07/x07intro.html
"""
# NAG Copyright 2017-2024.
[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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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
