/*=============================================================================

    This file is part of FLINT.

    FLINT is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    FLINT is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with FLINT; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA

=============================================================================*/
/******************************************************************************

    Copyright (C) 2012,2013 Andres Goens
    Copyright (C) 2012 Sebastian Pancratz
    Copyright (C) 2013 Mike Hansen

******************************************************************************/

*******************************************************************************

    Memory Management

*******************************************************************************

void fq_poly_factor_init(fq_poly_factor_t fac, const fq_ctx_t ctx)

    Initialises \code{fac} for use. An \code{fq_poly_factor_t}
    represents a polynomial in factorised form as a product of
    polynomials with associated exponents.

void fq_poly_factor_clear(fq_poly_factor_t fac, const fq_ctx_t ctx)

    Frees all memory associated with \code{fac}.

void fq_poly_factor_realloc(fq_poly_factor_t fac, slong alloc,
                            const fq_ctx_t ctx)

    Reallocates the factor structure to provide space for
    precisely \code{alloc} factors.

void fq_poly_factor_fit_length(fq_poly_factor_t fac, slong len,
                               const fq_ctx_t ctx)

    Ensures that the factor structure has space for at least
    \code{len} factors.  This functions takes care of the case of
    repeated calls by always at least doubling the number of factors
    the structure can hold.

*******************************************************************************

    Basic Operations

*******************************************************************************

void fq_poly_factor_set(fq_poly_factor_t res, const fq_poly_factor_t fac,
                        const fq_ctx_t ctx)

    Sets \code{res} to the same factorisation as \code{fac}.

void fq_poly_factor_print_pretty(const fq_poly_factor_t fac, const fq_ctx_t ctx)

    Pretty-prints the entries of \code{fac} to standard output.

void fq_poly_factor_print(const fq_poly_factor_t fac, const fq_ctx_t ctx)

    Prints the entries of \code{fac} to standard output.

void fq_poly_factor_insert(fq_poly_factor_t fac, const fq_poly_t poly,
                           slong exp, const fq_ctx_t ctx)

    Inserts the factor \code{poly} with multiplicity \code{exp} into
    the factorisation \code{fac}.

    If \code{fac} already contains \code{poly}, then \code{exp} simply
    gets added to the exponent of the existing entry.

void fq_poly_factor_concat(fq_poly_factor_t res, const fq_poly_factor_t fac,
                           const fq_ctx_t ctx)

    Concatenates two factorisations.

    This is equivalent to calling \code{fq_poly_factor_insert()}
    repeatedly with the individual factors of \code{fac}.

    Does not support aliasing between \code{res} and \code{fac}.

void fq_poly_factor_pow(fq_poly_factor_t fac, slong exp, const fq_ctx_t ctx)

    Raises \code{fac} to the power \code{exp}.

ulong fq_poly_remove(fq_poly_t f, const fq_poly_t p, const fq_ctx_t ctx)

    Removes the highest possible power of \code{p} from \code{f} and
    returns the exponent.

*******************************************************************************

    Irreducibility Testing

*******************************************************************************

int fq_poly_is_irreducible(const fq_poly_t f, const fq_ctx_t ctx)

    Returns 1 if the polynomial \code{f} is irreducible, otherwise returns 0.

int fq_poly_is_irreducible_ddf(const fq_poly_t f, const fq_ctx_t ctx)

    Returns 1 if the polynomial \code{f} is irreducible, otherwise returns 0.
    Uses fast distinct-degree factorisation.

int fq_poly_is_irreducible_ben_or(const fq_poly_t f, const fq_ctx_t ctx)

    Returns 1 if the polynomial \code{f} is irreducible, otherwise returns 0.
    Uses Ben-Or's irreducibility test.

int _fq_poly_is_squarefree(const fq_struct * f, slong len, const fq_ctx_t ctx)

    Returns 1 if \code{(f, len)} is squarefree, and 0 otherwise. As a
    special case, the zero polynomial is not considered squarefree.
    There are no restrictions on the length.

int fq_poly_is_squarefree(const fq_poly_t f, const fq_ctx_t ctx)

    Returns 1 if \code{f} is squarefree, and 0 otherwise. As a special
    case, the zero polynomial is not considered squarefree.


*******************************************************************************

    Factorisation

*******************************************************************************

int fq_poly_factor_equal_deg_prob(fq_poly_t factor, flint_rand_t state,
                                  const fq_poly_t pol, slong d,
                                  const fq_ctx_t ctx)

    Probabilistic equal degree factorisation of \code{pol} into
    irreducible factors of degree \code{d}. If it passes, a factor is
    placed in factor and 1 is returned, otherwise 0 is returned and
    the value of factor is undetermined.

    Requires that \code{pol} be monic, non-constant and squarefree.

