rsm.mod
Author: R. Scott McIntire
Description: Modular Arithmetic
Keywords: modular, arithmetic, Lisp

# Documentation for package rsm.mod

## Author : R. Scott McIntire ## Version: 1.2 ## Overview:
    This package supports modular arithmetic.

    Export Summary:

    +: Add numbers over Z mod n.
    *: Multiply numbers over Z mod n.
    ^: Exponentiate over Z mod n.

    euler-phi: Return the Euler phi function of a number.
    factors  : Return the factors of a number.
    gcd-with-pair: Gets the gcd of two numbers a and b returning also
        the integer pair, (r s), such that r*a + s*b = gcd(a,b).
    has-inverse-p: Does a number have in inverse in Z mod n?
    inverse  : Find the inverse (if it exists) in Z mod n.
    ppow     : Exponentiate over Z mod p where p is prime.

    rational-approx: Returns a simple rational approximation
                     within a given tolerance.
    solve-congruence-system: Solve for x: x = a_i mod m_i; i in [1,N]
## * (mod &rest args)
    Multiply <args> in Mod <mod> arithmetic.
    Example: (rsm.mod:* 3 2 5)
                1
## + (mod &rest args)
    Add <args> in Mod <mod> arithmetic.
    Example: (rsm.mod:+ 3 3 5)
                2
## ^ (b n mod &key (e-phi 0))
    Raise <b> to the <n>th power mod <mod> by repeated squaring. If <e-phi>
    is non zero, use the generalization of Fermat's little theorem:
    b^phi(mod) = 1 mod mod, when the gcd of b and mod is 1. The theorem is
    used to replace b^n with b^r where r = mod(n, phi(mod)) and phi is
    the Euler Phi function.
    Example: (rsm.mod:^ 213317 527131763 173)
              170
    Example: (rsm.mod:^ 7 2134145213317 33 :e-phi 20)
              28
## euler-phi (n)
    Computes the Euler Phi function of <n>.
    Example: (rsm.mod:euler-phi 15)
              8
## factors (n &key (no-dups t))
    Computes and returns a list of the primes factors of <n>. If <no-dups> is
    true, then no multiple entries of a factor are returned.
    Example: (rsm.mod:factors 100)
             (2 5)
    Example: (rsm.mod:factors 100 :no-dups nil)
             (2 2 5 5)
## gcd-with-pair (n m)
    Returns two values: The gcd of <n> and <m>, and the list (r s) such that
    r * n + s * m = gcd(n,m).
    Example: (rsm.mod:gcd-with-pair 15 21)
             3
             (3 -2)
## has-inverse-p (a n)
    Does <a> have an inverse in Z mod <n>?
    Example: (rsm.mod:has-inverse-p 10 100)
             nil
## inverse (a n &optional (error nil) (not-invert-return 0))
    Finds the inverse of <a> in Z mod <n>. If <a> inverse does not exist,
    an error is thrown if <error> is non nil. If <error> is nil, then
    <not-invert-return> is returned.
    Example: (rsm.mod:inverse 21 100)
              81
## ppow (b n p)
    Raise <b> to the <n>th power in the field Z mod <p>. Here <p> must be prime.
    Example: (rsm.mod:ppow 12 100 7)
              2
## rational-approx (number &optional (epsilon nil))
    Find a simple rational approximation to <number> within <epsilon>.
    Example: (rsm.mod:rational-approx pi 0.0000003)
             355/113
## solve-congruence-system (as ms)
    Use the Chinese remainder theorem to solve for x, the system of
    congruences: x = as_i mod ms_i. The moduli, <ms>, must all be pairwise
    relatively prime. x will be unique in Z mod (product of <ms>'s).
    Example: (rsm.mod:solve-congruence-system '(1 2 3) '(2 3 5))
              23