### Navigation

- index
- modules |
- next |
- previous |
- Standard Commutative Rings »

# Ring \(\ZZ\) of Integers

Ring \(\ZZ\) of Integers

The `IntegerRing_class` represents the ring \(\ZZ\) of (arbitrary precision) integers. Each integer is an instance of `Integer`, which is defined in a Pyrex extension module that wraps GMP integers (the `mpz_t` type in GMP).

    sage: Z = IntegerRing(); Z
    Integer Ring
    sage: Z.characteristic()
    0
    sage: Z.is_field()
    False

There is a unique instance of the `integer ring`. To create an `Integer`, coerce either a Python int, long, or a string. Various other types will also coerce to the integers, when it makes sense.

    sage: a = Z(1234); b = Z(5678); print a, b
    1234 5678
    sage: type(a)
    <type 'sage.rings.integer.Integer'>
    sage: a + b
    6912
    sage: Z('94803849083985934859834583945394')
    94803849083985934859834583945394

`sage.rings.integer_ring.``IntegerRing`()

  Return the integer ring.

  EXAMPLES:

      sage: IntegerRing()
      Integer Ring
      sage: ZZ==IntegerRing()
      True

class `sage.rings.integer_ring.``IntegerRing_class`

  Bases: `sage.rings.ring.PrincipalIdealDomain`

  The ring of integers.

  In order to introduce the ring \(\ZZ\) of integers, we illustrate creation, calling a few functions, and working with its elements.

      sage: Z = IntegerRing(); Z
      Integer Ring
      sage: Z.characteristic()
      0
      sage: Z.is_field()
      False
      sage: Z.category()
      Join of Category of euclidean domains
          and Category of infinite enumerated sets
      sage: Z(2^(2^5) + 1)
      4294967297

  One can give strings to create integers. Strings starting with `0x` are interpreted as hexadecimal, and strings starting with `0` are interpreted as octal:

      sage: parent('37')
      <type 'str'>
      sage: parent(Z('37'))
      Integer Ring
      sage: Z('0x10')
      16
      sage: Z('0x1a')
      26
      sage: Z('020')
      16

  As an inverse to `digits()`, lists of digits are accepted, provided that you give a base. The lists are interpreted in little-endian order, so that entry `i` of the list is the coefficient of `base^i`:

      sage: Z([4,1,7],base=100)
      70104
      sage: Z([4,1,7],base=10)
      714
      sage: Z([3, 7], 10)
      73
      sage: Z([3, 7], 9)
      66
      sage: Z([], 10)
      0

  Alphanumeric strings can be used for bases 2..36; letters `a` to `z` represent numbers 10 to 36. Letter case does not matter.

      sage: Z("sage",base=32)
      928270
      sage: Z("SAGE",base=32)
      928270
      sage: Z("Sage",base=32)
      928270
      sage: Z([14, 16, 10, 28],base=32)
      928270
      sage: 14 + 16*32 + 10*32^2 + 28*32^3
      928270

  We next illustrate basic arithmetic in \(\ZZ\):

      sage: a = Z(1234); b = Z(5678); print a, b
      1234 5678
      sage: type(a)
      <type 'sage.rings.integer.Integer'>
      sage: a + b
      6912
      sage: b + a
      6912
      sage: a * b
      7006652
      sage: b * a
      7006652
      sage: a - b
      -4444
      sage: b - a
      4444

  When we divide two integers using `/`, the result is automatically coerced to the field of rational numbers, even if the result is an integer.

      sage: a / b
      617/2839
      sage: type(a/b)
      <type 'sage.rings.rational.Rational'>
      sage: a/a
      1
      sage: type(a/a)
      <type 'sage.rings.rational.Rational'>

  For floor division, use the `//` operator instead:

      sage: a // b
      0
      sage: type(a//b)
      <type 'sage.rings.integer.Integer'>

  Next we illustrate arithmetic with automatic coercion. The types that coerce are: str, int, long, Integer.

      sage: a + 17
      1251
      sage: a * 374
      461516
      sage: 374 * a
      461516
      sage: a/19
      1234/19
      sage: 0 + Z(-64)
      -64

  Integers can be coerced:

      sage: a = Z(-64)
      sage: int(a)
      -64

  We can create integers from several types of objects:

      sage: Z(17/1)
      17
      sage: Z(Mod(19,23))
      19
      sage: Z(2 + 3*5 + O(5^3))
      17

  Arbitrary numeric bases are supported; strings or list of integers are used to provide the digits (more details in `IntegerRing_class`):

      sage: Z("sage",base=32)
      928270
      sage: Z([14, 16, 10, 28],base=32)
      928270

  The `digits` method allows you to get the list of digits of an integer in a different basis (note that the digits are returned in little-endian order):

      sage: b = Z([4,1,7],base=100)
      sage: b
      70104
      sage: b.digits(base=71)
      [27, 64, 13]

      sage: Z(15).digits(2)
      [1, 1, 1, 1]
      sage: Z(15).digits(3)
      [0, 2, 1]

  The `str` method returns a string of the digits, using letters `a` to `z` to represent digits 10..36:

      sage: Z(928270).str(base=32)
      'sage'

  Note that `str` only works with bases 2 through 36.

  TESTS:

      sage: TestSuite(ZZ).run()

  `absolute_degree`()

    Return the absolute degree of the integers, which is 1.

    Here, absolute degree refers to the rank of the ring as a module over the integers.

    EXAMPLES:

        sage: ZZ.absolute_degree()
        1

  `characteristic`()

    Return the characteristic of the integers, which is 0.

    EXAMPLES:

        sage: ZZ.characteristic()
        0

  `completion`(p, prec, extras={})

    Return the completion of the integers at the prime \(p\).

    INPUT:

    - `p` – a prime (or `infinity`)
    - `prec` – the desired precision
    - `extras` – any further parameters to pass to the method used to create the completion.

    OUTPUT:

    - The completion of \(\ZZ\) at \(p\).

    EXAMPLES:

        sage: ZZ.completion(infinity, 53)
        Real Field with 53 bits of precision
        sage: ZZ.completion(5, 15, {'print_mode': 'bars'})
        5-adic Ring with capped relative precision 15

  `degree`()

    Return the degree of the integers, which is 1.

    Here, degree refers to the rank of the ring as a module over the integers.

    EXAMPLES:

        sage: ZZ.degree()
        1

  `extension`(poly, names=None, embedding=None)

    Return the order generated by the specified list of polynomials.

    INPUT:

    - `poly` – a list of one or more polynomials
    - `names` – a parameter which will be passed to `EquationOrder()`.
    - `embedding` – a parameter which will be passed to `EquationOrder()`.

    OUTPUT:

    - Given a single polynomial as input, return the order generated by a root of the polynomial in the field generated by a root of the polynomial.

      Given a list of polynomials as input, return the relative order generated by a root of the first polynomial in the list, over the order generated by the roots of the subsequent polynomials.

    EXAMPLES:

        sage: ZZ.extension(x^2-5, 'a')
        Order in Number Field in a with defining polynomial x^2 - 5
        sage: ZZ.extension([x^2 + 1, x^2 + 2], 'a,b')
        Relative Order in Number Field in a with defining polynomial
        x^2 + 1 over its base field

  `fraction_field`()

    Return the field of rational numbers - the fraction field of the integers.

    EXAMPLES:

        sage: ZZ.fraction_field()
        Rational Field
        sage: ZZ.fraction_field() == QQ
        True

  `gen`(n=0)

    Return the additive generator of the integers, which is 1.

    INPUT:

    - `n` (default: 0) – In a ring with more than one generator, the optional parameter \(n\) indicates which generator to return; since there is only one generator in this case, the only valid value for \(n\) is 0.

    EXAMPLES:

        sage: ZZ.gen()
        1
        sage: type(ZZ.gen())
        <type 'sage.rings.integer.Integer'>

  `gens`()

    Return the tuple `(1,)` containing a single element, the additive generator of the integers, which is 1.

    EXAMPLES:

        sage: ZZ.gens(); ZZ.gens()[0]
        (1,)
        1
        sage: type(ZZ.gens()[0])
        <type 'sage.rings.integer.Integer'>

  `is_field`(proof=True)

    Return `False` since the integers are not a field.

    EXAMPLES:

        sage: ZZ.is_field()
        False

  `is_finite`()

    Return `False` since the integers are an infinite ring.

    EXAMPLES:

        sage: ZZ.is_finite()
        False

  `is_integrally_closed`()

    Return that the integer ring is, in fact, integrally closed.

    EXAMPLES:

        sage: ZZ.is_integrally_closed()
        True

  `is_noetherian`()

    Return `True` since the integers are a Noetherian ring.

    EXAMPLES:

        sage: ZZ.is_noetherian()
        True

  `is_subring`(other)

    Return `True` if \(\ZZ\) is a subring of other in a natural way.

    Every ring of characteristic \(0\) contains \(\ZZ\) as a subring.

    EXAMPLES:

        sage: ZZ.is_subring(QQ)
        True

  `krull_dimension`()

    Return the Krull dimension of the integers, which is 1.

    EXAMPLES:

        sage: ZZ.krull_dimension()
        1

  `ngens`()

    Return the number of additive generators of the ring, which is 1.

    EXAMPLES:

        sage: ZZ.ngens()
        1
        sage: len(ZZ.gens())
        1

  `order`()

    Return the order (cardinality) of the integers, which is `+Infinity`.

    EXAMPLES:

        sage: ZZ.order()
        +Infinity

  `parameter`()

    Return an integer of degree 1 for the Euclidean property of \(\ZZ\), namely 1.

    EXAMPLES:

        sage: ZZ.parameter()
        1

  `quotient`(I, names=None)

    Return the quotient of \(\ZZ\) by the ideal or integer `I`.

    EXAMPLES:

        sage: ZZ.quo(6*ZZ)
        Ring of integers modulo 6
        sage: ZZ.quo(0*ZZ)
        Integer Ring
        sage: ZZ.quo(3)
        Ring of integers modulo 3
        sage: ZZ.quo(3*QQ)
        Traceback (most recent call last):
        ...
        TypeError: I must be an ideal of ZZ

  `random_element`(x=None, y=None, distribution=None)

    Return a random integer.

    INPUT:

    - `x`, `y` integers – bounds for the result.

    - `distribution`– a string:
        - `'uniform'`
        - `'mpz_rrandomb'`
        - `'1/n'`
        - `'gaussian'`

    OUTPUT:

    - With no input, return a random integer.

      If only one integer \(x\) is given, return an integer between 0 and \(x-1\).

      If two integers are given, return an integer between \(x\) and \(y-1\) inclusive.

      If at least one bound is given, the default distribution is the uniform distribution; otherwise, it is the distribution described below.

      If the distribution `'1/n'` is specified, the bounds are ignored.

      If the distribution `'mpz_rrandomb'` is specified, the output is in the range from 0 to \(2^x - 1\).

      If the distribution `'gaussian'` is specified, the output is sampled from a discrete Gaussian distribution with parameter \(\sigma=x\) and centered at zero. That is, the integer \(v\) is returned with probability proportional to \(\mathrm{exp}(-v^2/(2\sigma^2))\). See `sage.stats.distributions.discrete_gaussian_integer` for details. Note that if many samples from the same discrete Gaussian distribution are needed, it is faster to construct a `sage.stats.distributions.discrete_gaussian_integer.DiscreteGaussianDistributionIntegerSampler` object which is then repeatedly queried.

    The default distribution for `ZZ.random_element()` is based on \(X = \mbox{trunc}(4/(5R))\), where \(R\) is a random variable uniformly distributed between \(-1\) and \(1\). This gives \(\mbox{Pr}(X = 0) = 1/5\), and \(\mbox{Pr}(X = n) = 2/(5|n|(|n|+1))\) for \(n \neq 0\). Most of the samples will be small; \(-1\), \(0\), and \(1\) occur with probability \(1/5\) each. But we also have a small but non-negligible proportion of “outliers”; \(\mbox{Pr}(|X| \geq n) = 4/(5n)\), so for instance, we expect that \(|X| \geq 1000\) on one in 1250 samples.

    We actually use an easy-to-compute truncation of the above distribution; the probabilities given above hold fairly well up to about \(|n| = 10000\), but around \(|n| = 30000\) some values will never be returned at all, and we will never return anything greater than \(2^{30}\).

    EXAMPLES:

        sage: [ZZ.random_element() for _ in range(10)]
        [-8, 2, 0, 0, 1, -1, 2, 1, -95, -1]

    The default uniform distribution is integers in \([-2, 2]\):

        sage: [ZZ.random_element(distribution="uniform") for _ in range(10)]
        [2, -2, 2, -2, -1, 1, -1, 2, 1, 0]

    Here we use the distribution `'1/n'`:

        sage: [ZZ.random_element(distribution="1/n") for _ in range(10)]
        [-6, 1, -1, 1, 1, -1, 1, -1, -3, 1]

    If a range is given, the default distribution is uniform in that range:

        sage: ZZ.random_element(-10,10)
        -2
        sage: ZZ.random_element(10)
        2
        sage: ZZ.random_element(10^50)
        9531604786291536727294723328622110901973365898988
        sage: [ZZ.random_element(5) for _ in range(10)]
        [3, 1, 2, 3, 0, 0, 3, 4, 0, 3]

    Notice that the right endpoint is not included:

        sage: [ZZ.random_element(-2,2) for _ in range(10)]
        [1, -2, -2, -1, -2, -1, -1, -2, 0, -2]

    We compute a histogram over 1000 samples of the default distribution:

        sage: from collections import defaultdict
        sage: d = defaultdict(lambda: 0)
        sage: for _ in range(1000):
        ...       samp = ZZ.random_element()
        ...       d[samp] = d[samp] + 1

        sage: sorted(d.items())
        [(-1955, 1), (-1026, 1), (-357, 1), (-248, 1), (-145, 1), (-81, 1), (-80, 1), (-79, 1), (-75, 1), (-69, 1), (-68, 1), (-63, 2), (-61, 1), (-57, 1), (-50, 1), (-37, 1), (-35, 1), (-33, 1), (-29, 2), (-27, 1), (-25, 1), (-23, 2), (-22, 3), (-20, 1), (-19, 1), (-18, 1), (-16, 4), (-15, 3), (-14, 1), (-13, 2), (-12, 2), (-11, 2), (-10, 7), (-9, 3), (-8, 3), (-7, 7), (-6, 8), (-5, 13), (-4, 24), (-3, 34), (-2, 75), (-1, 206), (0, 208), (1, 189), (2, 63), (3, 35), (4, 13), (5, 11), (6, 10), (7, 4), (8, 3), (10, 1), (11, 1), (12, 1), (13, 1), (14, 1), (16, 3), (18, 2), (19, 1), (26, 2), (27, 1), (28, 2), (29, 1), (30, 1), (32, 1), (33, 2), (35, 1), (37, 1), (39, 1), (41, 1), (42, 1), (52, 1), (91, 1), (94, 1), (106, 1), (111, 1), (113, 2), (132, 1), (134, 1), (232, 1), (240, 1), (2133, 1), (3636, 1)]

    We return a sample from a discrete Gaussian distribution:

        sage: ZZ.random_element(11.0, distribution="gaussian")
        5

  `range`(start, end=None, step=None)

    Optimized range function for Sage integers.

    AUTHORS:

    - Robert Bradshaw (2007-09-20)

    EXAMPLES:

        sage: ZZ.range(10)
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
        sage: ZZ.range(-5,5)
        [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4]
        sage: ZZ.range(0,50,5)
        [0, 5, 10, 15, 20, 25, 30, 35, 40, 45]
        sage: ZZ.range(0,50,-5)
        []
        sage: ZZ.range(50,0,-5)
        [50, 45, 40, 35, 30, 25, 20, 15, 10, 5]
        sage: ZZ.range(50,0,5)
        []
        sage: ZZ.range(50,-1,-5)
        [50, 45, 40, 35, 30, 25, 20, 15, 10, 5, 0]

    It uses different code if the step doesn’t fit in a long:

        sage: ZZ.range(0,2^83,2^80)
        [0, 1208925819614629174706176, 2417851639229258349412352, 3626777458843887524118528, 4835703278458516698824704, 6044629098073145873530880, 7253554917687775048237056, 8462480737302404222943232]

    Make sure trac ticket #8818 is fixed:

        sage: ZZ.range(1r, 10r)
        [1, 2, 3, 4, 5, 6, 7, 8, 9]

  `residue_field`(prime, check=True)

    Return the residue field of the integers modulo the given prime, i.e. \(\ZZ/p\ZZ\).

    INPUT:

    - `prime` - a prime number
    - `check` - (boolean, default `True`) whether or not to check the primality of prime.

    OUTPUT: The residue field at this prime.

    EXAMPLES:

        sage: F = ZZ.residue_field(61); F
        Residue field of Integers modulo 61
        sage: pi = F.reduction_map(); pi
        Partially defined reduction map:
          From: Rational Field
          To:   Residue field of Integers modulo 61
        sage: pi(123/234)
        6
        sage: pi(1/61)
        Traceback (most recent call last):
        ...
        ZeroDivisionError: Cannot reduce rational 1/61 modulo 61:
        it has negative valuation
        sage: lift = F.lift_map(); lift
        Lifting map:
          From: Residue field of Integers modulo 61
          To:   Integer Ring
        sage: lift(F(12345/67890))
        33
        sage: (12345/67890) % 61
        33

    Construction can be from a prime ideal instead of a prime:

        sage: ZZ.residue_field(ZZ.ideal(97))
        Residue field of Integers modulo 97

    TESTS:

        sage: ZZ.residue_field(ZZ.ideal(96))
        Traceback (most recent call last):
        ...
        TypeError: Principal ideal (96) of Integer Ring is not prime
        sage: ZZ.residue_field(96)
        Traceback (most recent call last):
        ...
        TypeError: 96 is not prime

  `zeta`(n=2)

    Return a primitive `n`-th root of unity in the integers, or raise an error if none exists.

    INPUT:

    - `n` – (default 2) a positive integer

    OUTPUT:

    - an `n`-th root of unity in \(\ZZ\).

    EXAMPLE:

        sage: ZZ.zeta()
        -1
        sage: ZZ.zeta(1)
        1
        sage: ZZ.zeta(3)
        Traceback (most recent call last):
        ...
        ValueError: no nth root of unity in integer ring
        sage: ZZ.zeta(0)
        Traceback (most recent call last):
        ...
        ValueError: n must be positive in zeta()

`sage.rings.integer_ring.``crt_basis`(X, xgcd=None)

  Compute and return a Chinese Remainder Theorem basis for the list `X` of coprime integers.

  INPUT:

  - `X` – a list of Integers that are coprime in pairs.
  - `xgcd` – an optional parameter which is ignored.

  OUTPUT:

  - `E` - a list of Integers such that `E[i] = 1` (mod `X[i]`) and `E[i] = 0` (mod `X[j]`) for all \(j \neq i\).

  For this explanation, let `E[i]` be denoted by \(E_i\).

  The \(E_i\) have the property that if \(A\) is a list of objects, e.g., integers, vectors, matrices, etc., where \(A_i\) is understood modulo \(X_i\), then a CRT lift of \(A\) is simply

  \[\sum_i E_i A_i.\]

  ALGORITHM: To compute \(E_i\), compute integers \(s\) and \(t\) such that

  \[s X_i + t \prod_{i \neq j} X_j = 1. (\*)\]

  Then

  \[E_i = t \prod_{i \neq j} X[j].\]

  Notice that equation (*) implies that \(E_i\) is congruent to 1 modulo \(X_i\) and to 0 modulo the other \(X_j\) for \(j \neq i\).

  COMPLEXITY: We compute `len(X)` extended GCD’s.

  EXAMPLES:

      sage: X = [11,20,31,51]
      sage: E = crt_basis([11,20,31,51])
      sage: E[0]%X[0], E[1]%X[0], E[2]%X[0], E[3]%X[0]
      (1, 0, 0, 0)
      sage: E[0]%X[1], E[1]%X[1], E[2]%X[1], E[3]%X[1]
      (0, 1, 0, 0)
      sage: E[0]%X[2], E[1]%X[2], E[2]%X[2], E[3]%X[2]
      (0, 0, 1, 0)
      sage: E[0]%X[3], E[1]%X[3], E[2]%X[3], E[3]%X[3]
      (0, 0, 0, 1)

`sage.rings.integer_ring.``is_IntegerRing`(x)

  Internal function: return `True` iff `x` is the ring \(\ZZ\) of integers.

  TESTS:

      sage: from sage.rings.integer_ring import is_IntegerRing
      sage: is_IntegerRing(ZZ)
      True
      sage: is_IntegerRing(QQ)
      False
      sage: is_IntegerRing(parent(3))
      True
      sage: is_IntegerRing(parent(1/3))
      False

### Navigation

- index
- modules |
- next |
- previous |
- Standard Commutative Rings »