ca_mat_entry_ptr mat i j

Returns a pointer to the entry at row i and column j. Equivalent to ca_mat_entry but implemented as a function.

ca_mat_init mat r c ctx

Initializes the matrix, setting it to the zero matrix with r rows and c columns.

ca_mat_clear mat ctx

Clears the matrix, deallocating all entries.

ca_mat_swap mat1 mat2 ctx

Efficiently swaps mat1 and mat2.

ca_mat_window_init window mat r1 c1 r2 c2 ctx

Initializes window to a window matrix into the submatrix of mat starting at the corner at row r1 and column c1 (inclusive) and ending at row r2 and column c2 (exclusive).

ca_mat_window_clear window ctx

Frees the window matrix.

ca_mat_set dest src ctx

ca_mat_set_fmpz_mat dest src ctx

ca_mat_set_fmpq_mat dest src ctx

Sets dest to src. The operands must have identical dimensions.

ca_mat_set_ca mat c ctx

Sets mat to the matrix with the scalar c on the main diagonal and zeros elsewhere.

ca_mat_transfer res res_ctx src src_ctx

Sets res to src where the corresponding context objects res_ctx and src_ctx may be different.

This operation preserves the mathematical value represented by src, but may result in a different internal representation depending on the settings of the context objects.

ca_mat_randtest mat state depth bits ctx

Sets mat to a random matrix with entries having complexity up to depth and bits (see ca_randtest).

ca_mat_randtest_rational mat state bits ctx

Sets mat to a random rational matrix with entries up to bits bits in size.

ca_mat_randops mat state count ctx

Randomizes mat in-place by performing elementary row or column operations. More precisely, at most count random additions or subtractions of distinct rows and columns will be performed. This leaves the rank (and for square matrices, the determinant) unchanged.

ca_mat_print mat ctx

Prints mat to standard output. The entries are printed on separate lines.

ca_mat_printn mat digits ctx

Prints a decimal representation of mat with precision specified by digits. The entries are comma-separated with square brackets and comma separation for the rows.

ca_mat_zero mat ctx

Sets all entries in mat to zero.

ca_mat_one mat ctx

Sets the entries on the main diagonal of mat to one, and all other entries to zero.

ca_mat_ones mat ctx

Sets all entries in mat to one.

ca_mat_pascal mat triangular ctx

Sets mat to a Pascal matrix, whose entries are binomial coefficients. If triangular is 0, constructs a full symmetric matrix with the rows of Pascal's triangle as successive antidiagonals. If triangular is 1, constructs the upper triangular matrix with the rows of Pascal's triangle as columns, and if triangular is -1, constructs the lower triangular matrix with the rows of Pascal's triangle as rows.

ca_mat_stirling mat kind ctx

Sets mat to a Stirling matrix, whose entries are Stirling numbers. If kind is 0, the entries are set to the unsigned Stirling numbers of the first kind. If kind is 1, the entries are set to the signed Stirling numbers of the first kind. If kind is 2, the entries are set to the Stirling numbers of the second kind.

ca_mat_hilbert mat ctx

Sets mat to the Hilbert matrix, which has entries \(A_{i,j} = 1/(i+j+1)\).

ca_mat_dft mat type ctx

Sets mat to the DFT (discrete Fourier transform) matrix of order n where n is the smallest dimension of mat (if mat is not square, the matrix is extended periodically along the larger dimension). The type parameter selects between four different versions of the DFT matrix (in which \(\omega = e^{2\pi i/n}\)):

• Type 0 -- entries \(A_{j,k} = \omega^{-jk}\)
• Type 1 -- entries \(A_{j,k} = \omega^{jk} / n\)
• Type 2 -- entries \(A_{j,k} = \omega^{-jk} / \sqrt{n}\)
• Type 3 -- entries \(A_{j,k} = \omega^{jk} / \sqrt{n}\)

The type 0 and 1 matrices are inverse pairs, and similarly for the type 2 and 3 matrices.

ca_mat_check_equal A B ctx

Compares A and B for equality.

ca_mat_check_is_zero A ctx

Tests if A is the zero matrix.

ca_mat_check_is_one A ctx

Tests if A has ones on the main diagonal and zeros elsewhere.

ca_mat_transpose res A ctx

Sets res to the transpose of A.

ca_mat_conj res A ctx

Sets res to the entrywise complex conjugate of A.

ca_mat_conj_transpose res A ctx

Sets res to the conjugate transpose (Hermitian transpose) of A.

ca_mat_neg res A ctx

