# Source code for naginterfaces.library.machine

# -*- coding: utf-8 -*-
# pylint: disable=chained-comparison,invalid-name,line-too-long,protected-access,too-many-arguments,too-many-boolean-expressions,too-many-branches,too-many-lines,too-many-locals,too-many-statements,unneeded-not,unused-import
r"""
Module Summary
--------------
Interfaces for the NAG Mark 28.4 machine Chapter.

machine - Machine Constants

This module is concerned with **parameters** which characterise certain aspects of the **computing environment** in which the NAG Library is implemented.
They relate primarily to floating-point arithmetic, but also to integer arithmetic, the elementary functions and exception handling.
The values of the parameters vary from one implementation of the NAG Library to another, but within the context of a single implementation they are constants.

The parameters are intended for use primarily by other functions in the NAG Library, but users of the NAG Library may sometimes need to refer to them directly.

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

**Derived parameters of model of floating-point arithmetic**

largest positive model number: :meth:real_largest

machine precision: :meth:precision

safe range: :meth:real_safe

safe range of complex floating-point arithmetic: :meth:complex_safe

smallest positive model number: :meth:real_smallest

Largest permissible argument for SIN and COS: :meth:sinarg_max

Largest representable integer: :meth:integer_max

Maximum number of decimal digits that can be represented: :meth:decimal_digits

**Parameters of model of floating-point arithmetic**

:math:b: :meth:model_base

:math:e_{\mathrm{max}}: :meth:model_maxexp

:math:e_{\mathrm{min}}: :meth:model_minexp

:math:p: :meth:model_digits

For full information please refer to the NAG Library document

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html
"""

from ..base import machine as _b_machine

[docs]def sinarg_max():
r"""
sinarg_max returns the largest positive argument for which the Fortran intrinsic functions SIN and COS return a result with some meaningful accuracy.

.. _x02ah-py2-py-doc:

For full information please refer to the NAG Library document for x02ah

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02ahf.html

**Returns**
**maxsc** : float
The largest positive argument for which the Fortran intrinsic functions SIN and COS return a result with some meaningful accuracy.

.. _x02ah-py2-py-notes:

**Notes**
The trigonometric functions :math:\textit{sin} and :math:\textit{cos} supplied in some compiler run-time libraries do not return accurate results when their argument is large.
Often the related accuracy of a result gets progressively worse as the argument gets larger. sinarg_max gives a value beyond which the compiler run-time library returns results with no relative accuracy at all.
Note that some run-time libraries do return accurate results for all arguments to :math:\textit{sin} and :math:\textit{cos}.
"""
raise NotImplementedError

[docs]def precision():
r"""
precision returns :math:\epsilon, the value machine precision.

.. _x02aj-py2-py-doc:

For full information please refer to the NAG Library document for x02aj

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02ajf.html

**Returns**
**eps** : float
:math:\epsilon, the value machine precision.

.. _x02aj-py2-py-notes:

**Notes**
precision returns machine precision, computed as :math:\epsilon = \frac{1}{2}\times b^{{1-p}}, where :math:b is the arithmetic base (see :meth:model_base) and :math:p is the number of significant base-:math:b digits (see :meth:model_digits).

It is important to note that the definition of :math:\epsilon here differs from that in ISO Fortran 95 (1997).

.. _x02aj-py2-py-references:

**References**
ISO Fortran 95, 1997, ISO Fortran 95 programming language, (ISO/IEC 1539--1:1997)
"""

_return_scalar = _b_machine.precision(
)
return _return_scalar

[docs]def real_smallest():
r"""
real_smallest returns the smallest positive floating-point number.

.. _x02ak-py2-py-doc:

For full information please refer to the NAG Library document for x02ak

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02akf.html

**Returns**
**tiny_nag** : float
The smallest positive floating-point number.

.. _x02ak-py2-py-notes:

**Notes**
real_smallest returns the smallest positive number in the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.
The returned value is equal to :math:b^{{e_{\textit{min}}-1}}, where :math:b is the arithmetic base (see :meth:model_base) and :math:e_{\textit{min}} is the minimum exponent (see :meth:model_minexp) in the model.
"""
raise NotImplementedError

[docs]def real_largest():
r"""
real_largest returns the largest positive floating-point number.

.. _x02al-py2-py-doc:

For full information please refer to the NAG Library document for x02al

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02alf.html

**Returns**
**huge_nag** : float
The largest positive floating-point number.

.. _x02al-py2-py-notes:

**Notes**
real_largest returns the largest positive number in the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.
The returned value is equal to :math:\left(1-b^{{-p}}\right)\times b^{e_{\textit{max}}}, where :math:b is the arithmetic base (see :meth:model_base) and :math:e_{\textit{max}} is the maximum exponent (see :meth:model_maxexp) in the model.
"""
raise NotImplementedError

