added libtompoly-0.02

Author: Tom St Denis

TODO

@@ -4,19 +4,10 @@ Short term goals [say around June]
    - Stable code, demos to show for it
    - Completed user manual
 
-For v0.02 
-   - Make sure all of the functions are consistent as to where they take the source
-    characteristic from the rightmost argument
-   - Get the pb_invmod to work
-   - Get the core functions [add/sub/mul/div] stable by testing their dependents [grow/init/copy more]
-   - Add a pb_exptmod, pb_isirreducible and various helper functions (e.g. to work with constants)
-   - Add more to the testing demo
-   - Add a MSVC makefile
-   - Add some examples to manual
-
 Down the road
    - Add a Karatsuba multiplier for larger polynomials and add a tuning function
    - write a division algo for Z[x]
    - Some form of trace function?
+   - I/O functions (to_raw, read_raw)
 
 

changes.txt

@@ -1,3 +1,15 @@
+Jan 3rd, 2004
+v0.02 - Update pb_div() to shift r(x) after multplying it wit b(x) to save a bit of time
+      - improved pb_gcd() to handle inputs which are zero
+      - Added pb_shrink()
+      - fixed pb_invmod()
+      - added pb_exteuclid() [back ported that code into LTM... hehehe]
+      - added pb_exptmod()   [this led me to find a bug in LTM!!!]
+      - added pb_monic()
+      - added pb_isirreduc()
+      - Some minor additions to test/documentation
+
+Dec 31st, 2003
 v0.01 ++ thanks goes to Martin Marcel, Greg Rose and Colin Percival for providing some missing knowledge and
          helping me get this release going
       -  Initial release.

demo/demo.c

@@ -27,9 +27,12 @@ void draw_poly(pb_poly *a)
 int main(void)
 {
    mp_int chara;
-   pb_poly a,b,c,d,e;
+   pb_poly a,b,c,d,e; 
+   mp_int  aa,bb,cc,dd,ee;
+   int res;
 
    mp_init(&chara);
+   mp_init_multi(&aa,&bb,&cc,&dd,&ee,NULL);
    pb_init_size(&a, &chara, 32);
    pb_init_size(&b, &chara, 32);
    pb_init_size(&c, &chara, 32);
@@ -170,10 +173,10 @@ int main(void)
    printf("a == \n");
    draw_poly(&a);
 
-   /* take inverse of x + 1 */
+   /* take inverse of 2x + 9 */
    pb_zero(&b);
-   mp_set(&(b.terms[1]), 1);
-   mp_set(&(b.terms[0]), 1);
+   mp_set(&(b.terms[1]), 2);
+   mp_set(&(b.terms[0]), 9);
    b.used = 2;
    pb_clamp(&b);
    printf("b == \n");
@@ -187,7 +190,24 @@ int main(void)
    /* test */
    pb_mulmod(&b, &c, &a, &d);
    pb_mul(&b, &c, &e);
-   draw_poly(&d); draw_poly(&e);
+   printf("This should be 1               : "); draw_poly(&d); 
+   printf("This should be equal to k*a + 1: "); draw_poly(&e);
+
+   /* now b has order [dividing] 17^2 - 1 == 288 so b^287 should equal c */
+   printf("exptmod test\n");
+   mp_set(&aa, 287);
+   pb_exptmod(&b, &aa, &a, &d);
+   printf("This should be invmod          : "); draw_poly(&d);
+
+   /* test irreduc */
+   printf("Irreducibility testing\n");
+   pb_isirreduc(&a, &res);
+   printf("This should be 1               : %d\n", res);
+
+   pb_isirreduc(&b, &res);
+   printf("This should be 0               : %d\n", res);
+
+  
 
    return EXIT_SUCCESS;
 }

makefile

@@ -1,7 +1,7 @@
 #Makefile for GCC by Tom St Denis
 CFLAGS += -I. -Os -Wall -W 
 
-VERSION=0.01
+VERSION=0.02
 
 #default files to install
 LIBNAME=libtompoly.a
