ca_mat.h

Returns a pointer to the entry in row i and column j, like ca_mat_entry.

Returns whether mat has no entries (zero rows or zero columns), or whether it is square.

Initialises mat as the zero matrix with r rows and c columns.

Clears mat, freeing its entries.

Swaps mat1 and mat2 in constant time.

Initialises window as a view of the submatrix of mat formed by rows r_1 \le i < r_2 and columns c_1 \le j < c_2, sharing the entries of mat (nothing is copied). The window must not outlive mat.

Clears a window. This does nothing, since a window owns no memory.

Sets dest to src, which must have the same dimensions.

Sets y to the matrix with x on the main diagonal and zeros elsewhere (it need not be square).

Sets res, belonging to the context res_ctx, to the matrix src, belonging to src_ctx, transferring each entry with ca_transfer.

Sets res to a symbolic expression Matrix(Row(...), ..., Row(...)) for A, wrapped in Where(..., Def(a_1, ...), ...) defining the extension numbers that occur, as for ca_get_fexpr, which also explains flags.

Sets mat to a random matrix whose entries are generated by ca_randtest with depth len and size parameter bits.

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

Modifies mat in place by at most count random additions or subtractions of one row (or column) to another. This preserves the rank and, for a square matrix, the determinant. Wrapper of gr_mat_randops.

Prints the line ca_mat of size r x c: followed by the entries in row order, one per line, printed with ca_print and indented by four spaces, and a blank line.

Prints decimal approximations of the entries with digits significant digits as a nested list [[a, b],\n[c, d]], one row per line, followed by a newline.

Sets mat to the zero matrix, to the matrix with ones on the main diagonal and zeros elsewhere, or to the matrix with all entries 1.

Sets mat to a Pascal matrix of binomial coefficients: for triangular = 0 the symmetric matrix with entries \binom{i+j}{i}, for 1 the upper triangular matrix with entries \binom{j}{i}, and for -1 the lower triangular matrix with entries \binom{i}{j}. Wrapper of gr_mat_pascal.

Sets mat to the matrix of Stirling numbers S(i, j): unsigned Stirling numbers of the first kind for kind = 0, signed ones for kind = 1, Stirling numbers of the second kind for kind = 2. Wrapper of gr_mat_stirling.

Sets mat to the Hilbert matrix with entries 1/(i + j + 1), i, j \ge 0. Wrapper of gr_mat_hilbert.

Sets res to a matrix of the discrete Fourier transform of length n, the smaller of the two dimensions (along the larger dimension the entries repeat periodically). With \omega = e^{2 \pi i / n}, the entries A_{j,k} are \omega^{-jk} for type = 0, \omega^{jk}/n for type 1, \omega^{-jk}/\sqrt{n} for type 2 and \omega^{jk}/\sqrt{n} for type 3. Types 0 and 1 are inverse to each other, and so are types 2 and 3. The entries are elements of the cyclotomic field \mathbb{Q}(\omega) (and \sqrt{n}).

Checks whether A = B entrywise (T_FALSE if the dimensions differ), whether A is zero, or whether A has ones on the main diagonal and zeros elsewhere. Wrappers of gr_mat_equal, gr_mat_is_zero and gr_mat_is_one.

Sets B to the transpose of A. Aliasing is allowed for square matrices. Wrapper of gr_mat_transpose.

Sets the output to the entrywise complex conjugate of the input, or to its conjugate (Hermitian) transpose. Entries are conjugated with ca_conj.

Sets the output to the negation of src, or to the sum or difference of mat1 and mat2.

Sets y to a + x I or a - x I, that is, adds or subtracts the scalar x on the main diagonal.

Sets y to y + x a or y - x a.

Sets B to A multiplied or divided by the scalar c, entry by entry. Division by zero gives special values as entries.

Sets C to the matrix product AB. The dimensions must be compatible; otherwise an exception is raised.

Sets res to A^2.

Sets B to A^{\mathit{exp}} for a square matrix A (not checked), by binary exponentiation.

Sets the output to f(A) for the polynomial f (given as an array of len coefficients for the underscore version) and the square matrix A, using the Paterson–Stockmeyer algorithm, which needs about 2\sqrt{n} matrix multiplications for a polynomial of degree n. Wrappers of _gr_mat_gr_poly_evaluate.

Sets trace to the sum of the diagonal entries of the square matrix mat. Wrapper of gr_mat_trace.

Looks for a nonzero entry in column column of mat with row index in [\mathit{start\_row}, \mathit{end\_row}), which must be a nonempty range. Returns T_TRUE and sets pivot_row if one is found, T_FALSE if all these entries are proved zero, and T_UNKNOWN otherwise.

Swaps rows r and s of mat (by swapping entries) and, if perm is not NULL, the corresponding entries of the permutation array perm.

Computes a generalised LU decomposition A = PLU of the m \times n matrix A, writes the rank to rank and the row permutation to the array P of length m, and returns 1. Returns 0 if a pivot can neither be proved zero nor nonzero, in which case the outputs are meaningless.

Like ca_mat_lu, but computes a fraction-free LU decomposition with Bareiss's algorithm and writes its denominator (the last pivot) to den. Although no divisions by pivots that do not cancel exactly are performed, fractions can appear in the entries since the symbolic simplification of exact quotients is not complete.

