/*============================================================================= 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.