pqc/external/flint-2.4.3/padic_poly/doc/padic_poly.txt

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

    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) 2011, 2012 Sebastian Pancratz

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

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

    Module documentation

    We represent a polynomial in $\mathbf{Q}_p[x]$ as a 
    product $p^v f(x)$, where $p$ is a prime number, 
    $v \in \mathbf{Z}$ and $f(x) \in \mathbf{Z}[x]$.

    As a data structure, we call this polynomial \emph{normalised} 
    if the polynomial $f(x)$ is \emph{normalised}, that is, if the top 
    coefficient is non-zero.

    We say this polynomial is in \emph{canonical form} if one of the 
    coefficients of $f(x)$ is a $p$-adic unit.  If $f(x)$ is the zero 
    polynomial, we require that $v = 0$.

    We say this polynomial is \emph{reduced} modulo $p^N$ if it is 
    canonical form and if all coefficients lie in the range $[0, p^N)$.

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

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

    Memory management

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

void padic_poly_init(padic_poly_t poly)

    Initialises \code{poly} for use, setting its length to zero.  
    The precision of the polynomial is set to \code{PADIC_DEFAULT_PREC}. 
    A corresponding call to \code{padic_poly_clear()} must be made 
    after finishing with the \code{padic_poly_t} to free the memory 
    used by the polynomial.

void padic_poly_init2(padic_poly_t poly, slong alloc, slong prec)

    Initialises \code{poly} with space for at least \code{alloc} coefficients 
    and sets the length to zero.  The allocated coefficients are all set to 
    zero.  The precision is set to \code{prec}.

void padic_poly_realloc(padic_poly_t poly, slong alloc, const fmpz_t p)

    Reallocates the given polynomial to have space for \code{alloc} 
    coefficients.  If \code{alloc} is zero the polynomial is cleared 
    and then reinitialised.  If the current length is greater than 
    \code{alloc} the polynomial is first truncated to length \code{alloc}.

void padic_poly_fit_length(padic_poly_t poly, slong len)

    If \code{len} is greater than the number of coefficients currently 
    allocated, then the polynomial is reallocated to have space for at 
    least \code{len} coefficients.  No data is lost when calling this 
    function.

    The function efficiently deals with the case where \code{fit_length} is 
    called many times in small increments by at least doubling the number 
    of allocated coefficients when length is larger than the number of 
    coefficients currently allocated.

void _padic_poly_set_length(padic_poly_t poly, slong len)

    Demotes the coefficients of \code{poly} beyond \code{len} and sets 
    the length of \code{poly} to \code{len}.

    Note that if the current length is greater than \code{len} the 
    polynomial may no slonger be in canonical form.

void padic_poly_clear(padic_poly_t poly)

    Clears the given polynomial, releasing any memory used.  It must 
    be reinitialised in order to be used again.

void _padic_poly_normalise(padic_poly_t poly)

    Sets the length of \code{poly} so that the top coefficient is non-zero. 
    If all coefficients are zero, the length is set to zero.  This function 
    is mainly used internally, as all functions guarantee normalisation.

void _padic_poly_canonicalise(fmpz *poly, slong *v, slong len, const fmpz_t p)

void padic_poly_canonicalise(padic_poly_t poly, const fmpz_t p)

    Brings the polynomial \code{poly} into canonical form, 
    assuming that it is normalised already.  Does \emph{not} 
    carry out any reduction.

void padic_poly_reduce(padic_poly_t poly, const padic_ctx_t ctx)

    Reduces the polynomial \code{poly} modulo $p^N$, assuming 
    that it is in canonical form already.

void padic_poly_truncate(padic_poly_t poly, slong n, const fmpz_t p)

    Truncates the polynomial to length at most~$n$.

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

    Polynomial parameters

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

slong padic_poly_degree(padic_poly_t poly)

    Returns the degree of the polynomial \code{poly}.

slong padic_poly_length(padic_poly_t poly)

    Returns the length of the polynomial \code{poly}.

slong padic_poly_val(padic_poly_t poly)

    Returns the valuation of the polynomial \code{poly}, 
    which is defined to be the minimum valuation of all 
    its coefficients.

    The valuation of the zero polynomial is~$0$.

    Note that this is implemented as a macro and can be 
    used as either a \code{lvalue} or a \code{rvalue}.

