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