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


-- | Multidimensional arrays and simple tensor computations.
--   
--   This is an experimental library for multidimensional arrays, oriented
--   to support simple tensor computations and multilinear algebra.
--   
--   Array dimensions have an "identity" which is preserved in data
--   manipulation. Indices are explicitly selected by name in expressions,
--   and Einstein's summation convention for repeated indices is
--   automatically applied.
--   
--   The library has a purely functional interface: arrays are immutable,
--   and operations typically work on whole structures which can be
--   assembled and decomposed using simple primitives. Arguments are
--   automatically made conformant by replicating them along extra
--   dimensions appearing in an operation. There is preliminary support for
--   Geometric Algebra.
--   
--   A tutorial can be found in the website of the project.
@package hTensor
@version 0.1.1


-- | Additional tools for manipulation of multidimensional arrays.
module Numeric.LinearAlgebra.Array.Util

-- | Types that can be elements of the multidimensional arrays.
class (Num (Vector t), Field t) => Coord t

-- | Class of compatible indices for contractions.
class (Eq a, Show (Idx a)) => Compat a
compat :: (Compat a) => Idx a -> Idx a -> Bool

-- | A multidimensional array with index type i and elements t.
data NArray i t

-- | Dimension descriptor.
data Idx i
Idx :: Int -> Name -> i -> Idx i
iDim :: Idx i -> Int
iName :: Idx i -> Name
iType :: Idx i -> i

-- | indices are denoted by strings, (frequently single-letter)
type Name = String

-- | Create a 0-dimensional structure.
scalar :: (Coord t) => t -> NArray i t

-- | The number of dimensions of a multidimensional array.
rank :: NArray i t -> Int

-- | Index names.
names :: NArray i t -> [Name]

-- | Dimension of given index.
size :: Name -> NArray i t -> Int

-- | Type of given index.
typeOf :: (Compat i) => Name -> NArray i t -> i

-- | Get detailed dimension information about the array.
dims :: NArray i t -> [Idx i]

-- | Get the coordinates of an array as a flattened structure (in the order
--   specified by <a>dims</a>).
coords :: NArray i t -> Vector t

-- | Rename indices. Equal indices are contracted out.
rename :: (Coord t, Compat i) => NArray i t -> [Name] -> NArray i t

-- | <a>rename</a> the indices with single-letter names. Equal indices of
--   compatible type are contracted out.
(!) :: (Coord t, Compat i) => NArray i t -> String -> NArray i t

-- | Create a list of the substructures at the given level.
parts :: (Coord t) => NArray i t -> Name -> [NArray i t]

-- | Create an array from a list of subarrays. (The inverse of
--   <a>parts</a>.)
newIndex :: (Coord t, Compat i) => i -> Name -> [NArray i t] -> NArray i t

-- | Apply a function (defined on hmatrix <a>Vector</a>s) to all elements
--   of a structure. Use <tt>mapArray (mapVector f)</tt> for general
--   functions.
mapArray :: (Coord b) => (Vector a -> Vector b) -> NArray i a -> NArray i b

-- | Apply an element-by-element binary function to the coordinates of two
--   arrays. The arguments are automatically made conformant.
zipArray :: (Coord a, Coord b, Compat i) => (Vector a -> Vector b -> Vector c) -> NArray i a -> NArray i b -> NArray i c

-- | Tensor product with automatic contraction of repeated indices,
--   following Einstein summation convention.
(|*|) :: (Coord t, Compat i) => NArray i t -> NArray i t -> NArray i t

-- | Select some parts of an array, taking into account position and value.
extract :: (Compat i, Coord t) => (Int -> NArray i t -> Bool) -> Name -> NArray i t -> NArray i t

-- | Apply a list function to the parts of an array at a given index.
onIndex :: (Coord a, Coord b, Compat i) => ([NArray i a] -> [NArray i b]) -> Name -> NArray i a -> NArray i b

-- | Change the internal layout of coordinates. The array, considered as an
--   abstract object, does not change.
reorder :: (Coord t) => [Name] -> NArray i t -> NArray i t

-- | <a>reorder</a> (transpose) the dimensions of the array (with single
--   letter names).
--   
--   Operations are defined by named indices, so the transposed array is
--   operationally equivalent to the original one.
(~>) :: (Coord t) => NArray i t -> String -> NArray i t

-- | Show a multidimensional array as a nested 2D table.
formatArray :: (Coord t, Compat i) => (t -> String) -> NArray i t -> String

-- | Show the array as a nested table with a "%.nf" format. If all entries
--   are approximate integers the array is shown without the .00.. digits.
formatFixed :: (Compat i) => Int -> NArray i Double -> String

