source: git/ntl/doc/ZZX.txt @ 199b5c

/**************************************************************************\

MODULE: ZZX

SUMMARY:

The class ZZX implements polynomials in ZZ[X], i.e., univariate
polynomials with integer coefficients.

Polynomial multiplication is implemented using one of 4 different
algorithms:

1) classical 

2) Karatsuba

3) Schoenhage & Strassen --- performs an FFT by working
     modulo a "Fermat number" of appropriate size...
     good for polynomials with huge coefficients
     and moderate degree

4) CRT/FFT --- performs an FFT by working modulo several
     small primes...good for polynomials with moderate coefficients
     and huge degree.

The choice of algorithm is somewhat heuristic, and may not always be
perfect.

Many thanks to Juergen Gerhard <jngerhar@plato.uni-paderborn.de> for
pointing out the deficiency in the NTL-1.0 ZZX arithmetic, and for
contributing the Schoenhage/Strassen code.

Extensive use is made of modular algorithms to enhance performance
(e.g., the GCD algorithm and amny others).

\**************************************************************************/

#include <NTL/vec_ZZ.h>
#include "zz_pX.h"
#include <NTL/ZZ_pX.h>


class ZZX {
public:


   ZZX(); // initial value 0

   ZZX(const ZZX& a); // copy

   ZZX& operator=(const ZZX& a); // assignment
   ZZX& operator=(const ZZ& a);
   ZZX& operator=(long a);

   ~ZZX();

   ZZX(long i, const ZZ& c); // initial value X^i*c
   ZZX(long i, long c); 

   // ...

};



/**************************************************************************\

                                  Comparison

\**************************************************************************/

long operator==(const ZZX& a, const ZZX& b);
long operator!=(const ZZX& a, const ZZX& b);

long IsZero(const ZZX& a);  // test for 0
long IsOne(const ZZX& a);  // test for 1

// PROMOTIONS: operators ==, != promote {long, ZZ} to ZZX on (a, b).


/**************************************************************************\

                                   Addition

\**************************************************************************/

// operator notation:

ZZX operator+(const ZZX& a, const ZZX& b);
ZZX operator-(const ZZX& a, const ZZX& b);
ZZX operator-(const ZZX& a); // unary -

ZZX& operator+=(ZZX& x, const ZZX& a);
ZZX& operator-=(ZZX& x, const ZZX& a);

ZZX& operator++(ZZX& x);  // prefix
void operator++(ZZX& x, int);  // postfix

ZZX& operator--(ZZX& x);  // prefix
void operator--(ZZX& x, int);  // postfix


// procedural versions:

void add(ZZX& x, const ZZX& a, const ZZX& b); // x = a + b
void sub(ZZX& x, const ZZX& a, const ZZX& b); // x = a - b
void negate(ZZX& x, const ZZX& a); // x = -a

// PROMOTIONS: binary +, - and procedures add, sub promote {long, ZZ} 
// to ZZX on (a, b).


/**************************************************************************\

                               Multiplication

\**************************************************************************/

// operator notation:

ZZX operator*(const ZZX& a, const ZZX& b);

ZZX& operator*=(ZZX& x, const ZZX& a);


// procedural versions:

void mul(ZZX& x, const ZZX& a, const ZZX& b); // x = a * b

void sqr(ZZX& x, const ZZX& a); // x = a^2
ZZX sqr(const ZZX& a);

// PROMOTIONS: operator * and procedure mul promote {long, ZZ} to ZZX 
// on (a, b).


/**************************************************************************\

                               Shift Operations

LeftShift by n means multiplication by X^n
RightShift by n means division by X^n

A negative shift amount reverses the direction of the shift.

\**************************************************************************/

// operator notation:

ZZX operator<<(const ZZX& a, long n);
ZZX operator>>(const ZZX& a, long n);

ZZX& operator<<=(ZZX& x, long n);
ZZX& operator>>=(ZZX& x, long n);

// procedural versions:

void LeftShift(ZZX& x, const ZZX& a, long n); 
ZZX LeftShift(const ZZX& a, long n);

void RightShift(ZZX& x, const ZZX& a, long n); 
ZZX RightShift(const ZZX& a, long n); 