slong padic_poly_prec(padic_poly_t poly)

    Returns the precision of the polynomial \code{poly}. 

    Note that this is implemented as a macro and can be 
    used as either a \code{lvalue} or a \code{rvalue}.

    Note that increasing the precision might require 
    a call to \code{padic_poly_reduce()}.

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

    Randomisation

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

void padic_poly_randtest(padic_poly_t f, flint_rand_t state, 
                         slong len, const padic_ctx_t ctx)

    Sets $f$ to a random polynomial of length at most \code{len} 
    with entries reduced modulo $p^N$.

void padic_poly_randtest_not_zero(padic_poly_t f, flint_rand_t state,
                                  slong len, const padic_ctx_t ctx)

    Sets $f$ to a non-zero random polynomial of length at most \code{len} 
    with entries reduced modulo $p^N$.

void padic_poly_randtest_val(padic_poly_t f, flint_rand_t state, 
                             slong val, slong len, const padic_ctx_t ctx)

    Sets $f$ to a random polynomial of length at most \code{len} 
    with at most the prescribed valuation \code{val} and entries 
    reduced modulo $p^N$.

    Specifically, we aim to set the valuation to be exactly equal 
    to \code{val}, but do not check for additional cancellation 
    when creating the coefficients.

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

    Assignment and basic manipulation

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

void padic_poly_set_padic(padic_poly_t poly, const padic_t x, 
                          const padic_ctx_t ctx)

    Sets the polynomial \code{poly} to the $p$-adic number $x$, 
    reduced to the precision of the polynomial.

void padic_poly_set(padic_poly_t poly1, const padic_poly_t poly2, 
                    const padic_ctx_t ctx)

    Sets the polynomial \code{poly1} to the polynomial \code{poly2}, 
    reduced to the precision of \code{poly1}.

void padic_poly_set_si(padic_poly_t poly, slong x, const padic_ctx_t ctx)

    Sets the polynomial \code{poly} to the \code{signed slong} 
    integer $x$ reduced to the precision of the polynomial.

void padic_poly_set_ui(padic_poly_t poly, ulong x, const padic_ctx_t ctx)

    Sets the polynomial \code{poly} to the \code{unsigned slong} 
    integer $x$ reduced to the precision of the polynomial.

void padic_poly_set_fmpz(padic_poly_t poly, const fmpz_t x, 
                         const padic_ctx_t ctx)

    Sets the polynomial \code{poly} to the integer $x$ 
    reduced to the precision of the polynomial.

void padic_poly_set_fmpq(padic_poly_t poly, const fmpq_t x, 
                         const padic_ctx_t ctx)

    Sets the polynomial \code{poly} to the value of the rational $x$, 
    reduced to the precision of the polynomial.

void padic_poly_set_fmpz_poly(padic_poly_t rop, const fmpz_poly_t op, 
                              const padic_ctx_t ctx)

    Sets the polynomial \code{rop} to the integer polynomial \code{op}
    reduced to the precision of the polynomial.

void padic_poly_set_fmpq_poly(padic_poly_t rop, 
                              const fmpq_poly_t op, const padic_ctx_t ctx)

    Sets the polynomial \code{rop} to the value of the rational 
    polynomial \code{op}, reduced to the precision of the polynomial.

int padic_poly_get_fmpz_poly(fmpz_poly_t rop, const padic_poly_t op, 
                             const padic_ctx_t ctx)

    Sets the integer polynomial \code{rop} to the value of the $p$-adic 
    polynomial \code{op} and returns $1$ if the polynomial is $p$-adically 
    integral.  Otherwise, returns $0$.

void padic_poly_get_fmpq_poly(fmpq_poly_t rop, 
                              const padic_poly_t op, const padic_ctx_t ctx)

    Sets \code{rop} to the rational polynomial corresponding to 
    the $p$-adic polynomial \code{op}.

void padic_poly_zero(padic_poly_t poly)

    Sets \code{poly} to the zero polynomial.

void padic_poly_one(padic_poly_t poly)

    Sets \code{poly} to the constant polynomial $1$, 
    reduced to the precision of the polynomial.

void padic_poly_swap(padic_poly_t poly1, padic_poly_t poly2)

    Swaps the two polynomials \code{poly1} and \code{poly2}, 
    including their precisions.

    This is done efficiently by swapping pointers.

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

    Getting and setting coefficients

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

void padic_poly_get_coeff_padic(padic_t c, const padic_poly_t poly, slong n, 
                                           const padic_ctx_t ctx)

    Sets $c$ to the coefficient of $x^n$ in the polynomial, 
    reduced modulo the precision of $c$.

