### Navigation

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

# Elements of \(\ZZ/n\ZZ\)

Elements of \(\ZZ/n\ZZ\)

An element of the integers modulo \(n\).

There are three types of integer_mod classes, depending on the size of the modulus.

- `IntegerMod_int` stores its value in a `int_fast32_t` (typically an `int`); this is used if the modulus is less than \(\sqrt{2^{31}-1}\).
- `IntegerMod_int64` stores its value in a `int_fast64_t` (typically a `long long`); this is used if the modulus is less than \(2^{31}-1\).
- `IntegerMod_gmp` stores its value in a `mpz_t`; this can be used for an arbitrarily large modulus.

All extend `IntegerMod_abstract`.

For efficiency reasons, it stores the modulus (in all three forms, if possible) in a common (cdef) class `NativeIntStruct` rather than in the parent.

AUTHORS:

- Robert Bradshaw: most of the work
- Didier Deshommes: bit shifting
- William Stein: editing and polishing; new arith architecture
- Robert Bradshaw: implement native is_square and square_root
- William Stein: sqrt
- Maarten Derickx: moved the valuation code from the global valuation function to here

TESTS:

    sage: R = Integers(101^3)
    sage: a = R(824362); b = R(205942)
    sage: a * b
    851127

    sage: type(IntegerModRing(2^31-1).an_element())
    <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int64'>
    sage: type(IntegerModRing(2^31).an_element())
    <type 'sage.rings.finite_rings.integer_mod.IntegerMod_gmp'>

