-- 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
--   <tt>cabal update</tt> and then use <tt>cabal install matrix</tt>,
--   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, <tt>hmatrix</tt>
--   (<a>http://hackage.haskell.org/package/hmatrix</a>) is the way to go.
@package matrix
@version 0.3.6.1


-- | Matrix datatype and operations.
--   
--   Every provided example has been tested. Run <tt>cabal test</tt> 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 <tt>m :: Matrix a</tt> and <tt>i,j :: Int</tt>,
--   then <tt>m ! (i,j)</tt> is the element in the <tt>i</tt>-th row and
--   <tt>j</tt>-th column of <tt>m</tt>.
data Matrix a

-- | Display a matrix as a <a>String</a> using the <a>Show</a> instance of
--   its elements.
prettyMatrix :: Show a => Matrix a -> String

-- | Number of rows.
nrows :: Matrix a -> Int

-- | Number of columns.
ncols :: Matrix a -> Int

-- | <i>O(rows*cols)</i>. Similar to <a>force</a>. It copies the matrix
--   content dropping any extra memory.
--   
--   Useful when using <a>submatrix</a> from a big matrix.
forceMatrix :: Matrix a -> Matrix a

-- | <i>O(rows*cols)</i>. Generate a matrix from a generator function.
--   Example of usage:
--   
--   <pre>
--                                    (  1  0 -1 -2 )
--                                    (  3  2  1  0 )
--                                    (  5  4  3  2 )
--   matrix 4 4 $ \(i,j) -&gt; 2*i - j = (  7  6  5  4 )
--   </pre>
matrix :: Int -> Int -> ((Int, Int) -> a) -> Matrix a

-- | <i>O(1)</i>. Represent a vector as a one row matrix.
rowVector :: Vector a -> Matrix a

-- | <i>O(1)</i>. Represent a vector as a one column matrix.
colVector :: Vector a -> Matrix a

-- | <i>O(rows*cols)</i>. The zero matrix of the given size.
--   
--   <pre>
--   zero n m =
--                   m
--     1 ( 0 0 ... 0 0 )
--     2 ( 0 0 ... 0 0 )
--       (     ...     )
--       ( 0 0 ... 0 0 )
--     n ( 0 0 ... 0 0 )
--   </pre>
zero :: Num a => Int -> Int -> Matrix a

-- | <i>O(rows*cols)</i>. Identity matrix of the given order.
--   
--   <pre>
--   identity n =
--                   n
--     1 ( 1 0 ... 0 0 )
--     2 ( 0 1 ... 0 0 )
--       (     ...     )
--       ( 0 0 ... 1 0 )
--     n ( 0 0 ... 0 1 )
--   </pre>
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 <i>order</i> elements.
--   
--   <pre>
--   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 )
--   </pre>
diagonalList :: Int -> a -> [a] -> Matrix a

-- | Similar to <a>diagonalList</a>, but using <a>Vector</a>, which should
--   be more efficient.
diagonal :: a -> Vector a -> Matrix a

-- | <i>O(rows*cols)</i>. Permutation matrix.
--   
--   <pre>
--   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 )
--   </pre>
--   
--   When <tt>i == j</tt> it reduces to <a>identity</a> <tt>n</tt>.
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 <i>rows*cols</i> elements. An example:
--   
--   <pre>
--                         ( 1 2 3 )
--                         ( 4 5 6 )
--   fromList 3 3 [1..] =  ( 7 8 9 )
--   </pre>
fromList :: Int -> Int -> [a] -> Matrix a

-- | Create a matrix from a non-empty list of non-empty lists. <i>Each list
--   must have at least as many elements as the first list</i>. Examples:
--   
--   <pre>
--   fromLists [ [1,2,3]      ( 1 2 3 )
--             , [4,5,6]      ( 4 5 6 )
--             , [7,8,9] ] =  ( 7 8 9 )
--   </pre>
--   
--   <pre>
--   fromLists [ [1,2,3  ]     ( 1 2 3 )
--             , [4,5,6,7]     ( 4 5 6 )
--             , [8,9,0  ] ] = ( 8 9 0 )
--   </pre>
fromLists :: [[a]] -> Matrix a

