pqc/external/flint-2.4.3/padic_mat/doc/padic_mat.txt
2014-05-24 23:16:06 +02:00

350 lines
12 KiB
Plaintext

/*=============================================================================
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, 2013 Sebastian Pancratz
******************************************************************************/
*******************************************************************************
Module documentation
We represent a matrix over $\mathbf{Q}_p$ as a product $p^v M$,
where $p$ is a prime number, $v \in \mathbf{Z}$ and $M$ a matrix
over $\mathbf{Z}$.
We say this matrix is in \emph{canonical form} if either $M$ is zero,
in which case we choose $v = 0$, too, or if $M$ contains at least one
$p$-adic unit.
We say this matrix is \emph{reduced} modulo $p^N$ if it is canonical
form and if all coefficients of $M$ lie in the range $[0, p^{N-v})$.
*******************************************************************************
*******************************************************************************
Macros
*******************************************************************************
fmpz_mat_struct * padic_mat(const padic_mat_t A)
Returns a pointer to the unit part of the matrix, which
is a matrix over $\mathbf{Z}$.
The return value can be used as an argument to
the functions in the \code{fmpz_mat} module.
fmpz * padic_mat_entry(const padic_mat_t A, slong i, slong j)
Returns a pointer to unit part of the entry in position $(i, j)$.
Note that this is not necessarily a unit.
The return value can be used as an argument to
the functions in the \code{fmpz} module.
slong padic_mat_val(const padic_mat_t A)
Returns the valuation of the matrix.
This is implemented as a macro and can be used as an \emph{lvalue}
as well as an \emph{rvalue}.
slong padic_mat_nrows(const padic_mat_t A)
Returns the number of rows of the matrix $A$.
slong padic_mat_ncols(const padic_mat_t A)
Returns the number of columns of the matrix $A$.
*******************************************************************************
Memory management
*******************************************************************************
void padic_mat_init(padic_mat_t A, slong r, slong c)
Initialises the matrix $A$ as a zero matrix with the specified numbers
of rows and columns and precision \code{PADIC_DEFAULT_PREC}.
void padic_mat_init2(padic_mat_t A, slong r, slong c, slong prec)
Initialises the matrix $A$ as a zero matrix with the specified numbers
of rows and columns and the given precision.
void padic_mat_clear(padic_mat_t A)
Clears the matrix $A$.
void _padic_mat_canonicalise(padic_mat_t A, const padic_ctx_t ctx)
Ensures that the matrix $A$ is in canonical form.
void _padic_mat_reduce(padic_mat_t A, const padic_ctx_t ctx)
Ensures that the matrix $A$ is reduced modulo $p^N$,
assuming that it is in canonical form already.
void padic_mat_reduce(padic_mat_t A, const padic_ctx_t ctx)
Ensures that the matrix $A$ is reduced modulo $p^N$,
without assuming that it is necessarily in canonical form.
int padic_mat_is_empty(const padic_mat_t A)
Returns whether the matrix $A$ is empty, that is,
whether it has zero rows or zero columns.
int padic_mat_is_square(const padic_mat_t A)
Returns whether the matrix $A$ is square.
int padic_mat_is_canonical(const padic_mat_t A, const fmpz_t p)
Returns whether the matrix $A$ is in canonical form.
*******************************************************************************
Basic assignment
*******************************************************************************
void padic_mat_set(padic_mat_t B, const padic_mat_t A)
Sets $B$ to a copy of $A$, respecting the precision of $B$.
void padic_mat_swap(padic_mat_t A, padic_mat_t B)
Swaps the two matrices $A$ and $B$. This is done efficiently by
swapping pointers.
void padic_mat_zero(padic_mat_t A)
Sets the matrix $A$ to zero.
void padic_mat_one(padic_mat_t A)
Sets the matrix $A$ to the identity matrix. If the precision
is negative then the matrix will be the zero matrix.
*******************************************************************************
Conversions
*******************************************************************************
void padic_mat_set_fmpq_mat(padic_mat_t B,
const fmpq_mat_t A, const padic_ctx_t ctx)
Sets the $p$-adic matrix $B$ to the rational matrix $A$, reduced
according to the given context.
void padic_mat_get_fmpq_mat(fmpq_mat_t B,
const padic_mat_t A, const padic_ctx_t ctx)
Sets the rational matrix $B$ to the $p$-adic matrices $A$;
no reduction takes place.
*******************************************************************************
Entries
Because of the choice of the data structure, representing the matrix
as $p^v M$, setting an entry of the matrix might lead to changes in
all entries in the matrix $M$. Also, a specific entry is not readily
available as a $p$-adic number. Thus, there are separate functions
available for getting and setting entries.
*******************************************************************************
void padic_mat_get_entry_padic(padic_t rop,
const padic_mat_t op, slong i, slong j,
const padic_ctx_t ctx)
Sets \code{rop} to the entry in position $(i, j)$ in the matrix \code{op}.
void padic_mat_set_entry_padic(padic_mat_t rop, slong i, slong j,
const padic_t op, const padic_ctx_t ctx)
Sets the entry in position $(i, j)$ in the matrix to \code{rop}.
*******************************************************************************
Comparison
*******************************************************************************
int padic_mat_equal(const padic_mat_t A, const padic_mat_t B)
Returns whether the two matrices $A$ and $B$ are equal.
int padic_mat_is_zero(const padic_mat_t A)
Returns whether the matrix $A$ is zero.
*******************************************************************************
Input and output
*******************************************************************************
int padic_mat_fprint(FILE * file,
const padic_mat_t A, const padic_ctx_t ctx)
Prints a simple representation of the matrix $A$ to the
output stream \code{file}. The format is the number of rows,
a space, the number of columns, two spaces, followed by a list
of all the entries, one row after the other.
In the current implementation, always returns $1$.
int padic_mat_fprint_pretty(FILE * file, const padic_mat_t A,
const padic_ctx_t ctx)
Prints a \emph{pretty} representation of the matrix $A$
to the output stream \code{file}.
In the current implementation, always returns $1$.
int padic_mat_print(const padic_mat_t A, const padic_ctx_t ctx)
int padic_mat_print_pretty(const padic_mat_t A, const padic_ctx_t ctx)
*******************************************************************************
Random matrix generation
*******************************************************************************
void padic_mat_randtest(padic_mat_t A, flint_rand_t state,
const padic_ctx_t ctx)
Sets $A$ to a random matrix.
The valuation will be in the range $[- \ceil{N/10}, N)$,
$[N - \ceil{-N/10}, N)$, or $[-10, 0)$ as $N$ is positive,
negative or zero.
*******************************************************************************
Transpose
*******************************************************************************
void padic_mat_transpose(padic_mat_t B, const padic_mat_t A)
Sets $B$ to $A^t$.
*******************************************************************************
Addition and subtraction
*******************************************************************************
void _padic_mat_add(padic_mat_t C, const padic_mat_t A, const padic_mat_t B,
const padic_ctx_t ctx)
Sets $C$ to the exact sum $A + B$, ensuring that the result is in
canonical form.
void padic_mat_add(padic_mat_t C, const padic_mat_t A, const padic_mat_t B,
const padic_ctx_t ctx)
Sets $C$ to the sum $A + B$ modulo $p^N$.
void _padic_mat_sub(padic_mat_t C, const padic_mat_t A, const padic_mat_t B,
const padic_ctx_t ctx)
Sets $C$ to the exact difference $A - B$, ensuring that the result is in
canonical form.
void padic_mat_sub(padic_mat_t C, const padic_mat_t A, const padic_mat_t B,
const padic_ctx_t ctx)
Sets $C$ to $A - B$, ensuring that the result is reduced.
void _padic_mat_neg(padic_mat_t B, const padic_mat_t A)
Sets $B$ to $-A$ in canonical form.
void padic_mat_neg(padic_mat_t B, const padic_mat_t A, const padic_ctx_t ctx)
Sets $B$ to $-A$, ensuring the result is reduced.
*******************************************************************************
Scalar operations
*******************************************************************************
void _padic_mat_scalar_mul_padic(padic_mat_t B,
const padic_mat_t A, const padic_t c,
const padic_ctx_t ctx)
Sets $B$ to $c A$, ensuring that the result is in canonical form.
void padic_mat_scalar_mul_padic(padic_mat_t B,
const padic_mat_t A, const padic_t c,
const padic_ctx_t ctx)
Sets $B$ to $c A$, ensuring that the result is reduced.
void _padic_mat_scalar_mul_fmpz(padic_mat_t B,
const padic_mat_t A, const fmpz_t c,
const padic_ctx_t ctx)
Sets $B$ to $c A$, ensuring that the result is in canonical form.
void padic_mat_scalar_mul_fmpz(padic_mat_t B,
const padic_mat_t A, const fmpz_t c,
const padic_ctx_t ctx)
Sets $B$ to $c A$, ensuring that the result is reduced.
void padic_mat_scalar_div_fmpz(padic_mat_t B,
const padic_mat_t A, const fmpz_t c,
const padic_ctx_t ctx)
Sets $B$ to $c^{-1} A$, assuming that $c \neq 0$.
Ensures that the result $B$ is reduced.
*******************************************************************************
Multiplication
*******************************************************************************
void _padic_mat_mul(padic_mat_t C, const padic_mat_t A, const padic_mat_t B,
const padic_ctx_t ctx)
Sets $C$ to the product $A B$ of the two matrices $A$ and $B$,
ensuring that $C$ is in canonical form.
void padic_mat_mul(padic_mat_t C, const padic_mat_t A, const padic_mat_t B,
const padic_ctx_t ctx)
Sets $C$ to the product $A B$ of the two matrices $A$ and $B$,
ensuring that $C$ is reduced.