-- | Show the array as a nested table with autoscaled entries.
formatScaled :: (Compat i) => Int -> NArray i Double -> String

-- | Insert a dummy index of dimension 1 at a given level (for formatting
--   purposes).
dummyAt :: Int -> NArray i t -> NArray i t

-- | Rename indices so that they are not shown in formatted output.
noIdx :: (Compat i) => NArray i t -> NArray i t

-- | Obtains most general structure of a list of dimension specifications
conformable :: (Compat i) => [[Idx i]] -> Maybe [Idx i]

-- | Check if two arrays have the same structure.
sameStructure :: (Eq i) => NArray i t1 -> NArray i t2 -> Bool

-- | Converts a list of arrays to a common structure.
makeConformant :: (Coord t, Compat i) => [NArray i t] -> [NArray i t]

-- | Obtain a canonical base for the array.
basisOf :: (Coord t) => NArray i t -> [NArray i t]

-- | Extract the scalar element corresponding to a 0-dimensional array.
asScalar :: (Coord t) => NArray i t -> t

-- | Extract the <a>Vector</a> corresponding to a one-dimensional array.
asVector :: (Coord t) => NArray i t -> Vector t

-- | Extract the <a>Matrix</a> corresponding to a two-dimensional array, in
--   the rows,cols order.
asMatrix :: (Coord t) => NArray i t -> Matrix t

-- | Create a rank-1 array from an hmatrix <a>Vector</a>.
fromVector :: (Compat i) => i -> Vector t -> NArray i t

-- | Create a rank-2 array from an hmatrix <a>Matrix</a>.
fromMatrix :: (Compat i, Coord t) => i -> i -> Matrix t -> NArray i t

-- | conversion utilities
class (Element e) => Container c :: (* -> *) e
toComplex :: (Container c e) => (c e, c e) -> c (Complex e)
fromComplex :: (Container c e) => c (Complex e) -> (c e, c e)
comp :: (Container c e) => c e -> c (Complex e)
conj :: (Container c e) => c (Complex e) -> c (Complex e)
real :: (Container c e) => c Double -> c e
complex :: (Container c e) => c e -> c (Complex Double)


-- | Simple multidimensional array with useful numeric instances.
--   
--   Contractions only require equal dimension.
module Numeric.LinearAlgebra.Array

-- | Unespecified coordinate type. Contractions only require equal
--   dimension.
data None
None :: None

-- | Multidimensional array with unespecified coordinate type.
type Array t = NArray None t

-- | Construction of an <a>Array</a> from a list of dimensions and a list
--   of elements in left to right order.
listArray :: (Coord t) => [Int] -> [t] -> Array t

-- | Create a 0-dimensional structure.
scalar :: (Coord t) => t -> NArray i t

-- | Create an <a>Array</a> from a list of parts (<tt>index =
--   <a>newIndex</a> <a>None</a></tt>).
index :: (Coord t) => Name -> [Array t] -> Array t

-- | <a>rename</a> the indices with single-letter names. Equal indices of
--   compatible type are contracted out.
(!) :: (Coord t, Compat i) => NArray i t -> String -> NArray i t

-- | <a>reorder</a> (transpose) the dimensions of the array (with single
--   letter names).
--   
--   Operations are defined by named indices, so the transposed array is
--   operationally equivalent to the original one.
(~>) :: (Coord t) => NArray i t -> String -> NArray i t

-- | Element by element product.
(.*) :: (Coord a, Compat i) => NArray i a -> NArray i a -> NArray i a

-- | Print the array as a nested table with the desired format (e.g. %7.2f)
--   (see also <a>formatArray</a>, and <a>formatScaled</a>).
printA :: (Coord t, Compat i, PrintfArg t) => String -> NArray i t -> IO ()
instance (Coord t, Compat i, Fractional (NArray i t), Floating (Vector t)) => Floating (NArray i t)
instance (Coord t, Compat i, Num (NArray i t)) => Fractional (NArray i t)
instance (Show (NArray i t), Coord t, Compat i) => Num (NArray i t)
instance (Coord t, Compat i) => Eq (NArray i t)


-- | Tensor computations. Indices can only be contracted if they are of
--   different <a>Variant</a> type.
module Numeric.LinearAlgebra.Tensor
type Tensor t = NArray Variant t
data Variant
Co :: Variant
Contra :: Variant

-- | Creates a tensor from a list of dimensions and a list of coordinates.
--   A positive dimension means that the index is assumed to be
--   contravariant (vector-like), and a negative dimension means that the
--   index is assumed to be covariant (like a linear function, or
--   covector). Contractions can only be performed between indices of
--   different type.
listTensor :: (Coord t) => [Int] -> [t] -> Tensor t