@@ -20,7 +20,7 @@ default: libtompoly.a
 OBJECTS = pb_init.o pb_clear.o pb_init_size.o pb_grow.o pb_copy.o pb_clamp.o pb_init_copy.o \
 pb_add.o pb_sub.o pb_mul.o pb_div.o pb_zero.o pb_lshd.o pb_rshd.o pb_exch.o pb_mod.o \
 pb_addmod.o pb_submod.o pb_mulmod.o pb_gcd.o pb_init_multi.o pb_clear_multi.o pb_invmod.o \
-pb_cmp.o 
+pb_cmp.o pb_shrink.o pb_exteuclid.o pb_monic.o pb_exptmod.o pb_isirreduc.o 
 
 libtompoly.a: $(OBJECTS)
 	ar $(ARFLAGS) libtompoly.a $(OBJECTS)

makefile.msvc

@@ -0,0 +1,16 @@
+#Makefile for MSVC by Tom St Denis
+CFLAGS = /W3 /Ox /I.
+
+default: tompoly.lib
+
+OBJECTS = pb_init.obj pb_clear.obj pb_init_size.obj pb_grow.obj pb_copy.obj pb_clamp.obj pb_init_copy.obj \
+pb_add.obj pb_sub.obj pb_mul.obj pb_div.obj pb_zero.obj pb_lshd.obj pb_rshd.obj pb_exch.obj pb_mod.obj \
+pb_addmod.obj pb_submod.obj pb_mulmod.obj pb_gcd.obj pb_init_multi.obj pb_clear_multi.obj pb_invmod.obj \
+pb_cmp.obj pb_shrink.obj pb_exteuclid.obj pb_monic.obj pb_exptmod.obj pb_isirreduc.obj
+
+tompoly.lib: $(OBJECTS)
+	lib /out:tompoly.lib $(OBJECTS)
+
+demo: demo/demo.obj tompoly.lib
+	cl demo.obj tompoly.lib tommath.lib
+

pb.pdf

@@ -49,7 +49,7 @@
 \begin{document}
 \frontmatter
 \pagestyle{empty}
-\title{LibTomPoly User Manual \\ v0.01}
+\title{LibTomPoly User Manual \\ v0.02}
 \author{Tom St Denis \\ tomstdenis@iahu.ca}
 \maketitle
 This text and library are  hereby placed in the public domain.  This book has been 
@@ -291,7 +291,12 @@ \section{Multiplying and Dividing by $x$}
 int pb_rshd(pb_poly *a, int i);
 \end{alltt}
 These will multiply (or divide, respectfully) the polynomial ``a'' by $x^i$.  If $i \le 0$ the functions return without
-performing any operation.  
+performing any operation.  For example,
+
+\begin{alltt}
+pb_lshd(a, 2);  /* a(x) = a(x) * x^2 */
+pb_rshd(a, 7);  /* a(x) = a(x) / x^7 */
+\end{alltt}
 
 \chapter{Basic Arithmetic}
 \section{Addition, Subtraction and Multiplication}
@@ -319,9 +324,14 @@ \section{Division}
 \begin{alltt}
 int pb_div(pb_poly *a, pb_poly *b, pb_poly *c, pb_poly *d);
 \end{alltt}
-This will divide the polynomial ``a'' by ``b'' and store the quotient in ``c'' and remainder in ``d''.  Either of
-``c'' and ``d'' can be set to \textbf{NULL} to signify their value is not desired.  This is useful if you only want the
-quotient or remainder but not both.  
+This will divide the polynomial ``a'' by ``b'' and store the quotient in ``c'' and remainder in ``d''.  That is
+
+\begin{equation}
+b(x) \cdot c(x) + d(x) = a(x)
+\end{equation}
+
+The value of $deg(d(x))$ is always less than $deg(b(x))$.  Either of ``c'' and ``d'' can be set to \textbf{NULL} to 
+signify their value is not desired.  This is useful if you only want the quotient or remainder but not both.  
 
 Since one of the destinations can be \textbf{NULL} the characteristic of the result is taken from ``b''.  The function
 will return an error if the characteristic of ``a'' differs from that of ``b''.  
@@ -341,6 +351,37 @@ \section{Modular Functions}
 and store the result in the polynomial ``d''.  
 
 \chapter{Algebraic Functions}
