Copyright | (c) Christopher Chalmers |
---|---|
License | BSD3 |
Maintainer | Christopher Chalmers |
Stability | provisional |
Portability | non-portable |
Safe Haskell | None |
Language | Haskell2010 |
This module provides a large subset of the full functionality of "dense" without exporting names that conflict with names in prelude, so it can often be imported unqualified. It also includes reexported classes and data types from other modules. However it does not contain much functions necessary to construct arrays, for that see Data.Dense.Generic or one of the type specific modules intended to be imported qualified. Typical imports for shaped will look like this:
import Data.Dense import qualified Data.Dense.Unboxed as U
For boxed-specific arrays (a la Data.Vector) see Data.Dense.Boxed.
- data Array v f a
- type BArray = Array Vector
- type UArray = Array Vector
- type SArray = Array Vector
- type PArray = Array Vector
- type Layout f = f Int
- class Shape f => HasLayout f a | a -> f where
- class (Eq1 f, Additive f, Traversable f) => Shape f
- extent :: HasLayout f a => a -> f Int
- size :: HasLayout f a => a -> Int
- indexes :: HasLayout f a => IndexedFold Int a (f Int)
- indexesBetween :: HasLayout f a => f Int -> f Int -> IndexedFold Int a (f Int)
- indexesFrom :: HasLayout f a => f Int -> IndexedFold Int a (f Int)
- vector :: (Vector v a, Vector w b) => IndexedLens (Layout f) (Array v f a) (Array w f b) (v a) (w b)
- values :: (Shape f, Vector v a, Vector w b) => IndexedTraversal (f Int) (Array v f a) (Array w f b) a b
- values' :: (Shape f, Vector v a, Vector v b) => IndexedTraversal (f Int) (Array v f a) (Array v f b) a b
- valuesBetween :: (Shape f, Vector v a) => f Int -> f Int -> IndexedTraversal' (f Int) (Array v f a) a
- flat :: Vector w b => Iso (Array v V1 a) (Array w V1 b) (v a) (w b)
- fromListInto :: (Shape f, Vector v a) => Layout f -> [a] -> Maybe (Array v f a)
- fromListInto_ :: (Shape f, Vector v a) => Layout f -> [a] -> Array v f a
- fromVectorInto :: (Shape f, Vector v a) => Layout f -> v a -> Maybe (Array v f a)
- fromVectorInto_ :: (Shape f, Vector v a) => Layout f -> v a -> Array v f a
- ixRow :: Vector v a => Int -> IndexedTraversal' Int (Array v V2 a) (v a)
- rows :: (Vector v a, Vector w b) => IndexedTraversal Int (Array v V2 a) (Array w V2 b) (v a) (w b)
- ixColumn :: Vector v a => Int -> IndexedTraversal' Int (Array v V2 a) (v a)
- columns :: (Vector v a, Vector w b) => IndexedTraversal Int (Array v V2 a) (Array w V2 b) (v a) (w b)
- ixPlane :: Vector v a => ALens' (V3 Int) (V2 Int) -> Int -> IndexedTraversal' Int (Array v V3 a) (Array v V2 a)
- planes :: (Vector v a, Vector w b) => ALens' (V3 Int) (V2 Int) -> IndexedTraversal Int (Array v V3 a) (Array w V3 b) (Array v V2 a) (Array w V2 b)
- flattenPlane :: (Vector v a, Vector w b) => ALens' (V3 Int) (V2 Int) -> (v a -> b) -> Array v V3 a -> Array w V2 b
- data MArray v l s a
- type BMArray = MArray MVector
- type UMArray = MArray MVector
- type SMArray = MArray MVector
- type PMArray = MArray MVector
- data Delayed f a
- delayed :: (Vector v a, Vector w b, Shape f, Shape g) => Iso (Array v f a) (Array w g b) (Delayed f a) (Delayed g b)
- seqDelayed :: (Vector v a, Vector w b, Shape f, Shape g) => Iso (Array v f a) (Array w g b) (Delayed f a) (Delayed g b)
- delay :: (Vector v a, Shape f) => Array v f a -> Delayed f a
- manifest :: (Vector v a, Shape f) => Delayed f a -> Array v f a
- seqManifest :: (Vector v a, Shape f) => Delayed f a -> Array v f a
- genDelayed :: Layout f -> (f Int -> a) -> Delayed f a
- indexDelayed :: Shape f => Delayed f a -> f Int -> a
- affirm :: (Shape f, Unbox a) => Delayed f a -> Delayed f a
- seqAffirm :: (Shape f, Unbox a) => Delayed f a -> Delayed f a
- (*^) :: (Functor f, Num a) => a -> f a -> f a
- (^*) :: (Functor f, Num a) => f a -> a -> f a
- (^/) :: (Functor f, Fractional a) => f a -> a -> f a
- class Functor f => Additive f where
- class Additive f => Metric f where
- data Focused f a
- focusOn :: f Int -> Delayed f a -> Focused f a
- unfocus :: Focused f a -> Delayed f a
- unfocused :: IndexedLens (f Int) (Focused f a) (Focused f b) (Delayed f a) (Delayed f b)
- extendFocus :: Shape f => (Focused f a -> b) -> Delayed f a -> Delayed f b
- locale :: ComonadStore s w => Lens' (w a) s
- shiftFocus :: Applicative f => f Int -> Focused f a -> Focused f a
- data Boundary
- peekB :: Shape f => Boundary -> f Int -> Focused f a -> a
- peeksB :: Shape f => Boundary -> (f Int -> f Int) -> Focused f a -> a
- peekRelativeB :: Shape f => Boundary -> f Int -> Focused f a -> a
- class Functor w => Comonad w where
- class Comonad w => ComonadStore s w | w -> s where
- data Stencil f a
- stencil :: QuasiQuoter
- mkStencil :: [(f Int, a)] -> Stencil f a
- mkStencilTH :: (ShapeLift f, Lift a) => [(f Int, a)] -> Q Exp
- stencilSum :: (Shape f, Num a) => Boundary -> Stencil f a -> Focused f a -> a
- newtype V1 a :: * -> * = V1 a
- data V2 a :: * -> * = V2 ~a ~a
- data V3 a :: * -> * = V3 ~a ~a ~a
- data V4 a :: * -> * = V4 ~a ~a ~a ~a
- class R1 t where
- class R1 t => R2 t where
- class R2 t => R3 t where
- class R3 t => R4 t where
- _xz :: R3 t => Lens' (t a) (V2 a)
- _yz :: R3 t => Lens' (t a) (V2 a)
- _yx :: R2 t => Lens' (t a) (V2 a)
- _zy :: R3 t => Lens' (t a) (V2 a)
- _zx :: R3 t => Lens' (t a) (V2 a)
Array types
An Array
is a vector with a shape.
Indexing
type Layout f = f Int Source #
A Layout
is the full size of an array. This alias is used to help
distinguish between the layout of an array and an index (usually
just l Int
) in a type signature.
class Shape f => HasLayout f a | a -> f where Source #
Class of things that have a Layout
. This means we can use the
same functions for the various different arrays in the library.
layout :: Lens' a (Layout f) Source #
Lens onto the Layout
of something.
layout :: a ~ f Int => (Layout f -> g (Layout f)) -> a -> g a Source #
Lens onto the Layout
of something.
(~) * i Int => HasLayout V4 (V4 i) Source # | |
(~) * i Int => HasLayout V3 (V3 i) Source # | |
(~) * i Int => HasLayout V2 (V2 i) Source # | |
(~) * i Int => HasLayout V1 (V1 i) Source # | |
(~) * i Int => HasLayout V0 (V0 i) Source # | |
Shape f => HasLayout f (Focused f a) Source # | The |
Shape f => HasLayout f (Delayed f a) Source # | The |
Shape f => HasLayout f (Array v f a) Source # | The |
Shape f => HasLayout f (MArray v f s a) Source # | |
class (Eq1 f, Additive f, Traversable f) => Shape f Source #
Class for types that can be converted to and from linear indexes.
Folds over indexes
indexes :: HasLayout f a => IndexedFold Int a (f Int) Source #
Indexed fold for all the indexes in the layout.
indexesBetween :: HasLayout f a => f Int -> f Int -> IndexedFold Int a (f Int) Source #
Indexed fold between the two indexes where the index is the linear index for the original layout.
indexesFrom :: HasLayout f a => f Int -> IndexedFold Int a (f Int) Source #
Indexed fold starting starting from some point, where the index is the linear index for the original layout.
Lenses
vector :: (Vector v a, Vector w b) => IndexedLens (Layout f) (Array v f a) (Array w f b) (v a) (w b) Source #
Traversals
values :: (Shape f, Vector v a, Vector w b) => IndexedTraversal (f Int) (Array v f a) (Array w f b) a b Source #
Indexed traversal over the elements of an array. The index is the current position in the array.
values' :: (Shape f, Vector v a, Vector v b) => IndexedTraversal (f Int) (Array v f a) (Array v f b) a b Source #
Same as values
but restrictive in the vector type.
valuesBetween :: (Shape f, Vector v a) => f Int -> f Int -> IndexedTraversal' (f Int) (Array v f a) a Source #
Traverse over the values
between two indexes.
Construction
Flat arrays
flat :: Vector w b => Iso (Array v V1 a) (Array w V1 b) (v a) (w b) Source #
1D arrays are just vectors. You are free to change the length of
the vector when going over
this Iso
(unlike linear
).
Note that V1
arrays are an instance of Vector
so you can use
any of the functions in Data.Vector.Generic on them without
needing to convert.
Shaped from lists
fromListInto :: (Shape f, Vector v a) => Layout f -> [a] -> Maybe (Array v f a) Source #
O(n) Convert the first n
elements of a list to an Array with the
given shape. Returns Nothing
if there are not enough elements in
the list.
fromListInto_ :: (Shape f, Vector v a) => Layout f -> [a] -> Array v f a Source #
O(n) Convert the first n
elements of a list to an Array with the
given shape. Throw an error if the list is not long enough.
Shaped from vectors
Generating
See Data.Shaped.Generic.
Functions on arrays
Empty arrays
See AsEmpty
class or Data.Shaped.Generic.
Indexing
See Ixed
class.
Modifying arrays
See Data.Shaped.Generic.
Slices
Matrix
ixRow :: Vector v a => Int -> IndexedTraversal' Int (Array v V2 a) (v a) Source #
Affine traversal over a single row in a matrix.
>>>
traverseOf_ rows print $ m & ixRow 1 . each *~ 2
[a,b,c,d] [e * 2,f * 2,g * 2,h * 2] [i,j,k,l]
The row vector should remain the same size to satisfy traversal laws but give reasonable behaviour if the size differs:
>>>
traverseOf_ rows print $ m & ixRow 1 .~ B.fromList [0,1]
[a,b,c,d] [0,1,g,h] [i,j,k,l]
>>>
traverseOf_ rows print $ m & ixRow 1 .~ B.fromList [0..100]
[a,b,c,d] [0,1,2,3] [i,j,k,l]
rows :: (Vector v a, Vector w b) => IndexedTraversal Int (Array v V2 a) (Array w V2 b) (v a) (w b) Source #
Indexed traversal over the rows of a matrix. Each row is an
efficient slice
of the original vector.
>>>
traverseOf_ rows print m
[a,b,c,d] [e,f,g,h] [i,j,k,l]
ixColumn :: Vector v a => Int -> IndexedTraversal' Int (Array v V2 a) (v a) Source #
Affine traversal over a single column in a matrix.
>>>
traverseOf_ rows print $ m & ixColumn 2 . each +~ 1
[a,b,c + 1,d] [e,f,g + 1,h] [i,j,k + 1,l]
columns :: (Vector v a, Vector w b) => IndexedTraversal Int (Array v V2 a) (Array w V2 b) (v a) (w b) Source #
Indexed traversal over the columns of a matrix. Unlike rows
, each
column is a new separate vector.
>>>
traverseOf_ columns print m
[a,e,i] [b,f,j] [c,g,k] [d,h,l]
>>>
traverseOf_ rows print $ m & columns . indices odd . each .~ 0
[a,0,c,0] [e,0,g,0] [i,0,k,0]
The vectors should be the same size to be a valid traversal. If the vectors are different sizes, the number of rows in the new array will be the length of the smallest vector.
3D
ixPlane :: Vector v a => ALens' (V3 Int) (V2 Int) -> Int -> IndexedTraversal' Int (Array v V3 a) (Array v V2 a) Source #
planes :: (Vector v a, Vector w b) => ALens' (V3 Int) (V2 Int) -> IndexedTraversal Int (Array v V3 a) (Array w V3 b) (Array v V2 a) (Array w V2 b) Source #
flattenPlane :: (Vector v a, Vector w b) => ALens' (V3 Int) (V2 Int) -> (v a -> b) -> Array v V3 a -> Array w V2 b Source #
Flatten a plane by reducing a vector in the third dimension to a single value.
Mutable
A mutable array with a shape.
Delayed
A delayed representation of an array. This useful for mapping over an array in parallel.
Shape f => HasLayout f (Delayed f a) Source # | The |
Functor (Delayed f) Source # | |
Shape f => Foldable (Delayed f) Source # |
|
Shape f => Traversable (Delayed f) Source # | |
Shape f => Metric (Delayed f) Source # | |
Shape f => Additive (Delayed f) Source # | |
Shape f => Apply (Delayed f) Source # | |
FunctorWithIndex (f Int) (Delayed f) Source # | |
Shape f => FoldableWithIndex (f Int) (Delayed f) Source # |
|
Shape f => TraversableWithIndex (f Int) (Delayed f) Source # | |
(Shape f, Show1 f, Show a) => Show (Delayed f a) Source # | |
Shape f => Ixed (Delayed f a) Source # | |
Shape f => AsEmpty (Delayed f a) Source # | |
Shape f => Each (Delayed f a) (Delayed f b) a b Source # | |
type Index (Delayed f a) Source # | |
type IxValue (Delayed f a) Source # | |
Generating delayed
delayed :: (Vector v a, Vector w b, Shape f, Shape g) => Iso (Array v f a) (Array w g b) (Delayed f a) (Delayed g b) Source #
Isomorphism between an array and its delayed representation. Conversion to the array is done in parallel.
seqDelayed :: (Vector v a, Vector w b, Shape f, Shape g) => Iso (Array v f a) (Array w g b) (Delayed f a) (Delayed g b) Source #
Isomorphism between an array and its delayed representation. Conversion to the array is done in parallel.
delay :: (Vector v a, Shape f) => Array v f a -> Delayed f a Source #
Turn a material array into a delayed one with the same shape.
manifest :: (Vector v a, Shape f) => Delayed f a -> Array v f a Source #
Parallel manifestation of a delayed array into a material one.
seqManifest :: (Vector v a, Shape f) => Delayed f a -> Array v f a Source #
Sequential manifestation of a delayed array.
indexDelayed :: Shape f => Delayed f a -> f Int -> a Source #
Index a delayed array, returning a IndexOutOfBounds
exception if
the index is out of range.
affirm :: (Shape f, Unbox a) => Delayed f a -> Delayed f a Source #
manifest
an array to a UArray
and delay again. See
Data.Dense.Boxed or Data.Dense.Storable to affirm
for other
types of arrays.
seqAffirm :: (Shape f, Unbox a) => Delayed f a -> Delayed f a Source #
seqManifest
an array to a UArray
and delay again. See
Data.Dense.Boxed or Data.Dense.Storable to affirm
for other
types of arrays.
Helpful reexports
(*^) :: (Functor f, Num a) => a -> f a -> f a infixl 7 #
Compute the left scalar product
>>>
2 *^ V2 3 4
V2 6 8
(^*) :: (Functor f, Num a) => f a -> a -> f a infixl 7 #
Compute the right scalar product
>>>
V2 3 4 ^* 2
V2 6 8
(^/) :: (Functor f, Fractional a) => f a -> a -> f a infixl 7 #
Compute division by a scalar on the right.
class Functor f => Additive f where #
A vector is an additive group with additional structure.
Nothing
Additive [] | |
Additive Maybe | |
Additive Identity | |
Additive Complex | |
Additive ZipList | |
Additive IntMap | |
Additive Vector | |
Additive Quaternion | |
Additive Plucker | |
Additive V4 | |
Additive V3 | |
Additive V2 | |
Additive V1 | |
Additive V0 | |
Additive ((->) b) | |
Ord k => Additive (Map k) | |
(Eq k, Hashable k) => Additive (HashMap k) | |
Shape f => Additive (Delayed f) # | |
Dim k n => Additive (V k n) | |
Focused
A delayed representation of an array with a focus on a single
element. This element is the target of extract
.
Shape f => HasLayout f (Focused f a) Source # | The |
Functor (Focused f) Source # | |
Shape f => Foldable (Focused f) Source # | |
Shape f => Traversable (Focused f) Source # | |
Shape f => Comonad (Focused f) Source # | |
Shape f => Extend (Focused f) Source # | |
Shape f => ComonadStore (f Int) (Focused f) Source # | |
Shape f => FunctorWithIndex (f Int) (Focused f) Source # | Index relative to focus. |
Shape f => FoldableWithIndex (f Int) (Focused f) Source # | Index relative to focus. |
Shape f => TraversableWithIndex (f Int) (Focused f) Source # | Index relative to focus. |
(Shape f, Show1 f, Show a) => Show (Focused f a) Source # | |
Shape f => Ixed (Focused f a) Source # | Index relative to focus. |
type Index (Focused f a) Source # | |
type IxValue (Focused f a) Source # | |
Generating focused
focusOn :: f Int -> Delayed f a -> Focused f a Source #
Focus on a particular element of a delayed array.
unfocused :: IndexedLens (f Int) (Focused f a) (Focused f b) (Delayed f a) (Delayed f b) Source #
Indexed lens onto the delayed array, indexed at the focus.
Focus location
locale :: ComonadStore s w => Lens' (w a) s Source #
Lens onto the position of a ComonadStore
.
locale
::Lens'
(Focused
l a) (lInt
)
shiftFocus :: Applicative f => f Int -> Focused f a -> Focused f a Source #
Focus on a neighbouring element, relative to the current focus.
Boundary
The boundary condition used for indexing relative elements in a
Focused
.
peekB :: Shape f => Boundary -> f Int -> Focused f a -> a Source #
Index a focused using a Boundary
condition.
peeksB :: Shape f => Boundary -> (f Int -> f Int) -> Focused f a -> a Source #
Index an element by applying a function the current position, using a boundary condition.
peekRelativeB :: Shape f => Boundary -> f Int -> Focused f a -> a Source #
Index an element relative to the current focus using a Boundary
condition.
Helpful reexports
class Functor w => Comonad w where #
There are two ways to define a comonad:
I. Provide definitions for extract
and extend
satisfying these laws:
extend
extract
=id
extract
.extend
f = fextend
f .extend
g =extend
(f .extend
g)
In this case, you may simply set fmap
= liftW
.
These laws are directly analogous to the laws for monads and perhaps can be made clearer by viewing them as laws stating that Cokleisli composition must be associative, and has extract for a unit:
f=>=
extract
= fextract
=>=
f = f (f=>=
g)=>=
h = f=>=
(g=>=
h)
II. Alternately, you may choose to provide definitions for fmap
,
extract
, and duplicate
satisfying these laws:
extract
.duplicate
=id
fmap
extract
.duplicate
=id
duplicate
.duplicate
=fmap
duplicate
.duplicate
In this case you may not rely on the ability to define fmap
in
terms of liftW
.
You may of course, choose to define both duplicate
and extend
.
In that case you must also satisfy these laws:
extend
f =fmap
f .duplicate
duplicate
=extend
idfmap
f =extend
(f .extract
)
These are the default definitions of extend
and duplicate
and
the definition of liftW
respectively.
Comonad Identity | |
Comonad NonEmpty | |
Comonad Tree | |
Monoid m => Comonad ((->) m) | |
Comonad ((,) e) | |
(Representable f, Monoid (Rep f)) => Comonad (Co f) | |
Comonad (Arg e) | |
Functor f => Comonad (Cofree f) | |
Comonad w => Comonad (Yoneda w) | |
Monoid s => Comonad (ReifiedGetter s) | |
Comonad f => Comonad (MaybeApply f) | |
Shape f => Comonad (Focused f) # | |
(Comonad w, Monoid m) => Comonad (TracedT m w) | |
Comonad w => Comonad (StoreT s w) | |
Comonad w => Comonad (EnvT e w) | |
Comonad w => Comonad (IdentityT * w) | |
(~) * a b => Comonad (Context a b) | |
Comonad (Tagged * s) | |
(Comonad f, Comonad g) => Comonad (Sum * f g) | |
(~) * a b => Comonad (Molten i a b) | |
((~) * a b, Conjoined p) => Comonad (Pretext p a b) | |
((~) * a b, Conjoined p) => Comonad (PretextT p g a b) | |
class Comonad w => ComonadStore s w | w -> s where #
ComonadStore s w => ComonadStore s (Cofree w) | |
(ComonadStore s w, Monoid m) => ComonadStore s (TracedT m w) | |
Comonad w => ComonadStore s (StoreT s w) | |
ComonadStore s w => ComonadStore s (IdentityT * w) | |
ComonadStore s w => ComonadStore s (EnvT e w) | |
(~) * a b => ComonadStore a (Context a b) | |
((~) * a b, Conjoined p) => ComonadStore a (Pretext p a b) | |
((~) * a b, Conjoined p) => ComonadStore a (PretextT p g a b) | |
Shape f => ComonadStore (f Int) (Focused f) # | |
Stencils
Stencils are used to fold over neighbouring array sites. To
construct a stencil use mkStencil
, mkStencilUnboxed
. For
static sized stencils you can use the quasiquoter
stencil
.
To use a stencil you can use stencilSum
or use the Foldable
and
FoldableWithIndex
instances.
Constructing stencils
stencil :: QuasiQuoter Source #
QuasiQuoter for producing a static stencil definition. This is a
versatile parser for 1D, 2D and 3D stencils. The parsing is similar
to dense
but stencil
also supports _
, which means ignore this
element. Also, stencils should have an odd length in all dimensions
so there is always a center element (which is used as zero
).
Examples
- 1D stencils are of the form
[stencil
| 5 -3 1 -3 5 |] ::Num
a =>Stencil
V1
a
- 2D stencils are of the form
myStencil2 ::Num
a =>Stencil
V2
a myStencil2 = [stencil
| 0 1 0 1 0 1 0 1 0 |]
- 3D stencils have gaps between planes.
myStencil3 ::Fractional
a =>Stencil
V3
a myStencil3 :: [stencil
| 1/20 3/10 1/20 3/10 1 3/10 1/20 3/10 1/20 3/10 1 3/10 1 _ 1 3/10 1 3/10 1/20 3/10 1/20 3/10 1 3/10 1/20 3/10 1/20 |]
Variables can also be used
myStencil2' :: a -> a -> a ->Stencil
V2
a myStencil2' a b c = [stencil
| c b c b a b c b c |]
mkStencil :: [(f Int, a)] -> Stencil f a Source #
Make a stencil folding over a list.
If the list is staticlly known this should expand at compile time
via rewrite rules, similar to makeStencilTH
but less reliable. If
that does not happen the resulting could be slow. If the list is
not know at compile time, mkStencilUnboxed
can be signifcantly
faster (but isn't subject expending via rewrite rules).
mkStencilTH :: (ShapeLift f, Lift a) => [(f Int, a)] -> Q Exp Source #
Construct a Stencil
by unrolling the list at compile time. For
example
ifoldr
f b $(mkStencilTH
[(V1
(-1), 5), (V1
0, 3), (V1
1, 5)])
will be get turned into
f (V1
(-1)) 5 (f (V1
0) 3 (f (V1
1) 5 b))
at compile time. Since there are no loops and all target indexes are known at compile time, this can lead to more optimisations and faster execution times. This can lead to around a 2x speed up compared to folding over unboxed vectors.
myStencil = $(mkStencilTH
(as :: [(fInt
, a)])) ::Stencil
f a
Using stencils
stencilSum :: (Shape f, Num a) => Boundary -> Stencil f a -> Focused f a -> a Source #
Sum the elements around a Focused
using a Boundary
condition
and a Stencil
.
This is often used in conjunction with extendFocus
.
Common shapes
A 1-dimensional vector
>>>
pure 1 :: V1 Int
V1 1
>>>
V1 2 + V1 3
V1 5
>>>
V1 2 * V1 3
V1 6
>>>
sum (V1 2)
2
V1 a |
A 2-dimensional vector
>>>
pure 1 :: V2 Int
V2 1 1
>>>
V2 1 2 + V2 3 4
V2 4 6
>>>
V2 1 2 * V2 3 4
V2 3 8
>>>
sum (V2 1 2)
3
V2 ~a ~a |
A 3-dimensional vector
V3 ~a ~a ~a |
A 4-dimensional vector.
V4 ~a ~a ~a ~a |
A space that has at least 1 basis vector _x
.
Nothing
Nothing
Nothing
Nothing