/**************************************************************************\

                                  Division

\**************************************************************************/


// Given polynomials a, b in ZZ[X], there exist polynomials
// q, r in QQ[X] such that a = b*q + r, deg(r) < deg(b).
// These routines return q and/or r if q and/or r lie(s) in ZZ[X],
// and otherwise raise an error.  

// Note that if the leading coefficient of b is 1 or -1, 
// then q and r always lie in ZZ[X], and no error can occur.

// For example, you can write f/2 for a ZZX f.  If all coefficients
// of f are even, the result is f with a factor of two removed;
// otherwise, an error is raised.  More generally, f/g will be
// evaluate q in ZZ[X] such that f = q*g if such a q exists,
// and will otherwise raise an error.

// See also below the routines for pseudo-division and division
// predicates for routines that are perhaps more useful in
// some situations.


// operator notation: 

ZZX operator/(const ZZX& a, const ZZX& b);
ZZX operator/(const ZZX& a, const ZZ& b);
ZZX operator/(const ZZX& a, long b);

ZZX operator%(const ZZX& a, const ZZX& b);

ZZX& operator/=(ZZX& x, const ZZX& b);
ZZX& operator/=(ZZX& x, const ZZ& b);
ZZX& operator/=(ZZX& x, long b);

ZZX& operator%=(ZZX& x, const ZZX& b);


// procedural versions:

void DivRem(ZZX& q, ZZX& r, const ZZX& a, const ZZX& b);
// computes q, r such that a = b q + r and deg(r) < deg(b).
// requires LeadCoeff(b) is a unit (+1, -1); otherwise,
// an error is raised.

void div(ZZX& q, const ZZX& a, const ZZX& b);
void div(ZZX& q, const ZZX& a, const ZZ& b);
void div(ZZX& q, const ZZX& a, long b);
// same as DivRem, but only computes q

void rem(ZZX& r, const ZZX& a, const ZZX& b);
// same as DivRem, but only computes r



// divide predicates:

long divide(ZZX& q, const ZZX& a, const ZZX& b);
long divide(ZZX& q, const ZZX& a, const ZZ& b);
long divide(ZZX& q, const ZZX& a, long b);
// if b | a, sets q = a/b and returns 1; otherwise returns 0


long divide(const ZZX& a, const ZZX& b);
long divide(const ZZX& a, const ZZ& b);
long divide(const ZZX& a, long b);
// if b | a, returns 1; otherwise returns 0

// These algorithms employ a modular approach, performing the division
// modulo small primes (reconstructing q via the CRT).  It is
// usually much faster than the general division routines above
// (especially when b does not divide a).


void content(ZZ& d, const ZZX& f);
ZZ content(const ZZX& f);
// d = content of f, sign(d) == sign(LeadCoeff(f)); content(0) == 0

void PrimitivePart(ZZX& pp, const ZZX& f);
ZZX PrimitivePart(const ZZX& f); 
// pp = primitive part of f, LeadCoeff(pp) >= 0; PrimitivePart(0) == 0



// pseudo-division:

void PseudoDivRem(ZZX& q, ZZX& r, const ZZX& a, const ZZX& b);
// performs pseudo-division: computes q and r with deg(r) < deg(b),
// and LeadCoeff(b)^(deg(a)-deg(b)+1) a = b q + r.  Only the classical
// algorithm is used.

void PseudoDiv(ZZX& q, const ZZX& a, const ZZX& b);
ZZX PseudoDiv(const ZZX& a, const ZZX& b);
// same as PseudoDivRem, but only computes q

void PseudoRem(ZZX& r, const ZZX& a, const ZZX& b);
ZZX PseudoRem(const ZZX& a, const ZZX& b);
// same as PseudoDivRem, but only computes r


/**************************************************************************\

                                  GCD's

\**************************************************************************/


void GCD(ZZX& d, const ZZX& a, const ZZX& b);
ZZX GCD(const ZZX& a, const ZZX& b); 
// d = gcd(a, b), LeadCoeff(d) >= 0.  Uses a modular algorithm.


void XGCD(ZZ& r, ZZX& s, ZZX& t, const ZZX& a, const ZZX& b, 
          long deterministic=0);
