/Volumes/unix-files/u/ntl-new/ntl-9.10.0dev/doc/ZZ_pEXFactoring.cpp.html

/**************************************************************************\
MODULE: ZZ_pEXFactoring
SUMMARY:
Routines are provided for factorization of polynomials over ZZ_pE, as
well as routines for related problems such as testing irreducibility
and constructing irreducible polynomials of given degree.
\**************************************************************************/
#include <NTL/ZZ_pEX.h>
#include <NTL/pair_ZZ_pEX_long.h>
void SquareFreeDecomp(vec_pair_ZZ_pEX_long& u, const ZZ_pEX& f);
vec_pair_ZZ_pEX_long SquareFreeDecomp(const ZZ_pEX& f);
// Performs square-free decomposition. f must be monic. If f =
// prod_i g_i^i, then u is set to a list of pairs (g_i, i). The list
// is is increasing order of i, with trivial terms (i.e., g_i = 1)
// deleted.
void FindRoots(vec_ZZ_pE& x, const ZZ_pEX& f);
vec_ZZ_pE FindRoots(const ZZ_pEX& f);
// f is monic, and has deg(f) distinct roots. returns the list of
// roots
void FindRoot(ZZ_pE& root, const ZZ_pEX& f);
ZZ_pE FindRoot(const ZZ_pEX& f);
// finds a single root of f. assumes that f is monic and splits into
// distinct linear factors
void NewDDF(vec_pair_ZZ_pEX_long& factors, const ZZ_pEX& f,
const ZZ_pEX& h, long verbose=0);
vec_pair_ZZ_pEX_long NewDDF(const ZZ_pEX& f, const ZZ_pEX& h,
long verbose=0);
// This computes a distinct-degree factorization. The input must be
// monic and square-free. factors is set to a list of pairs (g, d),
// where g is the product of all irreducible factors of f of degree d.
// Only nontrivial pairs (i.e., g != 1) are included. The polynomial
// h is assumed to be equal to X^{ZZ_pE::cardinality()} mod f.
// This routine implements the baby step/giant step algorithm
// of [Kaltofen and Shoup, STOC 1995].
// further described in [Shoup, J. Symbolic Comp. 20:363-397, 1995].
// NOTE: When factoring "large" polynomials,
// this routine uses external files to store some intermediate
// results, which are removed if the routine terminates normally.
// These files are stored in the current directory under names of the
// form tmp-*.
// The definition of "large" is controlled by the variable
extern double ZZ_pEXFileThresh
// which can be set by the user. If the sizes of the tables
// exceeds ZZ_pEXFileThresh KB, external files are used.
// Initial value is NTL_FILE_THRESH (defined in tools.h).
void EDF(vec_ZZ_pEX& factors, const ZZ_pEX& f, const ZZ_pEX& h,
long d, long verbose=0);
vec_ZZ_pEX EDF(const ZZ_pEX& f, const ZZ_pEX& h,
long d, long verbose=0);
// Performs equal-degree factorization. f is monic, square-free, and
// all irreducible factors have same degree. h = X^{ZZ_pE::cardinality()} mod
// f. d = degree of irreducible factors of f. This routine
// implements the algorithm of [von zur Gathen and Shoup,
// Computational Complexity 2:187-224, 1992]
void RootEDF(vec_ZZ_pEX& factors, const ZZ_pEX& f, long verbose=0);
vec_ZZ_pEX RootEDF(const ZZ_pEX& f, long verbose=0);
// EDF for d==1
void SFCanZass(vec_ZZ_pEX& factors, const ZZ_pEX& f, long verbose=0);
vec_ZZ_pEX SFCanZass(const ZZ_pEX& f, long verbose=0);
// Assumes f is monic and square-free. returns list of factors of f.
// Uses "Cantor/Zassenhaus" approach, using the routines NewDDF and
// EDF above.
void CanZass(vec_pair_ZZ_pEX_long& factors, const ZZ_pEX& f,
long verbose=0);
vec_pair_ZZ_pEX_long CanZass(const ZZ_pEX& f, long verbose=0);
// returns a list of factors, with multiplicities. f must be monic.
// Calls SquareFreeDecomp and SFCanZass.
// NOTE: these routines use modular composition. The space
// used for the required tables can be controlled by the variable
// ZZ_pEXArgBound (see ZZ_pEX.txt).
void mul(ZZ_pEX& f, const vec_pair_ZZ_pEX_long& v);
ZZ_pEX mul(const vec_pair_ZZ_pEX_long& v);
// multiplies polynomials, with multiplicities
/**************************************************************************\
Irreducible Polynomials
\**************************************************************************/
long ProbIrredTest(const ZZ_pEX& f, long iter=1);
// performs a fast, probabilistic irreduciblity test. The test can
// err only if f is reducible, and the error probability is bounded by
// ZZ_pE::cardinality()^{-iter}. This implements an algorithm from [Shoup,
// J. Symbolic Comp. 17:371-391, 1994].
long DetIrredTest(const ZZ_pEX& f);
// performs a recursive deterministic irreducibility test. Fast in
// the worst-case (when input is irreducible). This implements an
// algorithm from [Shoup, J. Symbolic Comp. 17:371-391, 1994].
long IterIrredTest(const ZZ_pEX& f);
// performs an iterative deterministic irreducibility test, based on
// DDF. Fast on average (when f has a small factor).
void BuildIrred(ZZ_pEX& f, long n);
ZZ_pEX BuildIrred_ZZ_pEX(long n);
// Build a monic irreducible poly of degree n.
void BuildRandomIrred(ZZ_pEX& f, const ZZ_pEX& g);
ZZ_pEX BuildRandomIrred(const ZZ_pEX& g);
// g is a monic irreducible polynomial. Constructs a random monic
// irreducible polynomial f of the same degree.
long IterComputeDegree(const ZZ_pEX& h, const ZZ_pEXModulus& F);
// f is assumed to be an "equal degree" polynomial, and h =
// X^{ZZ_pE::cardinality()} mod f. The common degree of the irreducible
// factors of f is computed. Uses a "baby step/giant step" algorithm, similar
// to NewDDF. Although asymptotocally slower than RecComputeDegree
// (below), it is faster for reasonably sized inputs.
long RecComputeDegree(const ZZ_pEX& h, const ZZ_pEXModulus& F);
// f is assumed to be an "equal degree" polynomial,
// h = X^{ZZ_pE::cardinality()} mod f.
// The common degree of the irreducible factors of f is
// computed Uses a recursive algorithm similar to DetIrredTest.
void TraceMap(ZZ_pEX& w, const ZZ_pEX& a, long d, const ZZ_pEXModulus& F,
const ZZ_pEX& h);
ZZ_pEX TraceMap(const ZZ_pEX& a, long d, const ZZ_pEXModulus& F,
const ZZ_pEX& h);
// Computes w = a+a^q+...+^{q^{d-1}} mod f; it is assumed that d >= 0,
// and h = X^q mod f, q a power of ZZ_pE::cardinality(). This routine
// implements an algorithm from [von zur Gathen and Shoup,
// Computational Complexity 2:187-224, 1992]
void PowerCompose(ZZ_pEX& w, const ZZ_pEX& h, long d, const ZZ_pEXModulus& F);
ZZ_pEX PowerCompose(const ZZ_pEX& h, long d, const ZZ_pEXModulus& F);
// Computes w = X^{q^d} mod f; it is assumed that d >= 0, and h = X^q
// mod f, q a power of ZZ_pE::cardinality(). This routine implements an
// algorithm from [von zur Gathen and Shoup, Computational Complexity
// 2:187-224, 1992]