### Navigation

- index
- modules |
- next |
- previous |
- Fixed and Arbitrary Precision Numerical Fields »

# Arbitrary Precision Real Numbers

Arbitrary Precision Real Numbers

AUTHORS:

- Kyle Schalm (2005-09)
- William Stein: bug fixes, examples, maintenance
- Didier Deshommes (2006-03-19): examples
- David Harvey (2006-09-20): compatibility with Element._parent
- William Stein (2006-10): default printing truncates to avoid base-2 rounding confusing (fix suggested by Bill Hart)
- Didier Deshommes: special constructor for QD numbers
- Paul Zimmermann (2008-01): added new functions from mpfr-2.3.0, replaced some, e.g., sech = 1/cosh, by their original mpfr version.
- Carl Witty (2008-02): define floating-point rank and associated functions; add some documentation
- Robert Bradshaw (2009-09): decimal literals, optimizations
- Jeroen Demeyer (2012-05-27): set the MPFR exponent range to the maximal possible value (trac ticket #13033)
- Travis Scrimshaw (2012-11-02): Added doctests for full coverage

This is a binding for the MPFR arbitrary-precision floating point library.

We define a class `RealField`, where each instance of `RealField` specifies a field of floating-point numbers with a specified precision and rounding mode. Individual floating-point numbers are of `RealNumber`.

In Sage (as in MPFR), floating-point numbers of precision \(p\) are of the form \(s m 2^{e-p}\), where \(s \in \{-1, 1\}\), \(2^{p-1} \leq m < 2^p\), and \(-2^B + 1 \leq e \leq 2^B - 1\) where \(B = 30\) on 32-bit systems and \(B = 62\) on 64-bit systems; additionally, there are the special values `+0`, `-0`, `+infinity`, `-infinity` and `NaN` (which stands for Not-a-Number).

Operations in this module which are direct wrappers of MPFR functions are “correctly rounded”; we briefly describe what this means. Assume that you could perform the operation exactly, on real numbers, to get a result \(r\). If this result can be represented as a floating-point number, then we return that number.

Otherwise, the result \(r\) is between two floating-point numbers. For the directed rounding modes (round to plus infinity, round to minus infinity, round to zero), we return the floating-point number in the indicated direction from \(r\). For round to nearest, we return the floating-point number which is nearest to \(r\).

This leaves one case unspecified: in round to nearest mode, what happens if \(r\) is exactly halfway between the two nearest floating-point numbers? In that case, we round to the number with an even mantissa (the mantissa is the number \(m\) in the representation above).

Consider the ordered set of floating-point numbers of precision \(p\). (Here we identify `+0` and `-0`, and ignore `NaN`.) We can give a bijection between these floating-point numbers and a segment of the integers, where 0 maps to 0 and adjacent floating-point numbers map to adjacent integers. We call the integer corresponding to a given floating-point number the “floating-point rank” of the number. (This is not standard terminology; I just made it up.)

EXAMPLES:

A difficult conversion:

    sage: RR(sys.maxsize)
    9.22337203685478e18      # 64-bit
    2.14748364700000e9       # 32-bit

TESTS:

    sage: -1e30
    -1.00000000000000e30
    sage: hex(-1. + 2^-52)
    '-0xf.ffffffffffffp-4'

Make sure we don’t have a new field for every new literal:

    sage: parent(2.0) is parent(2.0)
    True
    sage: RealField(100, rnd='RNDZ') is RealField(100, rnd='RNDD')
    False
    sage: RealField(100, rnd='RNDZ') is RealField(100, rnd='RNDZ')
    True

class `sage.rings.real_mpfr.``QQtoRR`

  Bases: `sage.categories.map.Map`

  INPUT:

  There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

  TESTS:

      sage: from sage.categories.map import Map

  Using a hom space:

      sage: Map(Hom(QQ, ZZ, Rings()))
      Generic map:
        From: Rational Field
        To:   Integer Ring

  Using domain and codomain:

      sage: Map(QQ['x'], SymmetricGroup(6))
      Generic map:
        From: Univariate Polynomial Ring in x over Rational Field
        To:   Symmetric group of order 6! as a permutation group

class `sage.rings.real_mpfr.``RRtoRR`

  Bases: `sage.categories.map.Map`

  INPUT:

  There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

  TESTS:

      sage: from sage.categories.map import Map

  Using a hom space:

      sage: Map(Hom(QQ, ZZ, Rings()))
      Generic map:
        From: Rational Field
        To:   Integer Ring

  Using domain and codomain:

      sage: Map(QQ['x'], SymmetricGroup(6))
      Generic map:
        From: Univariate Polynomial Ring in x over Rational Field
        To:   Symmetric group of order 6! as a permutation group

  `section`()

    EXAMPLES:

        sage: from sage.rings.real_mpfr import RRtoRR
        sage: R10 = RealField(10)
        sage: R100 = RealField(100)
        sage: f = RRtoRR(R100, R10)
        sage: f.section()
        Generic map:
          From: Real Field with 10 bits of precision
          To:   Real Field with 100 bits of precision

`sage.rings.real_mpfr.``RealField`(prec=53, sci_not=0, rnd='RNDN')

  RealField(prec, sci_not, rnd):

  INPUT:

  - `prec` – (integer) precision; default = 53 prec is the number of bits used to represent the mantissa of a floating-point number. The precision can be any integer between `mpfr_prec_min()` and `mpfr_prec_max()`. In the current implementation, `mpfr_prec_min()` is equal to 2.
  - `sci_not` – (default: `False`) if `True`, always display using scientific notation; if `False`, display using scientific notation only for very large or very small numbers
  - `rnd` – (string) the rounding mode:
    - `'RNDN'` – (default) round to nearest (ties go to the even number): Knuth says this is the best choice to prevent “floating point drift”
    - `'RNDD'` – round towards minus infinity
    - `'RNDZ'` – round towards zero
    - `'RNDU'` – round towards plus infinity

  EXAMPLES:

      sage: RealField(10)
      Real Field with 10 bits of precision
      sage: RealField()
      Real Field with 53 bits of precision
      sage: RealField(100000)
      Real Field with 100000 bits of precision

  Here we show the effect of rounding:

      sage: R17d = RealField(17,rnd='RNDD')
      sage: a = R17d(1)/R17d(3); a.exact_rational()
      87381/262144
      sage: R17u = RealField(17,rnd='RNDU')
      sage: a = R17u(1)/R17u(3); a.exact_rational()
      43691/131072

  Note

  The default precision is 53, since according to the MPFR manual: ‘mpfr should be able to exactly reproduce all computations with double-precision machine floating-point numbers (double type in C), except the default exponent range is much wider and subnormal numbers are not implemented.’

class `sage.rings.real_mpfr.``RealField_class`

  Bases: `sage.rings.ring.Field`

  An approximation to the field of real numbers using floating point numbers with any specified precision. Answers derived from calculations in this approximation may differ from what they would be if those calculations were performed in the true field of real numbers. This is due to the rounding errors inherent to finite precision calculations.

  See the documentation for the module `sage.rings.real_mpfr` for more details.

  `algebraic_closure`()

    Return the algebraic closure of `self`, i.e., the complex field with the same precision.

    EXAMPLES:

        sage: RR.algebraic_closure()
        Complex Field with 53 bits of precision
        sage: RR.algebraic_closure() is CC
        True
        sage: RealField(100,rnd='RNDD').algebraic_closure()
        Complex Field with 100 bits of precision
        sage: RealField(100).algebraic_closure()
        Complex Field with 100 bits of precision

  `catalan_constant`()

    Returns Catalan’s constant to the precision of this field.

    EXAMPLES:

        sage: RealField(100).catalan_constant()
        0.91596559417721901505460351493

  `characteristic`()

    Returns 0, since the field of real numbers has characteristic 0.

    EXAMPLES:

        sage: RealField(10).characteristic()
        0

  `complex_field`()

    Return complex field of the same precision.

    EXAMPLES:

        sage: RR.complex_field()
        Complex Field with 53 bits of precision
        sage: RR.complex_field() is CC
        True
        sage: RealField(100,rnd='RNDD').complex_field()
        Complex Field with 100 bits of precision
        sage: RealField(100).complex_field()
        Complex Field with 100 bits of precision

  `construction`()

    Return the functorial construction of `self`, namely, completion of the rational numbers with respect to the prime at \(\infty\).

    Also preserves other information that makes this field unique (e.g. precision, rounding, print mode).

    EXAMPLES:

        sage: R = RealField(100, rnd='RNDU')
        sage: c, S = R.construction(); S
        Rational Field
        sage: R == c(S)
        True

  `euler_constant`()

    Returns Euler’s gamma constant to the precision of this field.

    EXAMPLES:

        sage: RealField(100).euler_constant()
        0.57721566490153286060651209008

  `factorial`(n)

    Return the factorial of the integer `n` as a real number.

    EXAMPLES:

        sage: RR.factorial(0)
        1.00000000000000
        sage: RR.factorial(1000000)
        8.26393168833124e5565708
        sage: RR.factorial(-1)
        Traceback (most recent call last):
        ...
        ArithmeticError: n must be nonnegative

  `gen`(i=0)

    Return the `i`-th generator of `self`.

    EXAMPLES:

        sage: R=RealField(100)
        sage: R.gen(0)
        1.0000000000000000000000000000
        sage: R.gen(1)
        Traceback (most recent call last):
        ...
        IndexError: self has only one generator

  `gens`()

    Return a list of generators.

    EXAMPLE:

        sage: RR.gens()
        [1.00000000000000]

  `is_exact`()

    Return `False`, since a real field (represented using finite precision) is not exact.

    EXAMPLE:

        sage: RR.is_exact()
        False
        sage: RealField(100).is_exact()
        False

  `is_finite`()

    Return `False`, since the field of real numbers is not finite.

    EXAMPLES:

        sage: RealField(10).is_finite()
        False

  `log2`()

    Return \(\log(2)\) (i.e., the natural log of 2) to the precision of this field.

    EXAMPLES:

        sage: R=RealField(100)
        sage: R.log2()
        0.69314718055994530941723212146
        sage: R(2).log()
        0.69314718055994530941723212146

  `name`()

    Return the name of `self`, which encodes the precision and rounding convention.

    EXAMPLES:

        sage: RR.name()
        'RealField53_0'
        sage: RealField(100,rnd='RNDU').name()
        'RealField100_2'

  `ngens`()

    Return the number of generators.

    EXAMPLES:

        sage: RR.ngens()
        1

  `pi`()

    Return \(\pi\) to the precision of this field.

    EXAMPLES:

        sage: R = RealField(100)
        sage: R.pi()
        3.1415926535897932384626433833
        sage: R.pi().sqrt()/2
        0.88622692545275801364908374167
        sage: R = RealField(150)
        sage: R.pi().sqrt()/2
        0.88622692545275801364908374167057259139877473

  `prec`()

    Return the precision of `self`.

    EXAMPLES:

        sage: RR.precision()
        53
        sage: RealField(20).precision()
        20

  `precision`()

    Return the precision of `self`.

    EXAMPLES:

        sage: RR.precision()
        53
        sage: RealField(20).precision()
        20

  `random_element`(min=-1, max=1, distribution=None)

    Return a uniformly distributed random number between `min` and `max` (default -1 to 1).

    Warning

    The argument `distribution` is ignored—the random number is from the uniform distribution.

    EXAMPLES:

        sage: RealField(100).random_element(-5, 10)
        -1.7093633198207765227646362966
        sage: RealField(10).random_element()
        -0.11

    TESTS:

        sage: RealField(31).random_element()
        -0.676162510
        sage: RealField(32).random_element()
        0.689774422
        sage: RealField(33).random_element()
        0.396496861
        sage: RealField(63).random_element()
        -0.339980711116375371
        sage: RealField(64).random_element()
        -0.0453049884016705260
        sage: RealField(65).random_element()
        -0.5926714709589708137
        sage: RealField(10).random_element()
        0.23
        sage: RealField(10).random_element()
        -0.41
        sage: RR.random_element()
        -0.0420335212948924
        sage: RR.random_element()
        -0.616678906367394

  `rounding_mode`()

    Return the rounding mode.

    EXAMPLES:

        sage: RR.rounding_mode()
        'RNDN'
        sage: RealField(20,rnd='RNDZ').rounding_mode()
        'RNDZ'
        sage: RealField(20,rnd='RNDU').rounding_mode()
        'RNDU'
        sage: RealField(20,rnd='RNDD').rounding_mode()
        'RNDD'

  `scientific_notation`(status=None)

    Set or return the scientific notation printing flag. If this flag is `True` then real numbers with this space as parent print using scientific notation.

    INPUT:

    - `status` – boolean optional flag

    EXAMPLES:

        sage: RR.scientific_notation()
        False
        sage: elt = RR(0.2512); elt
        0.251200000000000
        sage: RR.scientific_notation(True)
        sage: elt
        2.51200000000000e-1
        sage: RR.scientific_notation()
        True
        sage: RR.scientific_notation(False)
        sage: elt
        0.251200000000000
        sage: R = RealField(20, sci_not=1)
        sage: R.scientific_notation()
        True
        sage: R(0.2512)
        2.5120e-1

  `to_prec`(prec)

    Return the real field that is identical to `self`, except that it has the specified precision.

    EXAMPLES:

        sage: RR.to_prec(212)
        Real Field with 212 bits of precision
        sage: R = RealField(30, rnd="RNDZ")
        sage: R.to_prec(300)
        Real Field with 300 bits of precision and rounding RNDZ

  `zeta`(n=2)

    Return an \(n\)-th root of unity in the real field, if one exists, or raise a `ValueError` otherwise.

    EXAMPLES:

        sage: R = RealField()
        sage: R.zeta()
        -1.00000000000000
        sage: R.zeta(1)
        1.00000000000000
        sage: R.zeta(5)
        Traceback (most recent call last):
        ...
        ValueError: No 5th root of unity in self

class `sage.rings.real_mpfr.``RealLiteral`

  Bases: `sage.rings.real_mpfr.RealNumber`

  Real literals are created in preparsing and provide a way to allow casting into higher precision rings.

  `base`
  `literal`

class `sage.rings.real_mpfr.``RealNumber`

  Bases: `sage.structure.element.RingElement`

  A floating point approximation to a real number using any specified precision. Answers derived from calculations with such approximations may differ from what they would be if those calculations were performed with true real numbers. This is due to the rounding errors inherent to finite precision calculations.

  The approximation is printed to slightly fewer digits than its internal precision, in order to avoid confusing roundoff issues that occur because numbers are stored internally in binary.

  `agm`(other)

    Return the arithmetic-geometric mean of `self` and `other`.

    The arithmetic-geometric mean is the common limit of the sequences \(u_n\) and \(v_n\), where \(u_0\) is `self`, \(v_0\) is other, \(u_{n+1}\) is the arithmetic mean of \(u_n\) and \(v_n\), and \(v_{n+1}\) is the geometric mean of \(u_n\) and \(v_n\). If any operand is negative, the return value is `NaN`.

    INPUT:

    - `right` – another real number

    OUTPUT:

    - the AGM of `self` and `other`

    EXAMPLES:

        sage: a = 1.5
        sage: b = 2.5
        sage: a.agm(b)
        1.96811775182478
        sage: RealField(200)(a).agm(b)
        1.9681177518247777389894630877503739489139488203685819712291
        sage: a.agm(100)
        28.1189391225320

    The AGM always lies between the geometric and arithmetic mean:

        sage: sqrt(a*b) < a.agm(b) < (a+b)/2
        True

    It is, of course, symmetric:

        sage: b.agm(a)
        1.96811775182478

    and satisfies the relation \(AGM(ra, rb) = r AGM(a, b)\):

        sage: (2*a).agm(2*b) / 2
        1.96811775182478
        sage: (3*a).agm(3*b) / 3
        1.96811775182478

    It is also related to the elliptic integral

    \[\int_0^{\pi/2} \frac{d\theta}{\sqrt{1-m\sin^2\theta}}.\]

        sage: m = (a-b)^2/(a+b)^2
        sage: E = numerical_integral(1/sqrt(1-m*sin(x)^2), 0, RR.pi()/2)[0]
        sage: RR.pi()/4 * (a+b)/E
        1.96811775182478

    TESTS:

        sage: 1.5.agm(0)
        0.000000000000000

  `algdep`(n)

    Return a polynomial of degree at most \(n\) which is approximately satisfied by this number.

    Note

    The resulting polynomial need not be irreducible, and indeed usually won’t be if this number is a good approximation to an algebraic number of degree less than \(n\).

    ALGORITHM:

    Uses the PARI C-library `algdep` command.

    EXAMPLE:

        sage: r = sqrt(2.0); r
        1.41421356237310
        sage: r.algebraic_dependency(5)
        x^2 - 2

  `algebraic_dependency`(n)

    Return a polynomial of degree at most \(n\) which is approximately satisfied by this number.

    Note

    The resulting polynomial need not be irreducible, and indeed usually won’t be if this number is a good approximation to an algebraic number of degree less than \(n\).

    ALGORITHM:

    Uses the PARI C-library `algdep` command.

    EXAMPLE:

        sage: r = sqrt(2.0); r
        1.41421356237310
        sage: r.algebraic_dependency(5)
        x^2 - 2

  `arccos`()

    Return the inverse cosine of `self`.

    EXAMPLES:

        sage: q = RR.pi()/3
        sage: i = q.cos()
        sage: i.arccos() == q
        True

  `arccosh`()

    Return the hyperbolic inverse cosine of `self`.

    EXAMPLES:

        sage: q = RR.pi()/2
        sage: i = q.cosh() ; i
        2.50917847865806
        sage: q == i.arccosh()
        True

  `arccoth`()

    Return the inverse hyperbolic cotangent of `self`.

    EXAMPLES:

        sage: q = RR.pi()/5
        sage: i = q.coth()
        sage: i.arccoth() == q
        True

  `arccsch`()

    Return the inverse hyperbolic cosecant of `self`.

    EXAMPLES:

        sage: i = RR.pi()/5
        sage: q = i.csch()
        sage: q.arccsch() == i
        True

  `arcsech`()

    Return the inverse hyperbolic secant of `self`.

    EXAMPLES:

        sage: i = RR.pi()/3
        sage: q = i.sech()
        sage: q.arcsech() == i
        True

  `arcsin`()

    Return the inverse sine of `self`.

    EXAMPLES:

        sage: q = RR.pi()/5
        sage: i = q.sin()
        sage: i.arcsin() == q
        True
        sage: i.arcsin() - q
        0.000000000000000

  `arcsinh`()

    Return the hyperbolic inverse sine of `self`.

    EXAMPLES:

        sage: q = RR.pi()/7
        sage: i = q.sinh() ; i
        0.464017630492991
        sage: i.arcsinh() - q
        0.000000000000000

  `arctan`()

    Return the inverse tangent of `self`.

    EXAMPLES:

        sage: q = RR.pi()/5
        sage: i = q.tan()
        sage: i.arctan() == q
        True

  `arctanh`()

    Return the hyperbolic inverse tangent of `self`.

    EXAMPLES:

        sage: q = RR.pi()/7
        sage: i = q.tanh() ; i
        0.420911241048535
        sage: i.arctanh() - q
        0.000000000000000

  `ceil`()

    Return the ceiling of `self`.

    EXAMPLES:

        sage: (2.99).ceil()
        3
        sage: (2.00).ceil()
        2
        sage: (2.01).ceil()
        3

        sage: ceil(10^16 * 1.0)
        10000000000000000
        sage: ceil(10^17 * 1.0)
        100000000000000000
        sage: ceil(RR(+infinity))
        Traceback (most recent call last):
        ...
        ValueError: Calling ceil() on infinity or NaN

  `ceiling`()

    Return the ceiling of `self`.

    EXAMPLES:

        sage: (2.99).ceil()
        3
        sage: (2.00).ceil()
        2
        sage: (2.01).ceil()
        3

        sage: ceil(10^16 * 1.0)
        10000000000000000
        sage: ceil(10^17 * 1.0)
        100000000000000000
        sage: ceil(RR(+infinity))
        Traceback (most recent call last):
        ...
        ValueError: Calling ceil() on infinity or NaN

  `conjugate`()

    Return the complex conjugate of this real number, which is the number itself.

    EXAMPLES:

        sage: x = RealField(100)(1.238)
        sage: x.conjugate()
        1.2380000000000000000000000000

  `cos`()

    Returnn the cosine of `self`.

    EXAMPLES:

        sage: t=RR.pi()/2
        sage: t.cos()
        6.12323399573677e-17

  `cosh`()

    Return the hyperbolic cosine of `self`.

    EXAMPLES:

        sage: q = RR.pi()/12
        sage: q.cosh()
        1.03446564009551

  `cot`()

    Return the cotangent of `self`.

    EXAMPLES:

        sage: RealField(100)(2).cot()
        -0.45765755436028576375027741043

  `coth`()

    Return the hyperbolic cotangent of `self`.

    EXAMPLES:

        sage: RealField(100)(2).coth()
        1.0373147207275480958778097648

  `csc`()

    Return the cosecant of `self`.

    EXAMPLES:

        sage: RealField(100)(2).csc()
        1.0997501702946164667566973970

  `csch`()

    Return the hyperbolic cosecant of `self`.

    EXAMPLES:

        sage: RealField(100)(2).csch()
        0.27572056477178320775835148216

  `cube_root`()

    Return the cubic root (defined over the real numbers) of `self`.

    EXAMPLES:

        sage: r = 125.0; r.cube_root()
        5.00000000000000
        sage: r = -119.0
        sage: r.cube_root()^3 - r       # illustrates precision loss
        -1.42108547152020e-14

  `eint`()

    Returns the exponential integral of this number.

    EXAMPLES:

        sage: r = 1.0
        sage: r.eint()
        1.89511781635594

        sage: r = -1.0
        sage: r.eint()
        NaN

  `epsilon`(field=None)

    Returns `abs(self)` divided by \(2^b\) where \(b\) is the precision in bits of `self`. Equivalently, return `abs(self)` multiplied by the `ulp()` of 1.

    This is a scale-invariant version of `ulp()` and it lies in \([u/2, u)\) where \(u\) is `self.ulp()` (except in the case of zero or underflow).

    INPUT:

    - `field` – `RealField` used as parent of the result. If not specified, use `parent(self)`.

    OUTPUT:

    `field(self.abs() / 2^self.precision())`

    EXAMPLES:

        sage: RR(2^53).epsilon()
        1.00000000000000
        sage: RR(0).epsilon()
        0.000000000000000
        sage: a = RR.pi()
        sage: a.epsilon()
        3.48786849800863e-16
        sage: a.ulp()/2, a.ulp()
        (2.22044604925031e-16, 4.44089209850063e-16)
        sage: a / 2^a.precision()
        3.48786849800863e-16
        sage: (-a).epsilon()
        3.48786849800863e-16

    We use a different field:

        sage: a = RealField(256).pi()
        sage: a.epsilon()
        2.713132368784788677624750042896586252980746500631892201656843478528498954308e-77
        sage: e = a.epsilon(RealField(64))
        sage: e
        2.71313236878478868e-77
        sage: parent(e)
        Real Field with 64 bits of precision
        sage: e = a.epsilon(QQ)
        Traceback (most recent call last):
        ...
        TypeError: field argument must be a RealField

    Special values:

        sage: RR('nan').epsilon()
        NaN
        sage: parent(RR('nan').epsilon(RealField(42)))
        Real Field with 42 bits of precision
        sage: RR('+Inf').epsilon()
        +infinity
        sage: RR('-Inf').epsilon()
        +infinity

  `erf`()

    Return the value of the error function on `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).erf()
        0.995322265018953
        sage: R(6).erf()
        1.00000000000000

  `erfc`()

    Return the value of the complementary error function on `self`, i.e., \(1-\mathtt{erf}(\mathtt{self})\).

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).erfc()
        0.00467773498104727
        sage: R(6).erfc()
        2.15197367124989e-17

  `exact_rational`()

    Returns the exact rational representation of this floating-point number.

    EXAMPLES:

        sage: RR(0).exact_rational()
        0
        sage: RR(1/3).exact_rational()
        6004799503160661/18014398509481984
        sage: RR(37/16).exact_rational()
        37/16
        sage: RR(3^60).exact_rational()
        42391158275216203520420085760
        sage: RR(3^60).exact_rational() - 3^60
        6125652559
        sage: RealField(5)(-pi).exact_rational()
        -25/8

    TESTS:

        sage: RR('nan').exact_rational()
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number
        sage: RR('-infinity').exact_rational()
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number

  `exp`()

    Return \(e^\mathtt{self}\).

    EXAMPLES:

        sage: r = 0.0
        sage: r.exp()
        1.00000000000000

        sage: r = 32.3
        sage: a = r.exp(); a
        1.06588847274864e14
        sage: a.log()
        32.3000000000000

        sage: r = -32.3
        sage: r.exp()
        9.38184458849869e-15

  `exp10`()

    Return \(10^\mathtt{self}\).

    EXAMPLES:

        sage: r = 0.0
        sage: r.exp10()
        1.00000000000000

        sage: r = 32.0
        sage: r.exp10()
        1.00000000000000e32

        sage: r = -32.3
        sage: r.exp10()
        5.01187233627276e-33

  `exp2`()

    Return \(2^\mathtt{self}\).

    EXAMPLES:

        sage: r = 0.0
        sage: r.exp2()
        1.00000000000000

        sage: r = 32.0
        sage: r.exp2()
        4.29496729600000e9

        sage: r = -32.3
        sage: r.exp2()
        1.89117248253021e-10

  `expm1`()

    Return \(e^\mathtt{self}-1\), avoiding cancellation near 0.

    EXAMPLES:

        sage: r = 1.0
        sage: r.expm1()
        1.71828182845905

        sage: r = 1e-16
        sage: exp(r)-1
        0.000000000000000
        sage: r.expm1()
        1.00000000000000e-16

  `floor`()

    Return the floor of `self`.

    EXAMPLES:

        sage: R = RealField()
        sage: (2.99).floor()
        2
        sage: (2.00).floor()
        2
        sage: floor(RR(-5/2))
        -3
        sage: floor(RR(+infinity))
        Traceback (most recent call last):
        ...
        ValueError: Calling floor() on infinity or NaN

  `fp_rank`()

    Returns the floating-point rank of this number. That is, if you list the floating-point numbers of this precision in order, and number them starting with \(0.0 \rightarrow 0\) and extending the list to positive and negative infinity, returns the number corresponding to this floating-point number.

    EXAMPLES:

        sage: RR(0).fp_rank()
        0
        sage: RR(0).nextabove().fp_rank()
        1
        sage: RR(0).nextbelow().nextbelow().fp_rank()
        -2
        sage: RR(1).fp_rank()
        4835703278458516698824705            # 32-bit
        20769187434139310514121985316880385  # 64-bit
        sage: RR(-1).fp_rank()
        -4835703278458516698824705            # 32-bit
        -20769187434139310514121985316880385  # 64-bit
        sage: RR(1).fp_rank() - RR(1).nextbelow().fp_rank()
        1
        sage: RR(-infinity).fp_rank()
        -9671406552413433770278913            # 32-bit
        -41538374868278621023740371006390273  # 64-bit
        sage: RR(-infinity).fp_rank() - RR(-infinity).nextabove().fp_rank()
        -1

  `fp_rank_delta`(other)

    Return the floating-point rank delta between `self` and `other`. That is, if the return value is positive, this is the number of times you have to call `.nextabove()` to get from `self` to `other`.

    EXAMPLES:

        sage: [x.fp_rank_delta(x.nextabove()) for x in
        ...      (RR(-infinity), -1.0, 0.0, 1.0, RR(pi), RR(infinity))]
        [1, 1, 1, 1, 1, 0]

    In the 2-bit floating-point field, one subsegment of the floating-point numbers is: 1, 1.5, 2, 3, 4, 6, 8, 12, 16, 24, 32

        sage: R2 = RealField(2)
        sage: R2(1).fp_rank_delta(R2(2))
        2
        sage: R2(2).fp_rank_delta(R2(1))
        -2
        sage: R2(1).fp_rank_delta(R2(1048576))
        40
        sage: R2(24).fp_rank_delta(R2(4))
        -5
        sage: R2(-4).fp_rank_delta(R2(-24))
        -5

    There are lots of floating-point numbers around 0:

        sage: R2(-1).fp_rank_delta(R2(1))
        4294967298            # 32-bit
        18446744073709551618  # 64-bit

  `frac`()

    Return a real number such that `self = self.trunc() + self.frac()`. The return value will also satisfy `-1 < self.frac() < 1`.

    EXAMPLES:

        sage: (2.99).frac()
        0.990000000000000
        sage: (2.50).frac()
        0.500000000000000
        sage: (-2.79).frac()
        -0.790000000000000
        sage: (-2.79).trunc() + (-2.79).frac()
        -2.79000000000000

  `gamma`()

    Return the value of the Euler gamma function on `self`.

    EXAMPLES:

        sage: R = RealField()
        sage: R(6).gamma()
        120.000000000000
        sage: R(1.5).gamma()
        0.886226925452758

  `hex`()

    Return a hexadecimal floating-point representation of `self`, in the style of C99 hexadecimal floating-point constants.

    EXAMPLES:

        sage: RR(-1/3).hex()
        '-0x5.5555555555554p-4'
        sage: Reals(100)(123.456e789).hex()
        '0xf.721008e90630c8da88f44dd2p+2624'
        sage: (-0.).hex()
        '-0x0p+0'

        sage: [(a.hex(), float(a).hex()) for a in [.5, 1., 2., 16.]]
        [('0x8p-4', '0x1.0000000000000p-1'),
        ('0x1p+0', '0x1.0000000000000p+0'),
        ('0x2p+0', '0x1.0000000000000p+1'),
        ('0x1p+4', '0x1.0000000000000p+4')]

    Special values:

        sage: [RR(s).hex() for s in ['+inf', '-inf', 'nan']]
        ['inf', '-inf', 'nan']

  `imag`()

    Return the imaginary part of `self`.

    (Since `self` is a real number, this simply returns exactly 0.)

    EXAMPLES:

        sage: RR.pi().imag()
        0
        sage: RealField(100)(2).imag()
        0

  `integer_part`()

    If in decimal this number is written `n.defg`, returns `n`.

    OUTPUT: a Sage Integer

    EXAMPLE:

        sage: a = 119.41212
        sage: a.integer_part()
        119
        sage: a = -123.4567
        sage: a.integer_part()
        -123

    A big number with no decimal point:

        sage: a = RR(10^17); a
        1.00000000000000e17
        sage: a.integer_part()
        100000000000000000

  `is_NaN`()

    Return `True` if `self` is Not-a-Number `NaN`.

    EXAMPLES:

        sage: a = RR(0) / RR(0); a
        NaN
        sage: a.is_NaN()
        True

  `is_infinity`()

    Return `True` if `self` is \(\infty\) and `False` otherwise.

    EXAMPLES:

        sage: a = RR('1.494') / RR(0); a
        +infinity
        sage: a.is_infinity()
        True
        sage: a = -RR('1.494') / RR(0); a
        -infinity
        sage: a.is_infinity()
        True
        sage: RR(1.5).is_infinity()
        False
        sage: RR('nan').is_infinity()
        False

  `is_integer`()

    Return `True` if this number is a integer

    EXAMPLES:

        sage: RR(1).is_integer()
        True
        sage: RR(0.1).is_integer()
        False

  `is_negative_infinity`()

    Return `True` if `self` is \(-\infty\).

    EXAMPLES:

        sage: a = RR('1.494') / RR(0); a
        +infinity
        sage: a.is_negative_infinity()
        False
        sage: a = -RR('1.494') / RR(0); a
        -infinity
        sage: RR(1.5).is_negative_infinity()
        False
        sage: a.is_negative_infinity()
        True

  `is_positive_infinity`()

    Return `True` if `self` is \(+\infty\).

    EXAMPLES:

        sage: a = RR('1.494') / RR(0); a
        +infinity
        sage: a.is_positive_infinity()
        True
        sage: a = -RR('1.494') / RR(0); a
        -infinity
        sage: RR(1.5).is_positive_infinity()
        False
        sage: a.is_positive_infinity()
        False

  `is_real`()

    Return `True` if `self` is real (of course, this always returns `True` for a finite element of a real field).

    EXAMPLES:

        sage: RR(1).is_real()
        True
        sage: RR('-100').is_real()
        True

  `is_square`()

    Return whether or not this number is a square in this field. For the real numbers, this is `True` if and only if `self` is non-negative.

    EXAMPLES:

        sage: r = 3.5
        sage: r.is_square()
        True
        sage: r = 0.0
        sage: r.is_square()
        True
        sage: r = -4.0
        sage: r.is_square()
        False

  `is_unit`()

    Return `True` if `self` is a unit (has a multiplicative inverse) and `False` otherwise.

    EXAMPLES:

        sage: RR(1).is_unit()
        True
        sage: RR('0').is_unit()
        False
        sage: RR('-0').is_unit()
        False
        sage: RR('nan').is_unit()
        False
        sage: RR('inf').is_unit()
        False
        sage: RR('-inf').is_unit()
        False

  `j0`()

    Return the value of the Bessel \(J\) function of order 0 at `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).j0()
        0.223890779141236

  `j1`()

    Return the value of the Bessel \(J\) function of order 1 at `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).j1()
        0.576724807756873

  `jn`(n)

    Return the value of the Bessel \(J\) function of order \(n\) at `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).jn(3)
        0.128943249474402
        sage: R(2).jn(-17)
        -2.65930780516787e-15

  `lngamma`()

    This method is deprecated, please use `log_gamma()` instead.

    See the `log_gamma()` method for documentation and examples.

    EXAMPLES:

        sage: RR(6).lngamma()
        doctest:...: DeprecationWarning: The method lngamma() is deprecated. Use log_gamma() instead.
        See http://trac.sagemath.org/6992 for details.
        4.78749174278205

  `log`(base=None)

    Return the logarithm of `self` to the `base`.

    EXAMPLES:

        sage: R = RealField()
        sage: R(2).log()
        0.693147180559945
        sage: log(RR(2))
        0.693147180559945
        sage: log(RR(2), "e")
        0.693147180559945
        sage: log(RR(2), e)
        0.693147180559945

        sage: r = R(-1); r.log()
        3.14159265358979*I
        sage: log(RR(-1),e)
        3.14159265358979*I
        sage: r.log(2)
        4.53236014182719*I

    For the error value NaN (Not A Number), log will return NaN:

        sage: r = R(NaN); r.log()
        NaN

  `log10`()

    Return log to the base 10 of `self`.

    EXAMPLES:

        sage: r = 16.0; r.log10()
        1.20411998265592
        sage: r.log() / log(10.0)
        1.20411998265592

        sage: r = 39.9; r.log10()
        1.60097289568675

        sage: r = 0.0
        sage: r.log10()
        -infinity

        sage: r = -1.0
        sage: r.log10()
        1.36437635384184*I

  `log1p`()

    Return log base \(e\) of `1 + self`.

    EXAMPLES:

        sage: r = 15.0; r.log1p()
        2.77258872223978
        sage: (r+1).log()
        2.77258872223978

    For small values, this is more accurate than computing `log(1 + self)` directly, as it avoids cancellation issues:

        sage: r = 3e-10
        sage: r.log1p()
        2.99999999955000e-10
        sage: (1+r).log()
        3.00000024777111e-10
        sage: r100 = RealField(100)(r)
        sage: (1+r100).log()
        2.9999999995500000000978021372e-10

    For small values, this is more accurate than computing `log(1 + self)` directly, as it avoid cancelation issues:

        sage: r = 3e-10
        sage: r.log1p()
        2.99999999955000e-10
        sage: (1+r).log()
        3.00000024777111e-10
        sage: r100 = RealField(100)(r)
        sage: (1+r100).log()
        2.9999999995500000000978021372e-10

        sage: r = 38.9; r.log1p()
        3.68637632389582

        sage: r = -1.0
        sage: r.log1p()
        -infinity

        sage: r = -2.0
        sage: r.log1p()
        3.14159265358979*I

  `log2`()

    Return log to the base 2 of `self`.

    EXAMPLES:

        sage: r = 16.0
        sage: r.log2()
        4.00000000000000

        sage: r = 31.9; r.log2()
        4.99548451887751

        sage: r = 0.0
        sage: r.log2()
        -infinity

        sage: r = -3.0; r.log2()
        1.58496250072116 + 4.53236014182719*I

  `log_gamma`()

    Return the logarithm of gamma of `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(6).log_gamma()
        4.78749174278205
        sage: R(1e10).log_gamma()
        2.20258509288811e11

  `multiplicative_order`()

    Return the multiplicative order of `self`.

    EXAMPLES:

        sage: RR(1).multiplicative_order()
        1
        sage: RR(-1).multiplicative_order()
        2
        sage: RR(3).multiplicative_order()
        +Infinity

  `nearby_rational`(max_error=None, max_denominator=None)

    Find a rational near to `self`. Exactly one of `max_error` or `max_denominator` must be specified.

    If `max_error` is specified, then this returns the simplest rational in the range `[self-max_error .. self+max_error]`. If `max_denominator` is specified, then this returns the rational closest to `self` with denominator at most `max_denominator`. (In case of ties, we pick the simpler rational.)

    EXAMPLES:

        sage: (0.333).nearby_rational(max_error=0.001)
        1/3
        sage: (0.333).nearby_rational(max_error=1)
        0
        sage: (-0.333).nearby_rational(max_error=0.0001)
        -257/772

        sage: (0.333).nearby_rational(max_denominator=100)
        1/3
        sage: RR(1/3 + 1/1000000).nearby_rational(max_denominator=2999999)
        777780/2333333
        sage: RR(1/3 + 1/1000000).nearby_rational(max_denominator=3000000)
        1000003/3000000
        sage: (-0.333).nearby_rational(max_denominator=1000)
        -333/1000
        sage: RR(3/4).nearby_rational(max_denominator=2)
        1
        sage: RR(pi).nearby_rational(max_denominator=120)
        355/113
        sage: RR(pi).nearby_rational(max_denominator=10000)
        355/113
        sage: RR(pi).nearby_rational(max_denominator=100000)
        312689/99532
        sage: RR(pi).nearby_rational(max_denominator=1)
        3
        sage: RR(-3.5).nearby_rational(max_denominator=1)
        -3

    TESTS:

        sage: RR('nan').nearby_rational(max_denominator=1000)
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number
        sage: RR('nan').nearby_rational(max_error=0.01)
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number
        sage: RR(oo).nearby_rational(max_denominator=1000)
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number
        sage: RR(oo).nearby_rational(max_error=0.01)
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number

  `nextabove`()

    Return the next floating-point number larger than `self`.

    EXAMPLES:

        sage: RR('-infinity').nextabove()
        -2.09857871646739e323228496            # 32-bit
        -5.87565378911159e1388255822130839282  # 64-bit
        sage: RR(0).nextabove()
        2.38256490488795e-323228497            # 32-bit
        8.50969131174084e-1388255822130839284  # 64-bit
        sage: RR('+infinity').nextabove()
        +infinity
        sage: RR(-sqrt(2)).str(truncate=False)
        '-1.4142135623730951'
        sage: RR(-sqrt(2)).nextabove().str(truncate=False)
        '-1.4142135623730949'

  `nextbelow`()

    Return the next floating-point number smaller than `self`.

    EXAMPLES:

        sage: RR('-infinity').nextbelow()
        -infinity
        sage: RR(0).nextbelow()
        -2.38256490488795e-323228497            # 32-bit
        -8.50969131174084e-1388255822130839284  # 64-bit
        sage: RR('+infinity').nextbelow()
        2.09857871646739e323228496              # 32-bit
        5.87565378911159e1388255822130839282    # 64-bit
        sage: RR(-sqrt(2)).str(truncate=False)
        '-1.4142135623730951'
        sage: RR(-sqrt(2)).nextbelow().str(truncate=False)
        '-1.4142135623730954'

  `nexttoward`(other)

    Return the floating-point number adjacent to `self` which is closer to `other`. If `self` or other is `NaN`, returns `NaN`; if `self` equals `other`, returns `self`.

    EXAMPLES:

        sage: (1.0).nexttoward(2).str(truncate=False)
        '1.0000000000000002'
        sage: (1.0).nexttoward(RR('-infinity')).str(truncate=False)
        '0.99999999999999989'
        sage: RR(infinity).nexttoward(0)
        2.09857871646739e323228496            # 32-bit
        5.87565378911159e1388255822130839282  # 64-bit
        sage: RR(pi).str(truncate=False)
        '3.1415926535897931'
        sage: RR(pi).nexttoward(22/7).str(truncate=False)
        '3.1415926535897936'
        sage: RR(pi).nexttoward(21/7).str(truncate=False)
        '3.1415926535897927'

  `nth_root`(n, algorithm=0)

    Return an \(n^{th}\) root of `self`.

    INPUT:

    - `n` – A positive number, rounded down to the nearest integer. Note that \(n\) should be less than ``sys.maxsize``.
    - `algorithm` – Set this to 1 to call mpfr directly, set this to 2 to use interval arithmetic and logarithms, or leave it at the default of 0 to choose the algorithm which is estimated to be faster.

    AUTHORS:

    - Carl Witty (2007-10)

    EXAMPLES:

        sage: R = RealField()
        sage: R(8).nth_root(3)
        2.00000000000000
        sage: R(8).nth_root(3.7)    # illustrate rounding down
        2.00000000000000
        sage: R(-8).nth_root(3)
        -2.00000000000000
        sage: R(0).nth_root(3)
        0.000000000000000
        sage: R(32).nth_root(-1)
        Traceback (most recent call last):
        ...
        ValueError: n must be positive
        sage: R(32).nth_root(1.0)
        32.0000000000000
        sage: R(4).nth_root(4)
        1.41421356237310
        sage: R(4).nth_root(40)
        1.03526492384138
        sage: R(4).nth_root(400)
        1.00347174850950
        sage: R(4).nth_root(4000)
        1.00034663365385
        sage: R(4).nth_root(4000000)
        1.00000034657365
        sage: R(-27).nth_root(3)
        -3.00000000000000
        sage: R(-4).nth_root(3999999)
        -1.00000034657374

    Note that for negative numbers, any even root throws an exception:

        sage: R(-2).nth_root(6)
        Traceback (most recent call last):
        ...
        ValueError: taking an even root of a negative number

    The \(n^{th}\) root of 0 is defined to be 0, for any \(n\):

        sage: R(0).nth_root(6)
        0.000000000000000
        sage: R(0).nth_root(7)
        0.000000000000000

    TESTS:

    The old and new algorithms should give exactly the same results in all cases:

        sage: def check(x, n):
        ...       answers = []
        ...       for sign in (1, -1):
        ...           if is_even(n) and sign == -1:
        ...               continue
        ...           for rounding in ('RNDN', 'RNDD', 'RNDU', 'RNDZ'):
        ...               fld = RealField(x.prec(), rnd=rounding)
        ...               fx = fld(sign * x)
        ...               alg_mpfr = fx.nth_root(n, algorithm=1)
        ...               alg_mpfi = fx.nth_root(n, algorithm=2)
        ...               assert(alg_mpfr == alg_mpfi)
        ...               if sign == 1: answers.append(alg_mpfr)
        ...       return answers

    Check some perfect powers (and nearby numbers):

        sage: check(16.0, 4)
        [2.00000000000000, 2.00000000000000, 2.00000000000000, 2.00000000000000]
        sage: check((16.0).nextabove(), 4)
        [2.00000000000000, 2.00000000000000, 2.00000000000001, 2.00000000000000]
        sage: check((16.0).nextbelow(), 4)
        [2.00000000000000, 1.99999999999999, 2.00000000000000, 1.99999999999999]
        sage: check(((9.0 * 256)^7), 7)
        [2304.00000000000, 2304.00000000000, 2304.00000000000, 2304.00000000000]
        sage: check(((9.0 * 256)^7).nextabove(), 7)
        [2304.00000000000, 2304.00000000000, 2304.00000000001, 2304.00000000000]
        sage: check(((9.0 * 256)^7).nextbelow(), 7)
        [2304.00000000000, 2303.99999999999, 2304.00000000000, 2303.99999999999]
        sage: check(((5.0 / 512)^17), 17)
        [0.00976562500000000, 0.00976562500000000, 0.00976562500000000, 0.00976562500000000]
        sage: check(((5.0 / 512)^17).nextabove(), 17)
        [0.00976562500000000, 0.00976562500000000, 0.00976562500000001, 0.00976562500000000]
        sage: check(((5.0 / 512)^17).nextbelow(), 17)
        [0.00976562500000000, 0.00976562499999999, 0.00976562500000000, 0.00976562499999999]

    And check some non-perfect powers:

        sage: check(2.0, 3)
        [1.25992104989487, 1.25992104989487, 1.25992104989488, 1.25992104989487]
        sage: check(2.0, 4)
        [1.18920711500272, 1.18920711500272, 1.18920711500273, 1.18920711500272]
        sage: check(2.0, 5)
        [1.14869835499704, 1.14869835499703, 1.14869835499704, 1.14869835499703]

    And some different precisions:

        sage: check(RealField(20)(22/7), 19)
        [1.0621, 1.0621, 1.0622, 1.0621]
        sage: check(RealField(200)(e), 4)
        [1.2840254166877414840734205680624364583362808652814630892175, 1.2840254166877414840734205680624364583362808652814630892175, 1.2840254166877414840734205680624364583362808652814630892176, 1.2840254166877414840734205680624364583362808652814630892175]

    Check that trac ticket #12105 is fixed:

        sage: RealField(53)(0.05).nth_root(7 * 10^8)
        0.999999995720382

  `parent`()

    Return the parent of `self`.

    EXAMPLES:

        sage: R = RealField()
        sage: a = R('1.2456')
        sage: a.parent()
        Real Field with 53 bits of precision

  `prec`()

    Return the precision of `self`.

    EXAMPLES:

        sage: RR(1.0).precision()
        53
        sage: RealField(101)(-1).precision()
        101

  `precision`()

    Return the precision of `self`.

    EXAMPLES:

        sage: RR(1.0).precision()
        53
        sage: RealField(101)(-1).precision()
        101

  `real`()

    Return the real part of `self`.

    (Since `self` is a real number, this simply returns `self`.)

    EXAMPLES:

        sage: RR(2).real()
        2.00000000000000
        sage: RealField(200)(-4.5).real()
        -4.5000000000000000000000000000000000000000000000000000000000

  `round`()

    Rounds `self` to the nearest integer. The rounding mode of the parent field has no effect on this function.

    EXAMPLES:

        sage: RR(0.49).round()
        0
        sage: RR(0.5).round()
        1
        sage: RR(-0.49).round()
        0
        sage: RR(-0.5).round()
        -1

  `sec`()

    Returns the secant of this number

    EXAMPLES:

        sage: RealField(100)(2).sec()
        -2.4029979617223809897546004014

  `sech`()

    Return the hyperbolic secant of `self`.

    EXAMPLES:

        sage: RealField(100)(2).sech()
        0.26580222883407969212086273982

  `sign`()

    Return `+1` if `self` is positive, `-1` if `self` is negative, and `0` if `self` is zero.

    EXAMPLES:

        sage: R=RealField(100)
        sage: R(-2.4).sign()
        -1
        sage: R(2.1).sign()
        1
        sage: R(0).sign()
        0

  `sign_mantissa_exponent`()

    Return the sign, mantissa, and exponent of `self`.

    In Sage (as in MPFR), floating-point numbers of precision \(p\) are of the form \(s m 2^{e-p}\), where \(s \in \{-1, 1\}\), \(2^{p-1} \leq m < 2^p\), and \(-2^{30} + 1 \leq e \leq 2^{30} - 1\); plus the special values `+0`, `-0`, `+infinity`, `-infinity`, and `NaN` (which stands for Not-a-Number).

    This function returns \(s\), \(m\), and \(e-p\). For the special values:

    - `+0` returns `(1, 0, 0)` (analogous to IEEE-754; note that MPFR actually stores the exponent as “smallest exponent possible”)
    - `-0` returns `(-1, 0, 0)` (analogous to IEEE-754; note that MPFR actually stores the exponent as “smallest exponent possible”)
    - the return values for `+infinity`, `-infinity`, and `NaN` are not specified.

    EXAMPLES:

        sage: R = RealField(53)
        sage: a = R(exp(1.0)); a
        2.71828182845905
        sage: sign, mantissa, exponent = R(exp(1.0)).sign_mantissa_exponent()
        sage: sign, mantissa, exponent
        (1, 6121026514868073, -51)
        sage: sign*mantissa*(2**exponent) == a
        True

    The mantissa is always a nonnegative number (see trac ticket #14448):

        sage: RR(-1).sign_mantissa_exponent()
        (-1, 4503599627370496, -52)

    We can also calculate this also using \(p\)-adic valuations:

        sage: a = R(exp(1.0))
        sage: b = a.exact_rational()
        sage: valuation, unit = b.val_unit(2)
        sage: (b/abs(b), unit, valuation)
        (1, 6121026514868073, -51)
        sage: a.sign_mantissa_exponent()
        (1, 6121026514868073, -51)

    TESTS:

        sage: R('+0').sign_mantissa_exponent()
        (1, 0, 0)
        sage: R('-0').sign_mantissa_exponent()
        (-1, 0, 0)

  `simplest_rational`()

    Return the simplest rational which is equal to `self` (in the Sage sense). Recall that Sage defines the equality operator by coercing both sides to a single type and then comparing; thus, this finds the simplest rational which (when coerced to this RealField) is equal to `self`.

    Given rationals \(a / b\) and \(c / d\) (both in lowest terms), the former is simpler if \(b < d\) or if \(b = d\) and \(|a| < |c|\).

    The effect of rounding modes is slightly counter-intuitive. Consider the case of round-toward-minus-infinity. This rounding is performed when coercing a rational to a floating-point number; so the `simplest_rational()` of a round-to-minus-infinity number will be either exactly equal to or slightly larger than the number.

    EXAMPLES:

        sage: RRd = RealField(53, rnd='RNDD')
        sage: RRz = RealField(53, rnd='RNDZ')
        sage: RRu = RealField(53, rnd='RNDU')
        sage: def check(x):
        ...       rx = x.simplest_rational()
        ...       assert(x == rx)
        ...       return rx
        sage: RRd(1/3) < RRu(1/3)
        True
        sage: check(RRd(1/3))
        1/3
        sage: check(RRu(1/3))
        1/3
        sage: check(RRz(1/3))
        1/3
        sage: check(RR(1/3))
        1/3
        sage: check(RRd(-1/3))
        -1/3
        sage: check(RRu(-1/3))
        -1/3
        sage: check(RRz(-1/3))
        -1/3
        sage: check(RR(-1/3))
        -1/3
        sage: check(RealField(20)(pi))
        355/113
        sage: check(RR(pi))
        245850922/78256779
        sage: check(RR(2).sqrt())
        131836323/93222358
        sage: check(RR(1/2^210))
        1/1645504557321205859467264516194506011931735427766374553794641921
        sage: check(RR(2^210))
        1645504557321205950811116849375918117252433820865891134852825088
        sage: (RR(17).sqrt()).simplest_rational()^2 - 17
        -1/348729667233025
        sage: (RR(23).cube_root()).simplest_rational()^3 - 23
        -1404915133/264743395842039084891584
        sage: RRd5 = RealField(5, rnd='RNDD')
        sage: RRu5 = RealField(5, rnd='RNDU')
        sage: RR5 = RealField(5)
        sage: below1 = RR5(1).nextbelow()
        sage: check(RRd5(below1))
        31/32
        sage: check(RRu5(below1))
        16/17
        sage: check(below1)
        21/22
        sage: below1.exact_rational()
        31/32
        sage: above1 = RR5(1).nextabove()
        sage: check(RRd5(above1))
        10/9
        sage: check(RRu5(above1))
        17/16
        sage: check(above1)
        12/11
        sage: above1.exact_rational()
        17/16
        sage: check(RR(1234))
        1234
        sage: check(RR5(1234))
        1185
        sage: check(RR5(1184))
        1120
        sage: RRd2 = RealField(2, rnd='RNDD')
        sage: RRu2 = RealField(2, rnd='RNDU')
        sage: RR2 = RealField(2)
        sage: check(RR2(8))
        7
        sage: check(RRd2(8))
        8
        sage: check(RRu2(8))
        7
        sage: check(RR2(13))
        11
        sage: check(RRd2(13))
        12
        sage: check(RRu2(13))
        13
        sage: check(RR2(16))
        14
        sage: check(RRd2(16))
        16
        sage: check(RRu2(16))
        13
        sage: check(RR2(24))
        21
        sage: check(RRu2(24))
        17
        sage: check(RR2(-24))
        -21
        sage: check(RRu2(-24))
        -24

    TESTS:

        sage: RR('nan').simplest_rational()
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number
        sage: RR('-infinity').simplest_rational()
        Traceback (most recent call last):
        ...
        ValueError: Cannot convert NaN or infinity to rational number

  `sin`()

    Return the sine of `self`.

    EXAMPLES:

        sage: R = RealField(100)
        sage: R(2).sin()
        0.90929742682568169539601986591

  `sincos`()

    Return a pair consisting of the sine and cosine of `self`.

    EXAMPLES:

        sage: R = RealField()
        sage: t = R.pi()/6
        sage: t.sincos()
        (0.500000000000000, 0.866025403784439)

  `sinh`()

    Return the hyperbolic sine of `self`.

    EXAMPLES:

        sage: q = RR.pi()/12
        sage: q.sinh()
        0.264800227602271

  `sqrt`(extend=True, all=False)

    The square root function.

    INPUT:

    - `extend` – bool (default: `True`); if `True`, return a square root in a complex field if necessary if `self` is negative; otherwise raise a `ValueError`
    - `all` – bool (default: `False`); if `True`, return a list of all square roots.

    EXAMPLES:

        sage: r = -2.0
        sage: r.sqrt()
        1.41421356237310*I

        sage: r = 4.0
        sage: r.sqrt()
        2.00000000000000
        sage: r.sqrt()^2 == r
        True

        sage: r = 4344
        sage: r.sqrt()
        2*sqrt(1086)

        sage: r = 4344.0
        sage: r.sqrt()^2 == r
        True
        sage: r.sqrt()^2 - r
        0.000000000000000

        sage: r = -2.0
        sage: r.sqrt()
        1.41421356237310*I

  `str`(base=10, no_sci=None, e=None, truncate=1, skip_zeroes=0)

    Return a string representation of `self`.

    INPUT:

    - `base` – base for output
    - `no_sci` – if 2, never print using scientific notation; if 1 or `True`, print using scientific notation only for very large or very small numbers; if 0 or `False` always print with scientific notation; if `None` (the default), print how the parent prints.
    - `e` – symbol used in scientific notation; defaults to ‘e’ for base=10, and ‘@’ otherwise
    - `truncate` – if `True`, round off the last digits in printing to lessen confusing base-2 roundoff issues.
    - `skip_zeroes` – if `True`, skip trailing zeroes in mantissa

    EXAMPLES:

        sage: a = 61/3.0; a
        20.3333333333333
        sage: a.str(truncate=False)
        '20.333333333333332'
        sage: a.str(2)
        '10100.010101010101010101010101010101010101010101010101'
        sage: a.str(no_sci=False)
        '2.03333333333333e1'
        sage: a.str(16, no_sci=False)
        '1.4555555555555@1'
        sage: b = 2.0^99
        sage: b.str()
        '6.33825300114115e29'
        sage: b.str(no_sci=False)
        '6.33825300114115e29'
        sage: b.str(no_sci=True)
        '6.33825300114115e29'
        sage: c = 2.0^100
        sage: c.str()
        '1.26765060022823e30'
        sage: c.str(no_sci=False)
        '1.26765060022823e30'
        sage: c.str(no_sci=True)
        '1.26765060022823e30'
        sage: c.str(no_sci=2)
        '1267650600228230000000000000000.'
        sage: 0.5^53
        1.11022302462516e-16
        sage: 0.5^54
        5.55111512312578e-17
        sage: (0.01).str()
        '0.0100000000000000'
        sage: (0.01).str(skip_zeroes=True)
        '0.01'
        sage: (-10.042).str()
        '-10.0420000000000'
        sage: (-10.042).str(skip_zeroes=True)
        '-10.042'
        sage: (389.0).str(skip_zeroes=True)
        '389.'

    Test various bases:

        sage: print (65536.0).str(base=2)
        1.0000000000000000000000000000000000000000000000000000e16
        sage: print (65536.0).str(base=36)
        1ekg.00000000
        sage: print (65536.0).str(base=62)
        H32.0000000
        sage: print (65536.0).str(base=63)
        Traceback (most recent call last):
        ...
        ValueError: base (=63) must be an integer between 2 and 62

  `tan`()

    Return the tangent of `self`.

    EXAMPLES:

        sage: q = RR.pi()/3
        sage: q.tan()
        1.73205080756888
        sage: q = RR.pi()/6
        sage: q.tan()
        0.577350269189626

  `tanh`()

    Return the hyperbolic tangent of `self`.

    EXAMPLES:

        sage: q = RR.pi()/11
        sage: q.tanh()
        0.278079429295850

  `trunc`()

    Truncate `self`.

    EXAMPLES:

        sage: (2.99).trunc()
        2
        sage: (-0.00).trunc()
        0
        sage: (0.00).trunc()
        0

  `ulp`(field=None)

    Returns the unit of least precision of `self`, which is the weight of the least significant bit of `self`. This is always a strictly positive number. It is also the gap between this number and the closest number with larger absolute value that can be represented.

    INPUT:

    - `field` – `RealField` used as parent of the result. If not specified, use `parent(self)`.

    Note

    The ulp of zero is defined as the smallest representable positive number. For extremely small numbers, underflow occurs and the output is also the smallest representable positive number (the rounding mode is ignored, this computation is done by rounding towards +infinity).

    See also

    `epsilon()` for a scale-invariant version of this.

    EXAMPLES:

        sage: a = 1.0
        sage: a.ulp()
        2.22044604925031e-16
        sage: (-1.5).ulp()
        2.22044604925031e-16
        sage: a + a.ulp() == a
        False
        sage: a + a.ulp()/2 == a
        True

        sage: a = RealField(500).pi()
        sage: b = a + a.ulp()
        sage: (a+b)/2 in [a,b]
        True

    The ulp of zero is the smallest non-zero number:

        sage: a = RR(0).ulp()
        sage: a
        2.38256490488795e-323228497            # 32-bit
        8.50969131174084e-1388255822130839284  # 64-bit
        sage: a.fp_rank()
        1

    The ulp of very small numbers results in underflow, so the smallest non-zero number is returned instead:

        sage: a.ulp() == a
        True

    We use a different field:

        sage: a = RealField(256).pi()
        sage: a.ulp()
        3.454467422037777850154540745120159828446400145774512554009481388067436721265e-77
        sage: e = a.ulp(RealField(64))
        sage: e
        3.45446742203777785e-77
        sage: parent(e)
        Real Field with 64 bits of precision
        sage: e = a.ulp(QQ)
        Traceback (most recent call last):
        ...
        TypeError: field argument must be a RealField

    For infinity and NaN, we get back positive infinity and NaN:

        sage: a = RR(infinity)
        sage: a.ulp()
        +infinity
        sage: (-a).ulp()
        +infinity
        sage: a = RR('nan')
        sage: a.ulp()
        NaN
        sage: parent(RR('nan').ulp(RealField(42)))
        Real Field with 42 bits of precision

  `y0`()

    Return the value of the Bessel \(Y\) function of order 0 at `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).y0()
        0.510375672649745

  `y1`()

    Return the value of the Bessel \(Y\) function of order 1 at `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).y1()
        -0.107032431540938

  `yn`(n)

    Return the value of the Bessel \(Y\) function of order \(n\) at `self`.

    EXAMPLES:

        sage: R = RealField(53)
        sage: R(2).yn(3)
        -1.12778377684043
        sage: R(2).yn(-17)
        7.09038821729481e12

  `zeta`()

    Return the Riemann zeta function evaluated at this real number.

    Note

    PARI is vastly more efficient at computing the Riemann zeta function. See the example below for how to use it.

    EXAMPLES:

        sage: R = RealField()
        sage: R(2).zeta()
        1.64493406684823
        sage: R.pi()^2/6
        1.64493406684823
        sage: R(-2).zeta()
        0.000000000000000
        sage: R(1).zeta()
        +infinity

    Computing zeta using PARI is much more efficient in difficult cases. Here’s how to compute zeta with at least a given precision:

        sage: z = pari(2).zeta(precision=53); z
        1.64493406684823
        sage: pari(2).zeta(precision=128).python().prec()
        128
        sage: pari(2).zeta(precision=65).python().prec()
        128                                                # 64-bit
        96                                                 # 32-bit

    Note that the number of bits of precision in the constructor only effects the internal precision of the pari number, which is rounded up to the nearest multiple of 32 or 64. To increase the number of digits that gets displayed you must use `pari.set_real_precision`.

        sage: type(z)
        <type 'sage.libs.pari.gen.gen'>
        sage: R(z)
        1.64493406684823

class `sage.rings.real_mpfr.``ZZtoRR`

  Bases: `sage.categories.map.Map`

  INPUT:

  There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

  TESTS:

      sage: from sage.categories.map import Map

  Using a hom space:

      sage: Map(Hom(QQ, ZZ, Rings()))
      Generic map:
        From: Rational Field
        To:   Integer Ring

  Using domain and codomain:

      sage: Map(QQ['x'], SymmetricGroup(6))
      Generic map:
        From: Univariate Polynomial Ring in x over Rational Field
        To:   Symmetric group of order 6! as a permutation group

`sage.rings.real_mpfr.``create_RealField`(prec=53, type='MPFR', rnd='RNDN', sci_not=0)

  Create a real field with given precision, type, rounding mode and scientific notation.

  Some options are ignored for certain types (RDF for example).

  INPUT:

  - `prec` – a positive integer
  - `type` – type of real field:
    - `'RDF'` – the Sage real field corresponding to native doubles
    - `'Interval'` – real fields implementing interval arithmetic
    - `'RLF'` – the real lazy field
    - `'MPFR'` – floating point real numbers implemented using the MPFR library
  - `rnd` – rounding mode:
    - `'RNDN'` – round to nearest
    - `'RNDZ'` – round toward zero
    - `'RNDD'` – round down
    - `'RNDU'` – round up
  - `sci_not` – boolean, whether to use scientific notation for printing

  OUTPUT:

  the appropriate real field

  EXAMPLES:

      sage: from sage.rings.real_mpfr import create_RealField
      sage: create_RealField(30)
      Real Field with 30 bits of precision
      sage: create_RealField(20, 'RDF') # ignores precision
      Real Double Field
      sage: create_RealField(60, 'Interval')
      Real Interval Field with 60 bits of precision
      sage: create_RealField(40, 'RLF') # ignores precision
      Real Lazy Field

`sage.rings.real_mpfr.``create_RealNumber`(s, base=10, pad=0, rnd='RNDN', min_prec=53)

  Return the real number defined by the string `s` as an element of `RealField(prec=n)`, where `n` potentially has slightly more (controlled by pad) bits than given by `s`.

  INPUT:

  - `s` – a string that defines a real number (or something whose string representation defines a number)
  - `base` – an integer between 2 and 62
  - `pad` – an integer = 0.
  - `rnd` – rounding mode:
    - `'RNDN'` – round to nearest
    - `'RNDZ'` – round toward zero
    - `'RNDD'` – round down
    - `'RNDU'` – round up
  - `min_prec` – number will have at least this many bits of precision, no matter what.

  EXAMPLES:

      sage: RealNumber('2.3') # indirect doctest
      2.30000000000000
      sage: RealNumber(10)
      10.0000000000000
      sage: RealNumber('1.0000000000000000000000000000000000')
      1.000000000000000000000000000000000
      sage: RealField(200)(1.2)
      1.2000000000000000000000000000000000000000000000000000000000
      sage: (1.2).parent() is RR
      True

  We can use various bases:

      sage: RealNumber("10101e2",base=2)
      84.0000000000000
      sage: RealNumber("deadbeef", base=16)
      3.73592855900000e9
      sage: RealNumber("deadbeefxxx", base=16)
      Traceback (most recent call last):
      ...
      TypeError: Unable to convert x (='deadbeefxxx') to real number.
      sage: RealNumber("z", base=36)
      35.0000000000000
      sage: RealNumber("AAA", base=37)
      14070.0000000000
      sage: RealNumber("aaa", base=37)
      50652.0000000000
      sage: RealNumber("3.4", base="foo")
      Traceback (most recent call last):
      ...
      TypeError: an integer is required
      sage: RealNumber("3.4", base=63)
      Traceback (most recent call last):
      ...
      ValueError: base (=63) must be an integer between 2 and 62

  TESTS:

      sage: RealNumber('.000000000000000000000000000000001').prec()
      53
      sage: RealNumber('-.000000000000000000000000000000001').prec()
      53

  Make sure we’ve rounded up `log(10,2)` enough to guarantee sufficient precision (trac ticket #10164):

      sage: ks = 5*10**5, 10**6
      sage: all(RealNumber("1." + "0"*k +"1")-1 > 0 for k in ks)
      True

class `sage.rings.real_mpfr.``double_toRR`

  Bases: `sage.categories.map.Map`

  INPUT:

  There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

  TESTS:

      sage: from sage.categories.map import Map

  Using a hom space:

      sage: Map(Hom(QQ, ZZ, Rings()))
      Generic map:
        From: Rational Field
        To:   Integer Ring

  Using domain and codomain:

      sage: Map(QQ['x'], SymmetricGroup(6))
      Generic map:
        From: Univariate Polynomial Ring in x over Rational Field
        To:   Symmetric group of order 6! as a permutation group

class `sage.rings.real_mpfr.``int_toRR`

  Bases: `sage.categories.map.Map`

  INPUT:

  There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

  TESTS:

      sage: from sage.categories.map import Map

  Using a hom space:

      sage: Map(Hom(QQ, ZZ, Rings()))
      Generic map:
        From: Rational Field
        To:   Integer Ring

  Using domain and codomain:

      sage: Map(QQ['x'], SymmetricGroup(6))
      Generic map:
        From: Univariate Polynomial Ring in x over Rational Field
        To:   Symmetric group of order 6! as a permutation group

`sage.rings.real_mpfr.``is_RealField`(x)

  Returns `True` if `x` is technically of a Python real field type.

  EXAMPLES:

      sage: sage.rings.real_mpfr.is_RealField(RR)
      True
      sage: sage.rings.real_mpfr.is_RealField(CC)
      False

`sage.rings.real_mpfr.``is_RealNumber`(x)

  Return `True` if `x` is of type `RealNumber`, meaning that it is an element of the MPFR real field with some precision.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import is_RealNumber
      sage: is_RealNumber(2.5)
      True
      sage: is_RealNumber(float(2.3))
      False
      sage: is_RealNumber(RDF(2))
      False
      sage: is_RealNumber(pi)
      False

`sage.rings.real_mpfr.``mpfr_get_exp_max`()

  Return the current maximal exponent for MPFR numbers.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import mpfr_get_exp_max
      sage: mpfr_get_exp_max()
      1073741823            # 32-bit
      4611686018427387903   # 64-bit
      sage: 0.5 << mpfr_get_exp_max()
      1.04928935823369e323228496            # 32-bit
      2.93782689455579e1388255822130839282  # 64-bit
      sage: 0.5 << (mpfr_get_exp_max()+1)
      +infinity

`sage.rings.real_mpfr.``mpfr_get_exp_max_max`()

  Get the maximal value allowed for `mpfr_set_exp_max()`.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import mpfr_get_exp_max_max, mpfr_set_exp_max
      sage: mpfr_get_exp_max_max()
      1073741823            # 32-bit
      4611686018427387903   # 64-bit

  This is really the maximal value allowed:

      sage: mpfr_set_exp_max(mpfr_get_exp_max_max() + 1)
      Traceback (most recent call last):
      ...
      OverflowError: bad value for mpfr_set_exp_max()

`sage.rings.real_mpfr.``mpfr_get_exp_min`()

  Return the current minimal exponent for MPFR numbers.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import mpfr_get_exp_min
      sage: mpfr_get_exp_min()
      -1073741823            # 32-bit
      -4611686018427387903   # 64-bit
      sage: 0.5 >> (-mpfr_get_exp_min())
      2.38256490488795e-323228497            # 32-bit
      8.50969131174084e-1388255822130839284  # 64-bit
      sage: 0.5 >> (-mpfr_get_exp_min()+1)
      0.000000000000000

`sage.rings.real_mpfr.``mpfr_get_exp_min_min`()

  Get the minimal value allowed for `mpfr_set_exp_min()`.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import mpfr_get_exp_min_min, mpfr_set_exp_min
      sage: mpfr_get_exp_min_min()
      -1073741823            # 32-bit
      -4611686018427387903   # 64-bit

  This is really the minimal value allowed:

      sage: mpfr_set_exp_min(mpfr_get_exp_min_min() - 1)
      Traceback (most recent call last):
      ...
      OverflowError: bad value for mpfr_set_exp_min()

`sage.rings.real_mpfr.``mpfr_prec_max`()

  TESTS:

      sage: from sage.rings.real_mpfr import mpfr_prec_max
      sage: mpfr_prec_max()
      2147483391
      sage: R = RealField(2^31-257)
      sage: R
      Real Field with 2147483391 bits of precision
      sage: R = RealField(2^31-256)
      Traceback (most recent call last):
      ...
      ValueError: prec (=2147483392) must be >= 2 and <= 2147483391

`sage.rings.real_mpfr.``mpfr_prec_min`()

  Return the mpfr variable `MPFR_PREC_MIN`.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import mpfr_prec_min
      sage: mpfr_prec_min()
      2
      sage: R = RealField(2)
      sage: R(2) + R(1)
      3.0
      sage: R(4) + R(1)
      4.0
      sage: R = RealField(1)
      Traceback (most recent call last):
      ...
      ValueError: prec (=1) must be >= 2 and <= 2147483391

`sage.rings.real_mpfr.``mpfr_set_exp_max`(e)

  Set the maximal exponent for MPFR numbers.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import mpfr_get_exp_max, mpfr_set_exp_max
      sage: old = mpfr_get_exp_max()
      sage: mpfr_set_exp_max(1000)
      sage: 0.5 << 1000
      5.35754303593134e300
      sage: 0.5 << 1001
      +infinity
      sage: mpfr_set_exp_max(old)
      sage: 0.5 << 1001
      1.07150860718627e301

`sage.rings.real_mpfr.``mpfr_set_exp_min`(e)

  Set the minimal exponent for MPFR numbers.

  EXAMPLES:

      sage: from sage.rings.real_mpfr import mpfr_get_exp_min, mpfr_set_exp_min
      sage: old = mpfr_get_exp_min()
      sage: mpfr_set_exp_min(-1000)
      sage: 0.5 >> 1000
      4.66631809251609e-302
      sage: 0.5 >> 1001
      0.000000000000000
      sage: mpfr_set_exp_min(old)
      sage: 0.5 >> 1001
      2.33315904625805e-302

### Navigation

- index
- modules |
- next |
- previous |
- Fixed and Arbitrary Precision Numerical Fields »