-----------------------------------------------------------------------------
-- |
-- Module      :  ForSyDe.Shallow.Utility.Matrix
-- Copyright   :  (c) ForSyDe Group, KTH 2019
-- License     :  BSD-style (see the file LICENSE)
-- 
-- Maintainer  :  forsyde-dev@kth.se
-- Stability   :  experimental
-- Portability :  portable
--
-- This module defines the data type 'Matrix' and corresponding
-- functions. It is a shallow interpretation of 2D arrays and is used
-- for quick prototyping of array algorithms and skeletons, although
-- itself is a type synonym for a `Vector` of `Vector`s. Therefore
-- this module is simply a collection of utility functions on 2D
-- vectors used mainly for convenience. For a type-checked fixed-size
-- data type for representing matrices, see the
-- <http://hackage.haskell.org/package/matrix matrix> or
-- <http://hackage.haskell.org/package/repa REPA> packages.
--
-- __OBS:__ The lengths in the API documentation for function arguments
-- are not type-safe, but rather suggestions for usage in designing
-- matrix algorithms or skeletons.
-----------------------------------------------------------------------------
module ForSyDe.Shallow.Utility.Matrix (
  Matrix, prettyMat,
  -- * Queries
  nullMat, sizeMat, wellFormedMat,
  -- * Generators
  matrix, fromMatrix, unitMat, indexMat,
  -- * Functional skeletons
  mapMat, zipWithMat, zipWith3Mat, reduceMat, dotVecMat, dotMatMat,
  -- * Selectors
  atMat, takeMat, dropMat, cropMat, groupMat, stencilMat,
  -- * Permutators
  zipMat, unzipMat,
  rotateMat, reverseMat, transposeMat, replaceMat
  ) where

import ForSyDe.Shallow.Core.Vector
import Data.List (intercalate)

-- | 'Matrix' is simply a type synonym for vector of vectors. This
-- means that /any/ function on 'Vector' works also on 'Matrix'.
type Matrix a = Vector (Vector a)

-- | Prints out to the terminal a matrix in a readable format, where
-- all elements are right-aligned and separated by a custom separator.
--
-- >>> let m = matrix 3 3 [1,2,3,3,100,4,12,32,67]
-- >>> prettyMat "|" m
--  1|  2| 3
--  3|100| 4
-- 12| 32|67
prettyMat :: Show a
          => String   -- ^ separator string
          -> Matrix a -- ^ input matrix
          -> IO ()
prettyMat :: String -> Matrix a -> IO ()
prettyMat String
sep Matrix a
mat = (String -> IO ()) -> [String] -> IO ()
forall (t :: * -> *) (m :: * -> *) a b.
(Foldable t, Monad m) =>
(a -> m b) -> t a -> m ()
mapM_ String -> IO ()
putStrLn ([String] -> IO ()) -> [String] -> IO ()
forall a b. (a -> b) -> a -> b
$ Vector String -> [String]
forall a. Vector a -> [a]
fromVector (Vector String -> [String]) -> Vector String -> [String]
forall a b. (a -> b) -> a -> b
$ Vector Int -> Vector (Vector String) -> Vector String
printMat Vector Int
maxWdt Vector (Vector String)
strMat
  where
    maxWdt :: Vector Int
maxWdt = (Vector Int -> Vector Int -> Vector Int)
-> Vector (Vector Int) -> Vector Int
forall a. (a -> a -> a) -> Vector a -> a
reduceV ((Int -> Int -> Int) -> Vector Int -> Vector Int -> Vector Int
forall a b c. (a -> b -> c) -> Vector a -> Vector b -> Vector c
zipWithV Int -> Int -> Int
forall a. Ord a => a -> a -> a
max) (Vector (Vector Int) -> Vector Int)
-> Vector (Vector Int) -> Vector Int
forall a b. (a -> b) -> a -> b
$ (String -> Int) -> Vector (Vector String) -> Vector (Vector Int)
forall a b. (a -> b) -> Matrix a -> Matrix b
mapMat String -> Int
forall (t :: * -> *) a. Foldable t => t a -> Int
length Vector (Vector String)
strMat
    strMat :: Vector (Vector String)
strMat = (a -> String) -> Matrix a -> Vector (Vector String)
forall a b. (a -> b) -> Matrix a -> Matrix b
mapMat a -> String
forall a. Show a => a -> String
show Matrix a
mat
    printMat :: Vector Int -> Vector (Vector String) -> Vector String
printMat Vector Int
w  = (Vector String -> String)
-> Vector (Vector String) -> Vector String
forall a b. (a -> b) -> Vector a -> Vector b
mapV (\Vector String
row -> Vector Int -> Vector String -> String
printRow Vector Int
w Vector String
row)
    printRow :: Vector Int -> Vector String -> String