Sets res to the negation of A.

ca_mat_add res A B ctx

Sets res to the sum of A and B.

ca_mat_sub res A B ctx

Sets res to the difference of A and B.

ca_mat_mul_classical res A B ctx

ca_mat_mul_same_nf res A B K ctx

ca_mat_mul res A B ctx

Sets res to the matrix product of A and B. The classical version uses classical multiplication. The same_nf version assumes (not checked) that both A and B have coefficients in the same simple algebraic number field K or in \(\mathbb{Q}\). The default version chooses an algorithm automatically.

ca_mat_mul_si B A c ctx

ca_mat_mul_fmpz B A c ctx

ca_mat_mul_fmpq B A c ctx

ca_mat_mul_ca B A c ctx

Sets B to A multiplied by the scalar c.

ca_mat_div_si B A c ctx

ca_mat_div_fmpz B A c ctx

ca_mat_div_fmpq B A c ctx

ca_mat_div_ca B A c ctx

Sets B to A divided by the scalar c.

ca_mat_add_ca B A c ctx

ca_mat_sub_ca B A c ctx

Sets B to A plus or minus the scalar c (interpreted as a diagonal matrix).

ca_mat_addmul_ca B A c ctx

ca_mat_submul_ca B A c ctx

Sets the matrix B to B plus (or minus) the matrix A multiplied by the scalar c.

ca_mat_sqr B A ctx

Sets B to the square of A.

ca_mat_pow_ui_binexp B A exp ctx

Sets B to A raised to the power exp, evaluated using binary exponentiation.

_ca_mat_ca_poly_evaluate res poly len A ctx

ca_mat_ca_poly_evaluate res poly A ctx

Sets res to \(f(A)\) where f is the polynomial given by poly and A is a square matrix. Uses the Paterson-Stockmeyer algorithm.

ca_mat_find_pivot pivot_row mat start_row end_row column ctx

Attempts to find a nonzero entry in mat with column index column and row index between start_row (inclusive) and end_row (exclusive).

If the return value is T_TRUE, such an element exists, and pivot_row is set to the row index. If the return value is T_FALSE, no such element exists (all entries in this part of the column are zero). If the return value is T_UNKNOWN, it is unknown whether such an element exists (zero certification failed).

This function is destructive: any elements that are nontrivially zero but can be certified zero will be overwritten by exact zeros.

ca_mat_lu_classical rank P LU A rank_check ctx

ca_mat_lu_recursive rank P LU A rank_check ctx

ca_mat_lu rank P LU A rank_check ctx

Computes a generalized LU decomposition \(A = PLU\) of a given matrix A, writing the rank of A to rank.

If A is a nonsingular square matrix, LU will be set to a unit diagonal lower triangular matrix L and an upper triangular matrix U (the diagonal of L will not be stored explicitly).

If A is an arbitrary matrix of rank r, U will be in row echelon form having r nonzero rows, and L will be lower triangular but truncated to r columns, having implicit ones on the r first entries of the main diagonal. All other entries will be zero.

If a nonzero value for rank_check is passed, the function will abandon the output matrix in an undefined state and set the rank to 0 if A is detected to be rank-deficient.

The algorithm can fail if it fails to certify that a pivot element is zero or nonzero, in which case the correct rank cannot be determined. The return value is 1 on success and 0 on failure. On failure, the data in the output variables rank, P and LU will be meaningless.

The classical version uses iterative Gaussian elimination. The recursive version uses a block recursive algorithm to take advantage of fast matrix multiplication.

ca_mat_fflu rank P LU den A rank_check ctx

Similar to ca_mat_lu, but computes a fraction-free LU decomposition using the Bareiss algorithm. The denominator is written to den. Note that despite being "fraction-free", this algorithm may introduce fractions due to incomplete symbolic simplifications.

ca_mat_nonsingular_lu P LU A ctx

Wrapper for ca_mat_lu. If A can be proved to be invertible/nonsingular, returns T_TRUE and sets P and LU to a LU decomposition \(A = PLU\). If A can be proved to be singular, returns T_FALSE. If A cannot be proved to be either singular or nonsingular, returns T_UNKNOWN. When the return value is T_FALSE or T_UNKNOWN, the LU factorization is not completed and the values of P and LU are arbitrary.

ca_mat_nonsingular_fflu P LU den A ctx

Wrapper for ca_mat_fflu. Similar to ca_mat_nonsingular_lu, but computes a fraction-free LU decomposition using the Bareiss algorithm. The denominator is written to den. Note that despite being "fraction-free", this algorithm may introduce fractions due to incomplete symbolic simplifications.

