Function: charpoly
Section: linear_algebra
C-Name: charpoly0
Prototype: GDnD3,L,
Help: charpoly(A,{v=x},{flag=3}): det(v*Id-A)=characteristic polynomial of
 the matrix or polmod A. flag is optional and ignored unless A is a matrix;
 it may be set to 0 (Le Verrier), 1
 (Lagrange interpolation) or 2 (use Hessenberg form), 3 (Berkowitz, default).
 All algorithms except flag = 3 (Berkowitz) assume that n! is invertible,
 where n is the dimension of the matrix.
Doc:
 \idx{characteristic polynomial}
 of $A$ with respect to the variable $v$, i.e.~determinant of $v*I-A$ if $A$
 is a square matrix. If $A$ is not a square matrix, it returns the
 characteristic polynomial of the map ``multiplication by $A$'' if $A$ is a
 scalar, in particular a polmod. E.g.~\kbd{charpoly(I) = x\pow2+1}.

 The value of $\fl$ is only significant for matrices. Let $n$ be the dimension
 of $A$.

 If $\fl=0$, same method (Le Verrier's) as for computing the adjoint matrix,
 i.e.~using the traces of the powers of $A$. Assumes that $n!$ is
 invertible; uses $O(n^4)$ scalar operations.

 If $\fl=1$, uses Lagrange interpolation which is usually the slowest method.
 Assumes that $n!$ is invertible; uses $O(n^4)$ scalar operations.

 If $\fl=2$, uses the Hessenberg form. Assumes that the base ring is a field.
 Uses $O(n^3)$ scalar operations, but suffers from coefficient explosion
 unless the base field is finite or $\R$.

 If $\fl=3$, uses Berkowitz's division free algorithm, valid over any
 ring (commutative, with unit). Uses $O(n^4)$ scalar operations.

 If $\fl=4$, $x$ must be integral. Uses a modular algorithm.

 In practice one should use the default (Berkowitz) unless the base ring is
 $\Z$ (use $\fl=4$) or a field where coefficient explosion does not occur,
 e.g.~a finite field or the reals (use $\fl=2$).

Variant: Also available are \fun{GEN}{caract}{GEN A, long v} ($\fl=1$),
 \fun{GEN}{carhess}{GEN A, long v} ($\fl=2$), \fun{GEN}{carberkowitz}{GEN A,
 long v} ($\fl=3$) and \fun{GEN}{caradj}{GEN A, long v, GEN *pt}. In this
 last case, if \var{pt} is not \kbd{NULL}, \kbd{*pt} receives the address of
 the adjoint matrix of $A$ (see \tet{matadjoint}), so both can be obtained at
 once.