printRow Vector Int
w  = String -> [String] -> String
forall a. [a] -> [[a]] -> [a]
intercalate String
sep ([String] -> String)
-> (Vector String -> [String]) -> Vector String -> String
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Vector String -> [String]
forall a. Vector a -> [a]
fromVector (Vector String -> [String])
-> (Vector String -> Vector String) -> Vector String -> [String]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Int -> String -> String)
-> Vector Int -> Vector String -> Vector String
forall a b c. (a -> b -> c) -> Vector a -> Vector b -> Vector c
zipWithV Int -> String -> String
align Vector Int
w
    align :: Int -> String -> String
align Int
n String
str = Int -> Char -> String
forall a. Int -> a -> [a]
replicate (Int
n Int -> Int -> Int
forall a. Num a => a -> a -> a
- String -> Int
forall (t :: * -> *) a. Foldable t => t a -> Int
length String
str) Char
' ' String -> String -> String
forall a. [a] -> [a] -> [a]
++ String
str

-- | Checks if a matrix is null. @<>@ and @<<>>@ are both null
-- matrices.
nullMat :: Matrix a -> Bool
nullMat :: Matrix a -> Bool
nullMat Matrix a
NullV = Bool
True
nullMat (Vector a
NullV:>Matrix a
NullV) = Bool
True
nullMat Matrix a
_ = Bool
False

-- | Returns the X and Y dimensions of matrix and checks if it is well formed.
sizeMat :: Matrix a -> (Int,Int)
sizeMat :: Matrix a -> (Int, Int)
sizeMat Matrix a
m = (Int
x,Int
y)
  where
    y :: Int
y = Matrix a -> Int
forall a. Vector a -> Int
lengthV Matrix a
m
    x :: Int
x = (Vector a -> Int
forall a. Vector a -> Int
lengthV (Vector a -> Int) -> (Matrix a -> Vector a) -> Matrix a -> Int
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Matrix a -> Vector a
forall a. Vector a -> a
headV) (Matrix a -> Matrix a
forall a. Matrix a -> Matrix a
wellFormedMat Matrix a
m)

-- | Checks if a matrix is well-formed, meaning that all its rows are
-- of equal length. Returns the same matrix in case it is well-formed
-- or throws an exception if it is ill-formed.
wellFormedMat :: Matrix a -> Matrix a
wellFormedMat :: Matrix a -> Matrix a
wellFormedMat Matrix a
NullV = String -> Matrix a
forall a. HasCallStack => String -> a
error String
"matrix is null"
wellFormedMat m :: Matrix a
m@(Vector a
_:>Matrix a
NullV) = Matrix a
m
wellFormedMat m :: Matrix a
m@(Vector a
x:>Matrix a
xs)
  | (Bool -> Bool -> Bool) -> Vector Bool -> Bool
forall a. (a -> a -> a) -> Vector a -> a
reduceV Bool -> Bool -> Bool
(&&) ((Vector a -> Bool) -> Matrix a -> Vector Bool
forall a b. (a -> b) -> Vector a -> Vector b
mapV (\Vector a
r -> Vector a -> Int
forall a. Vector a -> Int
lengthV Vector a
r Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
== Vector a -> Int
forall a. Vector a -> Int
lengthV Vector a
x) Matrix a
xs) = Matrix a
m
  | Bool
otherwise = String -> Matrix a
forall a. HasCallStack => String -> a
error String
"matrix ill-formed: rows are of unequal lengths"

groupEvery :: Int -> [a] -> [[a]]
groupEvery :: Int -> [a] -> [[a]]
groupEvery Int
_ [] = []
groupEvery Int
n [a]
l
  | Int
n Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Int
0        = String -> [[a]]
forall a. HasCallStack => String -> a
error (String -> [[a]]) -> String -> [[a]]
forall a b. (a -> b) -> a -> b
$ String
"cannot group list by negative n: " String -> String -> String
forall a. [a] -> [a] -> [a]
++ Int -> String
forall a. Show a => a -> String
show Int
n
  | [a] -> Int
forall (t :: * -> *) a. Foldable t => t a -> Int
length [a]
l Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Int
n = String -> [[a]]
forall a. HasCallStack => String -> a
error String
"input list cannot be split into all-equal parts"
  | Bool
otherwise    = Int -> [a] -> [a]
forall a. Int -> [a] -> [a]
take Int
n [a]
l [a] -> [[a]] -> [[a]]
forall a. a -> [a] -> [a]
: Int -> [a] -> [[a]]
forall a. Int -> [a] -> [[a]]
groupEvery Int
n (Int -> [a] -> [a]
forall a. Int -> [a] -> [a]
drop Int
n [a]
l)

-- | Converts a list into a 'Matrix'. See example from 'prettyMat'.
matrix :: Int      -- ^ number of columns (X dimension) @= x@
       -> Int      -- ^ number of rows (Y dimension) @= y@
       -> [a]      -- ^ list of values; /length/ = @x * y@
       -> Matrix a -- ^ 'Matrix' of values; /size/ = @(x,y)@
