diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,31 @@ Changelog ========= +Version 0.1.3.0 +--------------- + +*February 11, 2020* + + + +* Added "generic" versions of vector conversions, to cover the common use + cases involving conversion to and from non-storable vectors. This + includes: + + * `grVec` + * `gvecR` + * `gcVec` + * `gvecC` + * `glVec` + * `gvecL` + * `gmVec` + * `gvecM` + + Rewrite rules are included so that you can use these with storable vectors + without any cost, but don't rely on those. + +* Added big-O analysis to documentation for all functions. + Version 0.1.2.0 --------------- diff --git a/hmatrix-vector-sized.cabal b/hmatrix-vector-sized.cabal --- a/hmatrix-vector-sized.cabal +++ b/hmatrix-vector-sized.cabal @@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 333f0f10beb5c9bbb414d7f8ad6e7e23eb992e393a3e945cd300ec8b6e1be88b +-- hash: a5877680d4dec870c954c7ea6cdff48cc6d104451fb00555c9e89a212b921cbc name: hmatrix-vector-sized -version: 0.1.2.0 +version: 0.1.3.0 synopsis: Conversions between hmatrix and vector-sized types description: Conversions between statically sized types in hmatrix and vector-sized. . diff --git a/src/Numeric/LinearAlgebra/Static/Vector.hs b/src/Numeric/LinearAlgebra/Static/Vector.hs --- a/src/Numeric/LinearAlgebra/Static/Vector.hs +++ b/src/Numeric/LinearAlgebra/Static/Vector.hs @@ -1,4 +1,5 @@ {-# LANGUAGE CPP #-} +{-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeApplications #-} {-# LANGUAGE TypeOperators #-} @@ -30,10 +31,14 @@ -- * Vector -- ** Real rVec + , grVec , vecR + , gvecR -- ** Complex , cVec + , gcVec , vecC + , gvecC -- * Matrix -- ** Real , lRows @@ -41,14 +46,18 @@ , lCols , colsL , lVec + , glVec , vecL + , gvecL -- ** Complex , mRows , rowsM , mCols , colsM , mVec + , gmVec , vecM + , gvecM ) where import Data.Foldable @@ -56,6 +65,8 @@ import GHC.TypeLits import Unsafe.Coerce import qualified Data.Vector as UV +import qualified Data.Vector.Generic as UVG +import qualified Data.Vector.Generic.Sized as VG import qualified Data.Vector.Sized as V import qualified Data.Vector.Storable.Sized as VS import qualified Numeric.LinearAlgebra as HU @@ -63,29 +74,88 @@ -- | Convert an /hmatrix/ vector (parameterized by its lenth) to -- a /vector-sized/ storable vector of 'Double's. +-- +-- This is normally /O(1)/, but will be /O(n)/ if the 'H.R' was contructed +-- with 'H.konst' or any other replicated-value constructor (like literals +-- and 'fromInteger'/'fromRational'). rVec :: KnownNat n => H.R n -> VS.Vector n H.ℝ rVec = unsafeCoerce . H.extract +-- | 'rVec', but generalized to work for all types of sized vectors. +-- +-- Usually /O(n)/, but if using this with storable vectors, should have the +-- same characteristics as 'rVec' due to rewrite rules. +-- +-- @since 0.1.3.0 +grVec :: (KnownNat n, UVG.Vector v H.ℝ) => H.R n -> VG.Vector v n H.ℝ +grVec = VG.convert . rVec +{-# NOINLINE[1] grVec #-} +{-# RULES "grVec" grVec = rVec #-} + -- | Convert a /vector-sized/ storable vector to an /hmatrix/ vector -- (parameterized by its lenth). +-- +-- /O(1)/ vecR :: VS.Vector n H.ℝ -> H.R n vecR = unsafeCoerce +-- | 'vecR', but generalized to work for all types of sized vectors. +-- +-- Usually /O(n)/, but if using this with storable vectors, should be /O(1)/ +-- due to rewrite rules (but don't rely on this). +-- +-- @since 0.1.3.0 +gvecR :: UVG.Vector v H.ℝ => VG.Vector v n H.ℝ -> H.R n +gvecR = vecR . VG.convert +{-# NOINLINE[1] gvecR #-} +{-# RULES "gvecR" gvecR = vecR #-} + -- | Convert an /hmatrix/ complex vector (parameterized by its lenth) to -- a /vector-sized/ storable vector of 'Complex Double's, preserving the -- length in the type. +-- +-- This is normally /O(1)/, but will be /O(n)/ if the 'H.C' was contructed +-- with 'H.konst' or any other replicated-value constructor (like literals +-- and 'fromInteger'/'fromRational'). cVec :: KnownNat n => H.C n -> VS.Vector n H.ℂ cVec = unsafeCoerce . H.extract +-- | 'cVec', but generalized to work for all types of sized vectors. +-- +-- Usually /O(n)/, but if using this with storable vectors, should have the +-- same characteristics as 'cVec' due to rewrite rules. +-- +-- @since 0.1.3.0 +gcVec :: (KnownNat n, UVG.Vector v H.ℂ) => H.C n -> VG.Vector v n H.ℂ +gcVec = VG.convert . cVec +{-# NOINLINE[1] gcVec #-} +{-# RULES "gcVec" gcVec = cVec #-} + -- | Convert a /vector-sized/ storable vector to an /hmatrix/ complex -- vector (parameterized by its lenth), preserving the length in the type. +-- +-- /O(1)/ vecC :: VS.Vector n H.ℂ -> H.C n vecC = unsafeCoerce +-- | 'vecC', but generalized to work for all types of sized vectors. +-- +-- Usually /O(n)/, but if using this with storable vectors, should be /O(1)/ +-- due to rewrite rules (but don't rely on this). +-- +-- @since 0.1.3.0 +gvecC :: UVG.Vector v H.ℂ => VG.Vector v n H.ℂ -> H.C n +gvecC = vecC . VG.convert +{-# NOINLINE[1] gvecC #-} +{-# RULES "gvecC" gvecC = vecC #-} + -- | Split an /hmatrix/ matrix (parameterized by its dimensions) to -- a /vector-sized/ boxed vector of its rows (as /hmatrix/ vectors). +-- +-- This is normally /O(m*n)/, but can sometimes be /O(m)/ depending on the +-- representation of the 'H.L' being used. lRows - :: forall m n. (KnownNat m, KnownNat n) + :: (KnownNat m, KnownNat n) => H.L m n -> V.Vector m (H.R n) lRows = unsafeCoerce @@ -95,6 +165,8 @@ -- | Join together a /vector-sized/ boxed vector of /hmatrix/ vectors to an -- /hmatrix/ matrix as its rows. +-- +-- /O(m*n)/ rowsL :: forall m n. KnownNat n => V.Vector m (H.R n) @@ -106,6 +178,9 @@ -- | Split an /hmatrix/ matrix (parameterized by its dimensions) to -- a /vector-sized/ boxed vector of its columns (as /hmatrix/ vectors). +-- +-- This is normally /O(m*n)/, but can sometimes be /O(n)/ depending on the +-- representation of the 'H.L' being used. lCols :: forall m n. (KnownNat m, KnownNat n) => H.L m n @@ -117,6 +192,8 @@ -- | Join together a /vector-sized/ boxed vector of /hmatrix/ vectors to an -- /hmatrix/ matrix as its columns. +-- +-- /O(m*n)/ colsL :: forall m n. KnownNat m => V.Vector n (H.R m) @@ -129,6 +206,9 @@ -- | Split an /hmatrix/ complex matrix (parameterized by its dimensions) to -- a /vector-sized/ boxed vector of its rows (as /hmatrix/ complex -- vectors). +-- +-- This is normally /O(m*n)/, but can sometimes be /O(m)/ depending on the +-- representation of the 'H.C' being used. mRows :: forall m n. (KnownNat m, KnownNat n) => H.M m n @@ -140,6 +220,8 @@ -- | Join together a /vector-sized/ boxed vector of /hmatrix/ complex -- vectors to an /hmatrix/ complex matrix as its rows. +-- +-- /O(m*n)/ rowsM :: forall m n. KnownNat n => V.Vector m (H.C n) @@ -152,6 +234,9 @@ -- | Split an /hmatrix/ complex matrix (parameterized by its dimensions) to -- a /vector-sized/ boxed vector of its columns (as /hmatrix/ complex -- vectors). +-- +-- This is normally /O(m*n)/, but can sometimes be /O(n)/ depending on the +-- representation of the 'H.C' being used. mCols :: forall m n. (KnownNat m, KnownNat n) => H.M m n @@ -163,6 +248,8 @@ -- | Join together a /vector-sized/ boxed vector of /hmatrix/ complex -- vectors to an /hmatrix/ complex matrix as its columns. +-- +-- /O(m*n)/ colsM :: forall m n. KnownNat m => V.Vector n (H.C m) @@ -175,6 +262,8 @@ -- | Shape a /vector-sized/ storable vector of elements into an /hmatrix/ -- matrix. -- +-- /O(1)/ +-- -- @since 0.1.1.0 vecL :: forall m n. KnownNat n @@ -184,9 +273,26 @@ . HU.reshape (fromIntegral (natVal (Proxy @n))) . unsafeCoerce +-- | 'vecL', but generalized to work for all types of sized vectors. +-- +-- Usually /O(n)/, but if using this with storable vectors, should be /O(1)/ +-- due to rewrite rules (but don't rely on this). +-- +-- @since 0.1.3.0 +gvecL + :: (KnownNat n, UVG.Vector v H.ℝ) + => VG.Vector v (m * n) H.ℝ + -> H.L m n +gvecL = vecL . VG.convert +{-# NOINLINE[1] gvecL #-} +{-# RULES "gvecL" gvecL = vecL #-} + -- | Flatten an /hmatrix/ matrix into a /vector-sized/ storable vector of -- its items. -- +-- This is normally /O(m*n)/, but can sometimes be /O(1)/ depending on the +-- representation of the 'H.L' being used. +-- -- @since 0.1.1.0 lVec :: forall m n. (KnownNat m, KnownNat n) @@ -196,9 +302,25 @@ . HU.flatten . H.extract +-- | 'lVec', but generalized to work for all types of sized vectors. +-- +-- Usually /O(m*n)/, but if using this with storable vectors, should have the +-- same characteristics as 'lVec' due to rewrite rules. +-- +-- @since 0.1.3.0 +glVec + :: (KnownNat m, KnownNat n, UVG.Vector v H.ℝ) + => H.L m n + -> VG.Vector v (m * n) H.ℝ +glVec = VG.convert . lVec +{-# NOINLINE[1] glVec #-} +{-# RULES "glVec" glVec = lVec #-} + -- | Shape a /vector-sized/ storable vector of elements into an /hmatrix/ -- complex matrix. -- +-- /O(1)/ +-- -- @since 0.1.1.0 vecM :: forall m n. KnownNat n @@ -208,9 +330,26 @@ . HU.reshape (fromIntegral (natVal (Proxy @n))) . unsafeCoerce +-- | 'vecM', but generalized to work for all types of sized vectors. +-- +-- Usually /O(m*n)/, but if using this with storable vectors, should be /O(1)/ +-- due to rewrite rules (but don't rely on this). +-- +-- @since 0.1.3.0 +gvecM + :: (KnownNat n, UVG.Vector v H.ℂ) + => VG.Vector v (m * n) H.ℂ + -> H.M m n +gvecM = vecM . VG.convert +{-# NOINLINE[1] gvecM #-} +{-# RULES "gvecM" gvecM = vecM #-} + -- | Flatten an /hmatrix/ complex matrix into a /vector-sized/ storable -- vector of its items. -- +-- This is normally /O(m*n)/, but can sometimes be /O(1)/ depending on the +-- representation of the 'H.M' being used. +-- -- @since 0.1.1.0 mVec :: forall m n. (KnownNat m, KnownNat n) @@ -220,3 +359,16 @@ . HU.flatten . H.extract +-- | 'mVec', but generalized to work for all types of sized vectors. +-- +-- Usually /O(m*n)/, but if using this with storable vectors, should have the +-- same characteristics as 'mVec' due to rewrite rules. +-- +-- @since 0.1.3.0 +gmVec + :: (KnownNat m, KnownNat n, UVG.Vector v H.ℂ) + => H.M m n + -> VG.Vector v (m * n) H.ℂ +gmVec = VG.convert . mVec +{-# NOINLINE[1] gmVec #-} +{-# RULES "gmVec" gmVec = mVec #-}