void padic_poly_set_coeff_padic(padic_poly_t f, slong n, const padic_t c, 
                                                const padic_ctx_t ctx)

    Sets the coefficient of $x^n$ in the polynomial $f$ to $c$, 
    reduced to the precision of the polynomial $f$.

    Note that this operation can take linear time in the length 
    of the polynomial.

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

    Comparison

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

int padic_poly_equal(const padic_poly_t poly1, const padic_poly_t poly2)

    Returns whether the two polynomials \code{poly1} and \code{poly2} 
    are equal.

int padic_poly_is_zero(const padic_poly_t poly)

    Returns whether the polynomial \code{poly} is the zero polynomial.

int padic_poly_is_one(const padic_poly_t poly, const padic_ctx_t ctx)

    Returns whether the polynomial \code{poly} is equal 
    to the constant polynomial~$1$, taking the precision 
    of the polynomial into account.

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

    Addition and subtraction

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

void _padic_poly_add(fmpz *rop, slong *rval, slong N, 
                     const fmpz *op1, slong val1, slong len1, slong N1, 
                     const fmpz *op2, slong val2, slong len2, slong N2, 
                     const padic_ctx_t ctx)

    Sets \code{(rop, *val, FLINT_MAX(len1, len2)} to the sum of 
    \code{(op1, val1, len1)} and \code{(op2, val2, len2)}.

    Assumes that the input is reduced and guarantees that this is 
    also the case for the output.

    Assumes that $\min\{v_1, v_2\} < N$.

    Supports aliasing between the output and input arguments.

void padic_poly_add(padic_poly_t f, 
                    const padic_poly_t g, const padic_poly_t h, 
                    const padic_ctx_t ctx);

    Sets $f$ to the sum $g + h$.

void _padic_poly_sub(fmpz *rop, slong *rval, 
                     const fmpz *op1, slong val1, slong len1, 
                     const fmpz *op2, slong val2, slong len2, 
                     const padic_ctx_t ctx);

    Sets \code{(rop, *val, FLINT_MAX(len1, len2)} to the difference of 
    \code{(op1, val1, len1)} and \code{(op2, val2, len2)}.

    Assumes that the input is reduced and guarantees that this is 
    also the case for the output.

    Assumes that $\min\{v_1, v_2\} < N$.

    Support aliasing between the output and input arguments.

void padic_poly_sub(padic_poly_t f, 
                    const padic_poly_t g, const padic_poly_t h, 
                    const padic_ctx_t ctx);

    Sets $f$ to the difference $g - h$.

void padic_poly_neg(padic_poly_t f, const padic_poly_t g, 
                    const padic_ctx_t ctx);

    Sets $f$ to $-g$.

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

    Scalar multiplication

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

void _padic_poly_scalar_mul_padic(fmpz *rop, slong *rval, 
                                  const fmpz *op, slong val, slong len, 
                                  const padic_t c, const padic_ctx_t ctx)

    Sets \code{(rop, *rval, len)} to \code{(op, val, len)} multiplied 
    by the scalar $c$.

    The result will only be correctly reduced if the polynomial 
    is non-zero.  Otherwise, the array \code{(rop, len)} will be 
    set to zero but the valuation \code{*rval} might be wrong.

void padic_poly_scalar_mul_padic(padic_poly_t rop, const padic_poly_t op, 
                                 const padic_t c, const padic_ctx_t ctx)

    Sets the polynomial \code{rop} to the product of the 
    polynomial \code{op} and the $p$-adic number $c$, 
    reducing the result modulo $p^N$.

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

    Multiplication

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

void _padic_poly_mul(fmpz *rop, slong *rval, slong N, 
                     const fmpz *op1, slong val1, slong len1, 
                     const fmpz *op2, slong val2, slong len2, 
                     const padic_ctx_t ctx)

    Sets \code{(rop, *rval, len1 + len2 - 1)} to the product of 
    \code{(op1, val1, len1)} and \code{(op2, val2, len2)}.

    Assumes that the resulting valuation \code{*rval}, which is 
    the sum of the valuations \code{val1} and \code{val2}, is less 
    than the precision~$N$ of the context.

    Assumes that \code{len1 >= len2 > 0}.

void padic_poly_mul(padic_poly_t res, 
                    const padic_poly_t poly1, const padic_poly_t poly2, 
                    const padic_ctx_t ctx)

    Sets the polynomial \code{res} to the product of the two polynomials 
    \code{poly1} and \code{poly2}, reduced modulo $p^N$.

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

    Powering

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

void _padic_poly_pow(fmpz *rop, slong *rval, slong N, 
                     const fmpz *op, slong val, slong len, ulong e,
                     const padic_ctx_t ctx)

    Sets the polynomial \code{(rop, *rval, e (len - 1) + 1)} to the 
    polynomial \code{(op, val, len)} raised to the power~$e$.

    Assumes that $e > 1$ and \code{len > 0}.

    Does not support aliasing between the input and output arguments.

void padic_poly_pow(padic_poly_t rop, const padic_poly_t op, ulong e, 
                    const padic_ctx_t ctx)

    Sets the polynomial \code{rop} to the polynomial \code{op} raised 
    to the power~$e$, reduced to the precision in \code{rop}.

    In the special case $e = 0$, sets \code{rop} to the constant 
    polynomial one reduced to the precision of \code{rop}.  
    Also note that when $e = 1$, this operation sets \code{rop} to 
    \code{op} and then reduces \code{rop}.

    When the valuation of the input polynomial is negative, 
    this results in a loss of $p$-adic precision.  Suppose 
    that the input polynomial is given to precision~$N$ and 
    has valuation~$v < 0$.  The result then has valuation 
    $e v < 0$ but is only correct to precision $N + (e - 1) v$.

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

    Series inversion

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

void padic_poly_inv_series(padic_poly_t g, const padic_poly_t f, slong n, 
                           const padic_ctx_t ctx)

    Computes the power series inverse $g$ of $f$ modulo $X^n$, 
    where $n \geq 1$.

    Given the polynomial $f \in \mathbf{Q}[X] \subset \mathbf{Q}_p[X]$, 
    there exists a unique polynomial $f^{-1} \in \mathbf{Q}[X]$ such that 
    $f f^{-1} = 1$ modulo $X^n$.  This function sets $g$ to $f^{-1}$ 
    reduced modulo $p^N$.

    Assumes that the constant coefficient of $f$ is non-zero.

    Moreover, assumes that the valuation of the constant coefficient 
    of $f$ is minimal among the coefficients of $f$.

    Note that the result $g$ is zero if and only if  $- \ord_p(f) \geq N$.

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

    Derivative

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

void _padic_poly_derivative(fmpz *rop, slong *rval, slong N, 
                            const fmpz *op, slong val, slong len, 
                            const padic_ctx_t ctx)

    Sets \code{(rop, rval)} to the derivative of \code{(op, val)} reduced 
    modulo $p^N$.

    Supports aliasing of the input and the output parameters.

void padic_poly_derivative(padic_poly_t rop, 
                           const padic_poly_t op, const padic_ctx_t ctx)

    Sets \code{rop} to the derivative of \code{op}, reducing the 
    result modulo the precision of \code{rop}.

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

    Shifting

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

void padic_poly_shift_left(padic_poly_t rop, const padic_poly_t op, slong n, 
                           const padic_ctx_t ctx)

    Notationally, sets the polynomial \code{rop} to the polynomial \code{op} 
    multiplied by $x^n$, where $n \geq 0$, and reduces the result.

void padic_poly_shift_right(padic_poly_t rop, const padic_poly_t op, slong n)

    Notationally, sets the polynomial \code{rop} to the polynomial 
    \code{op} after floor division by $x^n$, where $n \geq 0$, ensuring 
    the result is reduced.

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

    Evaluation

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

void _padic_poly_evaluate_padic(fmpz_t u, slong *v, slong N, 
                                const fmpz *poly, slong val, slong len, 
                                const fmpz_t a, slong b, const padic_ctx_t ctx)

void padic_poly_evaluate_padic(padic_t y, const padic_poly_t poly, 
                               const padic_t a, const padic_ctx_t ctx)

    Sets the $p$-adic number \code{y} to \code{poly} evaluated at $a$, 
    reduced in the given context.

    Suppose that the polynomial can be written as $F(X) = p^w f(X)$ 
    with $\ord_p(f) = 1$, that $\ord_p(a) = b$ and that both are 
    defined to precision~$N$.  Then $f$ is defined to precision 
    $N-w$ and so $f(a)$ is defined to precision $N-w$ when $a$ is 
    integral and $N-w+(n-1)b$ when $b < 0$, where $n = \deg(f)$.  Thus, 
    $y = F(a)$ is defined to precision $N$ when $a$ is integral and 
    $N+(n-1)b$ when $b < 0$.

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

    Composition

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

void _padic_poly_compose(fmpz *rop, slong *rval, slong N,  
                         const fmpz *op1, slong val1, slong len1, 
                         const fmpz *op2, slong val2, slong len2, 
                         const padic_ctx_t ctx)

    Sets \code{(rop, *rval, (len1-1)*(len2-1)+1)} to the composition 
    of the two input polynomials, reducing the result modulo $p^N$.

    Assumes that \code{len1} is non-zero.

    Does not support aliasing.

void padic_poly_compose(padic_poly_t rop, 
                        const padic_poly_t op1, const padic_poly_t op2, 
                        const padic_ctx_t ctx)

    Sets \code{rop} to the composition of \code{op1} and \code{op2}, 
    reducing the result in the given context.

    To be clear about the order of composition, let $f(X)$ and $g(X)$ 
    denote the polynomials \code{op1} and \code{op2}, respectively. 
    Then \code{rop} is set to $f(g(X))$.

void _padic_poly_compose_pow(fmpz *rop, slong *rval, slong N, 
                             const fmpz *op, slong val, slong len, slong k, 
                             const padic_ctx_t ctx)

    Sets \code{(rop, *rval, (len - 1)*k + 1)} to the composition of 
    \code{(op, val, len)} and the monomial $x^k$, where $k \geq 1$.

    Assumes that \code{len} is positive.

    Supports aliasing between the input and output polynomials.

void padic_poly_compose_pow(padic_poly_t rop, const padic_poly_t op, slong k, 
                            const padic_ctx_t ctx)

    Sets \code{rop} to the composition of \code{op} and the monomial $x^k$, 
    where $k \geq 1$.

    Note that no reduction takes place.

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

    Input and output

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

int padic_poly_debug(const padic_poly_t poly)

    Prints the data defining the $p$-adic polynomial \code{poly} 
    in a simple format useful for debugging purposes.

    In the current implementation, always returns $1$.

int _padic_poly_fprint(FILE *file, const fmpz *poly, slong val, slong len, 
                       const padic_ctx_t ctx)

int padic_poly_fprint(FILE *file, const padic_poly_t poly, 
                      const padic_ctx_t ctx)

    Prints a simple representation of the polynomial \code{poly} 
    to the stream \code{file}.

    A non-zero polynomial is represented by the number of coeffients, 
    two spaces, followed by a list of the coefficients, which are printed 
    in a way depending on the print mode,
    \begin{itemize}
    \item In the \code{PADIC_TERSE} mode, the coefficients are printed as 
          rational numbers.
    \item The \code{PADIC_SERIES} mode is currently not supported and will 
          raise an abort signal.
    \item In the \code{PADIC_VAL_UNIT} mode, the coefficients are printed 
          in the form $p^v u$.
    \end{itemize}

    The zero polynomial is represented by \code{"0"}.

    In the current implementation, always returns $1$.

int _padic_poly_print(const fmpz *poly, slong val, slong len, 
                      const padic_ctx_t ctx)

int padic_poly_print(const padic_poly_t poly, const padic_ctx_t ctx)

    Prints a simple representation of the polynomial \code{poly} 
    to \code{stdout}.

    In the current implementation, always returns $1$.

int _padic_poly_fprint_pretty(FILE *file, 
                              const fmpz *poly, slong val, slong len, 
                              const char *var, 
                              const padic_ctx_t ctx)

int padic_poly_fprint_pretty(FILE *file, 
                             const padic_poly_t poly, const char *var, 
                             const padic_ctx_t ctx)

int _padic_poly_print_pretty(FILE *file, 
                             const fmpz *poly, slong val, slong len, 
                             const char *var, 
                             const padic_ctx_t ctx)

int padic_poly_print_pretty(const padic_poly_t poly, const char *var, 
                            const padic_ctx_t ctx)

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

    Testing

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

int _padic_poly_is_canonical(const fmpz *op, slong val, slong len, 
                             const padic_ctx_t ctx);

int padic_poly_is_canonical(const padic_poly_t op, const padic_ctx_t ctx);

int _padic_poly_is_reduced(const fmpz *op, slong val, slong len, slong N, 
                           const padic_ctx_t ctx);

int padic_poly_is_reduced(const padic_poly_t op, const padic_ctx_t ctx);