// r = resultant of a and b; if r != 0, then computes s and t such
// that: a*s + b*t = r; otherwise s and t not affected.  if
// !deterministic, then resultant computation may use a randomized
// strategy that errs with probability no more than 2^{-80}.



/**************************************************************************\

                               Input/Output

I/O format:

   [a_0 a_1 ... a_n],

represents the polynomial a_0 + a_1*X + ... + a_n*X^n.


\**************************************************************************/


istream& operator>>(istream& s, ZZX& x);
ostream& operator<<(ostream& s, const ZZX& a);


/**************************************************************************\

                             Some utility routines

\**************************************************************************/


long deg(const ZZX& a);  returns degree of a; deg(0) == -1

const ZZ& coeff(const ZZX& a, long i);
// returns a read-only reference to a.rep[i], or zero if i not in
// range

const ZZ& LeadCoeff(const ZZX& a);
// read-only reference to leading term of a, or zero if a == 0

const ZZ& ConstTerm(const ZZX& a);
// read-only reference to constant term of a, or zero if a == 0

void SetCoeff(ZZX& x, long i, const ZZ& a);
void SetCoeff(ZZX& x, long i, long a);
// makes coefficient of X^i equal to a; error is raised if i < 0

void SetCoeff(ZZX& x, long i);
// makes coefficient of X^i equal to 1; error is raised if i < 0

void SetX(ZZX& x); // x is set to the monomial X

long IsX(const ZZX& a); // test if x = X

void diff(ZZX& x, const ZZX& a); // x = derivative of a
ZZX diff(const ZZX& a); 

long MaxBits(const ZZX& f);
// returns max NumBits of coefficients of f

void reverse(ZZX& x, const ZZX& a, long hi);
ZZX reverse(const ZZX& a, long hi);

void reverse(ZZX& x, const ZZX& a);
ZZX reverse(const ZZX& a);

// x = reverse of a[0]..a[hi] (hi >= -1);
// hi defaults to deg(a) in second version


void VectorCopy(vec_ZZ& x, const ZZX& a, long n);
vec_ZZ VectorCopy(const ZZX& a, long n);
// x = copy of coefficient vector of a of length exactly n.
// input is truncated or padded with zeroes as appropriate.



/**************************************************************************\

                       Arithmetic mod X^n

All routines require n >= 0, otherwise an error is raised.

\**************************************************************************/


void trunc(ZZX& x, const ZZX& a, long m); // x = a % X^m
ZZX trunc(const ZZX& a, long m);

void MulTrunc(ZZX& x, const ZZX& a, const ZZX& b, long n);
ZZX MulTrunc(const ZZX& a, const ZZX& b, long n);
// x = a * b % X^n

void SqrTrunc(ZZX& x, const ZZX& a, long n);
ZZX SqrTrunc(const ZZX& a, long n);
// x = a^2 % X^n

void InvTrunc(ZZX& x, const ZZX& a, long n);
ZZX InvTrunc(const ZZX& a, long n);
// computes x = a^{-1} % X^m.  Must have ConstTerm(a) invertible.




/**************************************************************************\

                               Modular Arithmetic

The modulus f must be monic with deg(f) > 0, 
and other arguments must have smaller degree.

\**************************************************************************/

void MulMod(ZZX& x, const ZZX& a, const ZZX& b, const ZZX& f);
ZZX MulMod(const ZZX& a, const ZZX& b, const ZZX& f);
// x = a * b mod f

void SqrMod(ZZX& x, const ZZX& a, const ZZX& f);
ZZX SqrMod(const ZZX& a, const ZZX& f);
// x = a^2 mod f

void MulByXMod(ZZX& x, const ZZX& a, const ZZX& f);
ZZX MulByXMod(const ZZX& a, const ZZX& f);
// x = a*X mod f


/**************************************************************************\

                  traces, norms, resultants, discriminants,
                   minimal and characteristic polynomials

\**************************************************************************/


void TraceMod(ZZ& res, const ZZX& a, const ZZX& f);
ZZ TraceMod(const ZZX& a, const ZZX& f);
// res = trace of (a mod f).  f must be monic, 0 < deg(f), deg(a) <
// deg(f)