ca_mat_inv X A ctx

Determines if the square matrix A is nonsingular, and if successful, sets \(X = A^{-1}\) and returns T_TRUE. Returns T_FALSE if A is singular, and T_UNKNOWN if the rank of A cannot be determined.

ca_mat_nonsingular_solve_adjugate X A B ctx

ca_mat_nonsingular_solve_fflu X A B ctx

ca_mat_nonsingular_solve_lu X A B ctx

ca_mat_nonsingular_solve X A B ctx

Determines if the square matrix A is nonsingular, and if successful, solves \(AX = B\) and returns T_TRUE. Returns T_FALSE if A is singular, and T_UNKNOWN if the rank of A cannot be determined.

ca_mat_solve_tril_classical X L B unit ctx

ca_mat_solve_tril_recursive X L B unit ctx

ca_mat_solve_tril X L B unit ctx

ca_mat_solve_triu_classical X U B unit ctx

ca_mat_solve_triu_recursive X U B unit ctx

ca_mat_solve_triu X U B unit ctx

Solves the lower triangular system \(LX = B\) or the upper triangular system \(UX = B\), respectively. It is assumed (not checked) that the diagonal entries are nonzero. If unit is set, the main diagonal of L or U is taken to consist of all ones, and in that case the actual entries on the diagonal are not read at all and can contain other data.

The classical versions perform the computations iteratively while the recursive versions perform the computations in a block recursive way to benefit from fast matrix multiplication. The default versions choose an algorithm automatically.

ca_mat_solve_fflu_precomp X perm A den B ctx

ca_mat_solve_lu_precomp X P LU B ctx

Solves \(AX = B\) given the precomputed nonsingular LU decomposition \(A = PLU\) or fraction-free LU decomposition with denominator den. The matrices \(X\) and \(B\) are allowed to be aliased with each other, but \(X\) is not allowed to be aliased with \(LU\).

ca_mat_rank rank A ctx

Computes the rank of the matrix A. If successful, returns 1 and writes the rank to rank. If unsuccessful, returns 0.

ca_mat_rref_fflu rank R A ctx

ca_mat_rref_lu rank R A ctx

ca_mat_rref rank R A ctx

Computes the reduced row echelon form (rref) of a given matrix. On success, sets R to the rref of A, writes the rank to rank, and returns 1. On failure to certify the correct rank, returns 0, leaving the data in rank and R meaningless.

The fflu version computes a fraction-free LU decomposition and then converts the output ro rref form. The lu version computes a regular LU decomposition and then converts the output to rref form. The default version uses an automatic algorithm choice and may implement additional methods for special cases.

ca_mat_right_kernel X A ctx

Sets X to a basis of the right kernel (nullspace) of A. The output matrix X will be resized in-place to have a number of columns equal to the nullity of A. Returns 1 on success. On failure, returns 0 and leaves the data in X meaningless.

ca_mat_trace trace mat ctx

Sets trace to the sum of the entries on the main diagonal of mat.

ca_mat_det_berkowitz det A ctx

ca_mat_det_lu det A ctx

ca_mat_det_bareiss det A ctx

ca_mat_det_cofactor det A ctx

ca_mat_det det A ctx

Sets det to the determinant of the square matrix A. Various algorithms are available:

• The berkowitz version uses the division-free Berkowitz algorithm performing \(O(n^4)\) operations. Since no zero tests are required, it is guaranteed to succeed.
• The cofactor version performs cofactor expansion. This is currently only supported for matrices up to size 4.
• The lu and bareiss versions use rational LU decomposition and fraction-free LU decomposition (Bareiss algorithm) respectively, requiring \(O(n^3)\) operations. These algorithms can fail if zero certification fails (see ca_mat_nonsingular_lu); they return 1 for success and 0 for failure. Note that the Bareiss algorithm, despite being "fraction-free", may introduce fractions due to incomplete symbolic simplifications.

The default function chooses an algorithm automatically. It will, in addition, recognize trivially rational and integer matrices and evaluate those determinants using fmpq_mat_t or fmpz_mat_t.

The various algorithms can produce different symbolic forms of the same determinant. Which algorithm performs better depends strongly and sometimes unpredictably on the structure of the matrix.

ca_mat_adjugate_cofactor adj det A ctx

ca_mat_adjugate_charpoly adj det A ctx

ca_mat_adjugate adj det A ctx