-- | Get the elements of a matrix stored in a list.
--   
--   <pre>
--          ( 1 2 3 )
--          ( 4 5 6 )
--   toList ( 7 8 9 ) = [1,2,3,4,5,6,7,8,9]
--   </pre>
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.
--   
--   <pre>
--           ( 1 2 3 )   [ [1,2,3]
--           ( 4 5 6 )   , [4,5,6]
--   toLists ( 7 8 9 ) = , [7,8,9] ]
--   </pre>
toLists :: Matrix a -> [[a]]

-- | <i>O(1)</i>. Get an element of a matrix. Indices range from
--   <i>(1,1)</i> to <i>(n,m)</i>. It returns an <a>error</a> if the
--   requested element is outside of range.
getElem :: Int -> Int -> Matrix a -> a

-- | Short alias for <a>getElem</a>.
(!) :: Matrix a -> (Int, Int) -> a

-- | <i>O(1)</i>. Unsafe variant of <a>getElem</a>, without bounds
--   checking.
unsafeGet :: Int -> Int -> Matrix a -> a

-- | Variant of <a>getElem</a> that returns Maybe instead of an error.
safeGet :: Int -> Int -> Matrix a -> Maybe a

-- | Variant of <a>setElem</a> that returns Maybe instead of an error.
safeSet :: a -> (Int, Int) -> Matrix a -> Maybe (Matrix a)

-- | <i>O(1)</i>. Get a row of a matrix as a vector.
getRow :: Int -> Matrix a -> Vector a

-- | Varian of <a>getRow</a> that returns a maybe instead of an error
safeGetRow :: Int -> Matrix a -> Maybe (Vector a)

-- | <i>O(rows)</i>. Get a column of a matrix as a vector.
getCol :: Int -> Matrix a -> Vector a

-- | Varian of <tt>getColumn</tt> that returns a maybe instead of an error
safeGetCol :: Int -> Matrix a -> Maybe (Vector a)

-- | <i>O(min rows cols)</i>. Diagonal of a <i>not necessarily square</i>
--   matrix.
getDiag :: Matrix a -> Vector a

-- | <i>O(rows*cols)</i>. Transform a <a>Matrix</a> to a <a>Vector</a> of
--   size <i>rows*cols</i>. This is equivalent to get all the rows of the
--   matrix using <a>getRow</a> 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 <a>setElem</a>, without bounds checking.
unsafeSet :: a -> (Int, Int) -> Matrix a -> Matrix a

-- | <i>O(rows*cols)</i>. The transpose of a matrix. Example:
--   
--   <pre>
--             ( 1 2 3 )   ( 1 4 7 )
--             ( 4 5 6 )   ( 2 5 8 )
--   transpose ( 7 8 9 ) = ( 3 6 9 )
--   </pre>
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
--   <i>never</i> reduced in size. Example:
--   
--   <pre>
--                              ( 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 )
--   </pre>
--   
--   The definition of <a>extendTo</a> is based on <a>setSize</a>:
--   
--   <pre>
--   extendTo e n m a = setSize e (max n $ nrows a) (max m $ ncols a) a
--   </pre>
extendTo :: a -> Int -> Int -> Matrix a -> Matrix a

-- | <i>O(rows*rows*rows*rows) = O(cols*cols*cols*cols)</i>. The inverse of
--   a square matrix. Uses naive Gaussian elimination formula.
inverse :: (Fractional a, Eq a) => Matrix a -> Either String (Matrix a)

-- | <i>O(rows*rows*cols*cols)</i>. Converts a matrix to reduced row
--   echelon form, thus solving a linear system of equations. This requires
--   that (cols &gt; rows) if cols &lt; 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).
rref :: (Fractional a, Eq a) => Matrix a -> Either String (Matrix a)

-- | <i>O(rows*cols)</i>. Map a function over a row. Example:
--   
--   <pre>
--                            ( 1 2 3 )   ( 1 2 3 )
--                            ( 4 5 6 )   ( 5 6 7 )
--   mapRow (\_ x -&gt; x + 1) 2 ( 7 8 9 ) = ( 7 8 9 )
--   </pre>
mapRow :: (Int -> a -> a) -> Int -> Matrix a -> Matrix a