matrix :: Int -> Int -> [a] -> Matrix a
matrix Int
x Int
y = [Vector a] -> Matrix a
forall a. [a] -> Vector a
vector ([Vector a] -> Matrix a) -> ([a] -> [Vector a]) -> [a] -> Matrix a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. ([a] -> Vector a) -> [[a]] -> [Vector a]
forall a b. (a -> b) -> [a] -> [b]
map [a] -> Vector a
forall a. [a] -> Vector a
vector ([[a]] -> [Vector a]) -> ([a] -> [[a]]) -> [a] -> [Vector a]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> [a] -> [[a]]
forall a. Int -> [a] -> [[a]]
groupEvery Int
x ([a] -> [[a]]) -> ([a] -> [a]) -> [a] -> [[a]]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. [a] -> [a]
forall (t :: * -> *) a. Foldable t => t a -> t a
check
  where
    check :: t a -> t a
check t a
l | t a -> Int
forall (t :: * -> *) a. Foldable t => t a -> Int
length t a
l Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
== Int
x Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
y = t a
l
            | Bool
otherwise
      = String -> t a
forall a. HasCallStack => String -> a
error (String -> t a) -> String -> t a
forall a b. (a -> b) -> a -> b
$ String
"cannot form matrix (" String -> String -> String
forall a. [a] -> [a] -> [a]
++ Int -> String
forall a. Show a => a -> String
show Int
x String -> String -> String
forall a. [a] -> [a] -> [a]
++ String
","
              String -> String -> String
forall a. [a] -> [a] -> [a]
++ Int -> String
forall a. Show a => a -> String
show Int
y String -> String -> String
forall a. [a] -> [a] -> [a]
++ String
") from a list with "
              String -> String -> String
forall a. [a] -> [a] -> [a]
++ Int -> String
forall a. Show a => a -> String
show (t a -> Int
forall (t :: * -> *) a. Foldable t => t a -> Int
length t a
l) String -> String -> String
forall a. [a] -> [a] -> [a]
++ String
" elements"

-- | Converts a matrix back to a list.
fromMatrix :: Matrix a -- ^ /size/ = @(x,y)@
           -> [a]      -- ^ /length/ = @x * y@
fromMatrix :: Matrix a -> [a]
fromMatrix = (Vector a -> [a]) -> [Vector a] -> [a]
forall (t :: * -> *) a b. Foldable t => (a -> [b]) -> t a -> [b]
concatMap Vector a -> [a]
forall a. Vector a -> [a]
fromVector ([Vector a] -> [a]) -> (Matrix a -> [Vector a]) -> Matrix a -> [a]
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Matrix a -> [Vector a]
forall a. Vector a -> [a]
fromVector

-- | Creates a unit (i.e. singleton) matrix, which is a matrix with
-- only one element.
unitMat :: a -> Matrix a -- ^ /size/ = @(1,1)@
unitMat :: a -> Matrix a
unitMat a
a = (a
aa -> Vector a -> Vector a
forall a. a -> Vector a -> Vector a
:>Vector a
forall a. Vector a
NullV)Vector a -> Matrix a -> Matrix a
forall a. a -> Vector a -> Vector a
:>Matrix a
forall a. Vector a
NullV

-- | Returns an /infinite matrix/ with (X,Y) index pairs. You need to
-- zip it against another (finite) matrix or to extract a finite
-- subset in order to be useful (see example below).
--
-- >>> prettyMat " " $ takeMat 3 4 indexMat 
-- (0,0) (1,0) (2,0)
-- (0,1) (1,1) (2,1)
-- (0,2) (1,2) (2,2)
-- (0,3) (1,3) (2,3)
indexMat :: Matrix (Int, Int)
indexMat :: Matrix (Int, Int)
indexMat = (Int -> Int -> (Int, Int))
-> Vector (Vector Int) -> Vector (Vector Int) -> Matrix (Int, Int)
forall a b c. (a -> b -> c) -> Matrix a -> Matrix b -> Matrix c
zipWithMat (,) Vector (Vector Int)
colix Vector (Vector Int)
rowix
  where
    colix :: Vector (Vector Int)
colix = [Vector Int] -> Vector (Vector Int)
forall a. [a] -> Vector a
vector ([Vector Int] -> Vector (Vector Int))
-> [Vector Int] -> Vector (Vector Int)
forall a b. (a -> b) -> a -> b
$ Vector Int -> [Vector Int]
forall a. a -> [a]
repeat (Vector Int -> [Vector Int]) -> Vector Int -> [Vector Int]
forall a b. (a -> b) -> a -> b
$ [Int] -> Vector Int
forall a. [a] -> Vector a
vector [Int
0..]
    rowix :: Vector (Vector Int)
rowix = Vector (Vector Int) -> Vector (Vector Int)
forall a. Matrix a -> Matrix a
transposeMat Vector (Vector Int)
colix 

-- | Maps a function on every value of a matrix.
--
-- __OBS:__ this function does not check if the output matrix is well-formed.
mapMat :: (a -> b)
       -> Matrix a -- ^ /size/ = @(xa,ya)@
       -> Matrix b -- ^ /size/ = @(xa,ya)@
