Arbitrary precision floating point real numbers using GNU MPFR

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 (Issue #13033)

  • Travis Scrimshaw (2012-11-02): Added doctests for full coverage

  • Eviatar Bach (2013-06): Fixing numerical evaluation of log_gamma

  • Vincent Klein (2017-06): RealNumber constructor support gmpy2.mpfr , gmpy2.mpq or gmpy2.mpz parameter. Add __mpfr__ to class RealNumber.

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

>>> from sage.all import *
>>> RR(sys.maxsize)
9.22337203685478e18      # 64-bit
2.14748364700000e9       # 32-bit
class sage.rings.real_mpfr.QQtoRR[source]

Bases: Map

class sage.rings.real_mpfr.RRtoRR[source]

Bases: Map

section()[source]

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

>>> from sage.all import *
>>> from sage.rings.real_mpfr import RRtoRR
>>> R10 = RealField(Integer(10))
>>> R100 = RealField(Integer(100))
>>> f = RRtoRR(R100, R10)
>>> 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='MPFR_RNDN')[source]

RealField(prec, sci_not, rnd):

INPUT:

  • prec – integer (default: 53); precision 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 – boolean (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

    • 'RNDA' – round away from zero

    • 'RNDF' – faithful rounding (currently experimental; not guaranteed correct for every operation)

    • for specialized applications, the rounding mode can also be given as an integer value of type mpfr_rnd_t. However, the exact values are unspecified.

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

>>> from sage.all import *
>>> RealField(Integer(10))
Real Field with 10 bits of precision
>>> RealField()
Real Field with 53 bits of precision
>>> RealField(Integer(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

>>> from sage.all import *
>>> R17d = RealField(Integer(17),rnd='RNDD')
>>> a = R17d(Integer(1))/R17d(Integer(3)); a.exact_rational()
87381/262144
>>> R17u = RealField(Integer(17),rnd='RNDU')
>>> a = R17u(Integer(1))/R17u(Integer(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.’

See also

class sage.rings.real_mpfr.RealField_class[source]

Bases: RealField

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 also

algebraic_closure()[source]

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

>>> from sage.all import *
>>> RR.algebraic_closure()
Complex Field with 53 bits of precision
>>> RR.algebraic_closure() is CC
True
>>> RealField(Integer(100),rnd='RNDD').algebraic_closure()
Complex Field with 100 bits of precision
>>> RealField(Integer(100)).algebraic_closure()
Complex Field with 100 bits of precision
catalan_constant()[source]

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

EXAMPLES:

sage: RealField(100).catalan_constant()
0.91596559417721901505460351493

>>> from sage.all import *
>>> RealField(Integer(100)).catalan_constant()
0.91596559417721901505460351493
characteristic()[source]

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

EXAMPLES:

sage: RealField(10).characteristic()
0

>>> from sage.all import *
>>> RealField(Integer(10)).characteristic()
0
complex_field()[source]

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

>>> from sage.all import *
>>> RR.complex_field()
Complex Field with 53 bits of precision
>>> RR.complex_field() is CC
True
>>> RealField(Integer(100),rnd='RNDD').complex_field()
Complex Field with 100 bits of precision
>>> RealField(Integer(100)).complex_field()
Complex Field with 100 bits of precision
construction()[source]

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

>>> from sage.all import *
>>> R = RealField(Integer(100), rnd='RNDU')
>>> c, S = R.construction(); S
Rational Field
>>> R == c(S)
True
euler_constant()[source]

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

EXAMPLES:

sage: RealField(100).euler_constant()
0.57721566490153286060651209008

>>> from sage.all import *
>>> RealField(Integer(100)).euler_constant()
0.57721566490153286060651209008
factorial(n)[source]

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

>>> from sage.all import *
>>> RR.factorial(Integer(0))
1.00000000000000
>>> RR.factorial(Integer(1000000))
8.26393168833124e5565708
>>> RR.factorial(-Integer(1))
Traceback (most recent call last):
...
ArithmeticError: n must be nonnegative
gen(i=0)[source]

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

>>> from sage.all import *
>>> R=RealField(Integer(100))
>>> R.gen(Integer(0))
1.0000000000000000000000000000
>>> R.gen(Integer(1))
Traceback (most recent call last):
...
IndexError: self has only one generator
gens()[source]

Return a list of generators.

EXAMPLES:

sage: RR.gens()
[1.00000000000000]

>>> from sage.all import *
>>> RR.gens()
[1.00000000000000]
is_exact()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> RR.is_exact()
False
>>> RealField(Integer(100)).is_exact()
False
log2()[source]

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

>>> from sage.all import *
>>> R=RealField(Integer(100))
>>> R.log2()
0.69314718055994530941723212146
>>> R(Integer(2)).log()
0.69314718055994530941723212146
name()[source]

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'

>>> from sage.all import *
>>> RR.name()
'RealField53_0'
>>> RealField(Integer(100),rnd='RNDU').name()
'RealField100_2'
ngens()[source]

Return the number of generators.

EXAMPLES:

sage: RR.ngens()
1

>>> from sage.all import *
>>> RR.ngens()
1
pi()[source]

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

>>> from sage.all import *
>>> R = RealField(Integer(100))
>>> R.pi()
3.1415926535897932384626433833
>>> R.pi().sqrt()/Integer(2)
0.88622692545275801364908374167
>>> R = RealField(Integer(150))
>>> R.pi().sqrt()/Integer(2)
0.88622692545275801364908374167057259139877473
prec()[source]

Return the precision of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RR.precision()
53
>>> RealField(Integer(20)).precision()
20
precision()[source]

Return the precision of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RR.precision()
53
>>> RealField(Integer(20)).precision()
20
random_element(min=-1, max=1, distribution=None)[source]

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: r = RealField(100).random_element(-5, 10)
sage: r.parent() is RealField(100)
True
sage: -5 <= r <= 10
True

>>> from sage.all import *
>>> r = RealField(Integer(100)).random_element(-Integer(5), Integer(10))
>>> r.parent() is RealField(Integer(100))
True
>>> -Integer(5) <= r <= Integer(10)
True
rounding_mode()[source]

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'

>>> from sage.all import *
>>> RR.rounding_mode()
'RNDN'
>>> RealField(Integer(20),rnd='RNDZ').rounding_mode()
'RNDZ'
>>> RealField(Integer(20),rnd='RNDU').rounding_mode()
'RNDU'
>>> RealField(Integer(20),rnd='RNDD').rounding_mode()
'RNDD'
scientific_notation(status=None)[source]

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

>>> from sage.all import *
>>> RR.scientific_notation()
False
>>> elt = RR(RealNumber('0.2512')); elt
0.251200000000000
>>> RR.scientific_notation(True)
>>> elt
2.51200000000000e-1
>>> RR.scientific_notation()
True
>>> RR.scientific_notation(False)
>>> elt
0.251200000000000
>>> R = RealField(Integer(20), sci_not=Integer(1))
>>> R.scientific_notation()
True
>>> R(RealNumber('0.2512'))
2.5120e-1
to_prec(prec)[source]

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

>>> from sage.all import *
>>> RR.to_prec(Integer(212))
Real Field with 212 bits of precision
>>> R = RealField(Integer(30), rnd="RNDZ")
>>> R.to_prec(Integer(300))
Real Field with 300 bits of precision and rounding RNDZ
zeta(n=2)[source]

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

>>> from sage.all import *
>>> R = RealField()
>>> R.zeta()
-1.00000000000000
>>> R.zeta(Integer(1))
1.00000000000000
>>> R.zeta(Integer(5))
Traceback (most recent call last):
...
ValueError: No 5th root of unity in self
class sage.rings.real_mpfr.RealLiteral[source]

Bases: RealNumber

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

base[source]
literal[source]
numerical_approx(prec=None, digits=None, algorithm=None)[source]

Change the precision of self to prec bits or digits decimal digits.

INPUT:

  • prec – precision in bits

  • digits – precision in decimal digits (only used if prec is not given)

  • algorithm – ignored for real numbers

If neither prec nor digits is given, the default precision is 53 bits (roughly 16 digits).

OUTPUT: a RealNumber with the given precision

EXAMPLES:

sage: (1.3).numerical_approx()
1.30000000000000
sage: n(1.3, 120)
1.3000000000000000000000000000000000

>>> from sage.all import *
>>> (RealNumber('1.3')).numerical_approx()
1.30000000000000
>>> n(RealNumber('1.3'), Integer(120))
1.3000000000000000000000000000000000

Compare with:

sage: RealField(120)(RR(13/10))
1.3000000000000000444089209850062616
sage: n(RR(13/10), 120)
Traceback (most recent call last):
...
TypeError: cannot approximate to a precision of 120 bits, use at most 53 bits

>>> from sage.all import *
>>> RealField(Integer(120))(RR(Integer(13)/Integer(10)))
1.3000000000000000444089209850062616
>>> n(RR(Integer(13)/Integer(10)), Integer(120))
Traceback (most recent call last):
...
TypeError: cannot approximate to a precision of 120 bits, use at most 53 bits

The result is a non-literal:

sage: type(1.3)
<class 'sage.rings.real_mpfr.RealLiteral'>
sage: type(n(1.3))
<class 'sage.rings.real_mpfr.RealNumber'>

>>> from sage.all import *
>>> type(RealNumber('1.3'))
<class 'sage.rings.real_mpfr.RealLiteral'>
>>> type(n(RealNumber('1.3')))
<class 'sage.rings.real_mpfr.RealNumber'>
class sage.rings.real_mpfr.RealNumber[source]

Bases: 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)[source]

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

>>> from sage.all import *
>>> a = RealNumber('1.5')
>>> b = RealNumber('2.5')
>>> a.agm(b)
1.96811775182478
>>> RealField(Integer(200))(a).agm(b)
1.9681177518247777389894630877503739489139488203685819712291
>>> a.agm(Integer(100))
28.1189391225320

The AGM always lies between the geometric and arithmetic mean:

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

>>> from sage.all import *
>>> sqrt(a*b) < a.agm(b) < (a+b)/Integer(2)
True

It is, of course, symmetric:

sage: b.agm(a)
1.96811775182478

>>> from sage.all import *
>>> 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

>>> from sage.all import *
>>> (Integer(2)*a).agm(Integer(2)*b) / Integer(2)
1.96811775182478
>>> (Integer(3)*a).agm(Integer(3)*b) / Integer(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]         # needs sage.symbolic
sage: RR.pi()/4 * (a+b)/E                                                   # needs sage.symbolic
1.96811775182478

>>> from sage.all import *
>>> m = (a-b)**Integer(2)/(a+b)**Integer(2)
>>> E = numerical_integral(Integer(1)/sqrt(Integer(1)-m*sin(x)**Integer(2)), Integer(0), RR.pi()/Integer(2))[Integer(0)]         # needs sage.symbolic
>>> RR.pi()/Integer(4) * (a+b)/E                                                   # needs sage.symbolic
1.96811775182478
algdep(n)[source]

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 pari:algdep command.

EXAMPLES:

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

>>> from sage.all import *
>>> r = sqrt(RealNumber('2.0')); r
1.41421356237310
>>> r.algebraic_dependency(Integer(5))
x^2 - 2
algebraic_dependency(n)[source]

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 pari:algdep command.

EXAMPLES:

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

>>> from sage.all import *
>>> r = sqrt(RealNumber('2.0')); r
1.41421356237310
>>> r.algebraic_dependency(Integer(5))
x^2 - 2
arccos()[source]

Return the inverse cosine of self.

EXAMPLES:

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(3)
>>> i = q.cos()
>>> i.arccos() == q
True
arccosh()[source]

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(2)
>>> i = q.cosh() ; i
2.50917847865806
>>> q == i.arccosh()
True
arccoth()[source]

Return the inverse hyperbolic cotangent of self.

EXAMPLES:

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(5)
>>> i = q.coth()
>>> i.arccoth() == q
True
arccsch()[source]

Return the inverse hyperbolic cosecant of self.

EXAMPLES:

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

>>> from sage.all import *
>>> i = RR.pi()/Integer(5)
>>> q = i.csch()
>>> q.arccsch() == i
True
arcsech()[source]

Return the inverse hyperbolic secant of self.

EXAMPLES:

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

>>> from sage.all import *
>>> i = RR.pi()/Integer(3)
>>> q = i.sech()
>>> q.arcsech() == i
True
arcsin()[source]

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(5)
>>> i = q.sin()
>>> i.arcsin() == q
True
>>> i.arcsin() - q
0.000000000000000
arcsinh()[source]

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(7)
>>> i = q.sinh() ; i
0.464017630492991
>>> i.arcsinh() - q
0.000000000000000
arctan()[source]

Return the inverse tangent of self.

EXAMPLES:

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(5)
>>> i = q.tan()
>>> i.arctan() == q
True
arctanh()[source]

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(7)
>>> i = q.tanh() ; i
0.420911241048535
>>> i.arctanh() - q
0.000000000000000
as_integer_ratio()[source]

Return a coprime pair of integers (a, b) such that self equals a / b exactly.

EXAMPLES:

sage: RR(0).as_integer_ratio()
(0, 1)
sage: RR(1/3).as_integer_ratio()
(6004799503160661, 18014398509481984)
sage: RR(37/16).as_integer_ratio()
(37, 16)
sage: RR(3^60).as_integer_ratio()
(42391158275216203520420085760, 1)
sage: RR('nan').as_integer_ratio()
Traceback (most recent call last):
...
ValueError: unable to convert NaN to a rational number

>>> from sage.all import *
>>> RR(Integer(0)).as_integer_ratio()
(0, 1)
>>> RR(Integer(1)/Integer(3)).as_integer_ratio()
(6004799503160661, 18014398509481984)
>>> RR(Integer(37)/Integer(16)).as_integer_ratio()
(37, 16)
>>> RR(Integer(3)**Integer(60)).as_integer_ratio()
(42391158275216203520420085760, 1)
>>> RR('nan').as_integer_ratio()
Traceback (most recent call last):
...
ValueError: unable to convert NaN to a rational number

This coincides with Python floats:

sage: pi = RR.pi()
sage: pi.as_integer_ratio()
(884279719003555, 281474976710656)
sage: float(pi).as_integer_ratio() == pi.as_integer_ratio()
True

>>> from sage.all import *
>>> pi = RR.pi()
>>> pi.as_integer_ratio()
(884279719003555, 281474976710656)
>>> float(pi).as_integer_ratio() == pi.as_integer_ratio()
True
ceil()[source]

Return the ceiling of self.

EXAMPLES:

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

>>> from sage.all import *
>>> (RealNumber('2.99')).ceil()
3
>>> (RealNumber('2.00')).ceil()
2
>>> (RealNumber('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

>>> from sage.all import *
>>> ceil(Integer(10)**Integer(16) * RealNumber('1.0'))
10000000000000000
>>> ceil(Integer(10)**Integer(17) * RealNumber('1.0'))
100000000000000000
>>> ceil(RR(+infinity))
Traceback (most recent call last):
...
ValueError: Calling ceil() on infinity or NaN
ceiling()[source]

Return the ceiling of self.

EXAMPLES:

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

>>> from sage.all import *
>>> (RealNumber('2.99')).ceil()
3
>>> (RealNumber('2.00')).ceil()
2
>>> (RealNumber('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

>>> from sage.all import *
>>> ceil(Integer(10)**Integer(16) * RealNumber('1.0'))
10000000000000000
>>> ceil(Integer(10)**Integer(17) * RealNumber('1.0'))
100000000000000000
>>> ceil(RR(+infinity))
Traceback (most recent call last):
...
ValueError: Calling ceil() on infinity or NaN
conjugate()[source]

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

>>> from sage.all import *
>>> x = RealField(Integer(100))(RealNumber('1.238'))
>>> x.conjugate()
1.2380000000000000000000000000
cos()[source]

Return the cosine of self.

EXAMPLES:

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

>>> from sage.all import *
>>> t=RR.pi()/Integer(2)
>>> t.cos()
6.12323399573677e-17
cosh()[source]

Return the hyperbolic cosine of self.

EXAMPLES:

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(12)
>>> q.cosh()
1.03446564009551
cot()[source]

Return the cotangent of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RealField(Integer(100))(Integer(2)).cot()
-0.45765755436028576375027741043
coth()[source]

Return the hyperbolic cotangent of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RealField(Integer(100))(Integer(2)).coth()
1.0373147207275480958778097648
csc()[source]

Return the cosecant of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RealField(Integer(100))(Integer(2)).csc()
1.0997501702946164667566973970
csch()[source]

Return the hyperbolic cosecant of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RealField(Integer(100))(Integer(2)).csch()
0.27572056477178320775835148216
cube_root()[source]

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

>>> from sage.all import *
>>> r = RealNumber('125.0'); r.cube_root()
5.00000000000000
>>> r = -RealNumber('119.0')
>>> r.cube_root()**Integer(3) - r       # illustrates precision loss
-1.42108547152020e-14
eint()[source]

Return the exponential integral of this number.

EXAMPLES:

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

>>> from sage.all import *
>>> r = RealNumber('1.0')
>>> r.eint()
1.89511781635594


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

>>> from sage.all import *
>>> r = -RealNumber('1.0')
>>> r.eint()
-0.219383934395520
epsilon(field=None)[source]

Return 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

>>> from sage.all import *
>>> RR(Integer(2)**Integer(53)).epsilon()
1.00000000000000
>>> RR(Integer(0)).epsilon()
0.000000000000000
>>> a = RR.pi()
>>> a.epsilon()
3.48786849800863e-16
>>> a.ulp()/Integer(2), a.ulp()
(2.22044604925031e-16, 4.44089209850063e-16)
>>> a / Integer(2)**a.precision()
3.48786849800863e-16
>>> (-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

>>> from sage.all import *
>>> a = RealField(Integer(256)).pi()
>>> a.epsilon()
2.713132368784788677624750042896586252980746500631892201656843478528498954308e-77
>>> e = a.epsilon(RealField(Integer(64)))
>>> e
2.71313236878478868e-77
>>> parent(e)
Real Field with 64 bits of precision
>>> 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

>>> from sage.all import *
>>> RR('nan').epsilon()
NaN
>>> parent(RR('nan').epsilon(RealField(Integer(42))))
Real Field with 42 bits of precision
>>> RR('+Inf').epsilon()
+infinity
>>> RR('-Inf').epsilon()
+infinity
erf()[source]

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).erf()
0.995322265018953
>>> R(Integer(6)).erf()
1.00000000000000
erfc()[source]

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).erfc()
0.00467773498104727
>>> R(Integer(6)).erfc()
2.15197367124989e-17
exact_rational()[source]

Return 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()                                    # needs sage.symbolic
-25/8

>>> from sage.all import *
>>> RR(Integer(0)).exact_rational()
0
>>> RR(Integer(1)/Integer(3)).exact_rational()
6004799503160661/18014398509481984
>>> RR(Integer(37)/Integer(16)).exact_rational()
37/16
>>> RR(Integer(3)**Integer(60)).exact_rational()
42391158275216203520420085760
>>> RR(Integer(3)**Integer(60)).exact_rational() - Integer(3)**Integer(60)
6125652559
>>> RealField(Integer(5))(-pi).exact_rational()                                    # needs sage.symbolic
-25/8
exp()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> r = RealNumber('0.0')
>>> r.exp()
1.00000000000000


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

>>> from sage.all import *
>>> r = RealNumber('32.3')
>>> a = r.exp(); a
1.06588847274864e14
>>> a.log()
32.3000000000000


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

>>> from sage.all import *
>>> r = -RealNumber('32.3')
>>> r.exp()
9.38184458849869e-15
exp10()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> r = RealNumber('0.0')
>>> r.exp10()
1.00000000000000


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

>>> from sage.all import *
>>> r = RealNumber('32.0')
>>> r.exp10()
1.00000000000000e32


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

>>> from sage.all import *
>>> r = -RealNumber('32.3')
>>> r.exp10()
5.01187233627276e-33
exp2()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> r = RealNumber('0.0')
>>> r.exp2()
1.00000000000000


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

>>> from sage.all import *
>>> r = RealNumber('32.0')
>>> r.exp2()
4.29496729600000e9


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

>>> from sage.all import *
>>> r = -RealNumber('32.3')
>>> r.exp2()
1.89117248253021e-10
expm1()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> r = RealNumber('1.0')
>>> r.expm1()
1.71828182845905


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

>>> from sage.all import *
>>> r = RealNumber('1e-16')
>>> exp(r)-Integer(1)
0.000000000000000
>>> r.expm1()
1.00000000000000e-16
floor()[source]

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

>>> from sage.all import *
>>> R = RealField()
>>> (RealNumber('2.99')).floor()
2
>>> (RealNumber('2.00')).floor()
2
>>> floor(RR(-Integer(5)/Integer(2)))
-3
>>> floor(RR(+infinity))
Traceback (most recent call last):
...
ValueError: Calling floor() on infinity or NaN
fp_rank()[source]

Return 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

>>> from sage.all import *
>>> RR(Integer(0)).fp_rank()
0
>>> RR(Integer(0)).nextabove().fp_rank()
1
>>> RR(Integer(0)).nextbelow().nextbelow().fp_rank()
-2
>>> RR(Integer(1)).fp_rank()
4835703278458516698824705            # 32-bit
20769187434139310514121985316880385  # 64-bit
>>> RR(-Integer(1)).fp_rank()
-4835703278458516698824705            # 32-bit
-20769187434139310514121985316880385  # 64-bit
>>> RR(Integer(1)).fp_rank() - RR(Integer(1)).nextbelow().fp_rank()
1
>>> RR(-infinity).fp_rank()
-9671406552413433770278913            # 32-bit
-41538374868278621023740371006390273  # 64-bit
>>> RR(-infinity).fp_rank() - RR(-infinity).nextabove().fp_rank()
-1
fp_rank_delta(other)[source]

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                              # needs sage.symbolic
....:    (RR(-infinity), -1.0, 0.0, 1.0, RR(pi), RR(infinity))]
[1, 1, 1, 1, 1, 0]

>>> from sage.all import *
>>> [x.fp_rank_delta(x.nextabove()) for x in                              # needs sage.symbolic
...    (RR(-infinity), -RealNumber('1.0'), RealNumber('0.0'), RealNumber('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

>>> from sage.all import *
>>> R2 = RealField(Integer(2))
>>> R2(Integer(1)).fp_rank_delta(R2(Integer(2)))
2
>>> R2(Integer(2)).fp_rank_delta(R2(Integer(1)))
-2
>>> R2(Integer(1)).fp_rank_delta(R2(Integer(1048576)))
40
>>> R2(Integer(24)).fp_rank_delta(R2(Integer(4)))
-5
>>> R2(-Integer(4)).fp_rank_delta(R2(-Integer(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

>>> from sage.all import *
>>> R2(-Integer(1)).fp_rank_delta(R2(Integer(1)))
4294967298            # 32-bit
18446744073709551618  # 64-bit
frac()[source]

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

>>> from sage.all import *
>>> (RealNumber('2.99')).frac()
0.990000000000000
>>> (RealNumber('2.50')).frac()
0.500000000000000
>>> (-RealNumber('2.79')).frac()
-0.790000000000000
>>> (-RealNumber('2.79')).trunc() + (-RealNumber('2.79')).frac()
-2.79000000000000
gamma()[source]

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

>>> from sage.all import *
>>> R = RealField()
>>> R(Integer(6)).gamma()
120.000000000000
>>> R(RealNumber('1.5')).gamma()
0.886226925452758
hex()[source]

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'

>>> from sage.all import *
>>> RR(-Integer(1)/Integer(3)).hex()
'-0x5.5555555555554p-4'
>>> Reals(Integer(100))(RealNumber('123.456e789')).hex()
'0xf.721008e90630c8da88f44dd2p+2624'
>>> (-RealNumber('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')]

>>> from sage.all import *
>>> [(a.hex(), float(a).hex()) for a in [RealNumber('.5'), RealNumber('1.'), RealNumber('2.'), RealNumber('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']

>>> from sage.all import *
>>> [RR(s).hex() for s in ['+inf', '-inf', 'nan']]
['inf', '-inf', 'nan']
imag()[source]

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

>>> from sage.all import *
>>> RR.pi().imag()
0
>>> RealField(Integer(100))(Integer(2)).imag()
0
integer_part()[source]

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

OUTPUT: a Sage Integer

EXAMPLES:

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

>>> from sage.all import *
>>> a = RealNumber('119.41212')
>>> a.integer_part()
119
>>> a = -RealNumber('123.4567')
>>> a.integer_part()
-123

A big number with no decimal point:

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

>>> from sage.all import *
>>> a = RR(Integer(10)**Integer(17)); a
1.00000000000000e17
>>> a.integer_part()
100000000000000000
is_NaN()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> a = RR(Integer(0)) / RR(Integer(0)); a
NaN
>>> a.is_NaN()
True
is_infinity()[source]

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

>>> from sage.all import *
>>> a = RR('1.494') / RR(Integer(0)); a
+infinity
>>> a.is_infinity()
True
>>> a = -RR('1.494') / RR(Integer(0)); a
-infinity
>>> a.is_infinity()
True
>>> RR(RealNumber('1.5')).is_infinity()
False
>>> RR('nan').is_infinity()
False
is_integer()[source]

Return True if this number is a integer.

EXAMPLES:

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

>>> from sage.all import *
>>> RR(Integer(1)).is_integer()
True
>>> RR(RealNumber('0.1')).is_integer()
False
is_negative_infinity()[source]

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

>>> from sage.all import *
>>> a = RR('1.494') / RR(Integer(0)); a
+infinity
>>> a.is_negative_infinity()
False
>>> a = -RR('1.494') / RR(Integer(0)); a
-infinity
>>> RR(RealNumber('1.5')).is_negative_infinity()
False
>>> a.is_negative_infinity()
True
is_positive_infinity()[source]

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

>>> from sage.all import *
>>> a = RR('1.494') / RR(Integer(0)); a
+infinity
>>> a.is_positive_infinity()
True
>>> a = -RR('1.494') / RR(Integer(0)); a
-infinity
>>> RR(RealNumber('1.5')).is_positive_infinity()
False
>>> a.is_positive_infinity()
False
is_real()[source]

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
sage: RR(NaN).is_real()                                                     # needs sage.symbolic
False

>>> from sage.all import *
>>> RR(Integer(1)).is_real()
True
>>> RR('-100').is_real()
True
>>> RR(NaN).is_real()                                                     # needs sage.symbolic
False
is_square()[source]

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 nonnegative.

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

>>> from sage.all import *
>>> r = RealNumber('3.5')
>>> r.is_square()
True
>>> r = RealNumber('0.0')
>>> r.is_square()
True
>>> r = -RealNumber('4.0')
>>> r.is_square()
False
is_unit()[source]

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

>>> from sage.all import *
>>> RR(Integer(1)).is_unit()
True
>>> RR('0').is_unit()
False
>>> RR('-0').is_unit()
False
>>> RR('nan').is_unit()
False
>>> RR('inf').is_unit()
False
>>> RR('-inf').is_unit()
False
j0()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).j0()
0.223890779141236
j1()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).j1()
0.576724807756873
jn(n)[source]

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).jn(Integer(3))
0.128943249474402
>>> R(Integer(2)).jn(-Integer(17))
-2.65930780516787e-15
log(base=None)[source]

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)                                                         # needs sage.symbolic
0.693147180559945

>>> from sage.all import *
>>> R = RealField()
>>> R(Integer(2)).log()
0.693147180559945
>>> log(RR(Integer(2)))
0.693147180559945
>>> log(RR(Integer(2)), "e")
0.693147180559945
>>> log(RR(Integer(2)), e)                                                         # needs sage.symbolic
0.693147180559945


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

>>> from sage.all import *
>>> r = R(-Integer(1)); r.log()
3.14159265358979*I
>>> log(RR(-Integer(1)), e)                                                        # needs sage.symbolic
3.14159265358979*I
>>> r.log(Integer(2))
4.53236014182719*I

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

sage: r = R(NaN); r.log()                                                   # needs sage.symbolic
NaN

>>> from sage.all import *
>>> r = R(NaN); r.log()                                                   # needs sage.symbolic
NaN
log10()[source]

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

>>> from sage.all import *
>>> r = RealNumber('16.0'); r.log10()
1.20411998265592
>>> r.log() / log(RealNumber('10.0'))
1.20411998265592


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

>>> from sage.all import *
>>> r = RealNumber('39.9'); r.log10()
1.60097289568675


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

>>> from sage.all import *
>>> r = RealNumber('0.0')
>>> r.log10()
-infinity


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

>>> from sage.all import *
>>> r = -RealNumber('1.0')
>>> r.log10()
1.36437635384184*I
log1p()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> r = RealNumber('15.0'); r.log1p()
2.77258872223978
>>> (r+Integer(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

>>> from sage.all import *
>>> r = RealNumber('3e-10')
>>> r.log1p()
2.99999999955000e-10
>>> (Integer(1)+r).log()
3.00000024777111e-10
>>> r100 = RealField(Integer(100))(r)
>>> (Integer(1)+r100).log()
2.9999999995500000000978021372e-10


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

>>> from sage.all import *
>>> r = RealNumber('38.9'); r.log1p()
3.68637632389582


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

>>> from sage.all import *
>>> r = -RealNumber('1.0')
>>> r.log1p()
-infinity


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

>>> from sage.all import *
>>> r = -RealNumber('2.0')
>>> r.log1p()
3.14159265358979*I
log2()[source]

Return log to the base 2 of self.

EXAMPLES:

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

>>> from sage.all import *
>>> r = RealNumber('16.0')
>>> r.log2()
4.00000000000000


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

>>> from sage.all import *
>>> r = RealNumber('31.9'); r.log2()
4.99548451887751


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

>>> from sage.all import *
>>> r = RealNumber('0.0')
>>> r.log2()
-infinity


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

>>> from sage.all import *
>>> r = -RealNumber('3.0'); r.log2()
1.58496250072116 + 4.53236014182719*I
log_gamma()[source]

Return the principal branch of the log gamma of self.

Note that this is not in general equal to log(gamma(self)) for negative input.

EXAMPLES:

sage: R = RealField(53)
sage: R(6).log_gamma()
4.78749174278205
sage: R(1e10).log_gamma()
2.20258509288811e11
sage: log_gamma(-2.1)
1.53171380819509 - 9.42477796076938*I
sage: log(gamma(-1.1)) == log_gamma(-1.1)
False

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(6)).log_gamma()
4.78749174278205
>>> R(RealNumber('1e10')).log_gamma()
2.20258509288811e11
>>> log_gamma(-RealNumber('2.1'))
1.53171380819509 - 9.42477796076938*I
>>> log(gamma(-RealNumber('1.1'))) == log_gamma(-RealNumber('1.1'))
False
multiplicative_order()[source]

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

>>> from sage.all import *
>>> RR(Integer(1)).multiplicative_order()
1
>>> RR(-Integer(1)).multiplicative_order()
2
>>> RR(Integer(3)).multiplicative_order()
+Infinity
nearby_rational(max_error=None, max_denominator=None)[source]

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

>>> from sage.all import *
>>> (RealNumber('0.333')).nearby_rational(max_error=RealNumber('0.001'))
1/3
>>> (RealNumber('0.333')).nearby_rational(max_error=Integer(1))
0
>>> (-RealNumber('0.333')).nearby_rational(max_error=RealNumber('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: # needs sage.symbolic
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

>>> from sage.all import *
>>> (RealNumber('0.333')).nearby_rational(max_denominator=Integer(100))
1/3
>>> RR(Integer(1)/Integer(3) + Integer(1)/Integer(1000000)).nearby_rational(max_denominator=Integer(2999999))
777780/2333333
>>> RR(Integer(1)/Integer(3) + Integer(1)/Integer(1000000)).nearby_rational(max_denominator=Integer(3000000))
1000003/3000000
>>> (-RealNumber('0.333')).nearby_rational(max_denominator=Integer(1000))
-333/1000
>>> RR(Integer(3)/Integer(4)).nearby_rational(max_denominator=Integer(2))
1

>>> # needs sage.symbolic
>>> RR(pi).nearby_rational(max_denominator=Integer(120))
355/113
>>> RR(pi).nearby_rational(max_denominator=Integer(10000))
355/113
>>> RR(pi).nearby_rational(max_denominator=Integer(100000))
312689/99532
>>> RR(pi).nearby_rational(max_denominator=Integer(1))
3

>>> RR(-RealNumber('3.5')).nearby_rational(max_denominator=Integer(1))
-3
nextabove()[source]

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()                                                    # needs sage.symbolic
'-1.4142135623730951'
sage: RR(-sqrt(2)).nextabove().str()                                        # needs sage.symbolic
'-1.4142135623730949'

>>> from sage.all import *
>>> RR('-infinity').nextabove()
-2.09857871646739e323228496            # 32-bit
-5.87565378911159e1388255822130839282  # 64-bit
>>> RR(Integer(0)).nextabove()
2.38256490488795e-323228497            # 32-bit
8.50969131174084e-1388255822130839284  # 64-bit
>>> RR('+infinity').nextabove()
+infinity
>>> RR(-sqrt(Integer(2))).str()                                                    # needs sage.symbolic
'-1.4142135623730951'
>>> RR(-sqrt(Integer(2))).nextabove().str()                                        # needs sage.symbolic
'-1.4142135623730949'
nextbelow()[source]

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()                                                    # needs sage.symbolic
'-1.4142135623730951'
sage: RR(-sqrt(2)).nextbelow().str()                                        # needs sage.symbolic
'-1.4142135623730954'

>>> from sage.all import *
>>> RR('-infinity').nextbelow()
-infinity
>>> RR(Integer(0)).nextbelow()
-2.38256490488795e-323228497            # 32-bit
-8.50969131174084e-1388255822130839284  # 64-bit
>>> RR('+infinity').nextbelow()
2.09857871646739e323228496              # 32-bit
5.87565378911159e1388255822130839282    # 64-bit
>>> RR(-sqrt(Integer(2))).str()                                                    # needs sage.symbolic
'-1.4142135623730951'
>>> RR(-sqrt(Integer(2))).nextbelow().str()                                        # needs sage.symbolic
'-1.4142135623730954'
nexttoward(other)[source]

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()
'1.0000000000000002'
sage: (1.0).nexttoward(RR('-infinity')).str()
'0.99999999999999989'
sage: RR(infinity).nexttoward(0)
2.09857871646739e323228496            # 32-bit
5.87565378911159e1388255822130839282  # 64-bit
sage: RR(pi).str()                                                          # needs sage.symbolic
'3.1415926535897931'
sage: RR(pi).nexttoward(22/7).str()                                         # needs sage.symbolic
'3.1415926535897936'
sage: RR(pi).nexttoward(21/7).str()                                         # needs sage.symbolic
'3.1415926535897927'

>>> from sage.all import *
>>> (RealNumber('1.0')).nexttoward(Integer(2)).str()
'1.0000000000000002'
>>> (RealNumber('1.0')).nexttoward(RR('-infinity')).str()
'0.99999999999999989'
>>> RR(infinity).nexttoward(Integer(0))
2.09857871646739e323228496            # 32-bit
5.87565378911159e1388255822130839282  # 64-bit
>>> RR(pi).str()                                                          # needs sage.symbolic
'3.1415926535897931'
>>> RR(pi).nexttoward(Integer(22)/Integer(7)).str()                                         # needs sage.symbolic
'3.1415926535897936'
>>> RR(pi).nexttoward(Integer(21)/Integer(7)).str()                                         # needs sage.symbolic
'3.1415926535897927'
nth_root(n, algorithm=0)[source]

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

>>> from sage.all import *
>>> R = RealField()
>>> R(Integer(8)).nth_root(Integer(3))
2.00000000000000
>>> R(Integer(8)).nth_root(RealNumber('3.7'))    # illustrate rounding down
2.00000000000000
>>> R(-Integer(8)).nth_root(Integer(3))
-2.00000000000000
>>> R(Integer(0)).nth_root(Integer(3))
0.000000000000000
>>> R(Integer(32)).nth_root(-Integer(1))
Traceback (most recent call last):
...
ValueError: n must be positive
>>> R(Integer(32)).nth_root(RealNumber('1.0'))
32.0000000000000
>>> R(Integer(4)).nth_root(Integer(4))
1.41421356237310
>>> R(Integer(4)).nth_root(Integer(40))
1.03526492384138
>>> R(Integer(4)).nth_root(Integer(400))
1.00347174850950
>>> R(Integer(4)).nth_root(Integer(4000))
1.00034663365385
>>> R(Integer(4)).nth_root(Integer(4000000))
1.00000034657365
>>> R(-Integer(27)).nth_root(Integer(3))
-3.00000000000000
>>> R(-Integer(4)).nth_root(Integer(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

>>> from sage.all import *
>>> R(-Integer(2)).nth_root(Integer(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

>>> from sage.all import *
>>> R(Integer(0)).nth_root(Integer(6))
0.000000000000000
>>> R(Integer(0)).nth_root(Integer(7))
0.000000000000000
prec()[source]

Return the precision of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RR(RealNumber('1.0')).precision()
53
>>> RealField(Integer(101))(-Integer(1)).precision()
101
precision()[source]

Return the precision of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RR(RealNumber('1.0')).precision()
53
>>> RealField(Integer(101))(-Integer(1)).precision()
101
real()[source]

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

>>> from sage.all import *
>>> RR(Integer(2)).real()
2.00000000000000
>>> RealField(Integer(200))(-RealNumber('4.5')).real()
-4.5000000000000000000000000000000000000000000000000000000000
round()[source]

Round self to the nearest representable integer, rounding halfway cases away from zero.

Note

The rounding mode of the parent field does not affect the result.

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

>>> from sage.all import *
>>> RR(RealNumber('0.49')).round()
0
>>> RR(RealNumber('0.5')).round()
1
>>> RR(-RealNumber('0.49')).round()
0
>>> RR(-RealNumber('0.5')).round()
-1
sec()[source]

Return the secant of this number.

EXAMPLES:

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

>>> from sage.all import *
>>> RealField(Integer(100))(Integer(2)).sec()
-2.4029979617223809897546004014
sech()[source]

Return the hyperbolic secant of self.

EXAMPLES:

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

>>> from sage.all import *
>>> RealField(Integer(100))(Integer(2)).sech()
0.26580222883407969212086273982
sign()[source]

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

>>> from sage.all import *
>>> R=RealField(Integer(100))
>>> R(-RealNumber('2.4')).sign()
-1
>>> R(RealNumber('2.1')).sign()
1
>>> R(Integer(0)).sign()
0
sign_mantissa_exponent()[source]

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> a = R(exp(RealNumber('1.0'))); a
2.71828182845905
>>> sign, mantissa, exponent = R(exp(RealNumber('1.0'))).sign_mantissa_exponent()
>>> sign, mantissa, exponent
(1, 6121026514868073, -51)
>>> sign*mantissa*(Integer(2)**exponent) == a
True

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

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

>>> from sage.all import *
>>> RR(-Integer(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)

>>> from sage.all import *
>>> a = R(exp(RealNumber('1.0')))
>>> b = a.exact_rational()
>>> valuation, unit = b.val_unit(Integer(2))
>>> (b/abs(b), unit, valuation)
(1, 6121026514868073, -51)
>>> a.sign_mantissa_exponent()
(1, 6121026514868073, -51)
simplest_rational()[source]

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: RRa = RealField(53, rnd='RNDA')
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(RRa(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(RRa(-1/3))
-1/3
sage: check(RR(-1/3))
-1/3
sage: check(RealField(20)(pi))                                              # needs sage.symbolic
355/113
sage: check(RR(pi))                                                         # needs sage.symbolic
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

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

Return the sine of self.

EXAMPLES:

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

>>> from sage.all import *
>>> R = RealField(Integer(100))
>>> R(Integer(2)).sin()
0.90929742682568169539601986591
sincos()[source]

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)

>>> from sage.all import *
>>> R = RealField()
>>> t = R.pi()/Integer(6)
>>> t.sincos()
(0.500000000000000, 0.866025403784439)
sinh()[source]

Return the hyperbolic sine of self.

EXAMPLES:

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(12)
>>> q.sinh()
0.264800227602271
sqrt(extend=True, all=False)[source]

The square root function.

INPUT:

  • extend – boolean (default: True); if True, return a square root in a complex field if necessary if self is negative. Otherwise raise a ValueError.

  • all – boolean (default: False); if True, return a list of all square roots

EXAMPLES:

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

>>> from sage.all import *
>>> r = -RealNumber('2.0')
>>> r.sqrt()
1.41421356237310*I


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

>>> from sage.all import *
>>> r = RealNumber('4.0')
>>> r.sqrt()
2.00000000000000
>>> r.sqrt()**Integer(2) == r
True


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

>>> from sage.all import *
>>> r = Integer(4344)
>>> r.sqrt()                                                              # needs sage.symbolic
2*sqrt(1086)


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

>>> from sage.all import *
>>> r = RealNumber('4344.0')
>>> r.sqrt()**Integer(2) == r
True
>>> r.sqrt()**Integer(2) - r
0.000000000000000


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

>>> from sage.all import *
>>> r = -RealNumber('2.0')
>>> r.sqrt()
1.41421356237310*I
str(base=10, digits=0, no_sci=None, e=None, truncate=False, skip_zeroes=False)[source]

Return a string representation of self.

INPUT:

  • base – (default: 10) base for output

  • digits – (default: 0) number of digits to display; when digits is zero, choose this automatically

  • no_sci – if 2, never print using scientific notation; if True, use scientific notation only for large or small numbers; if 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 – boolean (default: False); if True, round off the last digits in base-10 printing to lessen confusing base-2 roundoff issues. This flag may not be used in other bases or when digits is given.

  • skip_zeroes – boolean (default: False); if True, skip trailing zeroes in mantissa

EXAMPLES:

sage: a = 61/3.0; a
20.3333333333333
sage: a.str()
'20.333333333333332'
sage: a.str(truncate=True)
'20.3333333333333'
sage: a.str(2)
'10100.010101010101010101010101010101010101010101010101'
sage: a.str(no_sci=False)
'2.0333333333333332e1'
sage: a.str(16, no_sci=False)
'1.4555555555555@1'
sage: a.str(digits=5)
'20.333'
sage: a.str(2, digits=5)
'10100.'

sage: b = 2.0^99
sage: b.str()
'6.3382530011411470e29'
sage: b.str(no_sci=False)
'6.3382530011411470e29'
sage: b.str(no_sci=True)
'6.3382530011411470e29'
sage: c = 2.0^100
sage: c.str()
'1.2676506002282294e30'
sage: c.str(no_sci=False)
'1.2676506002282294e30'
sage: c.str(no_sci=True)
'1.2676506002282294e30'
sage: c.str(no_sci=2)
'1267650600228229400000000000000.'
sage: 0.5^53
1.11022302462516e-16
sage: 0.5^54
5.55111512312578e-17
sage: (0.01).str()
'0.010000000000000000'
sage: (0.01).str(skip_zeroes=True)
'0.01'
sage: (-10.042).str()
'-10.042000000000000'
sage: (-10.042).str(skip_zeroes=True)
'-10.042'
sage: (389.0).str(skip_zeroes=True)
'389.'

>>> from sage.all import *
>>> a = Integer(61)/RealNumber('3.0'); a
20.3333333333333
>>> a.str()
'20.333333333333332'
>>> a.str(truncate=True)
'20.3333333333333'
>>> a.str(Integer(2))
'10100.010101010101010101010101010101010101010101010101'
>>> a.str(no_sci=False)
'2.0333333333333332e1'
>>> a.str(Integer(16), no_sci=False)
'1.4555555555555@1'
>>> a.str(digits=Integer(5))
'20.333'
>>> a.str(Integer(2), digits=Integer(5))
'10100.'

>>> b = RealNumber('2.0')**Integer(99)
>>> b.str()
'6.3382530011411470e29'
>>> b.str(no_sci=False)
'6.3382530011411470e29'
>>> b.str(no_sci=True)
'6.3382530011411470e29'
>>> c = RealNumber('2.0')**Integer(100)
>>> c.str()
'1.2676506002282294e30'
>>> c.str(no_sci=False)
'1.2676506002282294e30'
>>> c.str(no_sci=True)
'1.2676506002282294e30'
>>> c.str(no_sci=Integer(2))
'1267650600228229400000000000000.'
>>> RealNumber('0.5')**Integer(53)
1.11022302462516e-16
>>> RealNumber('0.5')**Integer(54)
5.55111512312578e-17
>>> (RealNumber('0.01')).str()
'0.010000000000000000'
>>> (RealNumber('0.01')).str(skip_zeroes=True)
'0.01'
>>> (-RealNumber('10.042')).str()
'-10.042000000000000'
>>> (-RealNumber('10.042')).str(skip_zeroes=True)
'-10.042'
>>> (RealNumber('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

>>> from sage.all import *
>>> print((RealNumber('65536.0')).str(base=Integer(2)))
1.0000000000000000000000000000000000000000000000000000e16
>>> print((RealNumber('65536.0')).str(base=Integer(36)))
1ekg.00000000
>>> print((RealNumber('65536.0')).str(base=Integer(62)))
H32.0000000

String conversion respects rounding:

sage: x = -RR.pi()
sage: x.str(digits=1)
'-3.'
sage: y = RealField(53, rnd="RNDD")(x)
sage: y.str(digits=1)
'-4.'
sage: y = RealField(53, rnd="RNDU")(x)
sage: y.str(digits=1)
'-3.'
sage: y = RealField(53, rnd="RNDZ")(x)
sage: y.str(digits=1)
'-3.'
sage: y = RealField(53, rnd="RNDA")(x)
sage: y.str(digits=1)
'-4.'

>>> from sage.all import *
>>> x = -RR.pi()
>>> x.str(digits=Integer(1))
'-3.'
>>> y = RealField(Integer(53), rnd="RNDD")(x)
>>> y.str(digits=Integer(1))
'-4.'
>>> y = RealField(Integer(53), rnd="RNDU")(x)
>>> y.str(digits=Integer(1))
'-3.'
>>> y = RealField(Integer(53), rnd="RNDZ")(x)
>>> y.str(digits=Integer(1))
'-3.'
>>> y = RealField(Integer(53), rnd="RNDA")(x)
>>> y.str(digits=Integer(1))
'-4.'

Zero has the correct number of digits:

sage: zero = RR.zero()
sage: print(zero.str(digits=3))
0.00
sage: print(zero.str(digits=3, no_sci=False))
0.00e0
sage: print(zero.str(digits=3, skip_zeroes=True))
0.

>>> from sage.all import *
>>> zero = RR.zero()
>>> print(zero.str(digits=Integer(3)))
0.00
>>> print(zero.str(digits=Integer(3), no_sci=False))
0.00e0
>>> print(zero.str(digits=Integer(3), skip_zeroes=True))
0.

The output always contains a decimal point, except when using scientific notation with exactly one digit:

sage: print((1e1).str(digits=1))
10.
sage: print((1e10).str(digits=1))
1e10
sage: print((1e-1).str(digits=1))
0.1
sage: print((1e-10).str(digits=1))
1e-10
sage: print((-1e1).str(digits=1))
-10.
sage: print((-1e10).str(digits=1))
-1e10
sage: print((-1e-1).str(digits=1))
-0.1
sage: print((-1e-10).str(digits=1))
-1e-10

>>> from sage.all import *
>>> print((RealNumber('1e1')).str(digits=Integer(1)))
10.
>>> print((RealNumber('1e10')).str(digits=Integer(1)))
1e10
>>> print((RealNumber('1e-1')).str(digits=Integer(1)))
0.1
>>> print((RealNumber('1e-10')).str(digits=Integer(1)))
1e-10
>>> print((-RealNumber('1e1')).str(digits=Integer(1)))
-10.
>>> print((-RealNumber('1e10')).str(digits=Integer(1)))
-1e10
>>> print((-RealNumber('1e-1')).str(digits=Integer(1)))
-0.1
>>> print((-RealNumber('1e-10')).str(digits=Integer(1)))
-1e-10
tan()[source]

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(3)
>>> q.tan()
1.73205080756888
>>> q = RR.pi()/Integer(6)
>>> q.tan()
0.577350269189626
tanh()[source]

Return the hyperbolic tangent of self.

EXAMPLES:

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

>>> from sage.all import *
>>> q = RR.pi()/Integer(11)
>>> q.tanh()
0.278079429295850
trunc()[source]

Truncate self.

EXAMPLES:

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

>>> from sage.all import *
>>> (RealNumber('2.99')).trunc()
2
>>> (-RealNumber('0.00')).trunc()
0
>>> (RealNumber('0.00')).trunc()
0
ulp(field=None)[source]

Return 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

>>> from sage.all import *
>>> a = RealNumber('1.0')
>>> a.ulp()
2.22044604925031e-16
>>> (-RealNumber('1.5')).ulp()
2.22044604925031e-16
>>> a + a.ulp() == a
False
>>> a + a.ulp()/Integer(2) == a
True

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

The ulp of zero is the smallest nonzero number:

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

>>> from sage.all import *
>>> a = RR(Integer(0)).ulp()
>>> a
2.38256490488795e-323228497            # 32-bit
8.50969131174084e-1388255822130839284  # 64-bit
>>> a.fp_rank()
1

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

sage: a.ulp() == a
True

>>> from sage.all import *
>>> 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

>>> from sage.all import *
>>> a = RealField(Integer(256)).pi()
>>> a.ulp()
3.454467422037777850154540745120159828446400145774512554009481388067436721265e-77
>>> e = a.ulp(RealField(Integer(64)))
>>> e
3.45446742203777785e-77
>>> parent(e)
Real Field with 64 bits of precision
>>> 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

>>> from sage.all import *
>>> a = RR(infinity)
>>> a.ulp()
+infinity
>>> (-a).ulp()
+infinity
>>> a = RR('nan')
>>> a.ulp()
NaN
>>> parent(RR('nan').ulp(RealField(Integer(42))))
Real Field with 42 bits of precision
y0()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).y0()
0.510375672649745
y1()[source]

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

EXAMPLES:

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).y1()
-0.107032431540938
yn(n)[source]

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

>>> from sage.all import *
>>> R = RealField(Integer(53))
>>> R(Integer(2)).yn(Integer(3))
-1.12778377684043
>>> R(Integer(2)).yn(-Integer(17))
7.09038821729481e12
zeta()[source]

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

>>> from sage.all import *
>>> R = RealField()
>>> R(Integer(2)).zeta()
1.64493406684823
>>> R.pi()**Integer(2)/Integer(6)
1.64493406684823
>>> R(-Integer(2)).zeta()
0.000000000000000
>>> R(Integer(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                                     # needs sage.libs.pari
1.64493406684823
sage: pari(2).zeta(precision=128).sage().prec()                             # needs sage.libs.pari
128
sage: pari(2).zeta(precision=65).sage().prec()                              # needs sage.libs.pari
128                                                # 64-bit
96                                                 # 32-bit

>>> from sage.all import *
>>> z = pari(Integer(2)).zeta(precision=Integer(53)); z                                     # needs sage.libs.pari
1.64493406684823
>>> pari(Integer(2)).zeta(precision=Integer(128)).sage().prec()                             # needs sage.libs.pari
128
>>> pari(Integer(2)).zeta(precision=Integer(65)).sage().prec()                              # needs sage.libs.pari
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)                                                               # needs sage.libs.pari
<class 'cypari2.gen.Gen'>
sage: R(z)                                                                  # needs sage.libs.pari
1.64493406684823

>>> from sage.all import *
>>> type(z)                                                               # needs sage.libs.pari
<class 'cypari2.gen.Gen'>
>>> R(z)                                                                  # needs sage.libs.pari
1.64493406684823
class sage.rings.real_mpfr.ZZtoRR[source]

Bases: Map

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

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 – string that defines a real number (or something whose string representation defines a number)

  • base – integer between 2 and 62

  • pad – nonnegative integer

  • 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

>>> from sage.all import *
>>> RealNumber('2.3') # indirect doctest
2.30000000000000
>>> RealNumber(Integer(10))
10.0000000000000
>>> RealNumber('1.0000000000000000000000000000000000')
1.000000000000000000000000000000000
>>> RealField(Integer(200))(RealNumber('1.2'))
1.2000000000000000000000000000000000000000000000000000000000
>>> (RealNumber('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 'deadbeefxxx' to a 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

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

The rounding mode is respected in all cases:

sage: RealNumber("1.5", rnd="RNDU").parent()
Real Field with 53 bits of precision and rounding RNDU
sage: RealNumber("1.50000000000000000000000000000000000000", rnd="RNDU").parent()
Real Field with 130 bits of precision and rounding RNDU

>>> from sage.all import *
>>> RealNumber("1.5", rnd="RNDU").parent()
Real Field with 53 bits of precision and rounding RNDU
>>> RealNumber("1.50000000000000000000000000000000000000", rnd="RNDU").parent()
Real Field with 130 bits of precision and rounding RNDU
class sage.rings.real_mpfr.double_toRR[source]

Bases: Map

class sage.rings.real_mpfr.int_toRR[source]

Bases: Map

sage.rings.real_mpfr.is_RealNumber(x)[source]

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)
doctest:warning...
DeprecationWarning: The function is_RealNumber is deprecated;
use 'isinstance(..., RealNumber)' instead.
See https://github.com/sagemath/sage/issues/38128 for details.
True
sage: is_RealNumber(float(2.3))
False
sage: is_RealNumber(RDF(2))
False
sage: is_RealNumber(pi)                                                         # needs sage.symbolic
False

>>> from sage.all import *
>>> from sage.rings.real_mpfr import is_RealNumber
>>> is_RealNumber(RealNumber('2.5'))
doctest:warning...
DeprecationWarning: The function is_RealNumber is deprecated;
use 'isinstance(..., RealNumber)' instead.
See https://github.com/sagemath/sage/issues/38128 for details.
True
>>> is_RealNumber(float(RealNumber('2.3')))
False
>>> is_RealNumber(RDF(Integer(2)))
False
>>> is_RealNumber(pi)                                                         # needs sage.symbolic
False
sage.rings.real_mpfr.mpfr_get_exp_max()[source]

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

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_get_exp_max
>>> mpfr_get_exp_max()
1073741823            # 32-bit
4611686018427387903   # 64-bit
>>> RealNumber('0.5') << mpfr_get_exp_max()
1.04928935823369e323228496            # 32-bit
2.93782689455579e1388255822130839282  # 64-bit
>>> RealNumber('0.5') << (mpfr_get_exp_max()+Integer(1))
+infinity
sage.rings.real_mpfr.mpfr_get_exp_max_max()[source]

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

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_get_exp_max_max, mpfr_set_exp_max
>>> 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()

>>> from sage.all import *
>>> mpfr_set_exp_max(mpfr_get_exp_max_max() + Integer(1))
Traceback (most recent call last):
...
OverflowError: bad value for mpfr_set_exp_max()
sage.rings.real_mpfr.mpfr_get_exp_min()[source]

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

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_get_exp_min
>>> mpfr_get_exp_min()
-1073741823            # 32-bit
-4611686018427387903   # 64-bit
>>> RealNumber('0.5') >> (-mpfr_get_exp_min())
2.38256490488795e-323228497            # 32-bit
8.50969131174084e-1388255822130839284  # 64-bit
>>> RealNumber('0.5') >> (-mpfr_get_exp_min()+Integer(1))
0.000000000000000
sage.rings.real_mpfr.mpfr_get_exp_min_min()[source]

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

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_get_exp_min_min, mpfr_set_exp_min
>>> 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()

>>> from sage.all import *
>>> mpfr_set_exp_min(mpfr_get_exp_min_min() - Integer(1))
Traceback (most recent call last):
...
OverflowError: bad value for mpfr_set_exp_min()
sage.rings.real_mpfr.mpfr_prec_max()[source]

Return the mpfr variable MPFR_PREC_MAX.

EXAMPLES:

sage: from sage.rings.real_mpfr import mpfr_prec_max
sage: mpfr_prec_max()
2147483391              # 32-bit
9223372036854775551     # 64-bit

sage: R = RealField(2^31-257); R
Real Field with 2147483391 bits of precision

sage: R = RealField(2^31-256)
Traceback (most recent call last):                     # 32-bit
...                                                    # 32-bit
ValueError: prec (=...) must be >= 1 and <= ...        # 32-bit

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_prec_max
>>> mpfr_prec_max()
2147483391              # 32-bit
9223372036854775551     # 64-bit

>>> R = RealField(Integer(2)**Integer(31)-Integer(257)); R
Real Field with 2147483391 bits of precision

>>> R = RealField(Integer(2)**Integer(31)-Integer(256))
Traceback (most recent call last):                     # 32-bit
...                                                    # 32-bit
ValueError: prec (=...) must be >= 1 and <= ...        # 32-bit
sage.rings.real_mpfr.mpfr_prec_min()[source]

Return the mpfr variable MPFR_PREC_MIN.

EXAMPLES:

sage: from sage.rings.real_mpfr import mpfr_prec_min
sage: mpfr_prec_min()
1
sage: R = RealField(2)
sage: R(2) + R(1)
3.0
sage: R(4) + R(1)
4.0

sage: R = RealField(0)
Traceback (most recent call last):
...
ValueError: prec (=0) must be >= 1 and <= ...

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_prec_min
>>> mpfr_prec_min()
1
>>> R = RealField(Integer(2))
>>> R(Integer(2)) + R(Integer(1))
3.0
>>> R(Integer(4)) + R(Integer(1))
4.0

>>> R = RealField(Integer(0))
Traceback (most recent call last):
...
ValueError: prec (=0) must be >= 1 and <= ...
sage.rings.real_mpfr.mpfr_set_exp_max(e)[source]

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

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_get_exp_max, mpfr_set_exp_max
>>> old = mpfr_get_exp_max()
>>> mpfr_set_exp_max(Integer(1000))
>>> RealNumber('0.5') << Integer(1000)
5.35754303593134e300
>>> RealNumber('0.5') << Integer(1001)
+infinity
>>> mpfr_set_exp_max(old)
>>> RealNumber('0.5') << Integer(1001)
1.07150860718627e301
sage.rings.real_mpfr.mpfr_set_exp_min(e)[source]

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

>>> from sage.all import *
>>> from sage.rings.real_mpfr import mpfr_get_exp_min, mpfr_set_exp_min
>>> old = mpfr_get_exp_min()
>>> mpfr_set_exp_min(-Integer(1000))
>>> RealNumber('0.5') >> Integer(1000)
4.66631809251609e-302
>>> RealNumber('0.5') >> Integer(1001)
0.000000000000000
>>> mpfr_set_exp_min(old)
>>> RealNumber('0.5') >> Integer(1001)
2.33315904625805e-302