-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A native implementation of matrix operations.
--
-- Matrix library. Basic operations and some algorithms. . Usage examples
-- are included in the API reference generated by Haddock. . If you want
-- to use GSL, BLAS and LAPACK, hmatrix
-- (http://hackage.haskell.org/package/hmatrix) is the way to go.
@package matrix
@version 0.3.6.2
-- | Matrix datatype and operations.
--
-- Every provided example has been tested. Run cabal test for
-- further tests.
module Data.Matrix
-- | Type of matrices.
--
-- Elements can be of any type. Rows and columns are indexed starting by
-- 1. This means that, if m :: Matrix a and i,j :: Int,
-- then m ! (i,j) is the element in the i-th row and
-- j-th column of m.
data Matrix a
-- | Display a matrix as a String using the Show instance of
-- its elements.
prettyMatrix :: Show a => Matrix a -> String
-- | Number of rows.
nrows :: Matrix a -> Int
-- | Number of columns.
ncols :: Matrix a -> Int
-- | O(rows*cols). Similar to force. It copies the matrix
-- content dropping any extra memory.
--
-- Useful when using submatrix from a big matrix.
forceMatrix :: Matrix a -> Matrix a
-- | O(rows*cols). Generate a matrix from a generator function.
-- Example of usage:
--
--
-- ( 1 0 -1 -2 )
-- ( 3 2 1 0 )
-- ( 5 4 3 2 )
-- matrix 4 4 $ \(i,j) -> 2*i - j = ( 7 6 5 4 )
--
matrix :: Int -> Int -> ((Int, Int) -> a) -> Matrix a
-- | O(1). Represent a vector as a one row matrix.
rowVector :: Vector a -> Matrix a
-- | O(1). Represent a vector as a one column matrix.
colVector :: Vector a -> Matrix a
-- | O(rows*cols). The zero matrix of the given size.
--
--
-- zero n m =
-- m
-- 1 ( 0 0 ... 0 0 )
-- 2 ( 0 0 ... 0 0 )
-- ( ... )
-- ( 0 0 ... 0 0 )
-- n ( 0 0 ... 0 0 )
--
zero :: Num a => Int -> Int -> Matrix a
-- | O(rows*cols). Identity matrix of the given order.
--
--
-- identity n =
-- n
-- 1 ( 1 0 ... 0 0 )
-- 2 ( 0 1 ... 0 0 )
-- ( ... )
-- ( 0 0 ... 1 0 )
-- n ( 0 0 ... 0 1 )
--
identity :: Num a => Int -> Matrix a
-- | Diagonal matrix from a non-empty list given the desired size.
-- Non-diagonal elements will be filled with the given default element.
-- The list must have at least order elements.
--
--
-- diagonalList n 0 [1..] =
-- n
-- 1 ( 1 0 ... 0 0 )
-- 2 ( 0 2 ... 0 0 )
-- ( ... )
-- ( 0 0 ... n-1 0 )
-- n ( 0 0 ... 0 n )
--
diagonalList :: Int -> a -> [a] -> Matrix a
-- | Similar to diagonalList, but using Vector, which should
-- be more efficient.
diagonal :: a -> Vector a -> Matrix a
-- | O(rows*cols). Permutation matrix.
--
--
-- permMatrix n i j =
-- i j n
-- 1 ( 1 0 ... 0 ... 0 ... 0 0 )
-- 2 ( 0 1 ... 0 ... 0 ... 0 0 )
-- ( ... ... ... )
-- i ( 0 0 ... 0 ... 1 ... 0 0 )
-- ( ... ... ... )
-- j ( 0 0 ... 1 ... 0 ... 0 0 )
-- ( ... ... ... )
-- ( 0 0 ... 0 ... 0 ... 1 0 )
-- n ( 0 0 ... 0 ... 0 ... 0 1 )
--
--
-- When i == j it reduces to identity n.
permMatrix :: Num a => Int -> Int -> Int -> Matrix a
-- | Create a matrix from a non-empty list given the desired size. The list
-- must have at least rows*cols elements. An example:
--
--
-- ( 1 2 3 )
-- ( 4 5 6 )
-- fromList 3 3 [1..] = ( 7 8 9 )
--
fromList :: Int -> Int -> [a] -> Matrix a
-- | Create a matrix from a non-empty list of non-empty lists. Each list
-- must have at least as many elements as the first list. Examples:
--
--
-- fromLists [ [1,2,3] ( 1 2 3 )
-- , [4,5,6] ( 4 5 6 )
-- , [7,8,9] ] = ( 7 8 9 )
--
--
--
-- fromLists [ [1,2,3 ] ( 1 2 3 )
-- , [4,5,6,7] ( 4 5 6 )
-- , [8,9,0 ] ] = ( 8 9 0 )
--
fromLists :: [[a]] -> Matrix a
-- | Get the elements of a matrix stored in a list.
--
--
-- ( 1 2 3 )
-- ( 4 5 6 )
-- toList ( 7 8 9 ) = [1,2,3,4,5,6,7,8,9]
--
toList :: Matrix a -> [a]
-- | Get the elements of a matrix stored in a list of lists, where each
-- list contains the elements of a single row.
--
--
-- ( 1 2 3 ) [ [1,2,3]
-- ( 4 5 6 ) , [4,5,6]
-- toLists ( 7 8 9 ) = , [7,8,9] ]
--
toLists :: Matrix a -> [[a]]
-- | O(1). Get an element of a matrix. Indices range from
-- (1,1) to (n,m). It returns an error if the
-- requested element is outside of range.
getElem :: Int -> Int -> Matrix a -> a
-- | Short alias for getElem.
(!) :: Matrix a -> (Int, Int) -> a
-- | O(1). Unsafe variant of getElem, without bounds
-- checking.
unsafeGet :: Int -> Int -> Matrix a -> a
-- | Variant of getElem that returns Maybe instead of an error.
safeGet :: Int -> Int -> Matrix a -> Maybe a
-- | Variant of setElem that returns Maybe instead of an error.
safeSet :: a -> (Int, Int) -> Matrix a -> Maybe (Matrix a)
-- | O(1). Get a row of a matrix as a vector.
getRow :: Int -> Matrix a -> Vector a
-- | Varian of getRow that returns a maybe instead of an error
safeGetRow :: Int -> Matrix a -> Maybe (Vector a)
-- | O(rows). Get a column of a matrix as a vector.
getCol :: Int -> Matrix a -> Vector a
-- | Varian of getColumn that returns a maybe instead of an error
safeGetCol :: Int -> Matrix a -> Maybe (Vector a)
-- | O(min rows cols). Diagonal of a not necessarily square
-- matrix.
getDiag :: Matrix a -> Vector a
-- | O(rows*cols). Transform a Matrix to a Vector of
-- size rows*cols. This is equivalent to get all the rows of the
-- matrix using getRow and then append them, but far more
-- efficient.
getMatrixAsVector :: Matrix a -> Vector a
-- | Replace the value of a cell in a matrix.
setElem :: a -> (Int, Int) -> Matrix a -> Matrix a
-- | Unsafe variant of setElem, without bounds checking.
unsafeSet :: a -> (Int, Int) -> Matrix a -> Matrix a
-- | O(rows*cols). The transpose of a matrix. Example:
--
--
-- ( 1 2 3 ) ( 1 4 7 )
-- ( 4 5 6 ) ( 2 5 8 )
-- transpose ( 7 8 9 ) = ( 3 6 9 )
--
transpose :: Matrix a -> Matrix a
-- | Set the size of a matrix to given parameters. Use a default element
-- for undefined entries if the matrix has been extended.
setSize :: a -> Int -> Int -> Matrix a -> Matrix a
-- | Extend a matrix to a given size adding a default element. If the
-- matrix already has the required size, nothing happens. The matrix is
-- never reduced in size. Example:
--
--
-- ( 1 2 3 0 0 )
-- ( 1 2 3 ) ( 4 5 6 0 0 )
-- ( 4 5 6 ) ( 7 8 9 0 0 )
-- extendTo 0 4 5 ( 7 8 9 ) = ( 0 0 0 0 0 )
--
--
-- The definition of extendTo is based on setSize:
--
--
-- extendTo e n m a = setSize e (max n $ nrows a) (max m $ ncols a) a
--
extendTo :: a -> Int -> Int -> Matrix a -> Matrix a
-- | O(rows*rows*rows*rows) = O(cols*cols*cols*cols). The inverse of
-- a square matrix. Uses naive Gaussian elimination formula.
inverse :: (Fractional a, Eq a) => Matrix a -> Either String (Matrix a)
-- | Converts a matrix to reduced row echelon form, thus solving a linear
-- system of equations. This requires that (cols > rows) if cols <
-- rows, then there are fewer variables than equations and the problem
-- cannot be solved consistently. If rows = cols, then it is basically a
-- homogenous system of equations, so it will be reduced to identity or
-- an error depending on whether the marix is invertible (this case is
-- allowed for robustness). This implementation is taken from rosettacode
-- https://rosettacode.org/wiki/Reduced_row_echelon_form#Haskell
rref :: (Fractional a, Eq a) => Matrix a -> Either String (Matrix a)
-- | O(rows*cols). Map a function over a row. Example:
--
--
-- ( 1 2 3 ) ( 1 2 3 )
-- ( 4 5 6 ) ( 5 6 7 )
-- mapRow (\_ x -> x + 1) 2 ( 7 8 9 ) = ( 7 8 9 )
--
mapRow :: (Int -> a -> a) -> Int -> Matrix a -> Matrix a
-- | O(rows*cols). Map a function over a column. Example:
--
--
-- ( 1 2 3 ) ( 1 3 3 )
-- ( 4 5 6 ) ( 4 6 6 )
-- mapCol (\_ x -> x + 1) 2 ( 7 8 9 ) = ( 7 9 9 )
--
mapCol :: (Int -> a -> a) -> Int -> Matrix a -> Matrix a
-- | O(rows*cols). Map a function over elements. Example:
--
--
-- ( 1 2 3 ) ( 0 -1 -2 )
-- ( 4 5 6 ) ( 1 0 -1 )
-- mapPos (\(r,c) a -> r - c) ( 7 8 9 ) = ( 2 1 0 )
--
mapPos :: ((Int, Int) -> a -> b) -> Matrix a -> Matrix b
-- | O(1). Extract a submatrix given row and column limits. Example:
--
--
-- ( 1 2 3 )
-- ( 4 5 6 ) ( 2 3 )
-- submatrix 1 2 2 3 ( 7 8 9 ) = ( 5 6 )
--
submatrix :: Int -> Int -> Int -> Int -> Matrix a -> Matrix a
-- | O(rows*cols). Remove a row and a column from a matrix. Example:
--
--
-- ( 1 2 3 )
-- ( 4 5 6 ) ( 1 3 )
-- minorMatrix 2 2 ( 7 8 9 ) = ( 7 9 )
--
minorMatrix :: Int -> Int -> Matrix a -> Matrix a
-- | O(1). Make a block-partition of a matrix using a given element
-- as reference. The element will stay in the bottom-right corner of the
-- top-left corner matrix.
--
--
-- ( ) ( | )
-- ( ) ( ... | ... )
-- ( x ) ( x | )
-- splitBlocks i j ( ) = (-------------) , where x = a_{i,j}
-- ( ) ( | )
-- ( ) ( ... | ... )
-- ( ) ( | )
--
--
-- Note that some blocks can end up empty. We use the following notation
-- for these blocks:
--
--
-- ( TL | TR )
-- (---------)
-- ( BL | BR )
--
--
-- Where T = Top, B = Bottom, L = Left, R = Right.
splitBlocks :: Int -> Int -> Matrix a -> (Matrix a, Matrix a, Matrix a, Matrix a)
-- | Horizontally join two matrices. Visually:
--
--
-- ( A ) <|> ( B ) = ( A | B )
--
--
-- Where both matrices A and B have the same number of
-- rows. This condition is not checked.
(<|>) :: Matrix a -> Matrix a -> Matrix a
-- | Vertically join two matrices. Visually:
--
--
-- ( A )
-- ( A ) <-> ( B ) = ( - )
-- ( B )
--
--
-- Where both matrices A and B have the same number of
-- columns. This condition is not checked.
(<->) :: Matrix a -> Matrix a -> Matrix a
-- | Join blocks of the form detailed in splitBlocks. Precisely:
--
--
-- joinBlocks (tl,tr,bl,br) =
-- (tl <|> tr)
-- <->
-- (bl <|> br)
--
joinBlocks :: (Matrix a, Matrix a, Matrix a, Matrix a) -> Matrix a
-- | Perform an operation element-wise. The second matrix must have at
-- least as many rows and columns as the first matrix. If it's bigger,
-- the leftover items will be ignored. If it's smaller, it will cause a
-- run-time error. You may want to use elementwiseUnsafe if you
-- are definitely sure that a run-time error won't arise.
elementwise :: (a -> b -> c) -> Matrix a -> Matrix b -> Matrix c
-- | Unsafe version of elementwise, but faster.
elementwiseUnsafe :: (a -> b -> c) -> Matrix a -> Matrix b -> Matrix c
-- | Standard matrix multiplication by definition.
multStd :: Num a => Matrix a -> Matrix a -> Matrix a
-- | Standard matrix multiplication by definition.
multStd2 :: Num a => Matrix a -> Matrix a -> Matrix a
-- | Strassen's matrix multiplication.
multStrassen :: Num a => Matrix a -> Matrix a -> Matrix a
-- | Mixed Strassen's matrix multiplication.
multStrassenMixed :: Num a => Matrix a -> Matrix a -> Matrix a
-- | Scale a matrix by a given factor. Example:
--
--
-- ( 1 2 3 ) ( 2 4 6 )
-- ( 4 5 6 ) ( 8 10 12 )
-- scaleMatrix 2 ( 7 8 9 ) = ( 14 16 18 )
--
scaleMatrix :: Num a => a -> Matrix a -> Matrix a
-- | Scale a row by a given factor. Example:
--
--
-- ( 1 2 3 ) ( 1 2 3 )
-- ( 4 5 6 ) ( 8 10 12 )
-- scaleRow 2 2 ( 7 8 9 ) = ( 7 8 9 )
--
scaleRow :: Num a => a -> Int -> Matrix a -> Matrix a
-- | Add to one row a scalar multiple of another row. Example:
--
--
-- ( 1 2 3 ) ( 1 2 3 )
-- ( 4 5 6 ) ( 6 9 12 )
-- combineRows 2 2 1 ( 7 8 9 ) = ( 7 8 9 )
--
combineRows :: Num a => Int -> a -> Int -> Matrix a -> Matrix a
-- | Switch two rows of a matrix. Example:
--
--
-- ( 1 2 3 ) ( 4 5 6 )
-- ( 4 5 6 ) ( 1 2 3 )
-- switchRows 1 2 ( 7 8 9 ) = ( 7 8 9 )
--
switchRows :: Int -> Int -> Matrix a -> Matrix a
-- | Switch two coumns of a matrix. Example:
--
--
-- ( 1 2 3 ) ( 2 1 3 )
-- ( 4 5 6 ) ( 5 4 6 )
-- switchCols 1 2 ( 7 8 9 ) = ( 8 7 9 )
--
switchCols :: Int -> Int -> Matrix a -> Matrix a
-- | Matrix LU decomposition with partial pivoting. The result for a
-- matrix M is given in the format (U,L,P,d) where:
--
--
-- - U is an upper triangular matrix.
-- - L is an unit lower triangular matrix.
-- - P is a permutation matrix.
-- - d is the determinant of P.
-- - PM = LU.
--
--
-- These properties are only guaranteed when the input matrix is
-- invertible. An additional property matches thanks to the strategy
-- followed for pivoting:
--
--
-- - L_(i,j) <= 1, for all i,j.
--
--
-- This follows from the maximal property of the selected pivots, which
-- also leads to a better numerical stability of the algorithm.
--
-- Example:
--
--
-- ( 1 2 0 ) ( 2 0 2 ) ( 1 0 0 ) ( 0 0 1 )
-- ( 0 2 1 ) ( 0 2 -1 ) ( 1/2 1 0 ) ( 1 0 0 )
-- luDecomp ( 2 0 2 ) = ( ( 0 0 2 ) , ( 0 1 1 ) , ( 0 1 0 ) , 1 )
--
--
-- Nothing is returned if no LU decomposition exists.
luDecomp :: (Ord a, Fractional a) => Matrix a -> Maybe (Matrix a, Matrix a, Matrix a, a)
-- | Unsafe version of luDecomp. It fails when the input matrix is
-- singular.
luDecompUnsafe :: (Ord a, Fractional a) => Matrix a -> (Matrix a, Matrix a, Matrix a, a)
-- | Matrix LU decomposition with complete pivoting. The result for
-- a matrix M is given in the format (U,L,P,Q,d,e) where:
--
--
-- - U is an upper triangular matrix.
-- - L is an unit lower triangular matrix.
-- - P,Q are permutation matrices.
-- - d,e are the determinants of P and Q
-- respectively.
-- - PMQ = LU.
--
--
-- These properties are only guaranteed when the input matrix is
-- invertible. An additional property matches thanks to the strategy
-- followed for pivoting:
--
--
-- - L_(i,j) <= 1, for all i,j.
--
--
-- This follows from the maximal property of the selected pivots, which
-- also leads to a better numerical stability of the algorithm.
--
-- Example:
--
--
-- ( 1 0 ) ( 2 1 ) ( 1 0 0 ) ( 0 0 1 )
-- ( 0 2 ) ( 0 2 ) ( 0 1 0 ) ( 0 1 0 ) ( 1 0 )
-- luDecomp' ( 2 1 ) = ( ( 0 0 ) , ( 1/2 -1/4 1 ) , ( 1 0 0 ) , ( 0 1 ) , -1 , 1 )
--
--
-- Nothing is returned if no LU decomposition exists.
luDecomp' :: (Ord a, Fractional a) => Matrix a -> Maybe (Matrix a, Matrix a, Matrix a, Matrix a, a, a)
-- | Unsafe version of luDecomp'. It fails when the input matrix is
-- singular.
luDecompUnsafe' :: (Ord a, Fractional a) => Matrix a -> (Matrix a, Matrix a, Matrix a, Matrix a, a, a)
-- | Simple Cholesky decomposition of a symmetric, positive definite
-- matrix. The result for a matrix M is a lower triangular matrix
-- L such that:
--
--
--
-- Example:
--
--
-- ( 2 -1 0 ) ( 1.41 0 0 )
-- ( -1 2 -1 ) ( -0.70 1.22 0 )
-- cholDecomp ( 0 -1 2 ) = ( 0.00 -0.81 1.15 )
--
cholDecomp :: Floating a => Matrix a -> Matrix a
-- | Sum of the elements in the diagonal. See also getDiag. Example:
--
--
-- ( 1 2 3 )
-- ( 4 5 6 )
-- trace ( 7 8 9 ) = 15
--
trace :: Num a => Matrix a -> a
-- | Product of the elements in the diagonal. See also getDiag.
-- Example:
--
--
-- ( 1 2 3 )
-- ( 4 5 6 )
-- diagProd ( 7 8 9 ) = 45
--
diagProd :: Num a => Matrix a -> a
-- | Matrix determinant using Laplace expansion. If the elements of the
-- Matrix are instance of Ord and Fractional
-- consider to use detLU in order to obtain better performance.
-- Function detLaplace is extremely slow.
detLaplace :: Num a => Matrix a -> a
-- | Matrix determinant using LU decomposition. It works even when the
-- input matrix is singular.
detLU :: (Ord a, Fractional a) => Matrix a -> a
-- | Flatten a matrix of matrices. All sub matrices must have same
-- dimensions This criteria is not checked.
flatten :: Matrix (Matrix a) -> Matrix a
instance GHC.Generics.Generic (Data.Matrix.Matrix a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Matrix.Matrix a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Matrix.Matrix a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Matrix.Matrix a)
instance GHC.Base.Functor Data.Matrix.Matrix
instance GHC.Base.Monoid a => GHC.Base.Semigroup (Data.Matrix.Matrix a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Data.Matrix.Matrix a)
instance GHC.Base.Applicative Data.Matrix.Matrix
instance Data.Foldable.Foldable Data.Matrix.Matrix
instance Data.Traversable.Traversable Data.Matrix.Matrix
instance GHC.Num.Num a => GHC.Num.Num (Data.Matrix.Matrix a)