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

    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) 2010 William Hart

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

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

    Memory management

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

mp_ptr _nmod_vec_init(slong len)

    Returns a vector of the given length. The entries are not necessarily
    zero.

void _nmod_vec_clear(mp_ptr vec)

    Frees the memory used by the given vector.

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

    Modular reduction and arithmetic

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

void nmod_init(nmod_t * mod, mp_limb_t n)

    Initialises the given \code{nmod_t} structure for reduction modulo $n$
    with a precomputed inverse.

NMOD_RED2(r, a_hi, a_lo, mod)

    Macro to set $r$ to $a$ reduced modulo \code{mod.n}, where $a$ 
    consists of two limbs \code{(a_hi, a_lo)}. The \code{mod} parameter 
    must be a valid \code{nmod_t} structure. It is assumed that \code{a_hi} 
    is already reduced modulo \code{mod.n}.

NMOD_RED(r, a, mod)

    Macro to set $r$ to $a$ reduced modulo \code{mod.n}. The \code{mod} 
    parameter must be a valid \code{nmod_t} structure.

NMOD2_RED2(r, a_hi, a_lo, mod) 

    Macro to set $r$ to $a$ reduced modulo \code{mod.n}, where $a$ 
    consists of two limbs \code{(a_hi, a_lo)}. The \code{mod} parameter 
    must be a valid \code{nmod_t} structure. No assumptions are made 
    about \code{a_hi}.

NMOD_RED3(r, a_hi, a_me, a_lo, mod)

    Macro to set $r$ to $a$ reduced modulo \code{mod.n}, where $a$ 
    consists of three limbs \code{(a_hi, a_me, a_lo)}. The \code{mod} 
    parameter must be a valid \code{nmod_t} structure. It is assumed 
    that \code{a_hi} is already reduced modulo \code{mod.n}.

NMOD_ADDMUL(r, a, b, mod)

    Macro to set $r$ to $r + ab$ reduced modulo \code{mod.n}. The 
    \code{mod} parameter must be a valid \code{nmod_t} structure. It is 
    assumed that $r$, $a$, $b$ are already reduced modulo \code{mod.n}.

mp_limb_t _nmod_add(mp_limb_t a, mp_limb_t b, nmod_t mod)

    Returns $a + b$ modulo \code{mod.n}. It is assumed that \code{mod} is 
    no more than \code{FLINT_BITS - 1} bits. It is assumed that $a$ and $b$ 
    are already reduced modulo \code{mod.n}.

mp_limb_t nmod_add(mp_limb_t a, mp_limb_t b, nmod_t mod)

    Returns $a + b$ modulo \code{mod.n}. No assumptions are made about 
    \code{mod.n}. It is assumed that $a$ and $b$ are already reduced 
    modulo \code{mod.n}.

mp_limb_t _nmod_sub(mp_limb_t a, mp_limb_t b, nmod_t mod)

    Returns $a - b$ modulo \code{mod.n}. It is assumed that \code{mod} 
    is no more than \code{FLINT_BITS - 1} bits. It is assumed that 
    $a$ and $b$ are already reduced modulo \code{mod.n}.

mp_limb_t nmod_sub(mp_limb_t a, mp_limb_t b, nmod_t mod)

    Returns $a - b$ modulo \code{mod.n}. No assumptions are made about 
    \code{mod.n}. It is assumed that $a$ and $b$ are already reduced 
    modulo \code{mod.n}.

mp_limb_t nmod_neg(mp_limb_t a, nmod_t mod)

    Returns $-a$ modulo \code{mod.n}. It is assumed that $a$ is already 
    reduced modulo \code{mod.n}, but no assumptions are made about the 
    latter.

mp_limb_t nmod_mul(mp_limb_t a, mp_limb_t b, nmod_t mod)

    Returns $ab$ modulo \code{mod.n}. No assumptions are made about 
    \code{mod.n}. It is assumed that $a$ and $b$ are already reduced 
    modulo \code{mod.n}.

mp_limb_t nmod_inv(mp_limb_t a, nmod_t mod)

    Returns $a^{-1}$ modulo \code{mod.n}. The inverse is assumed to exist.

mp_limb_t nmod_div(mp_limb_t a, mp_limb_t b, nmod_t mod)

    Returns $a^{-1}$ modulo \code{mod.n}. The inverse of $b$ is assumed to
    exist. It is assumed that $a$ is already reduced modulo \code{mod.n}.

