-- 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.
--
-- To get the library update your cabal package list (if needed) with
-- cabal update and then use cabal install matrix,
-- assuming that you already have Cabal installed. 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.1.0
-- | Matrix datatype and operations.
--
-- Every provided example has been tested. Run cabal test for
-- further tests.
module Data.Matrix
-- | Type of matrices.
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, drop 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
-- | 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 an non-empty list of non-empty lists. Each
-- list must have the same number of elements. For example:
--
--
-- fromLists [ [1,2,3] ( 1 2 3 )
-- , [4,5,6] ( 4 5 6 )
-- , [7,8,9] ] = ( 7 8 9 )
--
fromLists :: [[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 =
-- n
-- 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
-- | 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
-- | O(1). Get an element of a matrix. Indices range from
-- (1,1) to (n,m).
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
-- | O(1). Get a row of a matrix as a vector.
getRow :: Int -> Matrix a -> Vector a
-- | O(rows). Get a column of a matrix as a vector.
getCol :: Int -> Matrix a -> Vector a
-- | O(min rows cols). Diagonal of a not necessarily square
-- matrix.
getDiag :: Matrix a -> Vector a
-- | O(1). 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
-- | O(1). Replace the value of a cell in a matrix.
setElem :: a -> (Int, Int) -> Matrix a -> Matrix a
-- | O(1). 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 )
--
extendTo :: a -> Int -> Int -> Matrix a -> 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(subrows*subcols). 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
-- | 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.
--
-- Implementation is done via slicing of vectors.
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.
joinBlocks :: (Matrix a, Matrix a, Matrix a, Matrix a) -> Matrix a
-- | Perform an operation elementwise. The input matrices are assumed to
-- have the same dimensions, but this is not checked.
elementwise :: (a -> b -> c) -> (Matrix a -> Matrix b -> Matrix c)
-- | Standard matrix multiplication by definition.
multStd :: 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 other 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 )
--
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 )
--
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
instance Eq a => Eq (Matrix a)
instance Num a => Num (Matrix a)
instance Traversable Matrix
instance Foldable Matrix
instance Functor Matrix
instance NFData a => NFData (Matrix a)
instance Show a => Show (Matrix a)