-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Eigen C++ library (linear algebra: matrices, vectors, numerical solvers).
--   
@package eigen
@version 1.2.5

module Data.Eigen.Matrix.Mutable

-- | Mutable matrix. You can modify elements
data MMatrix s
MMatrix :: Int -> Int -> MVector s CDouble -> MMatrix s
mm_rows :: MMatrix s -> Int
mm_cols :: MMatrix s -> Int
mm_vals :: MMatrix s -> MVector s CDouble
type IOMatrix = MMatrix RealWorld
type STMatrix s = MMatrix s

-- | Create a mutable matrix of the given size and fill it with 0 as an
--   initial value.
new :: PrimMonad m => Int -> Int -> m (MMatrix (PrimState m))

-- | Create a mutable matrix of the given size and fill it with as an
--   initial value.
replicate :: PrimMonad m => Int -> Int -> m (MMatrix (PrimState m))

-- | Yield the element at the given position.
read :: PrimMonad m => MMatrix (PrimState m) -> Int -> Int -> m Double

-- | Replace the element at the given position.
write :: PrimMonad m => MMatrix (PrimState m) -> Int -> Int -> Double -> m ()

-- | Yield the element at the given position. No bounds checks are
--   performed.
unsafeRead :: PrimMonad m => MMatrix (PrimState m) -> Int -> Int -> m Double

-- | Replace the element at the given position. No bounds checks are
--   performed.
unsafeWrite :: PrimMonad m => MMatrix (PrimState m) -> Int -> Int -> Double -> m ()

-- | Set all elements of the matrix to the given value
set :: PrimMonad m => (MMatrix (PrimState m)) -> Double -> m ()

-- | Copy a matrix. The two matrices must have the same length and may not
--   overlap.
copy :: PrimMonad m => (MMatrix (PrimState m)) -> (MMatrix (PrimState m)) -> m ()

-- | Pass a pointer to the matrix's data to the IO action. Modifying data
--   through the pointer is unsafe if the matrix could have been frozen
--   before the modification.
unsafeWith :: IOMatrix -> (Ptr CDouble -> CInt -> CInt -> IO a) -> IO a


-- | Some Eigen's algorithms can exploit the multiple cores present in your
--   hardware. To this end, it is enough to enable OpenMP on your compiler,
--   for instance: GCC: -fopenmp. You can control the number of thread that
--   will be used using either the OpenMP API or Eiegn's API using the
--   following priority: <tt> OMP_NUM_THREADS=n ./my_program setNbThreads n
--   </tt> Unless setNbThreads has been called, Eigen uses the number of
--   threads specified by OpenMP. You can restore this bahavior by calling
--   <tt>setNbThreads n</tt>
--   
--   Currently, the following algorithms can make use of multi-threading:
--   general matrix - matrix products PartialPivLU
module Data.Eigen.Parallel

-- | Sets the max number of threads reserved for Eigen
setNbThreads :: Int -> IO ()

-- | Gets the max number of threads reserved for Eigen
getNbThreads :: IO Int

module Data.Eigen.Matrix

-- | Matrix to be used in pure computations, uses column major memory
--   layout, features copy-free FFI with C++ <a>Eigen</a> library.
data Matrix
Matrix :: Int -> Int -> Vector CDouble -> Matrix
m_rows :: Matrix -> Int
m_cols :: Matrix -> Int
m_vals :: Matrix -> Vector CDouble

-- | Verify matrix dimensions and memory layout
valid :: Matrix -> Bool

-- | Construct matrix from a list of rows, column count is detected as
--   maximum row length. Missing values are filled with 0
fromList :: [[Double]] -> Matrix

-- | Convert matrix to a list of rows
toList :: Matrix -> [[Double]]

-- | Create matrix using generator function f :: row -&gt; col -&gt; val
generate :: Int -> Int -> (Int -> Int -> Double) -> Matrix

-- | Empty 0x0 matrix
empty :: Matrix

-- | Is matrix empty?
null :: Matrix -> Bool

-- | Is matrix square?
square :: Matrix -> Bool

-- | Matrix where all coeff are 0
zero :: Int -> Int -> Matrix

-- | Matrix where all coeff are 1
ones :: Int -> Int -> Matrix

-- | Square matrix with 1 on main diagonal and 0 elsewhere
identity :: Int -> Matrix

-- | Matrix where all coeffs are filled with given value
constant :: Int -> Int -> Double -> Matrix

-- | The random matrix of a given size
random :: Int -> Int -> IO Matrix

