add readme example and bump version

Author: MikaelSlevinsky

Project.toml

@@ -1,6 +1,6 @@
 name = "MatrixFactorizations"
 uuid = "a3b82374-2e81-5b9e-98ce-41277c0e4c87"
-version = "3.1.2"
+version = "3.1.3"
 
 [deps]
 ArrayLayouts = "4c555306-a7a7-4459-81d9-ec55ddd5c99a"

README.md

@@ -23,10 +23,10 @@ MatrixFactorizations.QL{Float64,Array{Float64,2}}
 Q factor:
 5×5 MatrixFactorizations.QLPackedQ{Float64,Array{Float64,2}}:
   0.155574  -0.112555   -0.686362   -0.701064   0.0233276
-  0.363037  -0.0583277  -0.0329428   0.152682   0.916736 
- -0.670742   0.294355   -0.547867    0.347157   0.206843 
- -0.61094   -0.566041    0.324432   -0.353128   0.276396 
-  0.144425  -0.759527   -0.349868    0.489877  -0.199681 
+  0.363037  -0.0583277  -0.0329428   0.152682   0.916736
+ -0.670742   0.294355   -0.547867    0.347157   0.206843
+ -0.61094   -0.566041    0.324432   -0.353128   0.276396
+  0.144425  -0.759527   -0.349868    0.489877  -0.199681
 L factor:
 5×5 Array{Float64,2}:
  -1.75734     0.0         0.0        0.0       0.0   
@@ -38,3 +38,35 @@ L factor:
 julia> b = randn(5); ql(A) \ b ≈ A \ b
 true
 ```
+
+## Jordan canonical form
+
+Every square matrix has a Jordan canonical form. Although Jordan blocks are unstable
+with respect to perturbations, the Jordan canonical form of a rational matrix with
+rational eigenvalues can be found exactly:
+```julia
+
+julia> A = [0 0 1 7 -1; -5 -6 -6 -35 5; 1 1 -7 7 -1; 0 0 0 -9 0; 2 1 -5 -42 -3];
+
+julia> λ = [-9, -7, -7, -1, -1//1];
+
+julia> V, J = jordan(A, λ)
+Jordan{Rational{Int64}, Matrix{Rational{Int64}}, Matrix{Rational{Int64}}}
+Generalized eigenvectors:
+5×5 Matrix{Rational{Int64}}:
+ 0  0   0  1   0
+ 0  1   0  0  -1
+ 0  1  -1  0   0
+ 1  0   0  0   0
+ 7  1  -1  1  -1
+Jordan normal form:
+5×5 Matrix{Rational{Int64}}:
+ -9   0   0   0   0
+  0  -7   1   0   0
+  0   0  -7   0   0
+  0   0   0  -1   1
+  0   0   0   0  -1
+
+julia> A == V*J/V
+true
+```