fmpz_poly_mat_init mat rows cols

Initialises a matrix with the given number of rows and columns for use.

fmpz_poly_mat_init_set mat src

Initialises a matrix mat of the same dimensions as src, and sets it to a copy of src.

fmpz_poly_mat_clear mat

Frees all memory associated with the matrix. The matrix must be reinitialised if it is to be used again.

fmpz_poly_mat_nrows mat

Returns the number of rows in mat.

fmpz_poly_mat_ncols mat

Returns the number of columns in mat.

fmpz_poly_mat_entry mat i j

Gives a reference to the entry at row i and column j. The reference can be passed as an input or output variable to any fmpz_poly function for direct manipulation of the matrix element. No bounds checking is performed.

fmpz_poly_mat_set mat1 mat2

Sets mat1 to a copy of mat2.

fmpz_poly_mat_swap mat1 mat2

Swaps mat1 and mat2 efficiently.

fmpz_poly_mat_swap_entrywise mat1 mat2

Swaps two matrices by swapping the individual entries rather than swapping the contents of the structs.

fmpz_poly_mat_print mat x

Prints the matrix mat to standard output, using the variable x.

fmpz_poly_mat_randtest mat state len bits

This is equivalent to applying fmpz_poly_randtest to all entries in the matrix.

fmpz_poly_mat_randtest_unsigned mat state len bits

This is equivalent to applying fmpz_poly_randtest_unsigned to all entries in the matrix.

fmpz_poly_mat_randtest_sparse A state len bits density

Creates a random matrix with the amount of nonzero entries given approximately by the density variable, which should be a fraction between 0 (most sparse) and 1 (most dense).

The nonzero entries will have random lengths between 1 and len.

fmpz_poly_mat_zero mat

Sets mat to the zero matrix.

fmpz_poly_mat_one mat

Sets mat to the unit or identity matrix of given shape, having the element 1 on the main diagonal and zeros elsewhere. If mat is nonsquare, it is set to the truncation of a unit matrix.

fmpz_poly_mat_equal mat1 mat2

Returns nonzero if mat1 and mat2 have the same shape and all their entries agree, and returns zero otherwise.

fmpz_poly_mat_is_zero mat

Returns nonzero if all entries in mat are zero, and returns zero otherwise.

fmpz_poly_mat_is_one mat

Returns nonzero if all entries of mat on the main diagonal are the constant polynomial 1 and all remaining entries are zero, and returns zero otherwise. The matrix need not be square.

fmpz_poly_mat_is_empty mat

Returns a non-zero value if the number of rows or the number of columns in mat is zero, and otherwise returns zero.

fmpz_poly_mat_is_square mat

Returns a non-zero value if the number of rows is equal to the number of columns in mat, and otherwise returns zero.

fmpz_poly_mat_max_bits A

Returns the maximum number of bits among the coefficients of the entries in A, or the negative of that value if any coefficient is negative.

fmpz_poly_mat_max_length A

Returns the maximum polynomial length among all the entries in A.

fmpz_poly_mat_transpose B A

Sets \(B\) to \(A^t\).

fmpz_poly_mat_evaluate_fmpz B A x

Sets the fmpz_mat_t B to A evaluated entrywise at the point x.

fmpz_poly_mat_scalar_mul_fmpz_poly B A c

Sets B to A multiplied entrywise by the polynomial c.

fmpz_poly_mat_scalar_mul_fmpz B A c

Sets B to A multiplied entrywise by the integer c.

fmpz_poly_mat_add C A B

Sets C to the sum of A and B. All matrices must have the same shape. Aliasing is allowed.

fmpz_poly_mat_sub C A B

Sets C to the sum of A and B. All matrices must have the same shape. Aliasing is allowed.

fmpz_poly_mat_neg B A

Sets B to the negation of A. The matrices must have the same shape. Aliasing is allowed.

fmpz_poly_mat_mul C A B

Sets C to the matrix product of A and B. The matrices must have compatible dimensions for matrix multiplication. Aliasing is allowed. This function automatically chooses between classical and KS multiplication.

fmpz_poly_mat_mul_classical C A B

Sets C to the matrix product of A and B, computed using the classical algorithm. The matrices must have compatible dimensions for matrix multiplication. Aliasing is allowed.

fmpz_poly_mat_mul_KS C A B

Sets C to the matrix product of A and B, computed using Kronecker segmentation. The matrices must have compatible dimensions for matrix multiplication. Aliasing is allowed.

fmpz_poly_mat_mullow C A B len

Sets C to the matrix product of A and B, truncating each entry in the result to length len. Uses classical matrix multiplication. The matrices must have compatible dimensions for matrix multiplication. Aliasing is allowed.

fmpz_poly_mat_sqr B A

Sets B to the square of A, which must be a square matrix. Aliasing is allowed. This function automatically chooses between classical and KS squaring.

fmpz_poly_mat_sqr_classical B A

Sets B to the square of A, which must be a square matrix. Aliasing is allowed. This function uses direct formulas for very small matrices, and otherwise classical matrix multiplication.

fmpz_poly_mat_sqr_KS B A

Sets B to the square of A, which must be a square matrix. Aliasing is allowed. This function uses Kronecker segmentation.

fmpz_poly_mat_sqrlow B A len