-- | <i>O(rows*cols)</i>. Map a function over a column. Example:
--   
--   <pre>
--                            ( 1 2 3 )   ( 1 3 3 )
--                            ( 4 5 6 )   ( 4 6 6 )
--   mapCol (\_ x -&gt; x + 1) 2 ( 7 8 9 ) = ( 7 9 9 )
--   </pre>
mapCol :: (Int -> a -> a) -> Int -> Matrix a -> Matrix a

-- | <i>O(rows*cols)</i>. Map a function over elements. Example:
--   
--   <pre>
--                              ( 1 2 3 )   ( 0 -1 -2 )
--                              ( 4 5 6 )   ( 1  0 -1 )
--   mapPos (\(r,c) a -&gt; r - c) ( 7 8 9 ) = ( 2  1  0 )
--   </pre>
mapPos :: ((Int, Int) -> a -> b) -> Matrix a -> Matrix b

-- | <i>O(1)</i>. Extract a submatrix given row and column limits. Example:
--   
--   <pre>
--                     ( 1 2 3 )
--                     ( 4 5 6 )   ( 2 3 )
--   submatrix 1 2 2 3 ( 7 8 9 ) = ( 5 6 )
--   </pre>
submatrix :: Int -> Int -> Int -> Int -> Matrix a -> Matrix a

-- | <i>O(rows*cols)</i>. Remove a row and a column from a matrix. Example:
--   
--   <pre>
--                   ( 1 2 3 )
--                   ( 4 5 6 )   ( 1 3 )
--   minorMatrix 2 2 ( 7 8 9 ) = ( 7 9 )
--   </pre>
minorMatrix :: Int -> Int -> Matrix a -> Matrix a

-- | <i>O(1)</i>. 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.
--   
--   <pre>
--                   (             )   (      |      )
--                   (             )   ( ...  | ...  )
--                   (    x        )   (    x |      )
--   splitBlocks i j (             ) = (-------------) , where x = a_{i,j}
--                   (             )   (      |      )
--                   (             )   ( ...  | ...  )
--                   (             )   (      |      )
--   </pre>
--   
--   Note that some blocks can end up empty. We use the following notation
--   for these blocks:
--   
--   <pre>
--   ( TL | TR )
--   (---------)
--   ( BL | BR )
--   </pre>
--   
--   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:
--   
--   <pre>
--   ( A ) &lt;|&gt; ( B ) = ( A | B )
--   </pre>
--   
--   Where both matrices <i>A</i> and <i>B</i> have the same number of
--   rows. <i>This condition is not checked</i>.
(<|>) :: Matrix a -> Matrix a -> Matrix a

-- | Vertically join two matrices. Visually:
--   
--   <pre>
--                     ( A )
--   ( A ) &lt;-&gt; ( B ) = ( - )
--                     ( B )
--   </pre>
--   
--   Where both matrices <i>A</i> and <i>B</i> have the same number of
--   columns. <i>This condition is not checked</i>.
(<->) :: Matrix a -> Matrix a -> Matrix a

-- | Join blocks of the form detailed in <a>splitBlocks</a>. Precisely:
--   
--   <pre>
--   joinBlocks (tl,tr,bl,br) =
--     (tl &lt;|&gt; tr)
--         &lt;-&gt;
--     (bl &lt;|&gt; br)
--   </pre>
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 <a>elementwiseUnsafe</a> 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 <a>elementwise</a>, 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:
--   
--   <pre>
--                 ( 1 2 3 )   (  2  4  6 )
--                 ( 4 5 6 )   (  8 10 12 )
--   scaleMatrix 2 ( 7 8 9 ) = ( 14 16 18 )
--   </pre>
scaleMatrix :: Num a => a -> Matrix a -> Matrix a

-- | Scale a row by a given factor. Example:
--   
--   <pre>
--                ( 1 2 3 )   (  1  2  3 )
--                ( 4 5 6 )   (  8 10 12 )
--   scaleRow 2 2 ( 7 8 9 ) = (  7  8  9 )
--   </pre>
scaleRow :: Num a => a -> Int -> Matrix a -> Matrix a

-- | Add to one row a scalar multiple of another row. Example:
--   
--   <pre>
--                     ( 1 2 3 )   (  1  2  3 )
--                     ( 4 5 6 )   (  6  9 12 )
--   combineRows 2 2 1 ( 7 8 9 ) = (  7  8  9 )
--   </pre>
combineRows :: Num a => Int -> a -> Int -> Matrix a -> Matrix a

