# Documentation

## Jordan Canonical Form

The Jordan canonical form results from attempts to convert a matrix to its diagonal form by a similarity transformation. For a given matrix `A`, find a nonsingular matrix `V`, so that `inv(V)*A*V`, or, more succinctly, ```J = V\A*V```, is "as close to diagonal as possible." For almost all matrices, the Jordan canonical form is the diagonal matrix of eigenvalues and the columns of the transformation matrix are the eigenvectors. This always happens if the matrix is symmetric or if it has distinct eigenvalues. Some nonsymmetric matrices with multiple eigenvalues cannot be converted to diagonal forms. The Jordan form has the eigenvalues on its diagonal, but some of the superdiagonal elements are one, instead of zero. The statement

`J = jordan(A)`

computes the Jordan canonical form of `A`. The statement

`[V,J] = jordan(A)`

also computes the similarity transformation. The columns of `V` are the generalized eigenvectors of `A`.

The Jordan form is extremely sensitive to perturbations. Almost any change in `A` causes its Jordan form to be diagonal. This makes it very difficult to compute the Jordan form reliably with floating-point arithmetic. It also implies that `A` must be known exactly (i.e., without round-off error, etc.). Its elements must be integers, or ratios of small integers. In particular, the variable-precision calculation, `jordan(vpa(A))`, is not allowed.

For example, let

```A = sym([12,32,66,116;-25,-76,-164,-294; 21,66,143,256;-6,-19,-41,-73])```
```A = [ 12, 32, 66, 116] [ -25, -76, -164, -294] [ 21, 66, 143, 256] [ -6, -19, -41, -73]```

Then

`[V,J] = jordan(A)`

produces

```V = [ 4, -2, 4, 3] [ -6, 8, -11, -8] [ 4, -7, 10, 7] [ -1, 2, -3, -2] J = [ 1, 1, 0, 0] [ 0, 1, 0, 0] [ 0, 0, 2, 1] [ 0, 0, 0, 2]```

Therefore `A` has a double eigenvalue at 1, with a single Jordan block, and a double eigenvalue at 2, also with a single Jordan block. The matrix has only two eigenvectors, `V(:,1)` and `V(:,3)`. They satisfy

```A*V(:,1) = 1*V(:,1) A*V(:,3) = 2*V(:,3)```

The other two columns of `V` are generalized eigenvectors of grade 2. They satisfy

```A*V(:,2) = 1*V(:,2) + V(:,1) A*V(:,4) = 2*V(:,4) + V(:,3)```

In mathematical notation, with `v`j = `v(:,j)`, the columns of `V` and eigenvalues satisfy the relationships

`$\left(A-{\lambda }_{1}I\right){v}_{2}={v}_{1}$`
`$\left(A-{\lambda }_{2}I\right){v}_{4}={v}_{3}.$`