[docs]def real_safe():
r"""
real_safe returns the **safe range** of floating-point arithmetic.

.. _x02am-py2-py-doc:

For full information please refer to the NAG Library document for x02am

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02amf.html

**Returns**
**saferange** : float
The **safe range** of floating-point arithmetic.

.. _x02am-py2-py-notes:

**Notes**
real_safe is defined to be the smallest positive model number :math:z such that for any :math:x in the range [:math:z,1/z] the following can be computed without undue loss of accuracy, overflow, underflow or other error:

:math:{-x}

:math:1/x

:math:-1/x

:math:\sqrt{x}

:math:\log\left(x\right)

:math:\mathrm{exp}\left(\log\left(x\right)\right)

:math:y^{\left(\log\left(x\right)/\log\left(y\right)\right)} for any :math:y
"""
raise NotImplementedError

[docs]def complex_safe():
r"""
complex_safe returns the **safe range** of complex floating-point arithmetic.

.. _x02an-py2-py-doc:

For full information please refer to the NAG Library document for x02an

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02anf.html

**Returns**
**zrange** : float
The **safe range** of complex floating-point arithmetic.

.. _x02an-py2-py-notes:

**Notes**
complex_safe is defined to be the smallest positive model number :math:z such that for any :math:x in the range [:math:z,1/z] the following can be computed without undue loss of accuracy, overflow, underflow or other error:

:math:{-w}

:math:1/w

:math:-1/w

:math:\sqrt{w}

:math:\log\left(w\right)

:math:\mathrm{exp}\left(\log\left(w\right)\right)

:math:y^{\left(\log\left(w\right)/\log\left(y\right)\right)} for any :math:y

:math:\left\lvert w\right\rvert

where :math:w is any of :math:x, :math:ix, :math:x+ix, :math:1/x, :math:i/x, :math:1/x+i/x, and :math:i is the square root of :math:-1.
"""
raise NotImplementedError

[docs]def integer_max():
r"""
integer_max returns the largest representable positive integer value.

.. _x02bb-py2-py-doc:

For full information please refer to the NAG Library document for x02bb

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02bbf.html

**Returns**
**hugeint** : int
The largest representable positive integer value.
"""
raise NotImplementedError

[docs]def decimal_digits():
r"""
decimal_digits returns the maximum number of decimal digits which can be accurately represented over the whole range of floating-point numbers.

.. _x02be-py2-py-doc:

For full information please refer to the NAG Library document for x02be

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02bef.html

**Returns**
**iprec** : int
The maximum number of decimal digits which can be accurately represented over the whole range of floating-point numbers.
"""
raise NotImplementedError

[docs]def model_base():
r"""
model_base returns the base argument :math:b of the model of floating-point arithmetic as described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.

.. _x02bh-py2-py-doc:

For full information please refer to the NAG Library document for x02bh

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02bhf.html

**Returns**
The base argument :math:b of the model of floating-point arithmetic as described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.
"""
raise NotImplementedError

[docs]def model_digits():
r"""
model_digits returns the precision argument :math:p (i.e., the number of significant base-:math:b digits) of the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.

.. _x02bj-py2-py-doc:

For full information please refer to the NAG Library document for x02bj

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02bjf.html

**Returns**
**idigs** : int
The precision argument :math:p (i.e., the number of significant base-:math:b digits) of the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.
"""
raise NotImplementedError

[docs]def model_minexp():
r"""
model_minexp returns the minimum exponent argument :math:e_{\mathrm{min}} of the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.

.. _x02bk-py2-py-doc:

For full information please refer to the NAG Library document for x02bk

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02bkf.html

**Returns**
**minexp** : int
The minimum exponent argument :math:e_{\mathrm{min}} of the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.
"""
raise NotImplementedError

[docs]def model_maxexp():
r"""
model_maxexp returns the maximum exponent argument :math:e_{\mathrm{max}} of the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.

.. _x02bl-py2-py-doc:

For full information please refer to the NAG Library document for x02bl

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02blf.html

**Returns**
**maxexp** : int
The maximum exponent argument :math:e_{\mathrm{max}} of the model of floating-point arithmetic described in the X02 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/x02/x02intro.html>__.
"""
raise NotImplementedError