class `sage.rings.finite_rings.integer_mod.``Int_to_IntegerMod`

  Bases: `sage.rings.finite_rings.integer_mod.IntegerMod_hom`

  EXAMPLES:

  We make sure it works for every type.

      sage: from sage.rings.finite_rings.integer_mod import Int_to_IntegerMod
      sage: Rs = [Integers(2**k) for k in range(1,50,10)]
      sage: [type(R(0)) for R in Rs]
      [<type 'sage.rings.finite_rings.integer_mod.IntegerMod_int'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int64'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_gmp'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_gmp'>]
      sage: fs = [Int_to_IntegerMod(R) for R in Rs]
      sage: [f(-1) for f in fs]
      [1, 2047, 2097151, 2147483647, 2199023255551]

`sage.rings.finite_rings.integer_mod.``IntegerMod`(parent, value)

  Create an integer modulo \(n\) with the given parent.

  This is mainly for internal use.

class `sage.rings.finite_rings.integer_mod.``IntegerMod_abstract`

  Bases: `sage.rings.finite_rings.element_base.FiniteRingElement`

  EXAMPLES:

      sage: a = Mod(10,30^10); a
      10
      sage: loads(a.dumps()) == a
      True

  `additive_order`()

    Returns the additive order of self.

    This is the same as `self.order()`.

    EXAMPLES:

        sage: Integers(20)(2).additive_order()
        10
        sage: Integers(20)(7).additive_order()
        20
        sage: Integers(90308402384902)(2).additive_order()
        45154201192451

  `centerlift`()

    Lift `self` to an integer \(i\) such that \(n/2 < i <= n/2\) (where \(n\) denotes the modulus).

    EXAMPLES:

        sage: Mod(0,5).centerlift()
        0
        sage: Mod(1,5).centerlift()
        1
        sage: Mod(2,5).centerlift()
        2
        sage: Mod(3,5).centerlift()
        -2
        sage: Mod(4,5).centerlift()
        -1
        sage: Mod(50,100).centerlift()
        50
        sage: Mod(51,100).centerlift()
        -49
        sage: Mod(-1,3^100).centerlift()
        -1

  `charpoly`(var='x')

    Returns the characteristic polynomial of this element.

    EXAMPLES:

        sage: k = GF(3)
        sage: a = k.gen()
        sage: a.charpoly('x')
        x + 2
        sage: a + 2
        0

    AUTHORS:

    - Craig Citro
  `crt`(other)

    Use the Chinese Remainder Theorem to find an element of the integers modulo the product of the moduli that reduces to `self` and to `other`. The modulus of `other` must be coprime to the modulus of `self`.

    EXAMPLES:

        sage: a = mod(3,5)
        sage: b = mod(2,7)
        sage: a.crt(b)
        23

        sage: a = mod(37,10^8)
        sage: b = mod(9,3^8)
        sage: a.crt(b)
        125900000037

        sage: b = mod(0,1)
        sage: a.crt(b) == a
        True
        sage: a.crt(b).modulus()
        100000000

    TESTS:

        sage: mod(0,1).crt(mod(4,2^127))
        4
        sage: mod(4,2^127).crt(mod(0,1))
        4
        sage: mod(4,2^30).crt(mod(0,1))
        4
        sage: mod(0,1).crt(mod(4,2^30))
        4
        sage: mod(0,1).crt(mod(4,2^15))
        4
        sage: mod(4,2^15).crt(mod(0,1))
        4

    AUTHORS:

    - Robert Bradshaw
  `generalised_log`()

    Return integers \(n_i\) such that

    ..math:

        \prod_i x_i^{n_i} = \text{self},

    where \(x_1, \dots, x_d\) are the generators of the unit group returned by `self.parent().unit_gens()`. See also `log()`.

    EXAMPLES:

        sage: m = Mod(3, 1568)
        sage: v = m.generalised_log(); v
        [1, 3, 1]
        sage: prod([Zmod(1568).unit_gens()[i] ** v[i] for i in [0..2]])
        3

  `is_nilpotent`()

    Return `True` if `self` is nilpotent, i.e., some power of `self` is zero.

    EXAMPLES:

        sage: a = Integers(90384098234^3)
        sage: factor(a.order())
        2^3 * 191^3 * 236607587^3
        sage: b = a(2*191)
        sage: b.is_nilpotent()
        False
        sage: b = a(2*191*236607587)
        sage: b.is_nilpotent()
        True

    ALGORITHM: Let \(m \geq \log_2(n)\), where \(n\) is the modulus. Then \(x \in \ZZ/n\ZZ\) is nilpotent if and only if \(x^m = 0\).

    PROOF: This is clear if you reduce to the prime power case, which you can do via the Chinese Remainder Theorem.

    We could alternatively factor \(n\) and check to see if the prime divisors of \(n\) all divide \(x\). This is asymptotically slower :-).

  `is_one`()
  `is_primitive_root`()

    Determines whether this element generates the group of units modulo n.

    This is only possible if the group of units is cyclic, which occurs if n is 2, 4, a power of an odd prime or twice a power of an odd prime.

    EXAMPLES:

        sage: mod(1,2).is_primitive_root()
        True
        sage: mod(3,4).is_primitive_root()
        True
        sage: mod(2,7).is_primitive_root()
        False
        sage: mod(3,98).is_primitive_root()
        True
        sage: mod(11,1009^2).is_primitive_root()
        True

    TESTS:

        sage: for p in prime_range(3,12):
        ...     for k in range(1,4):
        ...         for even in [1,2]:
        ...             n = even*p^k
        ...             phin = euler_phi(n)
        ...             for _ in range(6):
        ...                 a = Zmod(n).random_element()
        ...                 if not a.is_unit(): continue
        ...                 if a.is_primitive_root().__xor__(a.multiplicative_order()==phin):
        ...                     print "mod(%s,%s) incorrect"%(a,n)

  `is_square`()

    EXAMPLES:

        sage: Mod(3,17).is_square()
        False
        sage: Mod(9,17).is_square()
        True
        sage: Mod(9,17*19^2).is_square()
        True
        sage: Mod(-1,17^30).is_square()
        True
        sage: Mod(1/9, next_prime(2^40)).is_square()
        True
        sage: Mod(1/25, next_prime(2^90)).is_square()
        True

    TESTS:

        sage: Mod(1/25, 2^8).is_square()
        True
        sage: Mod(1/25, 2^40).is_square()
        True

        sage: for p,q,r in cartesian_product_iterator([[3,5],[11,13],[17,19]]): # long time
        ....:     for ep,eq,er in cartesian_product_iterator([[0,1,2,3],[0,1,2,3],[0,1,2,3]]):
        ....:         for e2 in [0, 1, 2, 3, 4]:
        ....:             n = p^ep * q^eq * r^er * 2^e2
        ....:             for _ in range(2):
        ....:                 a = Zmod(n).random_element()
        ....:                 if a.is_square().__xor__(a._pari_().issquare()):
        ....:                     print a, n

    ALGORITHM: Calculate the Jacobi symbol \((\mathtt{self}/p)\) at each prime \(p\) dividing \(n\). It must be 1 or 0 for each prime, and if it is 0 mod \(p\), where \(p^k || n\), then \(ord_p(\mathtt{self})\) must be even or greater than \(k\).

    The case \(p = 2\) is handled separately.

    AUTHORS:

    - Robert Bradshaw
  `is_unit`()
  `log`(b=None)

    Return an integer \(x\) such that \(b^x = a\), where \(a\) is `self`.

    INPUT:

    - `self` - unit modulo \(n\)
    - `b` - a unit modulo \(n\). If `b` is not given, `R.multiplicative_generator()` is used, where `R` is the parent of `self`.

    OUTPUT: Integer \(x\) such that \(b^x = a\), if this exists; a ValueError otherwise.

    Note

    If the modulus is prime and b is a generator, this calls Pari’s `znlog` function, which is rather fast. If not, it falls back on the generic discrete log implementation in `sage.groups.generic.discrete_log()`.

    EXAMPLES:

        sage: r = Integers(125)
        sage: b = r.multiplicative_generator()^3
        sage: a = b^17
        sage: a.log(b)
        17
        sage: a.log()
        51

    A bigger example:

        sage: FF = FiniteField(2^32+61)
        sage: c = FF(4294967356)
        sage: x = FF(2)
        sage: a = c.log(x)
        sage: a
        2147483678
        sage: x^a
        4294967356

    Things that can go wrong. E.g., if the base is not a generator for the multiplicative group, or not even a unit.

        sage: Mod(3, 7).log(Mod(2, 7))
        Traceback (most recent call last):
        ...
        ValueError: No discrete log of 3 found to base 2
        sage: a = Mod(16, 100); b = Mod(4,100)
        sage: a.log(b)
        Traceback (most recent call last):
        ...
        ZeroDivisionError: Inverse does not exist.

    We check that #9205 is fixed:

        sage: Mod(5,9).log(Mod(2, 9))
        5

    We test against a bug (side effect on PARI) fixed in #9438:

        sage: R.<a, b> = QQ[]
        sage: pari(b)
        b
        sage: GF(7)(5).log()
        5
        sage: pari(b)
        b

    AUTHORS:

    - David Joyner and William Stein (2005-11)
    - William Stein (2007-01-27): update to use PARI as requested by David Kohel.
    - Simon King (2010-07-07): fix a side effect on PARI
  `minimal_polynomial`(var='x')

    Returns the minimal polynomial of this element.

    EXAMPLES:
      sage: GF(241, ‘a’)(1).minimal_polynomial(var = ‘z’) z + 240
  `minpoly`(var='x')

    Returns the minimal polynomial of this element.

    EXAMPLES:
      sage: GF(241, ‘a’)(1).minpoly() x + 240
  `modulus`()

    EXAMPLES:

        sage: Mod(3,17).modulus()
        17

  `multiplicative_order`()

    Returns the multiplicative order of self.

    EXAMPLES:

        sage: Mod(-1,5).multiplicative_order()
        2
        sage: Mod(1,5).multiplicative_order()
        1
        sage: Mod(0,5).multiplicative_order()
        Traceback (most recent call last):
        ...
        ArithmeticError: multiplicative order of 0 not defined since it is not a unit modulo 5

  `norm`()

    Returns the norm of this element, which is itself. (This is here for compatibility with higher order finite fields.)

    EXAMPLES:

        sage: k = GF(691)
        sage: a = k(389)
        sage: a.norm()
        389

    AUTHORS:

    - Craig Citro
  `nth_root`(n, extend=False, all=False, algorithm=None, cunningham=False)

    Returns an \(n\)th root of `self`.

    INPUT:

    - `n` - integer \(\geq 1\)
    - `extend` - bool (default: True); if True, return an nth root in an extension ring, if necessary. Otherwise, raise a ValueError if the root is not in the base ring. Warning: this option is not implemented!
    - `all` - bool (default: `False`); if `True`, return all \(n\)th roots of `self`, instead of just one.
    - `algorithm` - string (default: None); The algorithm for the prime modulus case. CRT and p-adic log techniques are used to reduce to this case. ‘Johnston’ is the only currently supported option.
    - `cunningham` - bool (default: `False`); In some cases, factorization of `n` is computed. If cunningham is set to `True`, the factorization of `n` is computed using trial division for all primes in the so called Cunningham table. Refer to sage.rings.factorint.factor_cunningham for more information. You need to install an optional package to use this method, this can be done with the following command line `sage -i cunningham_tables`

    OUTPUT:

    If self has an \(n\)th root, returns one (if `all` is `False`) or a list of all of them (if `all` is `True`). Otherwise, raises a `ValueError` (if `extend` is `False`) or a `NotImplementedError` (if `extend` is `True`).

    Warning

    The ‘extend’ option is not implemented (yet).

    NOTES:

    - If \(n = 0\):
      - if `all=True`:
        - if `self=1`: all nonzero elements of the parent are returned in a list. Note that this could be very expensive for large parents.
        - otherwise: an empty list is returned
      - if `all=False`:
        - if `self=1`: `self` is returned
        - otherwise; a `ValueError` is raised
    - If \(n < 0\):
      - if self is invertible, the \((-n)\)th root of the inverse of self is returned
      - otherwise a `ValueError` is raised or empty list returned.

    EXAMPLES:

        sage: K = GF(31)
        sage: a = K(22)
        sage: K(22).nth_root(7)
        13
        sage: K(25).nth_root(5)
        5
        sage: K(23).nth_root(3)
        29
        sage: mod(225,2^5*3^2).nth_root(4, all=True)
        [225, 129, 33, 63, 255, 159, 9, 201, 105, 279, 183, 87, 81, 273, 177, 207, 111, 15, 153, 57, 249, 135, 39, 231]
        sage: mod(275,2^5*7^4).nth_root(7, all=True)
        [58235, 25307, 69211, 36283, 3355, 47259, 14331]
        sage: mod(1,8).nth_root(2,all=True)
        [1, 7, 5, 3]
        sage: mod(4,8).nth_root(2,all=True)
        [2, 6]
        sage: mod(1,16).nth_root(4,all=True)
        [1, 15, 13, 3, 9, 7, 5, 11]
        sage: (mod(22,31)^200).nth_root(200)
        5
        sage: mod(3,6).nth_root(0,all=True)
        []
        sage: mod(3,6).nth_root(0)
        Traceback (most recent call last):
        ...
        ValueError
        sage: mod(1,6).nth_root(0,all=True)
        [1, 2, 3, 4, 5]

    TESTS:

        sage: for p in [1009,2003,10007,100003]:
        ...       K = GF(p)
        ...       for r in (p-1).divisors():
        ...           if r == 1: continue
        ...           x = K.random_element()
        ...           y = x^r
        ...           if y.nth_root(r)**r != y: raise RuntimeError
        ...           if (y^41).nth_root(41*r)**(41*r) != y^41: raise RuntimeError
        ...           if (y^307).nth_root(307*r)**(307*r) != y^307: raise RuntimeError

        sage: for t in xrange(200):
        ...       n = randint(1,2^63)
        ...       K = Integers(n)
        ...       b = K.random_element()
        ...       e = randint(-2^62, 2^63)
        ...       try:
        ...           a = b.nth_root(e)
        ...           if a^e != b:
        ...               print n, b, e, a
        ...               raise NotImplementedError
        ...       except ValueError:
        ...           pass

    We check that #13172 is resolved:

        sage: mod(-1, 4489).nth_root(2, all=True)
        []

    Check that the code path cunningham might be used:

        sage: a = Mod(9,11)
        sage: a.nth_root(2, False, True, 'Johnston', cunningham = True) # optional - cunningham
        [3, 8]

    ALGORITHMS:

    - The default for prime modulus is currently an algorithm described in the following paper:

    Johnston, Anna M. A generalized qth root algorithm. Proceedings of the tenth annual ACM-SIAM symposium on Discrete algorithms. Baltimore, 1999: pp 929-930.

    AUTHORS:

    - David Roe (2010-2-13)
  `polynomial`(var='x')

    Returns a constant polynomial representing this value.

    EXAMPLES:

        sage: k = GF(7)
        sage: a = k.gen(); a
        1
        sage: a.polynomial()
        1
        sage: type(a.polynomial())
        <type 'sage.rings.polynomial.polynomial_zmod_flint.Polynomial_zmod_flint'>

  `rational_reconstruction`()

    Use rational reconstruction to try to find a lift of this element to the rational numbers.

    EXAMPLES:

        sage: R = IntegerModRing(97)
        sage: a = R(2) / R(3)
        sage: a
        33
        sage: a.rational_reconstruction()
        2/3

    This method is also inherited by prime finite fields elements:

        sage: k = GF(97)
        sage: a = k(RationalField()('2/3'))
        sage: a
        33
        sage: a.rational_reconstruction()
        2/3

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

    Returns square root or square roots of `self` modulo \(n\).

    INPUT:

    - `extend` - bool (default: `True`); if `True`, return a square root in an extension ring, if necessary. Otherwise, raise a `ValueError` if the square root is not in the base ring.
    - `all` - bool (default: `False`); if `True`, return {all} square roots of self, instead of just one.

    ALGORITHM: Calculates the square roots mod \(p\) for each of the primes \(p\) dividing the order of the ring, then lifts them \(p\)-adically and uses the CRT to find a square root mod \(n\).

    See also `square_root_mod_prime_power` and `square_root_mod_prime` (in this module) for more algorithmic details.

    EXAMPLES:

        sage: mod(-1, 17).sqrt()
        4
        sage: mod(5, 389).sqrt()
        86
        sage: mod(7, 18).sqrt()
        5
        sage: a = mod(14, 5^60).sqrt()
        sage: a*a
        14
        sage: mod(15, 389).sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: self must be a square
        sage: Mod(1/9, next_prime(2^40)).sqrt()^(-2)
        9
        sage: Mod(1/25, next_prime(2^90)).sqrt()^(-2)
        25

        sage: a = Mod(3,5); a
        3
        sage: x = Mod(-1, 360)
        sage: x.sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: self must be a square
        sage: y = x.sqrt(); y
        sqrt359
        sage: y.parent()
        Univariate Quotient Polynomial Ring in sqrt359 over Ring of integers modulo 360 with modulus x^2 + 1
        sage: y^2
        359

    We compute all square roots in several cases:

        sage: R = Integers(5*2^3*3^2); R
        Ring of integers modulo 360
        sage: R(40).sqrt(all=True)
        [20, 160, 200, 340]
        sage: [x for x in R if x^2 == 40]  # Brute force verification
        [20, 160, 200, 340]
        sage: R(1).sqrt(all=True)
        [1, 19, 71, 89, 91, 109, 161, 179, 181, 199, 251, 269, 271, 289, 341, 359]
        sage: R(0).sqrt(all=True)
        [0, 60, 120, 180, 240, 300]

        sage: R = Integers(5*13^3*37); R
        Ring of integers modulo 406445
        sage: v = R(-1).sqrt(all=True); v
        [78853, 111808, 160142, 193097, 213348, 246303, 294637, 327592]
        sage: [x^2 for x in v]
        [406444, 406444, 406444, 406444, 406444, 406444, 406444, 406444]
        sage: v = R(169).sqrt(all=True); min(v), -max(v), len(v)
        (13, 13, 104)
        sage: all([x^2==169 for x in v])
        True

        sage: t = FiniteField(next_prime(2^100))(4)
        sage: t.sqrt(extend = False, all = True)
        [2, 1267650600228229401496703205651]
        sage: t = FiniteField(next_prime(2^100))(2)
        sage: t.sqrt(extend = False, all = True)
        []

    Modulo a power of 2:

        sage: R = Integers(2^7); R
        Ring of integers modulo 128
        sage: a = R(17)
        sage: a.sqrt()
        23
        sage: a.sqrt(all=True)
        [23, 41, 87, 105]
        sage: [x for x in R if x^2==17]
        [23, 41, 87, 105]

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

    Returns square root or square roots of `self` modulo \(n\).

    INPUT:

    - `extend` - bool (default: `True`); if `True`, return a square root in an extension ring, if necessary. Otherwise, raise a `ValueError` if the square root is not in the base ring.
    - `all` - bool (default: `False`); if `True`, return {all} square roots of self, instead of just one.

    ALGORITHM: Calculates the square roots mod \(p\) for each of the primes \(p\) dividing the order of the ring, then lifts them \(p\)-adically and uses the CRT to find a square root mod \(n\).

    See also `square_root_mod_prime_power` and `square_root_mod_prime` (in this module) for more algorithmic details.

    EXAMPLES:

        sage: mod(-1, 17).sqrt()
        4
        sage: mod(5, 389).sqrt()
        86
        sage: mod(7, 18).sqrt()
        5
        sage: a = mod(14, 5^60).sqrt()
        sage: a*a
        14
        sage: mod(15, 389).sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: self must be a square
        sage: Mod(1/9, next_prime(2^40)).sqrt()^(-2)
        9
        sage: Mod(1/25, next_prime(2^90)).sqrt()^(-2)
        25

        sage: a = Mod(3,5); a
        3
        sage: x = Mod(-1, 360)
        sage: x.sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: self must be a square
        sage: y = x.sqrt(); y
        sqrt359
        sage: y.parent()
        Univariate Quotient Polynomial Ring in sqrt359 over Ring of integers modulo 360 with modulus x^2 + 1
        sage: y^2
        359

    We compute all square roots in several cases:

        sage: R = Integers(5*2^3*3^2); R
        Ring of integers modulo 360
        sage: R(40).sqrt(all=True)
        [20, 160, 200, 340]
        sage: [x for x in R if x^2 == 40]  # Brute force verification
        [20, 160, 200, 340]
        sage: R(1).sqrt(all=True)
        [1, 19, 71, 89, 91, 109, 161, 179, 181, 199, 251, 269, 271, 289, 341, 359]
        sage: R(0).sqrt(all=True)
        [0, 60, 120, 180, 240, 300]

        sage: R = Integers(5*13^3*37); R
        Ring of integers modulo 406445
        sage: v = R(-1).sqrt(all=True); v
        [78853, 111808, 160142, 193097, 213348, 246303, 294637, 327592]
        sage: [x^2 for x in v]
        [406444, 406444, 406444, 406444, 406444, 406444, 406444, 406444]
        sage: v = R(169).sqrt(all=True); min(v), -max(v), len(v)
        (13, 13, 104)
        sage: all([x^2==169 for x in v])
        True

        sage: t = FiniteField(next_prime(2^100))(4)
        sage: t.sqrt(extend = False, all = True)
        [2, 1267650600228229401496703205651]
        sage: t = FiniteField(next_prime(2^100))(2)
        sage: t.sqrt(extend = False, all = True)
        []

    Modulo a power of 2:

        sage: R = Integers(2^7); R
        Ring of integers modulo 128
        sage: a = R(17)
        sage: a.sqrt()
        23
        sage: a.sqrt(all=True)
        [23, 41, 87, 105]
        sage: [x for x in R if x^2==17]
        [23, 41, 87, 105]

  `trace`()

    Returns the trace of this element, which is itself. (This is here for compatibility with higher order finite fields.)

    EXAMPLES:

        sage: k = GF(691)
        sage: a = k(389)
        sage: a.trace()
        389

    AUTHORS:

    - Craig Citro
  `valuation`(p)

    The largest power r such that m is in the ideal generated by p^r or infinity if there is not a largest such power. However it is an error to take the valuation with respect to a unit.

    Note

    This is not a valuation in the mathematical sense. As shown with the examples below.

    EXAMPLES:

    This example shows that the (a*b).valuation(n) is not always the same as a.valuation(n) + b.valuation(n)

        sage: R=ZZ.quo(9)
        sage: a=R(3)
        sage: b=R(6)
        sage: a.valuation(3)
        1
        sage: a.valuation(3) + b.valuation(3)
        2
        sage: (a*b).valuation(3)
        +Infinity

    The valuation with respect to a unit is an error

        sage: a.valuation(4)
        Traceback (most recent call last):
        ...
        ValueError: Valuation with respect to a unit is not defined.

    TESTS:

        sage: R=ZZ.quo(12)
        sage: a=R(2)
        sage: b=R(4)
        sage: a.valuation(2)
        1
        sage: b.valuation(2)
        +Infinity
        sage: ZZ.quo(1024)(16).valuation(4)
        2