-- | Number of columns for the matrix
cols :: Matrix -> Int

-- | Number of rows for the matrix
rows :: Matrix -> Int

-- | Matrix coefficient at specific row and col
(!) :: Matrix -> (Int, Int) -> Double

-- | Matrix coefficient at specific row and col
coeff :: Int -> Int -> Matrix -> Double

-- | Unsafe version of coeff function. No bounds check performed so
--   SEGFAULT possible
unsafeCoeff :: Int -> Int -> Matrix -> Double

-- | List of coefficients for the given col
col :: Int -> Matrix -> [Double]

-- | List of coefficients for the given row
row :: Int -> Matrix -> [Double]

-- | Extract rectangular block from matrix defined by startRow startCol
--   blockRows blockCols
block :: Int -> Int -> Int -> Int -> Matrix -> Matrix

-- | Top <tt>N</tt> rows of matrix
topRows :: Int -> Matrix -> Matrix

-- | Bottom <tt>N</tt> rows of matrix
bottomRows :: Int -> Matrix -> Matrix

-- | Left <tt>N</tt> columns of matrix
leftCols :: Int -> Matrix -> Matrix

-- | Right <tt>N</tt> columns of matrix
rightCols :: Int -> Matrix -> Matrix

-- | The sum of all coefficients of the matrix
sum :: Matrix -> Double

-- | The product of all coefficients of the matrix
prod :: Matrix -> Double

-- | The mean of all coefficients of the matrix
mean :: Matrix -> Double

-- | The minimum coefficient of the matrix
minCoeff :: Matrix -> Double

-- | The maximum coefficient of the matrix
maxCoeff :: Matrix -> Double

-- | The trace of a matrix is the sum of the diagonal coefficients and can
--   also be computed as sum (diagonal m)
trace :: Matrix -> Double

-- | For vectors, the l2 norm, and for matrices the Frobenius norm. In both
--   cases, it consists in the square root of the sum of the square of all
--   the matrix entries. For vectors, this is also equals to the square
--   root of the dot product of this with itself.
norm :: Matrix -> Double

-- | For vectors, the squared l2 norm, and for matrices the Frobenius norm.
--   In both cases, it consists in the sum of the square of all the matrix
--   entries. For vectors, this is also equals to the dot product of this
--   with itself.
squaredNorm :: Matrix -> Double

-- | The l2 norm of the matrix using the Blue's algorithm. A Portable
--   Fortran Program to Find the Euclidean Norm of a Vector, ACM TOMS, Vol
--   4, Issue 1, 1978.
blueNorm :: Matrix -> Double

-- | The l2 norm of the matrix avoiding undeflow and overflow. This version
--   use a concatenation of hypot calls, and it is very slow.
hypotNorm :: Matrix -> Double

-- | The determinant of the matrix
determinant :: Matrix -> Double

-- | Reduce matrix using user provided function applied to each element.
fold :: (a -> Double -> a) -> a -> Matrix -> a

-- | Reduce matrix using user provided function applied to each element.
--   This is strict version of <a>fold</a>
fold' :: (a -> Double -> a) -> a -> Matrix -> a

-- | Reduce matrix using user provided function applied to each element and
--   it's index
ifold :: (Int -> Int -> a -> Double -> a) -> a -> Matrix -> a

-- | Reduce matrix using user provided function applied to each element and
--   it's index. This is strict version of <a>ifold</a>
ifold' :: (Int -> Int -> a -> Double -> a) -> a -> Matrix -> a

-- | Applied to a predicate and a matrix, all determines if all elements of
--   the matrix satisfies the predicate
all :: (Double -> Bool) -> Matrix -> Bool

-- | Applied to a predicate and a matrix, any determines if any element of
--   the matrix satisfies the predicate
any :: (Double -> Bool) -> Matrix -> Bool

-- | Returns the number of coefficients in a given matrix that evaluate to
--   true
count :: (Double -> Bool) -> Matrix -> Int

-- | Adding two matrices by adding the corresponding entries together. You
--   can use <tt>(+)</tt> function as well.
add :: Matrix -> Matrix -> Matrix

-- | Subtracting two matrices by subtracting the corresponding entries
--   together. You can use <tt>(-)</tt> function as well.
sub :: Matrix -> Matrix -> Matrix

-- | Matrix multiplication. You can use <tt>(*)</tt> function as well.
mul :: Matrix -> Matrix -> Matrix

