Rational Numbers#

AUTHORS:

  • William Stein (2005): first version

  • William Stein (2006-02-22): floor and ceil (pure fast GMP versions).

  • Gonzalo Tornaria and William Stein (2006-03-02): greatly improved python/GMP conversion; hashing

  • William Stein and Naqi Jaffery (2006-03-06): height, sqrt examples, and improve behavior of sqrt.

  • David Harvey (2006-09-15): added nth_root

  • Pablo De Napoli (2007-04-01): corrected the implementations of multiplicative_order, is_one; optimized __bool__ ; documented: lcm,gcd

  • John Cremona (2009-05-15): added support for local and global logarithmic heights.

  • Travis Scrimshaw (2012-10-18): Added doctests for full coverage.

  • Vincent Delecroix (2013): continued fraction

  • Vincent Delecroix (2017-05-03): faster integer-rational comparison

  • Vincent Klein (2017-05-11): add __mpq__() to class Rational

  • Vincent Klein (2017-05-22): Rational constructor support gmpy2.mpq or gmpy2.mpz parameter. Add __mpz__ to class Rational.

class sage.rings.rational.Q_to_Z#

Bases: Map

A morphism from \(\QQ\) to \(\ZZ\).

section()#

Return a section of this morphism.

EXAMPLES:

sage: sage.rings.rational.Q_to_Z(QQ, ZZ).section()
Natural morphism:
  From: Integer Ring
  To:   Rational Field
class sage.rings.rational.Rational#

Bases: FieldElement

A rational number.

Rational numbers are implemented using the GMP C library.

EXAMPLES:

sage: a = -2/3
sage: type(a)
<class 'sage.rings.rational.Rational'>
sage: parent(a)
Rational Field
sage: Rational('1/0')
Traceback (most recent call last):
...
TypeError: unable to convert '1/0' to a rational
sage: Rational(1.5)
3/2
sage: Rational('9/6')
3/2
sage: Rational((2^99,2^100))
1/2
sage: Rational(("2", "10"), 16)
1/8
sage: Rational(QQbar(125/8).nth_root(3))                                        # needs sage.rings.number_field
5/2
sage: Rational(AA(209735/343 - 17910/49*golden_ratio).nth_root(3)               # needs sage.rings.number_field sage.symbolic
....:          + 3*AA(golden_ratio))
53/7
sage: QQ(float(1.5))
3/2
sage: QQ(RDF(1.2))
6/5

Conversion from fractions:

sage: import fractions
sage: f = fractions.Fraction(1r, 2r)
sage: Rational(f)
1/2

Conversion from PARI:

sage: Rational(pari('-939082/3992923'))                                         # needs sage.libs.pari
-939082/3992923
sage: Rational(pari('Pol([-1/2])'))  #9595                                      # needs sage.libs.pari
-1/2

Conversions from numpy:

sage: # needs numpy
sage: import numpy as np
sage: QQ(np.int8('-15'))
-15
sage: QQ(np.int16('-32'))
-32
sage: QQ(np.int32('-19'))
-19
sage: QQ(np.uint32('1412'))
1412

sage: QQ(np.float16('12'))                                                      # needs numpy
12

Conversions from gmpy2:

sage: from gmpy2 import *
sage: QQ(mpq('3/4'))
3/4
sage: QQ(mpz(42))
42
sage: Rational(mpq(2/3))
2/3
sage: Rational(mpz(5))
5
absolute_norm()#

Return the norm from Q to Q of x (which is just x). This was added for compatibility with NumberFields

EXAMPLES:

sage: (6/5).absolute_norm()
6/5

sage: QQ(7/5).absolute_norm()
7/5
additive_order()#

Return the additive order of self.

OUTPUT: integer or infinity

EXAMPLES:

sage: QQ(0).additive_order()
1
sage: QQ(1).additive_order()
+Infinity
as_integer_ratio()#

Return the pair (self.numerator(), self.denominator()).

EXAMPLES:

sage: x = -12/29
sage: x.as_integer_ratio()
(-12, 29)
ceil()#

Return the ceiling of this rational number.

OUTPUT: Integer

If this rational number is an integer, this returns this number, otherwise it returns the floor of this number +1.

EXAMPLES:

sage: n = 5/3; n.ceil()
2
sage: n = -17/19; n.ceil()
0
sage: n = -7/2; n.ceil()
-3
sage: n = 7/2; n.ceil()
4
sage: n = 10/2; n.ceil()
5
charpoly(var='x')#

Return the characteristic polynomial of this rational number. This will always be just var - self; this is really here so that code written for number fields won’t crash when applied to rational numbers.

INPUT:

  • var - a string

OUTPUT: Polynomial

EXAMPLES:

sage: (1/3).charpoly('x')
 x - 1/3