class `sage.rings.finite_rings.integer_mod.``IntegerMod_gmp`

  Bases: `sage.rings.finite_rings.integer_mod.IntegerMod_abstract`

  Elements of \(\ZZ/n\ZZ\) for n not small enough to be operated on in word size.

  AUTHORS:

  - Robert Bradshaw (2006-08-24)
  `gcd`(other)

    Greatest common divisor

    Returns the “smallest” generator in \(\ZZ / N\ZZ\) of the ideal generated by `self` and `other`.

    INPUT:

    - `other` – an element of the same ring as this one.

    EXAMPLES:

        sage: mod(2^3*3^2*5, 3^3*2^2*17^8).gcd(mod(2^4*3*17, 3^3*2^2*17^8))
        12
        sage: mod(0,17^8).gcd(mod(0,17^8))
        0

  `is_one`()

    Returns `True` if this is \(1\), otherwise `False`.

    EXAMPLES:

        sage: mod(1,5^23).is_one()
        True
        sage: mod(0,5^23).is_one()
        False

  `is_unit`()

    Return True iff this element is a unit.

    EXAMPLES:

        sage: mod(13, 5^23).is_unit()
        True
        sage: mod(25, 5^23).is_unit()
        False

  `lift`()

    Lift an integer modulo \(n\) to the integers.

    EXAMPLES:

        sage: a = Mod(8943, 2^70); type(a)
        <type 'sage.rings.finite_rings.integer_mod.IntegerMod_gmp'>
        sage: lift(a)
        8943
        sage: a.lift()
        8943