-- | Switch two rows of a matrix. Example:
--   
--   <pre>
--                  ( 1 2 3 )   ( 4 5 6 )
--                  ( 4 5 6 )   ( 1 2 3 )
--   switchRows 1 2 ( 7 8 9 ) = ( 7 8 9 )
--   </pre>
switchRows :: Int -> Int -> Matrix a -> Matrix a

-- | Switch two coumns of a matrix. Example:
--   
--   <pre>
--                  ( 1 2 3 )   ( 2 1 3 )
--                  ( 4 5 6 )   ( 5 4 6 )
--   switchCols 1 2 ( 7 8 9 ) = ( 8 7 9 )
--   </pre>
switchCols :: Int -> Int -> Matrix a -> Matrix a

-- | Matrix LU decomposition with <i>partial pivoting</i>. The result for a
--   matrix <i>M</i> is given in the format <i>(U,L,P,d)</i> where:
--   
--   <ul>
--   <li><i>U</i> is an upper triangular matrix.</li>
--   <li><i>L</i> is an <i>unit</i> lower triangular matrix.</li>
--   <li><i>P</i> is a permutation matrix.</li>
--   <li><i>d</i> is the determinant of <i>P</i>.</li>
--   <li><i>PM = LU</i>.</li>
--   </ul>
--   
--   These properties are only guaranteed when the input matrix is
--   invertible. An additional property matches thanks to the strategy
--   followed for pivoting:
--   
--   <ul>
--   <li><i>L_(i,j)</i> &lt;= 1, for all <i>i,j</i>.</li>
--   </ul>
--   
--   This follows from the maximal property of the selected pivots, which
--   also leads to a better numerical stability of the algorithm.
--   
--   Example:
--   
--   <pre>
--            ( 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 )
--   </pre>
--   
--   <a>Nothing</a> 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 <a>luDecomp</a>. 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 <i>complete pivoting</i>. The result for
--   a matrix <i>M</i> is given in the format <i>(U,L,P,Q,d,e)</i> where:
--   
--   <ul>
--   <li><i>U</i> is an upper triangular matrix.</li>
--   <li><i>L</i> is an <i>unit</i> lower triangular matrix.</li>
--   <li><i>P,Q</i> are permutation matrices.</li>
--   <li><i>d,e</i> are the determinants of <i>P</i> and <i>Q</i>
--   respectively.</li>
--   <li><i>PMQ = LU</i>.</li>
--   </ul>
--   
--   These properties are only guaranteed when the input matrix is
--   invertible. An additional property matches thanks to the strategy
--   followed for pivoting:
--   
--   <ul>
--   <li><i>L_(i,j)</i> &lt;= 1, for all <i>i,j</i>.</li>
--   </ul>
--   
--   This follows from the maximal property of the selected pivots, which
--   also leads to a better numerical stability of the algorithm.
--   
--   Example:
--   
--   <pre>
--             ( 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 )
--   </pre>
--   
--   <a>Nothing</a> 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 <a>luDecomp'</a>. 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 <i>M</i> is a lower triangular matrix
--   <i>L</i> such that:
--   
--   <ul>
--   <li><i>M = LL^T</i>.</li>
--   </ul>
--   
--   Example:
--   
--   <pre>
--              (  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 )
--   </pre>
cholDecomp :: Floating a => Matrix a -> Matrix a

-- | Sum of the elements in the diagonal. See also <a>getDiag</a>. Example:
--   
--   <pre>
--         ( 1 2 3 )
--         ( 4 5 6 )
--   trace ( 7 8 9 ) = 15
--   </pre>
trace :: Num a => Matrix a -> a

-- | Product of the elements in the diagonal. See also <a>getDiag</a>.
--   Example:
--   
--   <pre>
--            ( 1 2 3 )
--            ( 4 5 6 )
--   diagProd ( 7 8 9 ) = 45
--   </pre>
diagProd :: Num a => Matrix a -> a

-- | Matrix determinant using Laplace expansion. If the elements of the
--   <a>Matrix</a> are instance of <a>Ord</a> and <a>Fractional</a>
--   consider to use <a>detLU</a> in order to obtain better performance.
--   Function <a>detLaplace</a> is <i>extremely</i> 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)