Sets adj to the adjuate matrix of A and det to the determinant of A, both computed simultaneously. The cofactor version uses cofactor expansion. The charpoly version computes and evaluates the characteristic polynomial. The default version uses an automatic algorithm choice.

_ca_mat_charpoly_berkowitz cp mat ctx

ca_mat_charpoly_berkowitz cp mat ctx

_ca_mat_charpoly_danilevsky cp mat ctx

ca_mat_charpoly_danilevsky cp mat ctx

_ca_mat_charpoly cp mat ctx

ca_mat_charpoly cp mat ctx

Sets poly to the characteristic polynomial of mat which must be a square matrix. If the matrix has n rows, the underscore method requires space for \(n + 1\) output coefficients.

The berkowitz version uses a division-free algorithm requiring \(O(n^4)\) operations. The danilevsky version only performs \(O(n^3)\) operations, but performs divisions and needs to check for zero which can fail. This version returns 1 on success and 0 on failure. The default version chooses an algorithm automatically.

ca_mat_companion mat poly ctx

Sets mat to the companion matrix of poly. This function verifies that the leading coefficient of poly is provably nonzero and that the output matrix has the right size, returning 1 on success. It returns 0 if the leading coefficient of poly cannot be proved nonzero or if the size of the output matrix does not match.

ca_mat_eigenvalues lambda exp mat ctx

Attempts to compute all complex eigenvalues of the given matrix mat. On success, returns 1 and sets lambda to the distinct eigenvalues with corresponding multiplicities in exp. The eigenvalues are returned in arbitrary order. On failure, returns 0 and leaves the values in lambda and exp arbitrary.

This function effectively computes the characteristic polynomial and then calls ca_poly_roots.

ca_mat_diagonalization D P A ctx

Matrix diagonalization: attempts to compute a diagonal matrix D and an invertible matrix P such that \(A = PDP^{-1}\). Returns T_TRUE if A is diagonalizable and the computation succeeds, T_FALSE if A is provably not diagonalizable, and T_UNKNOWN if it is unknown whether A is diagonalizable. If the return value is not T_TRUE, the values in D and P are arbitrary.

ca_mat_jordan_blocks lambda num_blocks block_lambda block_size A ctx

Computes the blocks of the Jordan canonical form of A. On success, returns 1 and sets lambda to the unique eigenvalues of A, sets num_blocks to the number of Jordan blocks, entry i of block_lambda to the index of the eigenvalue in Jordan block i, and entry i of block_size to the size of Jordan block i. On failure, returns 0, leaving arbitrary values in the output variables. The user should allocate space in block_lambda and block_size for up to n entries where n is the size of the matrix.

The Jordan form is unique up to the ordering of blocks, which is arbitrary.

ca_mat_set_jordan_blocks mat lambda num_blocks block_lambda block_size ctx

Sets mat to the concatenation of the Jordan blocks given in lambda, num_blocks, block_lambda and block_size. See ca_mat_jordan_blocks for an explanation of these variables.

ca_mat_jordan_transformation mat lambda num_blocks block_lambda block_size A ctx

Given the precomputed Jordan block decomposition (lambda, num_blocks, block_lambda, block_size) of the square matrix A, computes the corresponding transformation matrix P such that \(A = P J P^{-1}\). On success, writes P to mat and returns 1. On failure, returns 0, leaving the value of mat arbitrary.

ca_mat_jordan_form J P A ctx

Computes the Jordan decomposition \(A = P J P^{-1}\) of the given square matrix A. The user can pass NULL for the output variable P, in which case only J is computed. On success, returns 1. On failure, returns 0, leaving the values of J and P arbitrary.

This function is a convenience wrapper around ca_mat_jordan_blocks, ca_mat_set_jordan_blocks and ca_mat_jordan_transformation. For computations with the Jordan decomposition, it is often better to use those methods directly since they give direct access to the spectrum and block structure.

ca_mat_exp res A ctx

Matrix exponential: given a square matrix A, sets res to \(e^A\) and returns 1 on success. If unsuccessful, returns 0, leaving the values in res arbitrary.

This function uses Jordan decomposition. The matrix exponential always exists, but computation can fail if computing the Jordan decomposition fails.

ca_mat_log res A ctx

Matrix logarithm: given a square matrix A, sets res to a logarithm \(\log(A)\) and returns T_TRUE on success. If A can be proved to have no logarithm, returns T_FALSE. If the existence of a logarithm cannot be proved, returns T_UNKNOWN.

This function uses the Jordan decomposition, and the branch of the matrix logarithm is defined by taking the principal values of the logarithms of all eigenvalues.