+
+\section{Monic Reductions}
+\index{pb\_monic}
+\begin{alltt}
+int pb_monic(pb_poly *a, pb_poly *b)
+\end{alltt}
+Makes ``b'' the monic representation of ``a'' by ensuring the most significant coefficient is one.  Only defined
+over $GF(p)[x]$.  Note that this is not a straight copy to ``b'' so you must ensure the characteristic of the two
+are equal before you call the function\footnote{Note that $a == b$ is acceptable as well.}.  Monic polynomials
+are related to their original polynomial through an integer $k$ as follows
+
+\begin{equation}
+a(x) \cdot k^{-1} \equiv b(x)
+\end{equation}
+
+\section{Extended Euclidean Algorithm}
+\index{pb\_exteuclid}
+\begin{alltt}
+int pb_exteuclid(pb_poly *a, pb_poly *b, 
+                 pb_poly *U1, pb_poly *U2, pb_poly *U3);
+\end{alltt}
+
+This will compute the Euclidean algorithm and find values ``U1'', ``U2'', ``U3'' such that 
+
+\begin{equation}
+a(x) \cdot U1(x) + b(x) \cdot U2(x) = U3(x)
+\end{equation}
+
+The value of ``U3'' is reduced to a monic polynomial.  The three destination variables are all optional and can
+be specified as \textbf{NULL} if they are not desired.
+
 \section{Greatest Common Divisor}
 \index{pb\_gcd}
 \begin{alltt}
@@ -355,7 +396,33 @@ \section{Modular Inverse}
 int pb_invmod(pb_poly *a, pb_poly *b, pb_poly *c);
 \end{alltt}
 This finds the modular inverse of ``a'' modulo ``b'' and stores the result in ``c''.  The operation is only defined over 
-$GF(p)[x]$.  If the operation succeed then the congruent $a(x)b(x) \equiv 1 \mbox{ (mod }c(x)\mbox{)}$ should hold true.
+$GF(p)[x]$.  If the operation succeed then the following congruency should hold true.
+
+\begin{equation}
+a(x)c(x) \equiv 1 \mbox{ (mod }b(x)\mbox{)}
+\end{equation}
+
+\section{Modular Exponentiation}
+\index{pb\_exptmod}
+\begin{alltt}
+int pb_exptmod (pb_poly * G, mp_int * X, pb_poly * P, pb_poly * Y);
+\end{alltt}
+
+This raise ``G'' to the power of ``X'' modulo ``P'' and stores the result in ``Y''. Or as a congruence
+
+\begin{equation}
+Y(x) \equiv G(x)^X \mbox{ (mod }P(x)\mbox{)}
+\end{equation}
+
+Where ``X'' can be negative\footnote{But in that case $G^{-1}(x)$ must exist modulo $P(x)$.} or positive.  This function
+is only defined over $GF(p)[x]$.  
+
+\section{Irreducibility Testing}
+\index{pb\_isirreduc}
+\begin{alltt}
+int pb_isirreduc(pb_poly *a, int *res);
+\end{alltt}
+Sets ``res'' to MP\_YES is ``a'' is irreducible (only for $GF(p)[x]$) otherwise sets ``res'' to MP\_NO.  
 
 \input{pb.ind}
 

pb.tex

@@ -99,15 +99,14 @@ int pb_div(pb_poly *a, pb_poly *b, pb_poly *c, pb_poly *d)
       /* tmp is now a term of the quotient */
       if ((err = mp_copy(&tmp, &(q.terms[x - b->used + 1]))) != MP_OKAY)                     { goto __TMP2; }
 
-      /* create r(x) = C * x^k */
+      /* create r(x) = C */
       pb_zero(&r);
       if ((err = mp_copy(&tmp, &(r.terms[0]))) != MP_OKAY)                                   { goto __TMP2; }
       r.used = 1;
-      if ((err = pb_lshd(&r, x - b->used + 1)) != MP_OKAY)                                   { goto __TMP2; }
 
-      /* now multiply r(x) by b(x) and subtract from p(x) */
+      /* now multiply r(x) by b(x)*x^k and subtract from p(x) */
       if ((err = pb_mul(b, &r, &r)) != MP_OKAY)                                              { goto __TMP2; }
-
+      if ((err = pb_lshd(&r, x - b->used + 1)) != MP_OKAY)                                   { goto __TMP2; }
       if ((err = pb_sub(&p, &r, &p)) != MP_OKAY)                                             { goto __TMP2; }
    }