mapMat :: (a -> b) -> Matrix a -> Matrix b
mapMat = (Vector a -> Vector b) -> Matrix a -> Matrix b
forall a b. (a -> b) -> Vector a -> Vector b
mapV ((Vector a -> Vector b) -> Matrix a -> Matrix b)
-> ((a -> b) -> Vector a -> Vector b)
-> (a -> b)
-> Matrix a
-> Matrix b
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (a -> b) -> Vector a -> Vector b
forall a b. (a -> b) -> Vector a -> Vector b
mapV

-- | Applies a binary function pair-wise on each element in two matrices.
--
-- __OBS:__ this function does not check if the output matrix is well-formed.
zipWithMat :: (a -> b -> c)
           -> Matrix a -- ^ /size/ = @(xa,ya)@
           -> Matrix b -- ^ /size/ = @(xb,yb)@
           -> Matrix c -- ^ /size/ = @(minimum [xa,xb], minimum [ya,yb])@
zipWithMat :: (a -> b -> c) -> Matrix a -> Matrix b -> Matrix c
zipWithMat a -> b -> c
f = (Vector a -> Vector b -> Vector c)
-> Matrix a -> Matrix b -> Matrix c
forall a b c. (a -> b -> c) -> Vector a -> Vector b -> Vector c
zipWithV ((a -> b -> c) -> Vector a -> Vector b -> Vector c
forall a b c. (a -> b -> c) -> Vector a -> Vector b -> Vector c
zipWithV a -> b -> c
f)

-- | Applies a function 3-tuple-wise on each element in three matrices.
--
-- __OBS:__ this function does not check if the output matrix is well-formed.
zipWith3Mat :: (a -> b -> c -> d)
            -> Matrix a -- ^ /size/ = @(xa,ya)@
            -> Matrix b -- ^ /size/ = @(xb,yb)@
            -> Matrix c -- ^ /size/ = @(xc,yc)@
            -> Matrix d -- ^ /size/ = @(minimum [xa,xb,xc], minimum [ya,yb,yc])@