void fq_poly_factor_equal_deg(fq_poly_factor_t factors, const fq_poly_t pol,
                              slong d, const fq_ctx_t ctx)

    Assuming \code{pol} is a product of irreducible factors all of
    degree \code{d}, finds all those factors and places them in
    factors.  Requires that \code{pol} be monic, non-constant and
    squarefree.

void fq_poly_factor_distinct_deg(fq_poly_factor_t res, const fq_poly_t poly,
                                 slong * const *degs, const fq_ctx_t ctx)

    Factorises a monic non-constant squarefree polymnomial \code{poly}
    of degree n into factors $f[d]$ such that for $1 \leq d \leq n$
    $f[d]$ is the product of the monic irreducible factors of
    \code{poly} of degree $d$. Factors are stored in \code{res},
    assotiated powers of irreducible polynomials are stored in
    \code{degs} in the same order as factors.

    Requires that \code{degs} have enough space for irreducible polynomials'
    powers (maximum space required is $n * sizeof(slong)$).

void fq_poly_factor_squarefree(fq_poly_factor_t res, const fq_poly_t f,
                               const fq_ctx_t ctx)

    Sets \code{res} to a squarefree factorization of \code{f}.

void fq_poly_factor(fq_poly_factor_t res, const fq_poly_t f, const fq_ctx_t ctx)

    Factorises a non-constant polynomial \code{f} into monic
    irreducible factors choosing the best algorithm for given modulo
    and degree.  Choise is based on heuristic measurments.

void fq_poly_factor_cantor_zassenhaus(fq_poly_factor_t res, const fq_poly_t f,
                                      const fq_ctx_t ctx)

    Factorises a non-constant polynomial \code{f} into monic
    irreducible factors using the Cantor-Zassenhaus algorithm.

void fq_poly_factor_kaltofen_shoup(fq_poly_factor_t res, const fq_poly_t poly,
                                   const fq_ctx_t ctx)

    Factorises a non-constant polynomial \code{f} into monic
    irreducible factors using the fast version of Cantor-Zassenhaus
    algorithm proposed by Kaltofen and Shoup (1998). More precisely
    this algorithm uses a “baby step/giant step” strategy for the
    distinct-degree factorization step.

void fq_poly_factor_berlekamp(fq_poly_factor_t factors, const fq_poly_t f,
                              const fq_ctx_t ctx)

    Factorises a non-constant polynomial \code{f} into monic
    irreducible factors using the Berlekamp algorithm.

void fq_poly_factor_with_berlekamp(fq_poly_factor_t res, fq_t leading_coeff,
                                   const fq_poly_t f, const fq_ctx_t)

    Factorises a general polynomial \code{f} into monic irreducible
    factors and sets \code{leading_coeff} to the leading coefficient
    of \code{f}, or 0 if \code{f} is the zero polynomial.

    This function first checks for small special cases, deflates
    \code{f} if it is of the form $p(x^m)$ for some $m > 1$, then
    performs a square-free factorisation, and finally runs Berlekamp
    factorisation on all the individual square-free factors.

void fq_poly_factor_with_cantor_zassenhaus(fq_poly_factor_t res,
                                           fq_t leading_coeff
                                           const fq_poly_t f,
                                           const fq_ctx_t ctx)

    Factorises a general polynomial \code{f} into monic irreducible
    factors and sets \code{leading_coeff} to the leading coefficient
    of \code{f}, or 0 if \code{f} is the zero polynomial.

    This function first checks for small special cases, deflates
    \code{f} if it is of the form $p(x^m)$ for some $m > 1$, then
    performs a square-free factorisation, and finally runs
    Cantor-Zassenhaus on all the individual square-free factors.

void fq_poly_factor_with_kaltofen_shoup(fq_poly_factor_t res,
                                        fq_t leading_coeff,
                                        const fq_poly_t f,
                                        const fq_ctx_t ctx)

    Factorises a general polynomial \code{f} into monic irreducible
    factors and sets \code{leading_coeff} to the leading coefficient
    of \code{f}, or 0 if \code{f} is the zero polynomial.

    This function first checks for small special cases, deflates
    \code{f} if it is of the form $p(x^m)$ for some $m > 1$, then
    performs a square-free factorisation, and finally runs
    Kaltofen-Shoup on all the individual square-free factors.

void fq_poly_iterated_frobenius_preinv(fq_poly_t *rop, slong n,
                                       const fq_poly_t v, const fq_poly_t vinv,
                                       const fq_ctx_t ctx)

    Sets \code{rop[i]} to be $x^{q^i} mod v$ for $0 <= i < n$.

    It is required that \code{vinv} is the inverse of the reverse of
    \code{v} mod \code{x^lenv}.