void TraceVec(vec_ZZ& S, const ZZX& f);
vec_ZZ TraceVec(const ZZX& f);
// S[i] = Trace(X^i mod f), for i = 0..deg(f)-1.
// f must be a monic polynomial.


// The following routines use a modular approach.

void resultant(ZZ& res, const ZZX& a, const ZZX& b, long deterministic=0);
ZZ resultant(const ZZX& a, const ZZX& b, long deterministic=0);
// res = resultant of a and b. If !deterministic, then it may use a
// randomized strategy that errs with probability no more than
// 2^{-80}.



void NormMod(ZZ& res, const ZZX& a, const ZZX& f, long deterministic=0);
ZZ NormMod(const ZZX& a, const ZZX& f, long deterministic=0);
// res = norm of (a mod f).  f must be monic, 0 < deg(f), deg(a) <
// deg(f). If !deterministic, then it may use a randomized strategy
// that errs with probability no more than 2^{-80}.



void discriminant(ZZ& d, const ZZX& a, long deterministic=0);
ZZ discriminant(const ZZX& a, long deterministic=0);
// d = discriminant of a = (-1)^{m(m-1)/2} resultant(a, a')/lc(a),
// where m = deg(a). If !deterministic, then it may use a randomized
// strategy that errs with probability no more than 2^{-80}.


void CharPolyMod(ZZX& g, const ZZX& a, const ZZX& f, long deterministic=0);
ZZX CharPolyMod(const ZZX& a, const ZZX& f, long deterministic=0);
// g = char poly of (a mod f).  f must be monic.  If !deterministic,
// then it may use a randomized strategy that errs with probability no
// more than 2^{-80}.


void MinPolyMod(ZZX& g, const ZZX& a, const ZZX& f);
ZZX MinPolyMod(const ZZX& a, const ZZX& f);
// g = min poly of (a mod f).  f must be monic, 0 < deg(f), deg(a) <
// deg(f).  May use a probabilistic strategy that errs with
// probability no more than 2^{-80}.




/**************************************************************************\

                  Incremental Chinese Remaindering

\**************************************************************************/

long CRT(ZZX& a, ZZ& prod, const zz_pX& A);
long CRT(ZZX& a, ZZ& prod, const ZZ_pX& A);
// Incremental Chinese Remaindering: If p is the current zz_p/ZZ_p modulus with
// (p, prod) = 1; Computes a' such that a' = a mod prod and a' = A mod p,
// with coefficients in the interval (-p*prod/2, p*prod/2]; 
// Sets a := a', prod := p*prod, and returns 1 if a's value changed.





/**************************************************************************\

                                vectors of ZZX's

\**************************************************************************/

NTL_vector_decl(ZZX,vec_ZZX)
// vec_ZZX

NTL_eq_vector_decl(ZZX,vec_ZZX)
// == and !=

NTL_io_vector_decl(ZZX,vec_ZZX)
// I/O operators


/**************************************************************************\

                                Miscellany


A ZZX f is represented as a vec_ZZ, which can be accessed as
f.rep.  The constant term is f.rep[0] and the leading coefficient is
f.rep[f.rep.length()-1], except if f is zero, in which case
f.rep.length() == 0.  Note that the leading coefficient is always
nonzero (unless f is zero).  One can freely access and modify f.rep,
but one should always ensure that the leading coefficient is nonzero,
which can be done by invoking f.normalize().



\**************************************************************************/


void clear(ZZX& x); // x = 0
void set(ZZX& x); // x = 1

void ZZX::normalize();
// f.normalize() strips leading zeros from f.rep.

void ZZX::SetMaxLength(long n);
// f.SetMaxLength(n) pre-allocate spaces for n coefficients.  The
// polynomial that f represents is unchanged.

void ZZX::kill();
// f.kill() sets f to 0 and frees all memory held by f.  Equivalent to
// f.rep.kill().

ZZX::ZZX(INIT_SIZE_TYPE, long n);
// ZZX(INIT_SIZE, n) initializes to zero, but space is pre-allocated
// for n coefficients

static const ZZX& zero();
// ZZX::zero() is a read-only reference to 0

void swap(ZZX& x, ZZX& y); 
// swap x & y (by swapping pointers)