HMath.API.Shape

Module index · Numerical conventions

Description

Runtime-checked shapes and nominal type-indexed matrices/tensors. Shape witnesses never coerce arbitrary dimensions. Conversion checks occur at the dynamic/static boundary; multiplication then requires matching types.

On this page

API	Purpose
Shape	Scalars have shape [] and one element.
shapeDimensions	Return runtime dimensions in axis order.
shapeElements	Return the validated shape product, including one for scalar [] and zero when an axis is zero.
makeShape	Validate nonnegative dimensions and an Int-representable element product, returning an immutable shape witness.
ScalarShape	Read-only views: construction always uses makeShape.
VectorShape	Declaration and type contract below.
MatrixShape	Declaration and type contract below.
StaticMatrix	Nominal type-indexed matrix dimensions,validated by staticMatrix.
staticMatrix	Given a dynamic matrix, compare its dimensions against type-level m and n, returning a nominally indexed witness.
dynamicMatrix	Forget the nominal type-level dimensions of a StaticMatrix, returning the same immutable dynamic matrix without changing its values.
staticMultiply	Multiply statically compatible m-by-k and k-by-n matrices.
staticTranspose	Transpose a StaticMatrix m n to StaticMatrix n m, preserving values with axes exchanged.
KnownShape	Type-level list of natural dimensions, reflected without Int truncation.
reflectedShape	Given a type-level shape proxy, reflect exact Integer dimensions without truncation to Int.
StaticTensor	Nominal type-indexed tensor shape,validated against reflected runtime dimensions by staticTensor.
staticTensor	Given dynamic tensor and type-level shape ds, return a nominal witness only if runtime dimensions match reflectedShape exactly.
dynamicTensor	Forget a StaticTensor shape witness, returning its underlying immutable dynamic tensor without numerical conversion.
Coordinates	Fixed-length coordinates with lawful zip Applicative.
coordinates	Construct a type-indexed coordinate list only when list length equals the KnownNat index.
coordinateValues	Extract the ordered list of a Coordinates n value.
coordinatesToVector	Convert Coordinates n to a dynamic Vector.

Documentation

Shape

data Shape Source #

Scalars have shape [] and one element. Zero axes are allowed.

Instances

Instances details

Show Shape Source #
Instance details Defined in HMath.API.Shape Methods showsPrec :: Int -> Shape -> ShowS # show :: Shape -> String # showList :: [Shape] -> ShowS #
Eq Shape Source #
Instance details Defined in HMath.API.Shape Methods (==) :: Shape -> Shape -> Bool # (/=) :: Shape -> Shape -> Bool #
Ord Shape Source #
Instance details Defined in HMath.API.Shape Methods compare :: Shape -> Shape -> Ordering # (<) :: Shape -> Shape -> Bool # (<=) :: Shape -> Shape -> Bool # (>) :: Shape -> Shape -> Bool # (>=) :: Shape -> Shape -> Bool # max :: Shape -> Shape -> Shape # min :: Shape -> Shape -> Shape #

shapeDimensions

shapeDimensions :: Shape -> [Int] Source #

Return runtime dimensions in axis order. Scalars have []; zero-length axes are retained.

shapeElements

shapeElements :: Shape -> Int Source #

Return the validated shape product, including one for scalar [] and zero when an axis is zero.

makeShape

makeShape :: [Int] -> Either MathError Shape Source #

Validate nonnegative dimensions and an Int-representable element product, returning an immutable shape witness. Invalid dimensions/overflow return Left MathError. Example: shapeElements <$> makeShape [2,3] == Right 6.

ScalarShape

pattern ScalarShape :: Shape Source #

Read-only views: construction always uses makeShape.

VectorShape

pattern VectorShape :: Int -> Shape Source #

MatrixShape

pattern MatrixShape :: Int -> Int -> Shape Source #

StaticMatrix

data StaticMatrix (m :: Nat) (n :: Nat) a Source #

Nominal type-indexed matrix dimensions,validated by staticMatrix. Compatible multiplication is expressed by shared type indices.

Instances

Instances details