For a square matrix A: returns T_TRUE and an LU (or fraction-free LU) decomposition A = PLU if A is proved nonsingular, T_FALSE if it is proved singular, and T_UNKNOWN otherwise. Unless the result is T_TRUE, the outputs are meaningless.

For a square matrix A: if A is proved nonsingular, sets X = A^{-1} B and returns T_TRUE; returns T_FALSE if A is proved singular and T_UNKNOWN if this cannot be decided.

For a square matrix A: if A is proved nonsingular, sets X = A^{-1} and returns T_TRUE; returns T_FALSE if A is proved singular and T_UNKNOWN otherwise. Matrices of size at most 4, and matrices whose entries do not all lie in \mathbb{Q} or one number field, are inverted through the adjugate matrix; the others by LU decomposition.

Solves LX = B for a lower triangular L, or UX = B for an upper triangular U, by substitution (classical), block recursively (recursive), or with an automatic choice. The matrix must be triangular with nonzero diagonal entries; this is not checked. If unit is nonzero, the diagonal is taken to consist of ones and is not read. Wrappers of the gr_mat_nonsingular_solve_tril and _triu functions.

Solves AX = B given a nonsingular LU decomposition (permutation perm and the matrix A holding L and U), or a fraction-free one with denominator den, as computed by ca_mat_nonsingular_lu or ca_mat_nonsingular_fflu. The decomposition is not checked. X may be the same object as B but not as A.

Computes the rank of A by LU decomposition and returns 1, or returns 0 if a pivot cannot be decided. Wrapper of gr_mat_rank_lu.

Sets R to the reduced row echelon form of A, writes the rank to rank and returns 1; returns 0, with meaningless outputs, if the rank cannot be determined. The fflu version starts from a fraction-free LU decomposition, the lu version (a wrapper of gr_mat_rref_lu) from an ordinary one, and the default version is a wrapper of gr_mat_rref.

Sets X to a matrix whose columns form a basis of the right kernel (nullspace) of A and returns 1, or returns 0 on failure. X is reinitialised to have as many columns as the nullity of A. Wrapper of gr_mat_nullspace.

Sets det to the determinant of the square matrix A.

Sets adj to the adjugate matrix of A and det to its determinant, computed together, by cofactor expansion or from the characteristic polynomial p (using \operatorname{adj}(A) = \pm q(A) where p(x) = x q(x) + p(0), a wrapper of gr_mat_adjugate_charpoly). Neither needs zero tests. The default version uses cofactors for n \le 5.

Sets cp to the characteristic polynomial \det(xI - A) of the square matrix mat. The underscore versions write n + 1 coefficients.

Sets A to the companion matrix of poly and returns 1, or returns 0 if the leading coefficient of poly is not proved nonzero or A does not have size \deg(\mathit{poly}). Wrapper of gr_mat_companion.

Computes the distinct eigenvalues of the square matrix mat, in no particular order, with their algebraic multiplicities in exp (room for n entries), and returns 1; returns 0 on failure, leaving the outputs unspecified. The eigenvalues are the roots of the characteristic polynomial computed by ca_poly_roots, so the limitations of that function apply: in particular, a matrix with rational entries always succeeds, with eigenvalues that are algebraic numbers.

Attempts to compute a diagonal matrix D and an invertible matrix P with A = P D P^{-1}. Returns T_TRUE on success, T_FALSE if A is proved not to be diagonalisable (a geometric multiplicity is smaller than the algebraic one), and T_UNKNOWN if the eigenvalues or the eigenspaces cannot be computed. The columns of P are bases of the kernels of A - \lambda I.

Computes the block structure of the Jordan canonical form of A and returns 1, or returns 0 on failure. Sets lambda to the distinct eigenvalues, num_blocks to the number of Jordan blocks, and for block i, block_lambda[i] to the index in lambda of its eigenvalue and block_size[i] to its size. The arrays must have room for n entries. The order of the blocks is unspecified. Wrapper of gr_mat_jordan_blocks.

Sets mat to the block diagonal matrix of the Jordan blocks described by lambda, num_blocks, block_lambda and block_size (see ca_mat_jordan_blocks).

Given the Jordan block structure of A, computes a matrix P with A = P J P^{-1}, where J is the Jordan form, writes it to mat and returns 1; returns 0 on failure. Wrapper of gr_mat_jordan_transformation.

Computes the Jordan decomposition A = P J P^{-1} and returns 1, or returns 0 on failure. P may be NULL if only J is wanted. This combines ca_mat_jordan_blocks, ca_mat_set_jordan_blocks and ca_mat_jordan_transformation, which give direct access to the eigenvalues and the block structure. Wrapper of gr_mat_jordan_form.

Sets res to the matrix exponential e^A and returns 1, or returns 0 if the Jordan decomposition of A, on which the computation is based, cannot be computed. Wrapper of gr_mat_exp.

Sets res to a matrix logarithm of A and returns T_TRUE; returns T_FALSE if A is proved to have no logarithm (it is singular), and T_UNKNOWN if this cannot be decided or the Jordan decomposition fails. The branch is defined by the principal logarithms of the eigenvalues. Wrapper of gr_mat_log.

If all entries of A (and B) are rational numbers or elements of one common field K, returns K (the field \mathbb{Q} if all entries are rational); returns NULL if the entries lie in different fields or one is a special value.