-- 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.2


-- | Matrix datatype and operations.
--   
--   Every provided example has been tested.
module Data.Matrix

-- | Type of matrices.
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>, drop any extra memory.
--   
--   Useful when using <a>submatrix</a> from a big matrix.
forceMatrix :: Matrix a -> Matrix a

-- | 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

-- | Create a matrix from an non-empty list of non-empty lists. <i>Each
--   list must have the same number of elements</i>. For example:
--   
--   <pre>
--   fromLists [ [1,2,3]      ( 1 2 3 )
--             , [4,5,6]      ( 4 5 6 )
--             , [7,8,9] ] =  ( 7 8 9 )
--   </pre>
fromLists :: [[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

-- | The zero matrix of the given size.
--   
--   <pre>
--   zero n m =
--                   n
--     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

-- | 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

-- | 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

-- | <i>O(1)</i>. Get an element of a matrix.
getElem :: Int -> Int -> Matrix a -> a

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

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

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

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

-- | <i>O(1)</i>. Replace the value of a cell in a matrix.
setElem :: 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

-- | Extend a matrix to a given size adding zeroes. 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 4 5 ( 7 8 9 ) = ( 0 0 0 0 0 )
--   </pre>
extendTo :: Num a => Int -> Int -> Matrix a -> Matrix a

-- | 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

-- | 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

-- | 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

-- | 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.
--   
--   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:
--   
--   <pre>
--   ( A ) &lt;|&gt; ( B ) = ( A | B )
--   </pre>
--   
--   Where both matrices <i>A</i> and <i>B</i> have the same number of
--   rows.
(<|>) :: 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.
(<->) :: Matrix a -> Matrix a -> Matrix a

-- | Join blocks of the form detailed in <a>splitBlocks</a>.
joinBlocks :: (Matrix a, Matrix a, Matrix a, Matrix a) -> Matrix a

-- | 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:
--   
--   <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 other 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

-- | 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>
luDecomp :: (Ord a, Fractional a) => Matrix a -> (Matrix a, Matrix a, Matrix a, 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.
detLaplace :: Num a => Matrix a -> a

-- | Matrix determinant using LU decomposition.
detLU :: (Ord a, Fractional a) => Matrix a -> a
instance Eq a => Eq (Matrix a)
instance Num a => Num (Matrix a)
instance Functor Matrix
instance NFData a => NFData (Matrix a)
instance Show a => Show (Matrix a)