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


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

module Data.Eigen.Matrix.Mutable

-- | Mutable matrix. You can modify elements
data MMatrix a b s
MMatrix :: Int -> Int -> MVector s b -> MMatrix a b s
mm_rows :: MMatrix a b s -> Int
mm_cols :: MMatrix a b s -> Int
mm_vals :: MMatrix a b s -> MVector s b

-- | Alias for single precision mutable matrix
type MMatrixXf = MMatrix Float CFloat

-- | Alias for double precision mutable matrix
type MMatrixXd = MMatrix Double CDouble

-- | Alias for single previsiom mutable matrix of complex numbers
type MMatrixXcf = MMatrix (Complex Float) (CComplex CFloat)

-- | Alias for double prevision mutable matrix of complex numbers
type MMatrixXcd = MMatrix (Complex Double) (CComplex CDouble)
type IOMatrix a b = MMatrix a b RealWorld
type STMatrix a b s = MMatrix a b s

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

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

-- | Verify matrix dimensions and memory layout
valid :: Elem a b => MMatrix a b s -> Bool

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

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

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

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

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

-- | Copy a matrix. The two matrices must have the same length and may not
--   overlap.
copy :: (PrimMonad m, Elem a b) => (MMatrix a b (PrimState m)) -> (MMatrix a b (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 :: Elem a b => IOMatrix a b -> (Ptr b -> CInt -> CInt -> IO c) -> IO c


-- | 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:
--   
--   <ol>
--   <li>OMP_NUM_THREADS=n ./my_program</li>
--   <li>setNbThreads n</li>
--   </ol>
--   
--   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 a b
Matrix :: !Int -> !Int -> !(Vector b) -> Matrix a b

-- | Alias for single precision matrix
type MatrixXf = Matrix Float CFloat

-- | Alias for double precision matrix
type MatrixXd = Matrix Double CDouble

-- | Alias for single previsiom matrix of complex numbers
type MatrixXcf = Matrix (Complex Float) (CComplex CFloat)

-- | Alias for double prevision matrix of complex numbers
type MatrixXcd = Matrix (Complex Double) (CComplex CDouble)

-- | Verify matrix dimensions and values memory layout
valid :: Elem a b => Matrix a b -> Bool

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

-- | Convert matrix to a list of rows
toList :: Elem a b => Matrix a b -> [[a]]

-- | <ul>
--   <li><i>generate rows cols (λ row col -&gt; val)</i></li>
--   </ul>
--   
--   Create matrix using generator function <tt>f row col val</tt>
generate :: Elem a b => Int -> Int -> (Int -> Int -> a) -> Matrix a b

-- | Empty 0x0 matrix
empty :: Elem a b => Matrix a b

-- | Is matrix empty?
null :: Elem a b => Matrix a b -> Bool

-- | Is matrix square?
square :: Elem a b => Matrix a b -> Bool

-- | Matrix where all coeff are 0
zero :: Elem a b => Int -> Int -> Matrix a b

-- | Matrix where all coeff are 1
ones :: Elem a b => Int -> Int -> Matrix a b

-- | The identity matrix (not necessarily square).
identity :: Elem a b => Int -> Int -> Matrix a b

-- | Matrix where all coeffs are filled with given value
constant :: Elem a b => Int -> Int -> a -> Matrix a b

-- | The random matrix of a given size
random :: Elem a b => Int -> Int -> IO (Matrix a b)

-- | Number of columns for the matrix
cols :: Elem a b => Matrix a b -> Int

-- | Number of rows for the matrix
rows :: Elem a b => Matrix a b -> Int

-- | Mtrix size as (rows, cols) pair
dims :: Elem a b => Matrix a b -> (Int, Int)

-- | Matrix coefficient at specific row and col
(!) :: Elem a b => Matrix a b -> (Int, Int) -> a

-- | Matrix coefficient at specific row and col
coeff :: Elem a b => Int -> Int -> Matrix a b -> a

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

-- | List of coefficients for the given col
col :: Elem a b => Int -> Matrix a b -> [a]

-- | List of coefficients for the given row
row :: Elem a b => Int -> Matrix a b -> [a]

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

-- | Top <tt>N</tt> rows of matrix
topRows :: Elem a b => Int -> Matrix a b -> Matrix a b

-- | Bottom <tt>N</tt> rows of matrix
bottomRows :: Elem a b => Int -> Matrix a b -> Matrix a b

-- | Left <tt>N</tt> columns of matrix
leftCols :: Elem a b => Int -> Matrix a b -> Matrix a b

-- | Right <tt>N</tt> columns of matrix
rightCols :: Elem a b => Int -> Matrix a b -> Matrix a b

-- | The sum of all coefficients of the matrix
sum :: Elem a b => Matrix a b -> a

-- | The product of all coefficients of the matrix
prod :: Elem a b => Matrix a b -> a

-- | The mean of all coefficients of the matrix
mean :: Elem a b => Matrix a b -> a

-- | The minimum coefficient of the matrix
minCoeff :: (Elem a b, Ord a) => Matrix a b -> a

-- | The maximum coefficient of the matrix
maxCoeff :: (Elem a b, Ord a) => Matrix a b -> a

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

-- | 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 :: Elem a b => Matrix a b -> a

-- | 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 :: Elem a b => Matrix a b -> a

-- | 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 :: Elem a b => Matrix a b -> a

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

-- | The determinant of the matrix
determinant :: Elem a b => Matrix a b -> a

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

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

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

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

-- | Reduce matrix using user provided function applied to each element.
fold1 :: Elem a b => (a -> a -> a) -> Matrix a b -> a

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

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

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

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

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

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

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

-- | 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 :: Elem a b => (a -> a) -> Matrix a b -> Matrix a b

-- | 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 :: Elem a b => (Int -> Int -> a -> a) -> Matrix a b -> Matrix a b

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

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

-- | Diagonal of the matrix
diagonal :: Elem a b => Matrix a b -> Matrix a b

-- | Transpose of the matrix
transpose :: Elem a b => Matrix a b -> Matrix a b

-- | 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 :: Elem a b => Matrix a b -> Matrix a b

-- | Adjoint of the matrix
adjoint :: Elem a b => Matrix a b -> Matrix a b

-- | Conjugate of the matrix
conjugate :: Elem a b => Matrix a b -> Matrix a b

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

-- | 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 :: Elem a b => (forall s. MMatrix a b s -> ST s ()) -> Matrix a b -> Matrix a b

-- | Upper trinagle of the matrix
upperTriangle :: Elem a b => Matrix a b -> Matrix a b

-- | Lower trinagle of the matrix
lowerTriangle :: Elem a b => Matrix a b -> Matrix a b

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

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

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

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

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


-- | 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 :: Elem a b => Decomposition -> Matrix a b -> Matrix a b -> Matrix a b

-- | <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 :: Elem a b => Matrix a b -> Matrix a b -> Matrix a b -> a

-- | The rank of the matrix
rank :: Elem a b => Decomposition -> Matrix a b -> Int

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

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

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