The default is var='x'. (github issue #20967):

sage: a = QQ(2); a.charpoly('x')
x - 2

AUTHORS:

  • Craig Citro

conjugate()#

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

EXAMPLES:

sage: n = 23/11
sage: n.conjugate()
23/11
content(other)#

Return the content of self and other, i.e., the unique positive rational number \(c\) such that self/c and other/c are coprime integers.

other can be a rational number or a list of rational numbers.

EXAMPLES:

sage: a = 2/3
sage: a.content(2/3)
2/3
sage: a.content(1/5)
1/15
sage: a.content([2/5, 4/9])
2/45
continued_fraction()#

Return the continued fraction of that rational.

EXAMPLES:

sage: (641/472).continued_fraction()
[1; 2, 1, 3, 1, 4, 1, 5]

sage: a = (355/113).continued_fraction(); a
[3; 7, 16]
sage: a.n(digits=10)                                                        # needs sage.rings.real_mpfr
3.141592920
sage: pi.n(digits=10)                                                       # needs sage.rings.real_mpfr sage.symbolic
3.141592654

It’s almost pi!

continued_fraction_list(type='std')#

Return the list of partial quotients of this rational number.

INPUT:

  • type - either “std” (the default) for the standard continued fractions or “hj” for the Hirzebruch-Jung ones.

EXAMPLES:

sage: (13/9).continued_fraction_list()
[1, 2, 4]
sage: 1 + 1/(2 + 1/4)
13/9

sage: (225/157).continued_fraction_list()
[1, 2, 3, 4,  5]
sage: 1 + 1/(2 + 1/(3 + 1/(4 + 1/5)))
225/157

sage: (fibonacci(20)/fibonacci(19)).continued_fraction_list()               # needs sage.libs.pari
[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2]

sage: (-1/3).continued_fraction_list()
[-1, 1, 2]

Check that the partial quotients of an integer n is simply [n]:

sage: QQ(1).continued_fraction_list()
[1]
sage: QQ(0).continued_fraction_list()
[0]
sage: QQ(-1).continued_fraction_list()
[-1]

Hirzebruch-Jung continued fractions:

sage: (11/19).continued_fraction_list("hj")
[1, 3, 2, 3, 2]
sage: 1 - 1/(3 - 1/(2 - 1/(3 - 1/2)))
11/19

sage: (225/137).continued_fraction_list("hj")
[2, 3, 5, 10]
sage: 2 - 1/(3 - 1/(5 - 1/10))
225/137

sage: (-23/19).continued_fraction_list("hj")
[-1, 5, 4]
sage: -1 - 1/(5 - 1/4)
-23/19
denom()#

Return the denominator of this rational number. denom() is an alias of denominator().

EXAMPLES:

sage: x = -5/11
sage: x.denominator()
11

sage: x = 9/3
sage: x.denominator()
1

sage: x = 5/13
sage: x.denom()
13
denominator()#

Return the denominator of this rational number. denom() is an alias of denominator().

EXAMPLES:

sage: x = -5/11
sage: x.denominator()
11

sage: x = 9/3
sage: x.denominator()
1

sage: x = 5/13
sage: x.denom()
13
factor()#

Return the factorization of this rational number.

OUTPUT: Factorization

EXAMPLES:

sage: (-4/17).factor()
-1 * 2^2 * 17^-1

Trying to factor 0 gives an arithmetic error:

sage: (0/1).factor()
Traceback (most recent call last):
...
ArithmeticError: factorization of 0 is not defined
floor()#

Return the floor of this rational number as an integer.

OUTPUT: Integer

EXAMPLES:

sage: n = 5/3; n.floor()
1
sage: n = -17/19; n.floor()
-1
sage: n = -7/2; n.floor()
-4
sage: n = 7/2; n.floor()
3
sage: n = 10/2; n.floor()
5
gamma(prec=None)#

Return the gamma function evaluated at self. This value is exact for integers and half-integers, and returns a symbolic value otherwise. For a numerical approximation, use keyword prec.

EXAMPLES:

sage: # needs sage.symbolic
sage: gamma(1/2)
sqrt(pi)
sage: gamma(7/2)
15/8*sqrt(pi)
sage: gamma(-3/2)
4/3*sqrt(pi)
sage: gamma(6/1)
120
sage: gamma(1/3)
gamma(1/3)

This function accepts an optional precision argument:

sage: (1/3).gamma(prec=100)                                                 # needs sage.rings.real_mpfr
2.6789385347077476336556929410
sage: (1/2).gamma(prec=100)                                                 # needs sage.rings.real_mpfr
1.7724538509055160272981674833
global_height(prec=None)#

Return the absolute logarithmic height of this rational number.

INPUT:

  • prec (int) – desired floating point precision (default: default RealField precision).

OUTPUT:

(real) The absolute logarithmic height of this rational number.

ALGORITHM:

The height is the sum of the total archimedean and non-archimedean components, which is equal to \(\max(\log(n),\log(d))\) where \(n,d\) are the numerator and denominator of the rational number.

EXAMPLES:

sage: # needs sage.rings.real_mpfr
sage: a = QQ(6/25)
sage: a.global_height_arch() + a.global_height_non_arch()
3.21887582486820
sage: a.global_height()
3.21887582486820
sage: (1/a).global_height()
3.21887582486820
sage: QQ(0).global_height()
0.000000000000000
sage: QQ(1).global_height()
0.000000000000000
global_height_arch(prec=None)#

Return the total archimedean component of the height of this rational number.

INPUT:

  • prec (int) – desired floating point precision (default: default RealField precision).

OUTPUT:

(real) The total archimedean component of the height of this rational number.

ALGORITHM:

Since \(\QQ\) has only one infinite place this is just the value of the local height at that place. This separate function is included for compatibility with number fields.

EXAMPLES:

sage: a = QQ(6/25)
sage: a.global_height_arch()                                                # needs sage.rings.real_mpfr
0.000000000000000
sage: (1/a).global_height_arch()                                            # needs sage.rings.real_mpfr
1.42711635564015
sage: (1/a).global_height_arch(100)                                         # needs sage.rings.real_mpfr
1.4271163556401457483890413081
global_height_non_arch(prec=None)#

Return the total non-archimedean component of the height of this rational number.

INPUT:

  • prec (int) – desired floating point precision (default: default RealField precision).

OUTPUT:

(real) The total non-archimedean component of the height of this rational number.

ALGORITHM:

This is the sum of the local heights at all primes \(p\), which may be computed without factorization as the log of the denominator.

EXAMPLES:

sage: a = QQ(5/6)
sage: a.support()
[2, 3, 5]
sage: a.global_height_non_arch()                                            # needs sage.rings.real_mpfr
1.79175946922805
sage: [a.local_height(p) for p in a.support()]                              # needs sage.rings.real_mpfr
[0.693147180559945, 1.09861228866811, 0.000000000000000]
sage: sum([a.local_height(p) for p in a.support()])                         # needs sage.rings.real_mpfr
1.79175946922805
height()#

The max absolute value of the numerator and denominator of self, as an Integer.

OUTPUT: Integer

EXAMPLES:

sage: a = 2/3
sage: a.height()
3
sage: a = 34/3
sage: a.height()
34
sage: a = -97/4
sage: a.height()
97

AUTHORS:

  • Naqi Jaffery (2006-03-05): examples

Note

For the logarithmic height, use global_height().

imag()#

Return the imaginary part of self, which is zero.

EXAMPLES:

sage: (1/239).imag()
0
is_S_integral(S=[])#

Determine if the rational number is S-integral.

x is S-integral if x.valuation(p)>=0 for all p not in S, i.e., the denominator of x is divisible only by the primes in S.

INPUT:

  • S – list or tuple of primes.

OUTPUT: bool

Note

Primality of the entries in S is not checked.

EXAMPLES:

sage: QQ(1/2).is_S_integral()
False
sage: QQ(1/2).is_S_integral([2])
True
sage: [a for a in range(1,11) if QQ(101/a).is_S_integral([2,5])]
[1, 2, 4, 5, 8, 10]
is_S_unit(S=None)#

Determine if the rational number is an S-unit.

x is an S-unit if x.valuation(p)==0 for all p not in S, i.e., the numerator and denominator of x are divisible only by the primes in \(S\).

INPUT:

  • S – list or tuple of primes.

OUTPUT: bool

Note

Primality of the entries in S is not checked.

EXAMPLES:

sage: QQ(1/2).is_S_unit()
False
sage: QQ(1/2).is_S_unit([2])
True
sage: [a for a in range(1,11) if QQ(10/a).is_S_unit([2,5])]
[1, 2, 4, 5, 8, 10]
is_integer()#

Determine if a rational number is integral (i.e., is in \(\ZZ\)).

OUTPUT: bool

EXAMPLES:

sage: QQ(1/2).is_integral()
False
sage: QQ(4/4).is_integral()
True
is_integral()#

Determine if a rational number is integral (i.e., is in \(\ZZ\)).

OUTPUT: bool

EXAMPLES:

sage: QQ(1/2).is_integral()
False
sage: QQ(4/4).is_integral()
True
is_norm(L, element=False, proof=True)#

Determine whether self is the norm of an element of L.

INPUT:

  • L – a number field

  • element – (default: False) boolean whether to also output an element of which self is a norm

  • proof – If True, then the output is correct unconditionally. If False, then the output assumes GRH.

OUTPUT:

If element is False, then the output is a boolean B, which is True if and only if self is the norm of an element of L. If element is False, then the output is a pair (B, x), where B is as above. If B is True, then x an element of L such that self == x.norm(). Otherwise, x is None.

ALGORITHM:

Uses the PARI function pari:bnfisnorm. See _bnfisnorm().

EXAMPLES:

sage: # needs sage.rings.number_field
sage: x = polygen(QQ, 'x')
sage: K = NumberField(x^2 - 2, 'beta')
sage: (1/7).is_norm(K)
True
sage: (1/10).is_norm(K)
False
sage: 0.is_norm(K)
True
sage: (1/7).is_norm(K, element=True)
(True, 1/7*beta + 3/7)
sage: (1/10).is_norm(K, element=True)
(False, None)
sage: (1/691).is_norm(QQ, element=True)
(True, 1/691)

The number field doesn’t have to be defined by an integral polynomial:

sage: B, e = (1/5).is_norm(QuadraticField(5/4, 'a'), element=True)          # needs sage.rings.number_field
sage: B                                                                     # needs sage.rings.number_field
True
sage: e.norm()                                                              # needs sage.rings.number_field
1/5

A non-Galois number field:

sage: # needs sage.rings.number_field
sage: K.<a> = NumberField(x^3 - 2)
sage: B, e = (3/5).is_norm(K, element=True); B
True
sage: e.norm()
3/5
sage: 7.is_norm(K)                                                          # needs sage.groups
Traceback (most recent call last):
...
NotImplementedError: is_norm is not implemented unconditionally
 for norms from non-Galois number fields
sage: 7.is_norm(K, proof=False)
False

AUTHORS:

  • Craig Citro (2008-04-05)

  • Marco Streng (2010-12-03)

is_nth_power(n)#

Return True if self is an \(n\)-th power, else False.

INPUT:

  • n - integer (must fit in C int type)

Note

Use this function when you need to test if a rational number is an \(n\)-th power, but do not need to know the value of its \(n\)-th root. If the value is needed, use nth_root().

AUTHORS:

  • John Cremona (2009-04-04)

EXAMPLES:

sage: QQ(25/4).is_nth_power(2)
True
sage: QQ(125/8).is_nth_power(3)
True
sage: QQ(-125/8).is_nth_power(3)
True
sage: QQ(25/4).is_nth_power(-2)
True

sage: QQ(9/2).is_nth_power(2)
False
sage: QQ(-25).is_nth_power(2)
False
is_one()#

Determine if a rational number is one.

OUTPUT: bool

EXAMPLES:

sage: QQ(1/2).is_one()
False
sage: QQ(4/4).is_one()
True
is_padic_square(p, check=True)#

Determines whether this rational number is a square in \(\QQ_p\) (or in \(R\) when p = infinity).

INPUT:

  • p - a prime number, or infinity

  • check – (default: True); check if \(p\) is prime

EXAMPLES:

sage: QQ(2).is_padic_square(7)
True
sage: QQ(98).is_padic_square(7)
True
sage: QQ(2).is_padic_square(5)
False
is_perfect_power(expected_value=False)#

Return True if self is a perfect power.

INPUT:

  • expected_value - (bool) whether or not this rational is expected be a perfect power. This does not affect the correctness of the output, only the runtime.

If expected_value is False (default) it will check the smallest of the numerator and denominator is a perfect power as a first step, which is often faster than checking if the quotient is a perfect power.

EXAMPLES:

sage: (4/9).is_perfect_power()
True
sage: (144/1).is_perfect_power()
True
sage: (4/3).is_perfect_power()
False
sage: (2/27).is_perfect_power()
False
sage: (4/27).is_perfect_power()
False
sage: (-1/25).is_perfect_power()
False
sage: (-1/27).is_perfect_power()
True
sage: (0/1).is_perfect_power()
True

The second parameter does not change the result, but may change the runtime.

sage: (-1/27).is_perfect_power(True)
True
sage: (-1/25).is_perfect_power(True)
False
sage: (2/27).is_perfect_power(True)
False
sage: (144/1).is_perfect_power(True)
True

This test makes sure we workaround a bug in GMP (see github issue #4612):

sage: [-a for a in srange(100) if not QQ(-a^3).is_perfect_power()]
[]
sage: [-a for a in srange(100) if not QQ(-a^3).is_perfect_power(True)]
[]
is_rational()#

Return True since this is a rational number.

EXAMPLES:

sage: (3/4).is_rational()
True
is_square()#

Return whether or not this rational number is a square.

OUTPUT: bool

EXAMPLES:

sage: x = 9/4
sage: x.is_square()
True
sage: x = (7/53)^100
sage: x.is_square()
True
sage: x = 4/3
sage: x.is_square()
False
sage: x = -1/4
sage: x.is_square()
False
list()#

Return a list with the rational element in it, to be compatible with the method for number fields.

OUTPUT:

  • list - the list [self]

EXAMPLES:

sage: m = 5/3
sage: m.list()
[5/3]
local_height(p, prec=None)#

Return the local height of this rational number at the prime \(p\).

INPUT:

  • p – a prime number

  • prec (int) – desired floating point precision (default: default RealField precision).

OUTPUT:

(real) The local height of this rational number at the prime \(p\).

EXAMPLES:

sage: a = QQ(25/6)
sage: a.local_height(2)                                                     # needs sage.rings.real_mpfr
0.693147180559945
sage: a.local_height(3)                                                     # needs sage.rings.real_mpfr
1.09861228866811
sage: a.local_height(5)                                                     # needs sage.rings.real_mpfr
0.000000000000000
local_height_arch(prec=None)#

Return the Archimedean local height of this rational number at the infinite place.

INPUT:

  • prec (int) – desired floating point precision (default: default RealField precision).

OUTPUT:

(real) The local height of this rational number \(x\) at the unique infinite place of \(\QQ\), which is \(\max(\log(|x|),0)\).

EXAMPLES:

sage: a = QQ(6/25)
sage: a.local_height_arch()                                                 # needs sage.rings.real_mpfr
0.000000000000000
sage: (1/a).local_height_arch()                                             # needs sage.rings.real_mpfr
1.42711635564015
sage: (1/a).local_height_arch(100)                                          # needs sage.rings.real_mpfr
1.4271163556401457483890413081
log(m=None, prec=None)#

Return the log of self.

INPUT:

  • m – the base (default: natural log base e)

  • prec – integer (optional); the precision in bits

OUTPUT:

When prec is not given, the log as an element in symbolic ring unless the logarithm is exact. Otherwise the log is a RealField approximation to prec bit precision.

EXAMPLES:

sage: (124/345).log(5)                                                      # needs sage.symbolic
log(124/345)/log(5)
sage: (124/345).log(5, 100)                                                 # needs sage.rings.real_mpfr
-0.63578895682825611710391773754
sage: log(QQ(125))                                                          # needs sage.symbolic
3*log(5)
sage: log(QQ(125), 5)
3
sage: log(QQ(125), 3)                                                       # needs sage.symbolic
3*log(5)/log(3)
sage: QQ(8).log(1/2)
-3
sage: (1/8).log(1/2)
3
sage: (1/2).log(1/8)
1/3
sage: (1/2).log(8)
-1/3
sage: (16/81).log(8/27)                                                     # needs sage.libs.pari
4/3
sage: (8/27).log(16/81)                                                     # needs sage.libs.pari
3/4
sage: log(27/8, 16/81)                                                      # needs sage.libs.pari
-3/4
sage: log(16/81, 27/8)                                                      # needs sage.libs.pari
-4/3
sage: (125/8).log(5/2)                                                      # needs sage.libs.pari
3
sage: (125/8).log(5/2, prec=53)                                             # needs sage.rings.real_mpfr
3.00000000000000
minpoly(var='x')#

Return the minimal polynomial of this rational number. This will always be just x - self; this is really here so that code written for number fields won’t crash when applied to rational numbers.

INPUT:

  • var - a string

OUTPUT: Polynomial

EXAMPLES:

sage: (1/3).minpoly()
x - 1/3
sage: (1/3).minpoly('y')
y - 1/3

AUTHORS:

  • Craig Citro

mod_ui(n)#

Return the remainder upon division of self by the unsigned long integer n.

INPUT:

  • n - an unsigned long integer

OUTPUT: integer

EXAMPLES:

sage: (-4/17).mod_ui(3)
1
sage: (-4/17).mod_ui(17)
Traceback (most recent call last):
...
ArithmeticError: The inverse of 0 modulo 17 is not defined.
multiplicative_order()#

Return the multiplicative order of self.

OUTPUT: Integer or infinity

EXAMPLES:

sage: QQ(1).multiplicative_order()
1
sage: QQ('1/-1').multiplicative_order()
2
sage: QQ(0).multiplicative_order()
+Infinity
sage: QQ('2/3').multiplicative_order()
+Infinity
sage: QQ('1/2').multiplicative_order()
+Infinity
norm()#

Return the norm from \(\QQ\) to \(\QQ\) of \(x\) (which is just \(x\)). This was added for compatibility with NumberField.

OUTPUT:

  • Rational - reference to self

EXAMPLES:

sage: (1/3).norm()
 1/3

AUTHORS:

  • Craig Citro

nth_root(n)#

Computes the \(n\)-th root of self, or raises a ValueError if self is not a perfect \(n\)-th power.

INPUT:

  • n - integer (must fit in C int type)

AUTHORS:

  • David Harvey (2006-09-15)

EXAMPLES:

sage: (25/4).nth_root(2)
5/2
sage: (125/8).nth_root(3)
5/2
sage: (-125/8).nth_root(3)
-5/2
sage: (25/4).nth_root(-2)
2/5

sage: (9/2).nth_root(2)
Traceback (most recent call last):
...
ValueError: not a perfect 2nd power

sage: (-25/4).nth_root(2)
Traceback (most recent call last):
...
ValueError: cannot take even root of negative number
numer()#

Return the numerator of this rational number. numer() is an alias of numerator().

EXAMPLES:

sage: x = 5/11
sage: x.numerator()
5

sage: x = 9/3
sage: x.numerator()
3

sage: x = -5/11
sage: x.numer()
-5
numerator()#

Return the numerator of this rational number. numer() is an alias of numerator().

EXAMPLES:

sage: x = 5/11
sage: x.numerator()
5

sage: x = 9/3
sage: x.numerator()
3

sage: x = -5/11
sage: x.numer()
-5
ord(p)#

Return the power of p in the factorization of self.

INPUT:

  • p - a prime number

OUTPUT:

(integer or infinity) Infinity if self is zero, otherwise the (positive or negative) integer \(e\) such that self = \(m*p^e\) with \(m\) coprime to \(p\).

Note

See also val_unit() which returns the pair \((e,m)\). The function ord() is an alias for valuation().

EXAMPLES:

sage: x = -5/9
sage: x.valuation(5)
1
sage: x.ord(5)
1
sage: x.valuation(3)
-2
sage: x.valuation(2)
0

Some edge cases:

sage: (0/1).valuation(4)
+Infinity
sage: (7/16).valuation(4)
-2
period()#

Return the period of the repeating part of the decimal expansion of this rational number.

ALGORITHM:

When a rational number \(n/d\) with \((n,d)=1\) is expanded, the period begins after \(s\) terms and has length \(t\), where \(s\) and \(t\) are the smallest numbers satisfying \(10^s=10^{s+t} \mod d\). In general if \(d=2^a 5^b m\) where \(m\) is coprime to 10, then \(s=\max(a,b)\) and \(t\) is the order of 10 modulo \(m\).

EXAMPLES:

sage: (1/7).period()                                                        # needs sage.libs.pari
6
sage: RR(1/7)                                                               # needs sage.rings.real_mpfr
0.142857142857143
sage: (1/8).period()                                                        # needs sage.libs.pari
1
sage: RR(1/8)                                                               # needs sage.rings.real_mpfr
0.125000000000000
sage: RR(1/6)                                                               # needs sage.rings.real_mpfr
0.166666666666667
sage: (1/6).period()                                                        # needs sage.libs.pari
1
sage: x = 333/106
sage: x.period()                                                            # needs sage.libs.pari
13
sage: RealField(200)(x)                                                     # needs sage.rings.real_mpfr
3.1415094339622641509433962264150943396226415094339622641509
prime_to_S_part(S=[])#

Return self with all powers of all primes in S removed.

INPUT:

  • S - list or tuple of primes.

OUTPUT: rational

Note

Primality of the entries in \(S\) is not checked.

EXAMPLES:

sage: QQ(3/4).prime_to_S_part()
3/4
sage: QQ(3/4).prime_to_S_part([2])
3
sage: QQ(-3/4).prime_to_S_part([3])
-1/4
sage: QQ(700/99).prime_to_S_part([2,3,5])
7/11
sage: QQ(-700/99).prime_to_S_part([2,3,5])
-7/11
sage: QQ(0).prime_to_S_part([2,3,5])
0
sage: QQ(-700/99).prime_to_S_part([])
-700/99
real()#

Return the real part of self, which is self.

EXAMPLES:

sage: (1/2).real()
1/2
relative_norm()#

Return the norm from Q to Q of x (which is just x). This was added for compatibility with NumberFields

EXAMPLES:

sage: (6/5).relative_norm()
6/5

sage: QQ(7/5).relative_norm()
7/5
round(mode=None)#

Return the nearest integer to self, rounding away by default. Deprecation: in the future the default will be changed to rounding to even, for consistency with the builtin Python round().

INPUT:

  • self - a rational number

  • mode - a rounding mode for half integers:

    • ‘toward’ rounds toward zero

    • ‘away’ (default) rounds away from zero

    • ‘up’ rounds up

    • ‘down’ rounds down

    • ‘even’ rounds toward the even integer

    • ‘odd’ rounds toward the odd integer

OUTPUT: Integer

EXAMPLES:

sage: (9/2).round()
doctest:...: DeprecationWarning: the default rounding for rationals, currently `away`, will be changed to `even`.
See https://github.com/sagemath/sage/issues/35473 for details.
5
sage: n = 4/3; n.round()
1
sage: n = -17/4; n.round()
-4
sage: n = -5/2; n.round()
-3
sage: n.round("away")
-3
sage: n.round("up")
-2
sage: n.round("down")
-3
sage: n.round("even")
-2
sage: n.round("odd")
-3
sign()#

Return the sign of this rational number, which is -1, 0, or 1 depending on whether this number is negative, zero, or positive respectively.

OUTPUT: Integer

EXAMPLES:

sage: (2/3).sign()
1
sage: (0/3).sign()
0
sage: (-1/6).sign()
-1
sqrt(prec=None, extend=True, all=False)#

The square root function.

INPUT:

  • prec – integer (default: None): if None, returns an exact square root; otherwise returns a numerical square root if necessary, to the given bits of precision.

  • extend – bool (default: True); if True, return a square root in an extension ring, if necessary. Otherwise, raise a ValueError if the square is not in the base ring. Ignored if prec is not None.

  • all – bool (default: False); if True, return all square roots of self (a list of length 0, 1, or 2).

EXAMPLES:

sage: x = 25/9
sage: x.sqrt()
5/3
sage: sqrt(x)
5/3
sage: x = 64/4
sage: x.sqrt()
4
sage: x = 100/1
sage: x.sqrt()
10
sage: x.sqrt(all=True)
[10, -10]
sage: x = 81/5
sage: x.sqrt()                                                              # needs sage.symbolic
9*sqrt(1/5)
sage: x = -81/3
sage: x.sqrt()                                                              # needs sage.symbolic
3*sqrt(-3)

sage: n = 2/3
sage: n.sqrt()                                                              # needs sage.symbolic
sqrt(2/3)

sage: # needs sage.rings.real_mpfr
sage: n.sqrt(prec=10)
0.82
sage: n.sqrt(prec=100)
0.81649658092772603273242802490
sage: n.sqrt(prec=100)^2
0.66666666666666666666666666667
sage: n.sqrt(prec=53, all=True)
[0.816496580927726, -0.816496580927726]
sage: sqrt(-2/3, prec=53)
0.816496580927726*I
sage: sqrt(-2/3, prec=53, all=True)
[0.816496580927726*I, -0.816496580927726*I]

sage: n.sqrt(extend=False)
Traceback (most recent call last):
...
ValueError: square root of 2/3 not a rational number
sage: n.sqrt(extend=False, all=True)
[]
sage: sqrt(-2/3, all=True)                                                  # needs sage.symbolic
[sqrt(-2/3), -sqrt(-2/3)]

AUTHORS:

  • Naqi Jaffery (2006-03-05): some examples

squarefree_part()#

Return the square free part of \(x\), i.e., an integer \(z\) such that \(x = z y^2\), for a perfect square \(y^2\).

EXAMPLES:

sage: a = 1/2
sage: a.squarefree_part()
2
sage: b = a/a.squarefree_part()
sage: b, b.is_square()
(1/4, True)
sage: a = 24/5
sage: a.squarefree_part()
30
str(base=10)#

Return a string representation of self in the given base.

INPUT:

  • base – integer (default: 10); base must be between 2 and 36.

OUTPUT: string

EXAMPLES:

sage: (-4/17).str()
'-4/17'
sage: (-4/17).str(2)
'-100/10001'

Note that the base must be at most 36.

sage: (-4/17).str(40)
Traceback (most recent call last):
...
ValueError: base (=40) must be between 2 and 36
sage: (-4/17).str(1)
Traceback (most recent call last):
...
ValueError: base (=1) must be between 2 and 36
support()#

Return a sorted list of the primes where this rational number has non-zero valuation.

OUTPUT: The set of primes appearing in the factorization of this rational with nonzero exponent, as a sorted list.

EXAMPLES:

sage: (-4/17).support()
[2, 17]

Trying to find the support of 0 gives an arithmetic error:

sage: (0/1).support()
Traceback (most recent call last):
...
ArithmeticError: Support of 0 not defined.
trace()#

Return the trace from \(\QQ\) to \(\QQ\) of \(x\) (which is just \(x\)). This was added for compatibility with NumberFields.

OUTPUT:

  • Rational - reference to self

EXAMPLES:

sage: (1/3).trace()
 1/3

AUTHORS:

  • Craig Citro

trunc()#

Round this rational number to the nearest integer toward zero.

EXAMPLES:

sage: (5/3).trunc()
1
sage: (-5/3).trunc()
-1
sage: QQ(42).trunc()
42
sage: QQ(-42).trunc()
-42
val_unit(p)#

Return a pair: the \(p\)-adic valuation of self, and the \(p\)-adic unit of self, as a Rational.

We do not require the \(p\) be prime, but it must be at least 2. For more documentation see Integer.val_unit().

INPUT:

  • p - a prime

OUTPUT:

  • int - the \(p\)-adic valuation of this rational

  • Rational - \(p\)-adic unit part of self

EXAMPLES:

sage: (-4/17).val_unit(2)
(2, -1/17)
sage: (-4/17).val_unit(17)
(-1, -4)
sage: (0/1).val_unit(17)
(+Infinity, 1)

AUTHORS:

  • David Roe (2007-04-12)

valuation(p)#

Return the power of p in the factorization of self.

INPUT:

  • p - a prime number

OUTPUT:

(integer or infinity) Infinity if self is zero, otherwise the (positive or negative) integer \(e\) such that self = \(m*p^e\) with \(m\) coprime to \(p\).

Note

See also val_unit() which returns the pair \((e,m)\). The function ord() is an alias for valuation().

EXAMPLES:

sage: x = -5/9
sage: x.valuation(5)
1
sage: x.ord(5)
1
sage: x.valuation(3)
-2
sage: x.valuation(2)
0

Some edge cases:

sage: (0/1).valuation(4)
+Infinity
sage: (7/16).valuation(4)
-2
class sage.rings.rational.Z_to_Q#

Bases: Morphism

A morphism from \(\ZZ\) to \(\QQ\).

is_surjective()#

Return whether this morphism is surjective.

EXAMPLES:

sage: QQ.coerce_map_from(ZZ).is_surjective()
False
section()#

Return a section of this morphism.

EXAMPLES:

sage: f = QQ.coerce_map_from(ZZ).section(); f
Generic map:
  From: Rational Field
  To:   Integer Ring

This map is a morphism in the category of sets with partial maps (see github issue #15618):

sage: f.parent()
Set of Morphisms from Rational Field to Integer Ring
 in Category of sets with partial maps
class sage.rings.rational.int_to_Q#

Bases: Morphism

A morphism from Python 3 int to \(\QQ\).

sage.rings.rational.integer_rational_power(a, b)#

Compute \(a^b\) as an integer, if it is integral, or return None.

The nonnegative real root is taken for even denominators.

INPUT:

  • a – an Integer

  • b – a nonnegative Rational

OUTPUT:

\(a^b\) as an Integer or None

EXAMPLES:

sage: from sage.rings.rational import integer_rational_power
sage: integer_rational_power(49, 1/2)
7
sage: integer_rational_power(27, 1/3)
3
sage: integer_rational_power(-27, 1/3) is None
True
sage: integer_rational_power(-27, 2/3) is None
True
sage: integer_rational_power(512, 7/9)
128

sage: integer_rational_power(27, 1/4) is None
True
sage: integer_rational_power(-16, 1/4) is None
True

sage: integer_rational_power(0, 7/9)
0
sage: integer_rational_power(1, 7/9)
1
sage: integer_rational_power(-1, 7/9) is None
True
sage: integer_rational_power(-1, 8/9) is None
True
sage: integer_rational_power(-1, 9/8) is None
True

TESTS (github issue #11228):

sage: integer_rational_power(-10, QQ(2))
100
sage: integer_rational_power(0, QQ(0))
1
sage.rings.rational.is_Rational(x)#

Return True if x is of the Sage Rational type.

EXAMPLES:

sage: from sage.rings.rational import is_Rational
sage: is_Rational(2)
False
sage: is_Rational(2/1)
True
sage: is_Rational(int(2))
False
sage: is_Rational('5')
False
sage.rings.rational.make_rational(s)#

Make a rational number from s (a string in base 32)

INPUT:

  • s - string in base 32

OUTPUT: Rational

EXAMPLES:

sage: (-7/15).str(32)
'-7/f'
sage: sage.rings.rational.make_rational('-7/f')
-7/15
sage.rings.rational.rational_power_parts(a, b, factor_limit=100000)#

Compute rationals or integers \(c\) and \(d\) such that \(a^b = c*d^b\) with \(d\) small. This is used for simplifying radicals.

INPUT:

  • a – a rational or integer

  • b – a rational

  • factor_limit – the limit used in factoring a

EXAMPLES:

sage: from sage.rings.rational import rational_power_parts
sage: rational_power_parts(27, 1/2)
(3, 3)
sage: rational_power_parts(-128, 3/4)
(8, -8)
sage: rational_power_parts(-4, 1/2)
(2, -1)
sage: rational_power_parts(-4, 1/3)
(1, -4)
sage: rational_power_parts(9/1000, 1/2)
(3/10, 1/10)