HMath.Vector¶
Module index · Numerical conventions
Description
Immutable dynamically sized and type-indexed vectors. All indices are zero based. Checked operations reject mismatched dimensions and zero norms.
On this page¶
| API | Purpose |
|---|---|
| Vector | Immutable dynamically sized coordinate list. |
| vector | Wrap a list as an immutable dynamic vector without numeric validation. |
| vectorValues | Extract the immutable list of vector values in order; no shape conversion or numeric validation occurs. |
| vectorDimension | Return the number of coordinates in a dynamic vector. |
| FixedVector | Opaque vector whose length matches its KnownNat type index. |
| SparseVector | Opaque dynamic vector with canonical nonzero coordinate entries. |
| fixedVector | Construct a vector whose list length equals the type-level KnownNat size. |
| fixedValues | Extract the ordered coordinates of a type-indexed vector; its length is the type-level size. |
| sparseVector | Given nonnegative dimension and (zero-based index,value) entries, sum duplicate indices and remove explicit zeros. |
| sparseVectorValues | Expand a sparse vector to a dense list of its declared dimension, filling absent entries with zero. |
| vectorSlice | Given start, count, then vector, return the half-open slice [start,start+count). |
| vectorConcat | Concatenate a list of vectors in order. |
| vectorAdd | Add corresponding values of equally sized vectors, returning a new vector. |
| vectorSubtract | Subtract corresponding right-hand coordinates from left-hand coordinates. |
| vectorScale | Given scalar then vector, multiply every coordinate by the scalar. |
| vectorDot | Sum coordinatewise products of equally sized vectors. |
| cross | Compute the right-handed cross product of two three-dimensional vectors. |
| outer | Return the matrix of pairwise products a[i]*b[j], with shape (dimension a,dimension b). |
| triple | Given a,b,c, compute scalar triple product a dot (b cross c). |
| norm0 | Count nonzero coordinates, returning Int. |
| norm1 | Sum absolute coordinate values. |
| norm2 | Compute Euclidean length using a scaled stable norm to reduce intermediate overflow/underflow. |
| normP | Given positive exponent p then finite vector, compute the scaled p-norm. |
| normInfinity | Return maximum absolute coordinate, or zero for an empty vector. |
| normalizeVector | Return a unit-length vector in the same direction. |
| project | Given a then b, return the projection of a onto b. |
| reflect | Given incident vector then surface normal, return incident minus twice its projection onto the normal. |
| refract | Given positive finite refractive-index ratio, incident vector, then normal, return the refracted unit-direction expression. |
| distance | Return Euclidean distance between equal-sized finite vectors. |
| angle | Return the angle in radians, acos of cosineSimilarity, between two nonzero finite equally sized vectors. |
| cosineSimilarity | Return normalized dot product clamped to [-1,1]. |
| gramSchmidt | Given finite nonnegative relative tolerance then vectors, perform two-pass modified Gram-Schmidt, returning an orthonormal basis in input order. |
Documentation
Vector
Immutable dynamically sized coordinate list. Construct with vector; checked binary operations reject dimension mismatch.
vector
vector :: [a] -> Vector a Source #
Wrap a list as an immutable dynamic vector without numeric validation. The list order is preserved. Example: vectorValues (vector [1,2]) == [1,2].
vectorValues
vectorValues :: Vector a -> [a] Source #
Extract the immutable list of vector values in order; no shape conversion or numeric validation occurs.
vectorDimension
vectorDimension :: Vector a -> Int Source #
Return the number of coordinates in a dynamic vector. Empty vectors have dimension zero.
FixedVector
data FixedVector (n :: Nat) a Source #
Opaque vector whose length matches its KnownNat type index. Construct with fixedVector for a checked dynamic/static boundary.
Instances
| Show a => Show (FixedVector n a) Source # | |
Defined in HMath.Vector Methods showsPrec :: Int -> FixedVector n a -> ShowS # show :: FixedVector n a -> String # showList :: [FixedVector n a] -> ShowS # | |
| Eq a => Eq (FixedVector n a) Source # | |
Defined in HMath.Vector Methods (==) :: FixedVector n a -> FixedVector n a -> Bool # (/=) :: FixedVector n a -> FixedVector n a -> Bool # | |
SparseVector
data SparseVector a Source #
Opaque dynamic vector with canonical nonzero coordinate entries. Construct with sparseVector; duplicate indices add.
Instances
| Show a => Show (SparseVector a) Source # | |
Defined in HMath.Vector Methods showsPrec :: Int -> SparseVector a -> ShowS # show :: SparseVector a -> String # showList :: [SparseVector a] -> ShowS # | |
| Eq a => Eq (SparseVector a) Source # | |
Defined in HMath.Vector Methods (==) :: SparseVector a -> SparseVector a -> Bool # (/=) :: SparseVector a -> SparseVector a -> Bool # | |
fixedVector
fixedVector :: forall (n :: Nat) a. KnownNat n => [a] -> Either MathError (FixedVector n a) Source #
Construct a vector whose list length equals the type-level KnownNat size. A mismatch returns Left InvalidArgument. For example, fixedVector @3 requires exactly three values.
fixedValues
fixedValues :: forall (n :: Nat) a. FixedVector n a -> [a] Source #
Extract the ordered coordinates of a type-indexed vector; its length is the type-level size.
sparseVector
sparseVector :: (Eq a, Num a) => Int -> [(Int, a)] -> Either MathError (SparseVector a) Source #
Given nonnegative dimension and (zero-based index,value) entries, sum duplicate indices and remove explicit zeros. Reject out-of-range indices or negative dimension.
sparseVectorValues
sparseVectorValues :: Num a => SparseVector a -> [a] Source #
Expand a sparse vector to a dense list of its declared dimension, filling absent entries with zero.
vectorSlice
vectorSlice :: Int -> Int -> Vector a -> Either MathError (Vector a) Source #
Given start, count, then vector, return the half-open slice [start,start+count). Reject negative or out-of-range bounds; an empty end slice is valid.
vectorConcat
vectorConcat :: [Vector a] -> Either MathError (Vector a) Source #
Concatenate a list of vectors in order. Return Left InvalidArgument if the combined dimension would overflow Int; an empty list gives an empty vector.
vectorAdd
vectorAdd :: Num a => Vector a -> Vector a -> Either MathError (Vector a) Source #
Add corresponding values of equally sized vectors, returning a new vector. Unequal dimensions return VectorLengthMismatch. Generic Num arithmetic is unchecked.
vectorSubtract
vectorSubtract :: Num a => Vector a -> Vector a -> Either MathError (Vector a) Source #
Subtract corresponding right-hand coordinates from left-hand coordinates. Unequal dimensions return VectorLengthMismatch; Num arithmetic is unchecked.
vectorScale
vectorScale :: Num a => a -> Vector a -> Vector a Source #
Given scalar then vector, multiply every coordinate by the scalar. Return a new vector, retaining the original dimension and Num arithmetic behavior.
vectorDot
vectorDot :: Num a => Vector a -> Vector a -> Either MathError a Source #
Sum coordinatewise products of equally sized vectors. Empty vectors give zero; unequal dimensions return VectorLengthMismatch. No floating-point finiteness check is added.
cross
cross :: Num a => Vector a -> Vector a -> Either MathError (Vector a) Source #
Compute the right-handed cross product of two three-dimensional vectors. Any other dimension returns Left InvalidArgument.
outer
outer :: Num a => Vector a -> Vector a -> Either MathError (Matrix a) Source #
Return the matrix of pairwise products a[i]*b[j], with shape (dimension a,dimension b). Matrix construction can return shape/count errors.
triple
triple :: Num a => Vector a -> Vector a -> Vector a -> Either MathError a Source #
Given a,b,c, compute scalar triple product a dot (b cross c). All three vectors must have dimension three; dimension errors propagate.
norm0
norm0 :: (Eq a, Num a) => Vector a -> Int Source #
Count nonzero coordinates, returning Int. This is the usual sparsity count rather than a norm satisfying homogeneity.
norm1
norm1 :: Num a => Vector a -> a Source #
Sum absolute coordinate values. Empty vector returns zero; arithmetic follows the chosen Num type.
norm2
norm2 :: RealFloat a => Vector a -> a Source #
Compute Euclidean length using a scaled stable norm to reduce intermediate overflow/underflow. Empty vector returns zero; the result itself is not wrapped in Either.
normP
normP :: RealFloat a => a -> Vector a -> Either MathError a Source #
Given positive exponent p then finite vector, compute the scaled p-norm. Positive infinity selects normInfinity. NaN/nonpositive p or non-finite coordinates fail; p<1 is accepted as a quasi-norm.
normInfinity
normInfinity :: (Ord a, Num a) => Vector a -> a Source #
Return maximum absolute coordinate, or zero for an empty vector. NaN coordinates propagate rather than being silently discarded.
normalizeVector
normalizeVector :: RealFloat a => Vector a -> Either MathError (Vector a) Source #
Return a unit-length vector in the same direction. Reject non-finite coordinates, zero norm, or non-finite resulting norm. Empty input is a zero vector and fails.
project
project :: RealFloat a => Vector a -> Vector a -> Either MathError (Vector a) Source #
Given a then b, return the projection of a onto b. Dimensions must agree and b must have nonzero finite norm; non-finite input/result fails.
reflect
reflect :: RealFloat a => Vector a -> Vector a -> Either MathError (Vector a) Source #
Given incident vector then surface normal, return incident minus twice its projection onto the normal. The normal is normalized internally; invalid dimensions, zero normal, or non-finite values fail.
refract
refract :: RealFloat a => a -> Vector a -> Vector a -> Either MathError (Vector a) Source #
Given positive finite refractive-index ratio, incident vector, then normal, return the refracted unit-direction expression. Normalize both inputs; reject invalid dimensions, zero vectors, non-finite values, or total internal reflection.
distance
distance :: RealFloat a => Vector a -> Vector a -> Either MathError a Source #
Return Euclidean distance between equal-sized finite vectors. Dimension mismatch and non-finite inputintermediateresult return Left MathError.
angle
angle :: RealFloat a => Vector a -> Vector a -> Either MathError a Source #
Return the angle in radians, acos of cosineSimilarity, between two nonzero finite equally sized vectors. Invalid dimensions or zero/non-finite vectors fail.
cosineSimilarity
cosineSimilarity :: RealFloat a => Vector a -> Vector a -> Either MathError a Source #
Return normalized dot product clamped to [-1,1]. Equal dimensions and nonzero finite vectors are required; validation errors propagate.
gramSchmidt
gramSchmidt :: RealFloat a => a -> [Vector a] -> Either MathError [Vector a] Source #
Given finite nonnegative relative tolerance then vectors, perform two-pass modified Gram-Schmidt, returning an orthonormal basis in input order. Reject unequal dimensions, zero/dependent vectors (RankDeficient), invalid tolerance, or non-finite data.