class `sage.rings.finite_rings.integer_mod.``IntegerMod_hom`

  Bases: `sage.categories.morphism.Morphism`

class `sage.rings.finite_rings.integer_mod.``IntegerMod_int`

  Bases: `sage.rings.finite_rings.integer_mod.IntegerMod_abstract`

  Elements of \(\ZZ/n\ZZ\) for n small enough to be operated on in 32 bits

  AUTHORS:

  - Robert Bradshaw (2006-08-24)
  `gcd`(other)

    Greatest common divisor

    Returns the “smallest” generator in \(\ZZ / N\ZZ\) of the ideal generated by `self` and `other`.

    INPUT:

    - `other` – an element of the same ring as this one.

    EXAMPLES:

        sage: R = Zmod(60); S = Zmod(72)
        sage: a = R(40).gcd(S(30)); a
        2
        sage: a.parent()
        Ring of integers modulo 12
        sage: b = R(17).gcd(60); b
        1
        sage: b.parent()
        Ring of integers modulo 60

        sage: mod(72*5, 3^3*2^2*17^2).gcd(mod(48*17, 3^3*2^2*17^2))
        12
        sage: mod(0,1).gcd(mod(0,1))
        0

  `is_one`()

    Returns `True` if this is \(1\), otherwise `False`.

    EXAMPLES:

        sage: mod(6,5).is_one()
        True
        sage: mod(0,5).is_one()
        False

  `is_unit`()

    Return True iff this element is a unit

    EXAMPLES:

        sage: a=Mod(23,100)
        sage: a.is_unit()
        True
        sage: a=Mod(24,100)
        sage: a.is_unit()
        False

  `lift`()

    Lift an integer modulo \(n\) to the integers.

    EXAMPLES:

        sage: a = Mod(8943, 2^10); type(a)
        <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int'>
        sage: lift(a)
        751
        sage: a.lift()
        751

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

    Returns square root or square roots of `self` modulo \(n\).

    INPUT:

    - `extend` - bool (default: `True`); if `True`, return a square root in an extension ring, if necessary. Otherwise, raise a `ValueError` if the square root is not in the base ring.
    - `all` - bool (default: `False`); if `True`, return {all} square roots of self, instead of just one.

    ALGORITHM: Calculates the square roots mod \(p\) for each of the primes \(p\) dividing the order of the ring, then lifts them \(p\)-adically and uses the CRT to find a square root mod \(n\).

    See also `square_root_mod_prime_power` and `square_root_mod_prime` (in this module) for more algorithmic details.

    EXAMPLES:

        sage: mod(-1, 17).sqrt()
        4
        sage: mod(5, 389).sqrt()
        86
        sage: mod(7, 18).sqrt()
        5
        sage: a = mod(14, 5^60).sqrt()
        sage: a*a
        14
        sage: mod(15, 389).sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: self must be a square
        sage: Mod(1/9, next_prime(2^40)).sqrt()^(-2)
        9
        sage: Mod(1/25, next_prime(2^90)).sqrt()^(-2)
        25

        sage: a = Mod(3,5); a
        3
        sage: x = Mod(-1, 360)
        sage: x.sqrt(extend=False)
        Traceback (most recent call last):
        ...
        ValueError: self must be a square
        sage: y = x.sqrt(); y
        sqrt359
        sage: y.parent()
        Univariate Quotient Polynomial Ring in sqrt359 over Ring of integers modulo 360 with modulus x^2 + 1
        sage: y^2
        359

    We compute all square roots in several cases:

        sage: R = Integers(5*2^3*3^2); R
        Ring of integers modulo 360
        sage: R(40).sqrt(all=True)
        [20, 160, 200, 340]
        sage: [x for x in R if x^2 == 40]  # Brute force verification
        [20, 160, 200, 340]
        sage: R(1).sqrt(all=True)
        [1, 19, 71, 89, 91, 109, 161, 179, 181, 199, 251, 269, 271, 289, 341, 359]
        sage: R(0).sqrt(all=True)
        [0, 60, 120, 180, 240, 300]
        sage: GF(107)(0).sqrt(all=True)
        [0]

        sage: R = Integers(5*13^3*37); R
        Ring of integers modulo 406445
        sage: v = R(-1).sqrt(all=True); v
        [78853, 111808, 160142, 193097, 213348, 246303, 294637, 327592]
        sage: [x^2 for x in v]
        [406444, 406444, 406444, 406444, 406444, 406444, 406444, 406444]
        sage: v = R(169).sqrt(all=True); min(v), -max(v), len(v)
        (13, 13, 104)
        sage: all([x^2==169 for x in v])
        True

    Modulo a power of 2:

        sage: R = Integers(2^7); R
        Ring of integers modulo 128
        sage: a = R(17)
        sage: a.sqrt()
        23
        sage: a.sqrt(all=True)
        [23, 41, 87, 105]
        sage: [x for x in R if x^2==17]
        [23, 41, 87, 105]

