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 30.3 `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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x02/x02intro.html
"""
# NAG Copyright 2017-2024.
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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x02/x02intro.html>`__.
.. _x02bh-py2-py-doc:
For full information please refer to the NAG Library document for x02bh
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x02/x02bhf.html
**Returns**
**irad** : int
The base argument :math:`b` of the model of floating-point arithmetic as described in `the X02 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x02/x02intro.html>`__.
.. _x02bj-py2-py-doc:
For full information please refer to the NAG Library document for x02bj
https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x02/x02intro.html>`__.
.. _x02bk-py2-py-doc:
For full information please refer to the NAG Library document for x02bk
https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x02/x02intro.html>`__.
.. _x02bl-py2-py-doc:
For full information please refer to the NAG Library document for x02bl
https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/x02/x02intro.html>`__.
"""
raise NotImplementedError