Functor (StaticMatrix m n) Source #
Instance details Defined in HMath.API.Shape Methods fmap :: (a -> b) -> StaticMatrix m n a -> StaticMatrix m n b # (<$) :: a -> StaticMatrix m n b -> StaticMatrix m n a #
Foldable (StaticMatrix m n) Source #
Instance details Defined in HMath.API.Shape Methods fold :: Monoid m0 => StaticMatrix m n m0 -> m0 # foldMap :: Monoid m0 => (a -> m0) -> StaticMatrix m n a -> m0 # foldMap' :: Monoid m0 => (a -> m0) -> StaticMatrix m n a -> m0 # foldr :: (a -> b -> b) -> b -> StaticMatrix m n a -> b # foldr' :: (a -> b -> b) -> b -> StaticMatrix m n a -> b # foldl :: (b -> a -> b) -> b -> StaticMatrix m n a -> b # foldl' :: (b -> a -> b) -> b -> StaticMatrix m n a -> b # foldr1 :: (a -> a -> a) -> StaticMatrix m n a -> a # foldl1 :: (a -> a -> a) -> StaticMatrix m n a -> a # toList :: StaticMatrix m n a -> [a] # null :: StaticMatrix m n a -> Bool # length :: StaticMatrix m n a -> Int # elem :: Eq a => a -> StaticMatrix m n a -> Bool # maximum :: Ord a => StaticMatrix m n a -> a # minimum :: Ord a => StaticMatrix m n a -> a # sum :: Num a => StaticMatrix m n a -> a # product :: Num a => StaticMatrix m n a -> a #
Traversable (StaticMatrix m n) Source #
Instance details Defined in HMath.API.Shape Methods traverse :: Applicative f => (a -> f b) -> StaticMatrix m n a -> f (StaticMatrix m n b) # sequenceA :: Applicative f => StaticMatrix m n (f a) -> f (StaticMatrix m n a) # mapM :: Monad m0 => (a -> m0 b) -> StaticMatrix m n a -> m0 (StaticMatrix m n b) # sequence :: Monad m0 => StaticMatrix m n (m0 a) -> m0 (StaticMatrix m n a) #
Show a => Show (StaticMatrix m n a) Source #
Instance details Defined in HMath.API.Shape Methods showsPrec :: Int -> StaticMatrix m n a -> ShowS # show :: StaticMatrix m n a -> String # showList :: [StaticMatrix m n a] -> ShowS #
Eq a => Eq (StaticMatrix m n a) Source #
Instance details Defined in HMath.API.Shape Methods (==) :: StaticMatrix m n a -> StaticMatrix m n a -> Bool # (/=) :: StaticMatrix m n a -> StaticMatrix m n a -> Bool #

staticMatrix

staticMatrix :: forall (m :: Nat) (n :: Nat) a. (KnownNat m, KnownNat n) => Matrix a -> Either MathError (StaticMatrix m n a) Source #

Given a dynamic matrix, compare its dimensions against type-level m and n, returning a nominally indexed witness. Reject type-level Int overflow or runtime mismatch.

dynamicMatrix

dynamicMatrix :: forall (m :: Nat) (n :: Nat) a. StaticMatrix m n a -> Matrix a Source #

Forget the nominal type-level dimensions of a StaticMatrix, returning the same immutable dynamic matrix without changing its values.

staticMultiply

staticMultiply :: forall a (m :: Nat) (k :: Nat) (n :: Nat). Num a => StaticMatrix m k a -> StaticMatrix k n a -> Either MathError (StaticMatrix m n a) Source #

Multiply statically compatible m-by-k and k-by-n matrices. Return an m-by-n witness; checked dynamic size errors can still return Left MathError. Num arithmetic follows the element instance.

staticTranspose

staticTranspose :: forall (m :: Nat) (n :: Nat) a. StaticMatrix m n a -> StaticMatrix n m a Source #

Transpose a StaticMatrix m n to StaticMatrix n m, preserving values with axes exchanged.

KnownShape

class KnownShape (ds :: [Nat]) where Source #

Type-level list of natural dimensions, reflected without Int truncation.

Methods

reflectedShape :: proxy ds -> [Integer] Source #

Given a type-level shape proxy, reflect exact Integer dimensions without truncation to Int.

Instances

Instances details