class `sage.rings.finite_rings.integer_mod.``IntegerMod_int64`

  Bases: `sage.rings.finite_rings.integer_mod.IntegerMod_abstract`

  Elements of \(\ZZ/n\ZZ\) for n small enough to be operated on in 64 bits

  AUTHORS:

  - Robert Bradshaw (2006-09-14)
  `gcd`(other)

    Greatest common divisor

    Returns the “smallest” generator in \(\ZZ / N\ZZ\) of the ideal generated by `self` and `other`.

    INPUT:

    - `other` – an element of the same ring as this one.

    EXAMPLES:

        sage: mod(2^3*3^2*5, 3^3*2^2*17^5).gcd(mod(2^4*3*17, 3^3*2^2*17^5))
        12
        sage: mod(0,17^5).gcd(mod(0,17^5))
        0

  `is_one`()

    Returns `True` if this is \(1\), otherwise `False`.

    EXAMPLES:

        sage: (mod(-1,5^10)^2).is_one()
        True
        sage: mod(0,5^10).is_one()
        False

  `is_unit`()

    Return True iff this element is a unit.

    EXAMPLES:

        sage: mod(13, 5^10).is_unit()
        True
        sage: mod(25, 5^10).is_unit()
        False

  `lift`()

    Lift an integer modulo \(n\) to the integers.

    EXAMPLES:

        sage: a = Mod(8943, 2^25); type(a)
        <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int64'>
        sage: lift(a)
        8943
        sage: a.lift()
        8943