Sets B to the square of A, which must be a square matrix, truncating all entries to length len. Aliasing is allowed. This function uses direct formulas for very small matrices, and otherwise classical matrix multiplication.

fmpz_poly_mat_pow B A exp

Sets B to A raised to the power exp, where A is a square matrix. Uses exponentiation by squaring. Aliasing is allowed.

fmpz_poly_mat_pow_trunc B A exp len

Sets B to A raised to the power exp, truncating all entries to length len, where A is a square matrix. Uses exponentiation by squaring. Aliasing is allowed.

fmpz_poly_mat_prod res factors n

Sets res to the product of the n matrices given in the vector factors, all of which must be square and of the same size. Uses binary splitting.

fmpz_poly_mat_find_pivot_any mat start_row end_row c

Attempts to find a pivot entry for row reduction. Returns a row index \(r\) between start_row (inclusive) and stop_row (exclusive) such that column \(c\) in mat has a nonzero entry on row \(r\), or returns -1 if no such entry exists.

This implementation simply chooses the first nonzero entry it encounters. This is likely to be a nearly optimal choice if all entries in the matrix have roughly the same size, but can lead to unnecessary coefficient growth if the entries vary in size.

fmpz_poly_mat_find_pivot_partial mat start_row end_row c

Attempts to find a pivot entry for row reduction. Returns a row index \(r\) between start_row (inclusive) and stop_row (exclusive) such that column \(c\) in mat has a nonzero entry on row \(r\), or returns -1 if no such entry exists.

This implementation searches all the rows in the column and chooses the nonzero entry of smallest degree. If there are several entries with the same minimal degree, it chooses the entry with the smallest coefficient bit bound. This heuristic typically reduces coefficient growth when the matrix entries vary in size.

fmpz_poly_mat_fflu B den perm A rank_check

Uses fraction-free Gaussian elimination to set (B, den) to a fraction-free LU decomposition of A and returns the rank of A. Aliasing of A and B is allowed.

Pivot elements are chosen with fmpz_poly_mat_find_pivot_partial. If perm is non-NULL, the permutation of rows in the matrix will also be applied to perm.

If rank_check is set, the function aborts and returns 0 if the matrix is detected not to have full rank without completing the elimination.

The denominator den is set to \(\pm \operatorname{det}(A)\), where the sign is decided by the parity of the permutation. Note that the determinant is not generally the minimal denominator.

fmpz_poly_mat_rref B den A

Sets (B, den) to the reduced row echelon form of A and returns the rank of A. Aliasing of A and B is allowed.

The denominator den is set to \(\pm \operatorname{det}(A)\). Note that the determinant is not generally the minimal denominator.

fmpz_poly_mat_trace trace mat

Computes the trace of the matrix, i.e. the sum of the entries on the main diagonal. The matrix is required to be square.

fmpz_poly_mat_det det A

Sets det to the determinant of the square matrix A. Uses a direct formula, fraction-free LU decomposition, or interpolation, depending on the size of the matrix.

fmpz_poly_mat_det_fflu det A

Sets det to the determinant of the square matrix A. The determinant is computed by performing a fraction-free LU decomposition on a copy of A.

fmpz_poly_mat_det_interpolate det A

Sets det to the determinant of the square matrix A. The determinant is computed by determining a bound \(n\) for its length, evaluating the matrix at \(n\) distinct points, computing the determinant of each integer matrix, and forming the interpolating polynomial.

fmpz_poly_mat_rank A

Returns the rank of A. Performs fraction-free LU decomposition on a copy of A.

fmpz_poly_mat_inv Ainv den A

Sets (Ainv, den) to the inverse matrix of A. Returns 1 if A is nonsingular and 0 if A is singular. Aliasing of Ainv and A is allowed.

More precisely, det will be set to the determinant of A and Ainv will be set to the adjugate matrix of A. Note that the determinant is not necessarily the minimal denominator.

Uses fraction-free LU decomposition, followed by solving for the identity matrix.

fmpz_poly_mat_nullspace res mat

Computes the right rational nullspace of the matrix mat and returns the nullity.

More precisely, assume that mat has rank \(r\) and nullity \(n\). Then this function sets the first \(n\) columns of res to linearly independent vectors spanning the nullspace of mat. As a result, we always have rank(res) \(= n\), and mat \(\times\) res is the zero matrix.

The computed basis vectors will not generally be in a reduced form. In general, the polynomials in each column vector in the result will have a nontrivial common GCD.

fmpz_poly_mat_solve X den A B

Solves the equation \(AX = B\) for nonsingular \(A\). More precisely, computes (X, den) such that \(AX = B \times \operatorname{den}\). Returns 1 if \(A\) is nonsingular and 0 if \(A\) is singular. The computed denominator will not generally be minimal.

Uses fraction-free LU decomposition followed by fraction-free forward and back substitution.

fmpz_poly_mat_solve_fflu X den A B

Solves the equation \(AX = B\) for nonsingular \(A\). More precisely, computes (X, den) such that \(AX = B \times \operatorname{den}\). Returns 1 if \(A\) is nonsingular and 0 if \(A\) is singular. The computed denominator will not generally be minimal.

Uses fraction-free LU decomposition followed by fraction-free forward and back substitution.

fmpz_poly_mat_solve_fflu_precomp X perm FFLU B

Performs fraction-free forward and back substitution given a precomputed fraction-free LU decomposition and corresponding permutation.