mp_limb_t nmod_pow_ui(mp_limb_t a, ulong e, nmod_t mod)

    Returns $a^e$ modulo \code{mod.n}. No assumptions are made about 
    \code{mod.n}. It is assumed that $a$ is already reduced
    modulo \code{mod.n}.


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

    Random functions

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

void _nmod_vec_randtest(mp_ptr vec, flint_rand_t state, slong len, nmod_t mod)

    Sets \code{vec} to a random vector of the given length with entries 
    reduced modulo \code{mod.n}.

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

    Basic manipulation and comparison

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

void _nmod_vec_set(mp_ptr res, mp_srcptr vec, slong len)

    Copies \code{len} entries from the vector \code{vec} to \code{res}.

void _nmod_vec_zero(mp_ptr vec, slong len)

    Zeros the given vector of the given length.

void _nmod_vec_swap(mp_ptr a, mp_ptr b, slong length)

    Swaps the vectors \code{a} and \code{b} of length $n$ by actually
    swapping the entries.

void _nmod_vec_reduce(mp_ptr res, mp_srcptr vec, slong len, nmod_t mod)

    Reduces the entries of \code{(vec, len)} modulo \code{mod.n} and set 
    \code{res} to the result.

mp_bitcnt_t _nmod_vec_max_bits(mp_srcptr vec, slong len)

    Returns the maximum number of bits of any entry in the vector.

int _nmod_vec_equal(mp_srcptr vec, mp_srcptr vec2, slong len)

    Returns~$1$ if \code{(vec, len)} is equal to \code{(vec2, len)}, 
    otherwise returns~$0$.

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

    Arithmetic operations

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

void _nmod_vec_add(mp_ptr res, mp_srcptr vec1, 
                        mp_srcptr vec2, slong len, nmod_t mod)

    Sets \code{(res, len)} to the sum of \code{(vec1, len)} 
    and \code{(vec2, len)}.

void _nmod_vec_sub(mp_ptr res, mp_srcptr vec1, 
                        mp_srcptr vec2, slong len, nmod_t mod)

    Sets \code{(res, len)} to the difference of \code{(vec1, len)} 
    and \code{(vec2, len)}.

void _nmod_vec_neg(mp_ptr res, mp_srcptr vec, slong len, nmod_t mod)

    Sets \code{(res, len)} to the negation of \code{(vec, len)}.

void _nmod_vec_scalar_mul_nmod(mp_ptr res, mp_srcptr vec, 
                        slong len, mp_limb_t c, nmod_t mod)

    Sets \code{(res, len)} to \code{(vec, len)} multiplied by $c$.

void _nmod_vec_scalar_addmul_nmod(mp_ptr res, mp_srcptr vec, 
                        slong len, mp_limb_t c, nmod_t mod)

    Adds \code{(vec, len)} times $c$ to the vector \code{(res, len)}.


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

    Dot products

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

int _nmod_vec_dot_bound_limbs(slong len, nmod_t mod)

    Returns the number of limbs (0, 1, 2 or 3) needed to represent the
    unreduced dot product of two vectors of length \code{len} having entries
    modulo \code{mod.n}, assuming that \code{len} is nonnegative and that
    \code{mod.n} is nonzero. The computed bound is tight. In other words,
    this function returns the precise limb size of \code{len} times
    \code{(mod.n - 1) ^ 2}.

macro NMOD_VEC_DOT(res, i, len, expr1, expr2, mod, nlimbs)

    Effectively performs the computation

    \begin{verbatim}
        res = 0;
        for (i = 0; i < len; i++)
            res += (expr1) * (expr2);
    \end{verbatim}

    but with the arithmetic performed modulo \code{mod}.
    The \code{nlimbs} parameter should be 0, 1, 2 or 3, specifying the
    number of limbs needed to represent the unreduced result.

mp_limb_t _nmod_vec_dot(mp_srcptr vec1, mp_srcptr vec2,
                                            slong len, nmod_t mod, int nlimbs)

    Returns the dot product of (\code{vec1}, \code{len}) and
    (\code{vec2}, \code{len}). The \code{nlimbs} parameter should be
    0, 1, 2 or 3, specifying the number of limbs needed to represent the
    unreduced result.

mp_limb_t
_nmod_vec_dot_ptr(mp_srcptr vec1, const mp_ptr * vec2, slong offset, slong len,
    nmod_t mod, int nlimbs)

    Returns the dot product of (\code{vec1}, \code{len}) and the values at
    \code{vec2[i][offset]}. The \code{nlimbs} parameter should be
    0, 1, 2 or 3, specifying the number of limbs needed to represent the
    unreduced result.