class `sage.rings.finite_rings.integer_mod.``IntegerMod_to_Integer`

  Bases: `sage.categories.map.Map`

class `sage.rings.finite_rings.integer_mod.``IntegerMod_to_IntegerMod`

  Bases: `sage.rings.finite_rings.integer_mod.IntegerMod_hom`

  Very fast IntegerMod to IntegerMod homomorphism.

  EXAMPLES:

      sage: from sage.rings.finite_rings.integer_mod import IntegerMod_to_IntegerMod
      sage: Rs = [Integers(3**k) for k in range(1,30,5)]
      sage: [type(R(0)) for R in Rs]
      [<type 'sage.rings.finite_rings.integer_mod.IntegerMod_int'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int64'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int64'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_gmp'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_gmp'>]
      sage: fs = [IntegerMod_to_IntegerMod(S, R) for R in Rs for S in Rs if S is not R and S.order() > R.order()]
      sage: all([f(-1) == f.codomain()(-1) for f in fs])
      True
      sage: [f(-1) for f in fs]
      [2, 2, 2, 2, 2, 728, 728, 728, 728, 177146, 177146, 177146, 43046720, 43046720, 10460353202]

class `sage.rings.finite_rings.integer_mod.``Integer_to_IntegerMod`

  Bases: `sage.rings.finite_rings.integer_mod.IntegerMod_hom`

  Fast \(\ZZ \rightarrow \ZZ/n\ZZ\) morphism.

  EXAMPLES:

  We make sure it works for every type.

      sage: from sage.rings.finite_rings.integer_mod import Integer_to_IntegerMod
      sage: Rs = [Integers(10), Integers(10^5), Integers(10^10)]
      sage: [type(R(0)) for R in Rs]
      [<type 'sage.rings.finite_rings.integer_mod.IntegerMod_int'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_int64'>, <type 'sage.rings.finite_rings.integer_mod.IntegerMod_gmp'>]
      sage: fs = [Integer_to_IntegerMod(R) for R in Rs]
      sage: [f(-1) for f in fs]
      [9, 99999, 9999999999]

  `section`()

`sage.rings.finite_rings.integer_mod.``Mod`(n, m, parent=None)

  Return the equivalence class of \(n\) modulo \(m\) as an element of \(\ZZ/m\ZZ\).

  EXAMPLES:

      sage: x = Mod(12345678, 32098203845329048)
      sage: x
      12345678
      sage: x^100
      1017322209155072

  You can also use the lowercase version:

      sage: mod(12,5)
      2

  Illustrates that trac #5971 is fixed. Consider \(n\) modulo \(m\) when \(m = 0\). Then \(\ZZ/0\ZZ\) is isomorphic to \(\ZZ\) so \(n\) modulo \(0\) is is equivalent to \(n\) for any integer value of \(n\):

      sage: Mod(10, 0)
      10
      sage: a = randint(-100, 100)
      sage: Mod(a, 0) == a
      True

class `sage.rings.finite_rings.integer_mod.``NativeIntStruct`

  Bases: `object`

  We store the various forms of the modulus here rather than in the parent for efficiency reasons.

  We may also store a cached table of all elements of a given ring in this class.

  `precompute_table`(parent, inverses=True)

    Function to compute and cache all elements of this class.

    If `inverses == True`, also computes and caches the inverses of the invertible elements.

    EXAMPLES:

    This is used by the `sage.rings.finite_rings.integer_mod_ring.IntegerModRing_generic` constructor:

        sage: from sage.rings.finite_rings.integer_mod_ring import IntegerModRing_generic
        sage: R = IntegerModRing_generic(39, cache=False)
        sage: R(5)^-1
        8
        sage: R(5)^-1 is R(8)
        False
        sage: R = IntegerModRing_generic(39, cache=True)  # indirect doctest
        sage: R(5)^-1 is R(8)
        True

    Check that the inverse of 0 modulo 1 works, see trac ticket #13639:

        sage: R = IntegerModRing_generic(1, cache=True)  # indirect doctest
        sage: R(0)^-1 is R(0)
        True

`sage.rings.finite_rings.integer_mod.``is_IntegerMod`(x)

  Return `True` if and only if x is an integer modulo \(n\).

  EXAMPLES:

      sage: from sage.rings.finite_rings.integer_mod import is_IntegerMod
      sage: is_IntegerMod(5)
      False
      sage: is_IntegerMod(Mod(5,10))
      True

`sage.rings.finite_rings.integer_mod.``lucas`(k, P, Q=1, n=None)

  Return \([V_k(P, Q) \mod n, Q^{\lfloor k/2 \rfloor} \mod n]\) where \(V_k\) is the Lucas function defined by the recursive relation

  \[V_k(P, Q) = P V_{k-1}(P, Q) - Q V_{k-2}(P, Q)\]

  with \(V_0 = 2, V_1 = P\).

  INPUT:

  - `k` – integer; index to compute
  - `P`, `Q` – integers or modular integers; initial values
  - `n` – integer (optional); modulus to use if `P` is not a modular integer

  REFERENCES:

  [IEEEP1363] | IEEE P1363 / D13 (Draft Version 13). Standard Specifications for Public Key Cryptography Annex A (Informative). Number-Theoretic Background. Section A.2.4

  AUTHORS:

  - Somindu Chaya Ramanna, Shashank Singh and Srinivas Vivek Venkatesh (2011-09-15, ECC2011 summer school)
  - Robert Bradshaw

  TESTS:

      sage: from sage.rings.finite_rings.integer_mod import lucas
      sage: p = randint(0,100000)
      sage: q = randint(0,100000)
      sage: n = randint(0,100)
      sage: all([lucas(k,p,q,n)[0] == Mod(lucas_number2(k,p,q),n)
      ...        for k in Integers(20)])
      True
      sage: from sage.rings.finite_rings.integer_mod import lucas
      sage: p = randint(0,100000)
      sage: q = randint(0,100000)
      sage: n = randint(0,100)
      sage: k = randint(0,100)
      sage: lucas(k,p,q,n) == [Mod(lucas_number2(k,p,q),n),Mod(q^(int(k/2)),n)]
      True

  EXAMPLES:

      sage: [lucas(k,4,5,11)[0] for k in range(30)]
      [2, 4, 6, 4, 8, 1, 8, 5, 2, 5, 10, 4, 10, 9, 8, 9, 7, 5, 7, 3, 10, 3, 6, 9, 6, 1, 7, 1, 2, 3]

      sage: lucas(20,4,5,11)
      [10, 1]

`sage.rings.finite_rings.integer_mod.``lucas_q1`(mm, P)

  Return \(V_k(P, 1)\) where \(V_k\) is the Lucas function defined by the recursive relation

  \(V_k(P, Q) = PV_{k-1}(P, Q) - QV_{k-2}(P, Q)\)

  with \(V_0 = 2, V_1(P_Q) = P\).

  REFERENCES:

  [Pos88] | H. Postl. ‘Fast evaluation of Dickson Polynomials’ Contrib. to General Algebra, Vol. 6 (1988) pp. 223-225

  AUTHORS:

  - Robert Bradshaw

  TESTS:

      sage: from sage.rings.finite_rings.integer_mod import lucas_q1
      sage: all([lucas_q1(k, a) == BinaryRecurrenceSequence(a, -1, 2, a)(k)
      ....:      for a in Integers(23)
      ....:      for k in range(13)])
      True

`sage.rings.finite_rings.integer_mod.``makeNativeIntStruct`(z)

  Function to convert a Sage Integer into class NativeIntStruct.

  Note

  This function is only used for the unpickle override below.

`sage.rings.finite_rings.integer_mod.``mod`(n, m, parent=None)

  Return the equivalence class of \(n\) modulo \(m\) as an element of \(\ZZ/m\ZZ\).

  EXAMPLES:

      sage: x = Mod(12345678, 32098203845329048)
      sage: x
      12345678
      sage: x^100
      1017322209155072

  You can also use the lowercase version:

      sage: mod(12,5)
      2

  Illustrates that trac #5971 is fixed. Consider \(n\) modulo \(m\) when \(m = 0\). Then \(\ZZ/0\ZZ\) is isomorphic to \(\ZZ\) so \(n\) modulo \(0\) is is equivalent to \(n\) for any integer value of \(n\):

      sage: Mod(10, 0)
      10
      sage: a = randint(-100, 100)
      sage: Mod(a, 0) == a
      True

`sage.rings.finite_rings.integer_mod.``slow_lucas`(k, P, Q=1)

  Lucas function defined using the standard definition, for consistency testing. This is deprecated in trac ticket #11802. Use `BinaryRecurrenceSequence(P, -Q, 2, P)(k)` instead.

  See also

  `BinaryRecurrenceSequence`

  REFERENCES:

  - Wikipedia article Lucas_sequence

  TESTS:

      sage: from sage.rings.finite_rings.integer_mod import slow_lucas
      sage: [slow_lucas(k, 1, -1) for k in range(10)]
      doctest:...: DeprecationWarning: slow_lucas() is deprecated. Use BinaryRecurrenceSequence instead.
      See http://trac.sagemath.org/11802 for details.
      [2, 1, 3, 4, 7, 11, 18, 29, 47, 76]

`sage.rings.finite_rings.integer_mod.``square_root_mod_prime`(a, p=None)

  Calculates the square root of \(a\), where \(a\) is an integer mod \(p\); if \(a\) is not a perfect square, this returns an (incorrect) answer without checking.

  ALGORITHM: Several cases based on residue class of \(p \bmod 16\).

  - \(p \bmod 2 = 0\): \(p = 2\) so \(\sqrt{a} = a\).
  - \(p \bmod 4 = 3\): \(\sqrt{a} = a^{(p+1)/4}\).
  - \(p \bmod 8 = 5\): \(\sqrt{a} = \zeta i a\) where \(\zeta = (2a)^{(p-5)/8}\), \(i=\sqrt{-1}\).
  - \(p \bmod 16 = 9\): Similar, work in a bi-quadratic extension of \(\GF{p}\) for small \(p\), Tonelli and Shanks for large \(p\).
  - \(p \bmod 16 = 1\): Tonelli and Shanks.

  REFERENCES:

  - Siguna Muller. ‘On the Computation of Square Roots in Finite Fields’ Designs, Codes and Cryptography, Volume 31, Issue 3 (March 2004)
  - A. Oliver L. Atkin. ‘Probabilistic primality testing’ (Chapter 30, Section 4) In Ph. Flajolet and P. Zimmermann, editors, Algorithms Seminar, 1991-1992. INRIA Research Report 1779, 1992, http://www.inria.fr/rrrt/rr-1779.html. Summary by F. Morain. http://citeseer.ist.psu.edu/atkin92probabilistic.html
  - H. Postl. ‘Fast evaluation of Dickson Polynomials’ Contrib. to General Algebra, Vol. 6 (1988) pp. 223-225

  AUTHORS:

  - Robert Bradshaw

  TESTS: Every case appears in the first hundred primes.

      sage: from sage.rings.finite_rings.integer_mod import square_root_mod_prime   # sqrt() uses brute force for small p
      sage: all([square_root_mod_prime(a*a)^2 == a*a
      ...        for p in prime_range(100)
      ...        for a in Integers(p)])
      True

`sage.rings.finite_rings.integer_mod.``square_root_mod_prime_power`(a, p, e)

  Calculates the square root of \(a\), where \(a\) is an integer mod \(p^e\).

  ALGORITHM: Perform \(p\)-adically by stripping off even powers of \(p\) to get a unit and lifting \(\sqrt{unit} \bmod p\) via Newton’s method.

  AUTHORS:

  - Robert Bradshaw

  EXAMPLES:

      sage: from sage.rings.finite_rings.integer_mod import square_root_mod_prime_power
      sage: a=Mod(17,2^20)
      sage: b=square_root_mod_prime_power(a,2,20)
      sage: b^2 == a
      True

      sage: a=Mod(72,97^10)
      sage: b=square_root_mod_prime_power(a,97,10)
      sage: b^2 == a
      True

### Navigation

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