-- | Create an <a>Tensor</a> from a list of parts with a contravariant
--   index (<tt>superindex = <a>newIndex</a> <a>Contra</a></tt>).
superindex :: (Coord t) => Name -> [Tensor t] -> Tensor t

-- | Create an <a>Tensor</a> from a list of parts with a covariant index
--   (<tt>subindex = <a>newIndex</a> <a>Co</a></tt>).
subindex :: (Coord t) => Name -> [Tensor t] -> Tensor t

-- | Create a contravariant rank-1 tensor from a list of coordinates.
vector :: [Double] -> Tensor Double

-- | Create a covariant rank-1 tensor from a list of coordinates.
covector :: [Double] -> Tensor Double

-- | Create a 1-contravariant, 1-covariant rank-2 tensor from list of lists
--   of coordinates.
transf :: [[Double]] -> Tensor Double

-- | Change the <a>Variant</a> nature of all dimensions to the opposite
--   ones.
switch :: Tensor t -> Tensor t

-- | Make all dimensions covariant.
cov :: NArray i t -> Tensor t

-- | Make all dimensions contravariant.
contrav :: NArray i t -> Tensor t

-- | Remove the <a>Variant</a> nature of coordinates.
forget :: NArray i t -> Array t
instance Eq Variant
instance (Coord t) => Show (Tensor t)
instance Show (Idx Variant)
instance Compat Variant


-- | A simple implementation of Geometric Algebra.
--   
--   The Num instance provides the geometric product, and the Fractional
--   instance provides the inverse of multivectors.
--   
--   This module provides a simple Euclidean embedding.
module Numeric.LinearAlgebra.Multivector
data Multivector
coords :: Multivector -> [(Double, [Int])]

-- | Creates a scalar multivector.
scalar :: Double -> Multivector

-- | Creates a grade 1 multivector of from a list of coordinates.
vector :: [Double] -> Multivector

-- | The k-th basis element.
e :: Int -> Multivector

-- | The exterior (outer) product.
(/\) :: Multivector -> Multivector -> Multivector

-- | The contractive inner product.
(-|) :: Multivector -> Multivector -> Multivector

-- | Intersection of subspaces.
(\/) :: Multivector -> Multivector -> Multivector

-- | The reversion operator.
rever :: Multivector -> Multivector

-- | The full space of the given dimension. This is the leviCivita simbol,
--   and the basis of the pseudoscalar.
full :: Int -> Multivector

-- | The rotor operator, used in a sandwich product.
rotor :: Int -> Double -> Multivector -> Multivector

-- | Apply a linear transformation, expressed as the image of the element
--   i-th of the basis.
--   
--   (This is a monadic bind!)
apply :: (Int -> Multivector) -> Multivector -> Multivector
grade :: Int -> Multivector -> Multivector
maxGrade :: Multivector -> Int
maxDim :: Multivector -> Int

-- | Extract a multivector representation from a full antisymmetric tensor.
--   
--   (We do not check that the tensor is actually antisymmetric.)
fromTensor :: Tensor Double -> Multivector
instance Eq Multivector
instance Fractional Multivector
instance Num Multivector
instance Show Multivector


-- | Exterior Algebra.
module Numeric.LinearAlgebra.Exterior

-- | The exterior (wedge) product of two tensors. Obtains the union of
--   subspaces.
--   
--   Implemented as the antisymmetrization of the tensor product.
(/\) :: (Coord t) => Tensor t -> Tensor t -> Tensor t

-- | Euclidean inner product of multivectors.
inner :: (Coord t) => Tensor t -> Tensor t -> Tensor t

-- | The full antisymmetric tensor of rank n (contravariant version).
leviCivita :: Int -> Tensor Double

-- | Inner product of a r-vector with the whole space.
--   
--   <pre>
--   dual t = inner (leviCivita n) t
--   </pre>
dual :: Tensor Double -> Tensor Double

-- | The "meet" operator. Obtains the intersection of subspaces.
--   
--   <pre>
--   a \/ b = dual (dual a /\ dual b)
--   </pre>
(\/) :: Tensor Double -> Tensor Double -> Tensor Double

-- | Extract a compact multivector representation from a full antisymmetric
--   tensor.
--   
--   asMultivector = Multivector.<a>fromTensor</a>.
--   
--   (We do not check that the tensor is actually antisymmetric.)
asMultivector :: Tensor Double -> Multivector

-- | Create an explicit antisymmetric <a>Tensor</a> from the components of
--   a Multivector of a given grade.
fromMultivector :: Int -> Multivector -> Tensor Double