zipWith3Mat :: (a -> b -> c -> d) -> Matrix a -> Matrix b -> Matrix c -> Matrix d
zipWith3Mat a -> b -> c -> d
f = (Vector a -> Vector b -> Vector c -> Vector d)
-> Matrix a -> Matrix b -> Matrix c -> Matrix d
forall a b c d.
(a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
zipWith3V (\Vector a
a Vector b
b Vector c
c -> (a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
forall a b c d.
(a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
zipWith3V a -> b -> c -> d
f Vector a
a Vector b
b Vector c
c)

-- | Reduces all the elements of a matrix to one element based on a
-- binary function.
--
-- >>> let m = matrix 3 3 [1,2,3,11,12,13,21,22,23]
-- >>> reduceMat (+) m
-- 108
reduceMat :: (a -> a -> a) -> Matrix a -> a
reduceMat :: (a -> a -> a) -> Matrix a -> a
reduceMat a -> a -> a
f = (a -> a -> a) -> Vector a -> a
forall a. (a -> a -> a) -> Vector a -> a
reduceV a -> a -> a
f (Vector a -> a) -> (Matrix a -> Vector a) -> Matrix a -> a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Vector a -> a) -> Matrix a -> Vector a
forall a b. (a -> b) -> Vector a -> Vector b
mapV ((a -> a -> a) -> Vector a -> a
forall a. (a -> a -> a) -> Vector a -> a
reduceV a -> a -> a
f)

-- | Pattern implementing the template for a dot operation between a
-- vector and a matrix.
--
-- >>> let mA = matrix 4 4 [1,-1,1,1,  1,-1,-1,-1,  1,1,-1,1,  1,1,1,-1]
-- >>> let y  = vector[1,0,0,0]
-- >>> dotVecMat (+) (*) mA y
-- <1,1,1,1>
dotVecMat :: (a -> a -> a) -- ^ kernel function for a row/column reduction, e.g. @(+)@ for dot product
          -> (b -> a -> a) -- ^ binary operation for pair-wise elements, e.g. @(*)@ for dot product
          -> Matrix b      -- ^ /size/ = @(xa,ya)@
          -> Vector a      -- ^ /length/ = @xa@
          -> Vector a      -- ^ /length/ = @xa@
dotVecMat :: (a -> a -> a) -> (b -> a -> a) -> Matrix b -> Vector a -> Vector a
dotVecMat a -> a -> a
f b -> a -> a
g Matrix b
mA Vector a
y = (Vector b -> a) -> Matrix b -> Vector a
forall a b. (a -> b) -> Vector a -> Vector b
mapV (\Vector b
x -> (a -> a -> a) -> Vector a -> a
forall a. (a -> a -> a) -> Vector a -> a
reduceV a -> a -> a
f (Vector a -> a) -> Vector a -> a
forall a b. (a -> b) -> a -> b
$ (b -> a -> a) -> Vector b -> Vector a -> Vector a
forall a b c. (a -> b -> c) -> Vector a -> Vector b -> Vector c
zipWithV b -> a -> a
g Vector b
x Vector a
y) Matrix b
mA

-- | Pattern implementing the template for a dot operation between two
-- matrices.
--
-- >>> let mA = matrix 4 4 [1,-1,1,1,  1,-1,-1,-1,  1,1,-1,1,  1,1,1,-1]
-- >>> prettyMat " " $ dotMatMat (+) (*) mA mA
-- 2 -2  2  2
-- 2 -2 -2 -2
-- 2  2  2 -2
-- 2  2 -2  2
dotMatMat :: (a -> a -> a) -- ^ kernel function for a row/column reduction, e.g. @(+)@ for dot product
          -> (b -> a -> a) -- ^ binary operation for pair-wise elements, e.g. @(*)@ for dot product
          -> Matrix b      -- ^ /size/ = @(xa,ya)@
          -> Matrix a      -- ^ /size/ = @(ya,xa)@
          -> Matrix a      -- ^ /size/ = @(xa,xa)@
dotMatMat :: (a -> a -> a) -> (b -> a -> a) -> Matrix b -> Matrix a -> Matrix a
dotMatMat a -> a -> a
f b -> a -> a
g Matrix b
m = (Vector a -> Vector a) -> Matrix a -> Matrix a
forall a b. (a -> b) -> Vector a -> Vector b
mapV ((a -> a -> a) -> (b -> a -> a) -> Matrix b -> Vector a -> Vector a
forall a b.
(a -> a -> a) -> (b -> a -> a) -> Matrix b -> Vector a -> Vector a
dotVecMat a -> a -> a
f b -> a -> a
g Matrix b
m) (Matrix a -> Matrix a)
-> (Matrix a -> Matrix a) -> Matrix a -> Matrix a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Matrix a -> Matrix a
forall a. Matrix a -> Matrix a
transposeMat

-- | Returns the element of a matrix at a certain position.
--
-- >>> let m = matrix 3 3 [1,2,3,11,12,13,21,22,23]
-- >>> atMat 2 1 m
-- 13
atMat :: Int       -- ^ X index starting from zero
      -> Int       -- ^ Y index starting from zero
      -> Matrix a
      -> a
atMat :: Int -> Int -> Matrix a -> a
atMat Int
x Int
y Matrix a
mat = (Matrix a
mat Matrix a -> Int -> Vector a
forall a b. Integral a => Vector b -> a -> b
`atV` Int
y) Vector a -> Int -> a
forall a b. Integral a => Vector b -> a -> b
`atV` Int
x

-- | Returns the upper-left part of a matrix until a specific
-- position.
--
-- >>> let m = matrix 4 4 [1,2,3,4,11,12,13,14,21,22,23,24,31,32,33,34]
-- >>> prettyMat " " $ takeMat 2 2 m
--  1  2
-- 11 12
takeMat :: Int       -- ^ X index starting from zero
        -> Int       -- ^ Y index starting from zero
        -> Matrix a
        -> Matrix a
takeMat :: Int -> Int -> Matrix a -> Matrix a
takeMat Int
x Int
y = (Vector a -> Vector a) -> Matrix a -> Matrix a
forall a b. (a -> b) -> Vector a -> Vector b
mapV (Int -> Vector a -> Vector a
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
takeV Int
x) (Matrix a -> Matrix a)
-> (Matrix a -> Matrix a) -> Matrix a -> Matrix a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> Matrix a -> Matrix a
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
takeV Int
y

-- | Returns the upper-left part of a matrix until a specific
-- position.
--
-- >>> let m = matrix 4 4 [1,2,3,4,11,12,13,14,21,22,23,24,31,32,33,34]
-- >>> prettyMat " " $ dropMat 2 2 m
-- 23 24
-- 33 34
dropMat :: Int       -- ^ X index starting from zero
        -> Int       -- ^ Y index starting from zero
        -> Matrix a
        -> Matrix a
dropMat :: Int -> Int -> Matrix a -> Matrix a
dropMat Int
x Int
y = (Vector a -> Vector a) -> Matrix a -> Matrix a
forall a b. (a -> b) -> Vector a -> Vector b
mapV (Int -> Vector a -> Vector a
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
dropV Int
x) (Matrix a -> Matrix a)
-> (Matrix a -> Matrix a) -> Matrix a -> Matrix a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> Matrix a -> Matrix a
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
dropV Int
y

-- | Crops a section of a matrix.
--
-- >>> let m = matrix 4 4 [1,2,3,4,11,12,13,14,21,22,23,24,31,32,33,34]
-- >>> prettyMat " " m
--  1  2  3  4
-- 11 12 13 14
-- 21 22 23 24
-- 31 32 33 34
-- >>> prettyMat " " $ cropMat 2 3 1 1 m
-- 12 13
-- 22 23
-- 32 33
cropMat :: Int      -- ^ crop width  = @w@
        -> Int      -- ^ crop height = @h@
        -> Int      -- ^ X start position = @x0@
        -> Int      -- ^ Y start position = @y0@
        -> Matrix a -- ^ /size/ = @(xa,ya)@
        -> Matrix a -- ^ /size/ = @(minimum [w,xa-x0], minimum [h,xa-x0])@
cropMat :: Int -> Int -> Int -> Int -> Matrix a -> Matrix a
cropMat Int
w Int
h Int
pX Int
pY = Int -> Int -> Matrix a -> Matrix a
forall a. Int -> Int -> Matrix a -> Matrix a
takeMat Int
w Int
h (Matrix a -> Matrix a)
-> (Matrix a -> Matrix a) -> Matrix a -> Matrix a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> Int -> Matrix a -> Matrix a
forall a. Int -> Int -> Matrix a -> Matrix a
dropMat Int
pX Int
pY

-- cropMat w h pX pY = mapV (crop w pX) . crop h pY
--   where crop size pos = dropV pos . takeV (pos + size) 

-- | Groups a matrix into smaller equallly-shaped matrices.
--
-- >>> let m = matrix 4 4 [1,2,3,4,11,12,13,14,21,22,23,24,31,32,33,34]
-- >>> prettyMat " " $ groupMat 2 2 m
--   <<1,2>,<11,12>>   <<3,4>,<13,14>>
-- <<21,22>,<31,32>> <<23,24>,<33,34>>
groupMat :: Int      -- ^ width of groups = @w@
         -> Int      -- ^ height of groups = @h@
         -> Matrix a -- ^ /size/ = @(xa,ya)@
         -> Matrix (Matrix a) -- ^ /size/ = @(xa `div` w,ya `div` h)@
groupMat :: Int -> Int -> Matrix a -> Matrix (Matrix a)
groupMat Int
w Int
h = (Matrix (Vector a) -> Matrix (Vector a))
-> Matrix (Matrix a) -> Matrix (Matrix a)
forall a b. (a -> b) -> Vector a -> Vector b
mapV Matrix (Vector a) -> Matrix (Vector a)
forall a. Matrix a -> Matrix a
transposeMat (Matrix (Matrix a) -> Matrix (Matrix a))
-> (Matrix a -> Matrix (Matrix a)) -> Matrix a -> Matrix (Matrix a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> Matrix (Vector a) -> Matrix (Matrix a)
forall a. Int -> Vector a -> Vector (Vector a)
groupV Int
h (Matrix (Vector a) -> Matrix (Matrix a))
-> (Matrix a -> Matrix (Vector a)) -> Matrix a -> Matrix (Matrix a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Vector a -> Matrix a) -> Matrix a -> Matrix (Vector a)
forall a b. (a -> b) -> Vector a -> Vector b
mapV (Int -> Vector a -> Matrix a
forall a. Int -> Vector a -> Vector (Vector a)
groupV Int
w)


-- | Returns a stencil of neighboring elements for each possible
-- element in a vector.
--
-- >>> let m = matrix 4 4 [1,2,3,4,11,12,13,14,21,22,23,24,31,32,33,34]
-- >>> prettyMat " " $ stencilMat 2 2 m
--   <<1,2>,<11,12>>   <<2,3>,<12,13>>   <<3,4>,<13,14>>
-- <<11,12>,<21,22>> <<12,13>,<22,23>> <<13,14>,<23,24>>
-- <<21,22>,<31,32>> <<22,23>,<32,33>> <<23,24>,<33,34>>
stencilMat :: Int -> Int -> Matrix a -> Matrix (Matrix a)
stencilMat :: Int -> Int -> Matrix a -> Matrix (Matrix a)
stencilMat Int
r Int
c = Matrix (Matrix a) -> Matrix (Matrix a)
forall a. Vector (Matrix a) -> Vector (Matrix a)
arrange (Matrix (Matrix a) -> Matrix (Matrix a))
-> (Matrix a -> Matrix (Matrix a)) -> Matrix a -> Matrix (Matrix a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Matrix (Vector a) -> Matrix (Matrix a)
forall b. Matrix (Vector b) -> Matrix (Vector (Vector b))
groupCols (Matrix (Vector a) -> Matrix (Matrix a))
-> (Matrix a -> Matrix (Vector a)) -> Matrix a -> Matrix (Matrix a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Matrix a -> Matrix (Vector a)
forall b. Vector b -> Vector (Vector b)
groupRows
  where
    groupRows :: Vector b -> Vector (Vector b)
groupRows =         (Vector b -> Vector b) -> Vector (Vector b) -> Vector (Vector b)
forall a b. (a -> b) -> Vector a -> Vector b
mapV (Int -> Vector b -> Vector b
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
takeV Int
r) (Vector (Vector b) -> Vector (Vector b))
-> (Vector b -> Vector (Vector b)) -> Vector b -> Vector (Vector b)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> Vector (Vector b) -> Vector (Vector b)
forall b. Int -> Vector b -> Vector b
dropFromEnd Int
r (Vector (Vector b) -> Vector (Vector b))
-> (Vector b -> Vector (Vector b)) -> Vector b -> Vector (Vector b)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Vector b -> Vector (Vector b)
forall b. Vector b -> Vector (Vector b)
tailsV
    groupCols :: Matrix (Vector b) -> Matrix (Vector (Vector b))
groupCols = (Vector b -> Vector (Vector b))
-> Matrix (Vector b) -> Matrix (Vector (Vector b))
forall a b. (a -> b) -> Matrix a -> Matrix b
mapMat ((Vector b -> Vector b) -> Vector (Vector b) -> Vector (Vector b)
forall a b. (a -> b) -> Vector a -> Vector b
mapV (Int -> Vector b -> Vector b
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
takeV Int
c) (Vector (Vector b) -> Vector (Vector b))
-> (Vector b -> Vector (Vector b)) -> Vector b -> Vector (Vector b)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> Vector (Vector b) -> Vector (Vector b)
forall b. Int -> Vector b -> Vector b
dropFromEnd Int
c (Vector (Vector b) -> Vector (Vector b))
-> (Vector b -> Vector (Vector b)) -> Vector b -> Vector (Vector b)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Vector b -> Vector (Vector b)
forall b. Vector b -> Vector (Vector b)
tailsV)
    arrange :: Vector (Matrix a) -> Vector (Matrix a)
arrange   = (Matrix a -> Matrix a) -> Vector (Matrix a) -> Vector (Matrix a)
forall a b. (a -> b) -> Vector a -> Vector b
mapV Matrix a -> Matrix a
forall a. Matrix a -> Matrix a
transposeMat
    dropFromEnd :: Int -> Vector b -> Vector b
dropFromEnd Int
n Vector b
v = Int -> Vector b -> Vector b
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
takeV (Vector b -> Int
forall a. Vector a -> Int
lengthV Vector b
v Int -> Int -> Int
forall a. Num a => a -> a -> a
- Int
n) Vector b
v

-- | Reverses the order of elements in a matrix
reverseMat :: Matrix a -> Matrix a
reverseMat :: Matrix a -> Matrix a
reverseMat = Matrix a -> Matrix a
forall a. Vector a -> Vector a
reverseV (Matrix a -> Matrix a)
-> (Matrix a -> Matrix a) -> Matrix a -> Matrix a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Vector a -> Vector a) -> Matrix a -> Matrix a
forall a b. (a -> b) -> Vector a -> Vector b
mapV Vector a -> Vector a
forall a. Vector a -> Vector a
reverseV

-- | Pattern which "rotates" a matrix. The rotation is controled with
-- the /x/ and /y/ index arguments as following:
--
-- * @(> 0)@ : rotates the matrix right/down with the corresponding
-- number of positions.
-- 
-- * @(= 0)@ : does not modify the position for that axis.
-- 
-- * @(< 0)@ : rotates the matrix left/up with the corresponding
-- number of positions.
--
-- >>> let m = matrix 4 4 [1,2,3,4,11,12,13,14,21,22,23,24,31,32,33,34]
-- >>> prettyMat " " $ rotateMat (-1) 1 m
-- 32 33 34 31
--  2  3  4  1
-- 12 13 14 11
-- 22 23 24 21
rotateMat :: Int -- ^ index on X axis
          -> Int -- ^ index on Y axis
          -> Vector (Vector a)
          -> Vector (Vector a)
rotateMat :: Int -> Int -> Vector (Vector a) -> Vector (Vector a)
rotateMat Int
x Int
y = Int -> Vector (Vector a) -> Vector (Vector a)
forall b. Int -> Vector b -> Vector b
rotateV Int
y (Vector (Vector a) -> Vector (Vector a))
-> (Vector (Vector a) -> Vector (Vector a))
-> Vector (Vector a)
-> Vector (Vector a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Vector a -> Vector a) -> Vector (Vector a) -> Vector (Vector a)
forall a b. (a -> b) -> Vector a -> Vector b
mapV (Int -> Vector a -> Vector a
forall b. Int -> Vector b -> Vector b
rotateV Int
x)

-- | Transposes a matrx.
transposeMat :: Matrix a -- ^ /size/ = @(x,y)@
             -> Matrix a -- ^ /size/ = @(y,x)@
transposeMat :: Matrix a -> Matrix a
transposeMat Matrix a
NullV = Matrix a
forall a. Vector a
NullV
transposeMat (Vector a
NullV:>Matrix a
xss) = Matrix a -> Matrix a
forall a. Matrix a -> Matrix a
transposeMat Matrix a
xss
transposeMat Matrix a
rows = ((Vector a -> a) -> Matrix a -> Vector a
forall a b. (a -> b) -> Vector a -> Vector b
mapV Vector a -> a
forall a. Vector a -> a
headV Matrix a
rows) Vector a -> Matrix a -> Matrix a
forall a. a -> Vector a -> Vector a
:> Matrix a -> Matrix a
forall a. Matrix a -> Matrix a
transposeMat ((Vector a -> Vector a) -> Matrix a -> Matrix a
forall a b. (a -> b) -> Vector a -> Vector b
mapV Vector a -> Vector a
forall a. Vector a -> Vector a
tailV Matrix a
rows)

-- | Replaces a part of matrix with another (smaller) part, starting
-- from an arbitrary position.
--
-- >>> let m  = matrix 4 4 [1,2,3,4,11,12,13,14,21,22,23,24,31,32,33,34]
-- >>> let m1 = matrix 2 2 [101,202,303,404]
-- >>> prettyMat " " $ replaceMat 1 1 m1 m
--  1   2   3  4
-- 11 101 202 14
-- 21 303 404 24
-- 31  32  33 34
replaceMat :: Int -> Int -> Matrix a -> Matrix a -> Matrix a
replaceMat :: Int -> Int -> Matrix a -> Matrix a -> Matrix a
replaceMat Int
x Int
y Matrix a
mask = Int -> Int -> (Matrix a -> Matrix a) -> Matrix a -> Matrix a
forall a b.
(Num a, Ord a) =>
a -> a -> (Vector b -> Vector b) -> Vector b -> Vector b
replace Int
y Int
h ((Vector a -> Vector a -> Vector a)
-> Matrix a -> Matrix a -> Matrix a
forall a b c. (a -> b -> c) -> Vector a -> Vector b -> Vector c
zipWithV (\Vector a
m Vector a
o -> Int -> Int -> (Vector a -> Vector a) -> Vector a -> Vector a
forall a b.
(Num a, Ord a) =>
a -> a -> (Vector b -> Vector b) -> Vector b -> Vector b
replace Int
x Int
w (\Vector a
_ -> Vector a
m) Vector a
o) Matrix a
mask)
  where
    (Int
w,Int
h) = Matrix a -> (Int, Int)
forall a. Matrix a -> (Int, Int)
sizeMat Matrix a
mask
    replace :: a -> a -> (Vector b -> Vector b) -> Vector b -> Vector b
replace a
start a
size Vector b -> Vector b
replaceF Vector b
vec
      = let begin :: Vector b
begin  = a -> Vector b -> Vector b
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
takeV a
start Vector b
vec
            middle :: Vector b
middle = Vector b -> Vector b
replaceF (Vector b -> Vector b) -> Vector b -> Vector b
forall a b. (a -> b) -> a -> b
$ a -> Vector b -> Vector b
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
dropV a
start (Vector b -> Vector b) -> Vector b -> Vector b
forall a b. (a -> b) -> a -> b
$ a -> Vector b -> Vector b
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
takeV (a
start a -> a -> a
forall a. Num a => a -> a -> a
+ a
size) Vector b
vec
            end :: Vector b
end    = a -> Vector b -> Vector b
forall a b. (Num a, Ord a) => a -> Vector b -> Vector b
dropV (a
start a -> a -> a
forall a. Num a => a -> a -> a
+ a
size) Vector b
vec
        in Vector b
begin Vector b -> Vector b -> Vector b
forall a. Vector a -> Vector a -> Vector a
<+> Vector b
middle Vector b -> Vector b -> Vector b
forall a. Vector a -> Vector a -> Vector a
<+> Vector b
end

zipMat :: Matrix a     -- ^ /size/ = @(xa,ya)@
       -> Matrix b     -- ^ /size/ = @(xb,yb)@
       -> Matrix (a,b) -- ^ /size/ = @(minimum [xa,xb], minimum [ya,yb])@
zipMat :: Matrix a -> Matrix b -> Matrix (a, b)
zipMat = (a -> b -> (a, b)) -> Matrix a -> Matrix b -> Matrix (a, b)
forall a b c. (a -> b -> c) -> Matrix a -> Matrix b -> Matrix c
zipWithMat (,)

unzipMat :: Matrix (a,b)         -- ^ /size/ = @(x,y)@
         -> (Matrix a, Matrix b) -- ^ /size/ = @(x,y)@ and @(x,y)@
unzipMat :: Matrix (a, b) -> (Matrix a, Matrix b)
unzipMat = Vector (Vector a, Vector b) -> (Matrix a, Matrix b)
forall a b. Vector (a, b) -> (Vector a, Vector b)
unzipV (Vector (Vector a, Vector b) -> (Matrix a, Matrix b))
-> (Matrix (a, b) -> Vector (Vector a, Vector b))
-> Matrix (a, b)
-> (Matrix a, Matrix b)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Vector (a, b) -> (Vector a, Vector b))
-> Matrix (a, b) -> Vector (Vector a, Vector b)
forall a b. (a -> b) -> Vector a -> Vector b
mapV Vector (a, b) -> (Vector a, Vector b)
forall a b. Vector (a, b) -> (Vector a, Vector b)
unzipV