# Source code for naginterfaces.library.ieee

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.0 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_29/flhtml/x07/x07intro.html
"""

[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_29/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_29/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_29/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_29/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_29/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_29/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