KnownShape ('[] :: [Nat]) Source #
Instance details Defined in HMath.API.Shape Methods reflectedShape :: proxy ('[] :: [Nat]) -> [Integer] Source #
(KnownNat n, KnownShape ns) => KnownShape (n ': ns) Source #
Instance details Defined in HMath.API.Shape Methods reflectedShape :: proxy (n ': ns) -> [Integer] Source #

StaticTensor

data StaticTensor (ds :: [Nat]) a Source #

Nominal type-indexed tensor shape,validated against reflected runtime dimensions by staticTensor.

Instances

Instances details

Show a => Show (StaticTensor ds a) Source #
Instance details Defined in HMath.API.Shape Methods showsPrec :: Int -> StaticTensor ds a -> ShowS # show :: StaticTensor ds a -> String # showList :: [StaticTensor ds a] -> ShowS #
Eq a => Eq (StaticTensor ds a) Source #
Instance details Defined in HMath.API.Shape Methods (==) :: StaticTensor ds a -> StaticTensor ds a -> Bool # (/=) :: StaticTensor ds a -> StaticTensor ds a -> Bool #

staticTensor

staticTensor :: forall (ds :: [Nat]) a. KnownShape ds => Tensor a -> Either MathError (StaticTensor ds a) Source #

Given dynamic tensor and type-level shape ds, return a nominal witness only if runtime dimensions match reflectedShape exactly. A mismatch returns Left InvalidArgument.

dynamicTensor

dynamicTensor :: forall (ds :: [Nat]) a. StaticTensor ds a -> Tensor a Source #

Forget a StaticTensor shape witness, returning its underlying immutable dynamic tensor without numerical conversion.

Coordinates

data Coordinates (n :: Nat) a Source #

Fixed-length coordinates with lawful zip Applicative. Elements are lazy; purefmaptraverse preserve length. Type-level lengths can exceed Int; the conversion to ordinary vectors rejects such lengths before traversing data.

Instances

Instances details

KnownNat n => Applicative (Coordinates n) Source #
Instance details Defined in HMath.API.Shape Methods pure :: a -> Coordinates n a # (<*>) :: Coordinates n (a -> b) -> Coordinates n a -> Coordinates n b # liftA2 :: (a -> b -> c) -> Coordinates n a -> Coordinates n b -> Coordinates n c # (*>) :: Coordinates n a -> Coordinates n b -> Coordinates n b # (<*) :: Coordinates n a -> Coordinates n b -> Coordinates n a #
Functor (Coordinates n) Source #
Instance details Defined in HMath.API.Shape Methods fmap :: (a -> b) -> Coordinates n a -> Coordinates n b # (<$) :: a -> Coordinates n b -> Coordinates n a #
Foldable (Coordinates n) Source #
Instance details Defined in HMath.API.Shape Methods fold :: Monoid m => Coordinates n m -> m # foldMap :: Monoid m => (a -> m) -> Coordinates n a -> m # foldMap' :: Monoid m => (a -> m) -> Coordinates n a -> m # foldr :: (a -> b -> b) -> b -> Coordinates n a -> b # foldr' :: (a -> b -> b) -> b -> Coordinates n a -> b # foldl :: (b -> a -> b) -> b -> Coordinates n a -> b # foldl' :: (b -> a -> b) -> b -> Coordinates n a -> b # foldr1 :: (a -> a -> a) -> Coordinates n a -> a # foldl1 :: (a -> a -> a) -> Coordinates n a -> a # toList :: Coordinates n a -> [a] # null :: Coordinates n a -> Bool # length :: Coordinates n a -> Int # elem :: Eq a => a -> Coordinates n a -> Bool # maximum :: Ord a => Coordinates n a -> a # minimum :: Ord a => Coordinates n a -> a # sum :: Num a => Coordinates n a -> a # product :: Num a => Coordinates n a -> a #
Traversable (Coordinates n) Source #
Instance details Defined in HMath.API.Shape Methods traverse :: Applicative f => (a -> f b) -> Coordinates n a -> f (Coordinates n b) # sequenceA :: Applicative f => Coordinates n (f a) -> f (Coordinates n a) # mapM :: Monad m => (a -> m b) -> Coordinates n a -> m (Coordinates n b) # sequence :: Monad m => Coordinates n (m a) -> m (Coordinates n a) #
Show a => Show (Coordinates n a) Source #
Instance details Defined in HMath.API.Shape Methods showsPrec :: Int -> Coordinates n a -> ShowS # show :: Coordinates n a -> String # showList :: [Coordinates n a] -> ShowS #
Eq a => Eq (Coordinates n a) Source #
Instance details Defined in HMath.API.Shape Methods (==) :: Coordinates n a -> Coordinates n a -> Bool # (/=) :: Coordinates n a -> Coordinates n a -> Bool #

coordinates

coordinates :: forall (n :: Nat) a. KnownNat n => [a] -> Either MathError (Coordinates n a) Source #

Construct a type-indexed coordinate list only when list length equals the KnownNat index. A mismatch returns Left InvalidArgument; values remain lazy.

coordinateValues

coordinateValues :: forall (n :: Nat) a. Coordinates n a -> [a] Source #

Extract the ordered list of a Coordinates n value. The nominal length invariant is preserved by its public constructors.

coordinatesToVector

coordinatesToVector :: forall (n :: Nat) a. KnownNat n => Coordinates n a -> Either MathError (Vector a) Source #

Convert Coordinates n to a dynamic Vector. Reject a type-level length exceeding Int before traversing the coordinate list; otherwise preserve all values.