-- | Apply a given function to each element of the matrix.
--   
--   Here is an example how to implement scalar matrix multiplication:
--   
--   <pre>
--   &gt;&gt;&gt; let a = fromList [[1,2],[3,4]]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; a
--   Matrix 2x2
--   1.0 2.0
--   3.0 4.0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (*10) a
--   Matrix 2x2
--   10.0    20.0
--   30.0    40.0
--   </pre>
map :: (Double -> Double) -> Matrix -> Matrix

-- | Apply a given function to each element of the matrix.
--   
--   Here is an example how getting upper triangular matrix can be
--   implemented:
--   
--   <pre>
--   &gt;&gt;&gt; let a = fromList [[1,2,3],[4,5,6],[7,8,9]]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; a
--   Matrix 3x3
--   1.0 2.0 3.0
--   4.0 5.0 6.0
--   7.0 8.0 9.0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; imap (\row col val -&gt; if row &lt;= col then val else 0) a
--   Matrix 3x3
--   1.0 2.0 3.0
--   0.0 5.0 6.0
--   0.0 0.0 9.0
--   </pre>
imap :: (Int -> Int -> Double -> Double) -> Matrix -> Matrix

-- | Filter elements in the matrix. Filtered elements will be replaced by 0
filter :: (Double -> Bool) -> Matrix -> Matrix

-- | Filter elements in the matrix. Filtered elements will be replaced by 0
ifilter :: (Int -> Int -> Double -> Bool) -> Matrix -> Matrix

-- | Diagonal of the matrix
diagonal :: Matrix -> Matrix

-- | Transpose of the matrix
transpose :: Matrix -> Matrix

-- | Inverse of the matrix
--   
--   For small fixed sizes up to 4x4, this method uses cofactors. In the
--   general case, this method uses PartialPivLU decomposition
inverse :: Matrix -> Matrix

-- | Adjoint of the matrix
adjoint :: Matrix -> Matrix

-- | Conjugate of the matrix
conjugate :: Matrix -> Matrix

-- | Nomalize the matrix by deviding it on its <a>norm</a>
normalize :: Matrix -> Matrix

-- | Apply a destructive operation to a matrix. The operation will be
--   performed in place if it is safe to do so and will modify a copy of
--   the matrix otherwise.
modify :: (forall s. MMatrix s -> ST s ()) -> Matrix -> Matrix

-- | Upper trinagle of the matrix
upperTriangule :: Matrix -> Matrix

-- | Lower trinagle of the matrix
lowerTriangule :: Matrix -> Matrix

-- | Yield a mutable copy of the immutable matrix
thaw :: PrimMonad m => Matrix -> m (MMatrix (PrimState m))

-- | Yield an immutable copy of the mutable matrix
freeze :: PrimMonad m => MMatrix (PrimState m) -> m Matrix

-- | Unsafely convert an immutable matrix to a mutable one without copying.
--   The immutable matrix may not be used after this operation.
unsafeThaw :: PrimMonad m => Matrix -> m (MMatrix (PrimState m))

-- | Unsafe convert a mutable matrix to an immutable one without copying.
--   The mutable matrix may not be used after this operation.
unsafeFreeze :: PrimMonad m => MMatrix (PrimState m) -> m Matrix

-- | Pass a pointer to the matrix's data to the IO action. The data may not
--   be modified through the pointer.
unsafeWith :: Matrix -> (Ptr CDouble -> CInt -> CInt -> IO a) -> IO a
instance Num Matrix
instance Show Matrix


-- | The problem: You have a system of equations, that you have written as
--   a single matrix equation
--   
--   <pre>
--   Ax = b
--   </pre>
--   
--   Where A and b are matrices (b could be a vector, as a special case).
--   You want to find a solution x.
--   
--   The solution: You can choose between various decompositions, depending
--   on what your matrix A looks like, and depending on whether you favor
--   speed or accuracy. However, let's start with an example that works in
--   all cases, and is a good compromise:
--   
--   <pre>
--   import Data.Eigen.Matrix
--   import Data.Eigen.LA
--   
--   main = do
--       let
--           a = fromList [[1,2,3], [4,5,6], [7,8,10]]
--           b = fromList [[3],[3],[4]]
--           x = solve ColPivHouseholderQR a b
--       putStrLn "Here is the matrix A:" &gt;&gt; print a
--       putStrLn "Here is the vector b:" &gt;&gt; print b
--       putStrLn "The solution is:" &gt;&gt; print x
--   </pre>
--   
--   produces the following output
--   
--   <pre>
--   Here is the matrix A:
--   Matrix 3x3
--   1.0 2.0 3.0
--   4.0 5.0 6.0
--   7.0 8.0 10.0
--   
--   Here is the vector b:
--   Matrix 3x1
--   3.0
--   3.0
--   4.0
--   
--   The solution is:
--   Matrix 3x1
--   -2.0000000000000004
--   1.0000000000000018
--   0.9999999999999989
--   </pre>
--   
--   Checking if a solution really exists: Only you know what error margin
--   you want to allow for a solution to be considered valid.
--   
--   You can compute relative error using <tt><a>norm</a> (ax - b) /
--   <a>norm</a> b</tt> formula or use <a>relativeError</a> function which
--   provides the same calculation implemented slightly more efficient.
module Data.Eigen.LA

-- | <pre>
--   Decomposition           Requirements on the matrix          Speed   Accuracy  Rank  Kernel  Image
--   
--   PartialPivLU            Invertible                          ++      +         -     -       -
--   FullPivLU               None                                -       +++       +     +       +
--   HouseholderQR           None                                ++      +         -     -       -
--   ColPivHouseholderQR     None                                +       ++        +     -       -
--   FullPivHouseholderQR    None                                -       +++       +     -       -
--   LLT                     Positive definite                   +++     +         -     -       -
--   LDLT                    Positive or negative semidefinite   +++     ++        -     -       -
--   JacobiSVD               None                                -       +++       +     -       -
--   </pre>
--   
--   The best way to do least squares solving for square matrices is with a
--   SVD decomposition (<a>JacobiSVD</a>)
data Decomposition

-- | LU decomposition of a matrix with partial pivoting.
PartialPivLU :: Decomposition

-- | LU decomposition of a matrix with complete pivoting.
FullPivLU :: Decomposition

-- | Householder QR decomposition of a matrix.
HouseholderQR :: Decomposition

-- | Householder rank-revealing QR decomposition of a matrix with
--   column-pivoting.
ColPivHouseholderQR :: Decomposition

-- | Householder rank-revealing QR decomposition of a matrix with full
--   pivoting.
FullPivHouseholderQR :: Decomposition

-- | Standard Cholesky decomposition (LL^T) of a matrix.
LLT :: Decomposition

-- | Robust Cholesky decomposition of a matrix with pivoting.
LDLT :: Decomposition

-- | Two-sided Jacobi SVD decomposition of a rectangular matrix.
JacobiSVD :: Decomposition

-- | <ul>
--   <li><i>x = solve d a b</i> finds a solution <tt>x</tt> of <tt>ax =
--   b</tt> equation using decomposition <tt>d</tt></li>
--   </ul>
solve :: Decomposition -> Matrix -> Matrix -> Matrix

-- | <ul>
--   <li><i>e = relativeError x a b</i> computes <tt>norm (ax - b) / norm
--   b</tt> where <tt>norm</tt> is L2 norm</li>
--   </ul>
relativeError :: Matrix -> Matrix -> Matrix -> Double

-- | The rank of the matrix
rank :: Decomposition -> Matrix -> Int

-- | Return matrix whose columns form a basis of the null-space of
--   <tt>A</tt>
kernel :: Decomposition -> Matrix -> Matrix

-- | Return a matrix whose columns form a basis of the column-space of
--   <tt>A</tt>
image :: Decomposition -> Matrix -> Matrix

-- | <ul>
--   <li><i>(coeffs, error) = linearRegression points</i> computes multiple
--   linear regression <tt>y = a1 x1 + a2 x2 + ... + an xn + b</tt> using
--   <a>ColPivHouseholderQR</a> decomposition</li>
--   </ul>
--   
--   <ul>
--   <li>point format is <tt>[y, x1..xn]</tt></li>
--   <li>coeffs format is <tt>[b, a1..an]</tt></li>
--   <li>error is calculated using <a>relativeError</a></li>
--   </ul>
--   
--   <pre>
--   import Data.Eigen.LA
--   main = print $ linearRegression [
--       [-4.32, 3.02, 6.89],
--       [-3.79, 2.01, 5.39],
--       [-4.01, 2.41, 6.01],
--       [-3.86, 2.09, 5.55],
--       [-4.10, 2.58, 6.32]]
--   </pre>
--   
--   produces the following output
--   
--   <pre>
--   ([-2.3466569233817127,-0.2534897541434826,-0.1749653335680988],1.8905965120153139e-3)
--   </pre>
linearRegression :: [[Double]] -> ([Double], Double)
instance Show Decomposition
instance Enum Decomposition