Permalink
Browse files

Tweak documentation

  • Loading branch information...
1 parent d8887e9 commit 0becc8511ec0dc3e8e4ea127b536392e75484765 @Shimuuar committed Aug 29, 2012
Showing with 59 additions and 55 deletions.
  1. +6 −4 Data/Matrix/Generic.hs
  2. +5 −2 Data/Matrix/Generic/Mutable.hs
  3. +2 −3 Numeric/BLAS.hs
  4. +20 −17 Numeric/BLAS/Expression.hs
  5. +12 −12 Numeric/BLAS/Mutable.hs
  6. +14 −17 Numeric/BLAS/Mutable/Unsafe.hs
View
@@ -9,12 +9,12 @@
-- Maintainer : Aleksey Khudyakov <alexey.skladnoy@gmail.com>
-- Stability : experimental
--
--- Generic immutable matrix interface There are many different kinds
--- of matrices. They all support different operations so common API
--- is quite poor.
+-- Interface for generic immutable matrices. For matrix transposition
+-- and conjugate transposition newtype wrappers are used.
module Data.Matrix.Generic (
-- * Type class
IsMatrix(..)
+ , Mutable
-- * Accessors
, rows
, cols
@@ -42,7 +42,9 @@ import Data.Vector.Generic (Mutable)
-- Type class
----------------------------------------------------------------
--- | Basic API for immutable matrices.
+-- | Basic API for immutable matrices. Since there's many way to lay
+-- matrix in memory there isn't many operation which work for all of
+-- them.
--
-- Methods of this type class shouldn't be used directly.
class M.IsMMatrix (Mutable mat) a => IsMatrix mat a where
@@ -9,7 +9,8 @@
-- Maintainer : Aleksey Khudyakov <alexey.skladnoy@gmail.com>
-- Stability : experimental
--
--- Generic mutable matrix interface
+-- Interface for generic mutable matrices. For matrix transposition
+-- and conjugate transposition newtype wrappers are used.
module Data.Matrix.Generic.Mutable (
-- * Type class
IsMMatrix(..)
@@ -36,7 +37,9 @@ import Prelude hiding (read)
-- Type class
----------------------------------------------------------------
--- | API for mutable matrices. Matrices
+-- | Type class of mutable matrices. Since there's many way to lay
+-- matrix in memory there isn't many operation which work for all of
+-- them.
--
-- Indexing uses following form: @(row,column)@
class IsMMatrix mat a where
View
@@ -10,7 +10,7 @@
-- Maintainer : Aleksey Khudyakov <alexey.skladnoy@gmail.com>
-- Stability : experimental
--
--- BLAS operations on the immutable vectors
+-- BLAS operations for immutable vectors and matrices.
module Numeric.BLAS (
-- * Type class based API
Add(..)
@@ -24,7 +24,6 @@ module Numeric.BLAS (
, vectorNorm
, absSum
, absIndex
- -- * Matrix vector operations
) where
import Control.Monad.ST
@@ -71,7 +70,7 @@ instance (AddM (Mutable m) a, Freeze m a) => Add (m a) where
x .-. y = eval $ Sub () (Lit x) (Lit y)
{-# INLINE (.-.) #-}
--- | Scalar multiplication
+-- | Multiplication by scalar.
class Scale v a where
(*.) :: a -> v a -> v a
View
@@ -6,11 +6,15 @@
{-# LANGUAGE GADTs #-}
{-# LANGUAGE PatternGuards #-}
-- |
+-- Module : Numeric.BLAS.Expression
+-- Copyright : Copyright (c) 2012 Aleksey Khudyakov <alexey.skladnoy@gmail.com>
+-- License : BSD3
+-- Maintainer : Aleksey Khudyakov <alexey.skladnoy@gmail.com>
+-- Stability : experimental
--
-- This module provides functions for building immutable API using
--- stateful primitives. All dirty work of converting syntax tree to
--- stateful computation is done here. Module 'Numeric.BLAS' provides
--- API for building them.
+-- stateful primitives. Implementation tries to reduce amount of BLAS
+-- calls and amount of allocation.
module Numeric.BLAS.Expression (
-- * Expression data type
Expr(..)
@@ -112,7 +116,7 @@ class Scalable m a where
-- | Elementwise addition and subtraction for mutable data. First
--- argument of 'addM' is modified in place.
+-- arguments of 'addM' and 'subM' are modified in place.
--
-- > x ← x + y
-- > x ← x - y
@@ -132,37 +136,37 @@ class AddM m a where
-- | Expression tree which is compiled by function 'eval'.
data Expr m a where
- -- | Literal value. Could not be altered.
+ -- Literal value. Could not be altered.
Lit :: Freeze m a => m a -> Expr m a
- -- | Addition
+ -- Addition
Add :: (Freeze m a, AddM (Mutable m) a)
=> () -> Expr m a -> Expr m a -> Expr m a
- -- | Subtraction
+ -- Subtraction
Sub :: (Freeze m a, AddM (Mutable m) a)
=> () -> Expr m a -> Expr m a -> Expr m a
- -- | Scalar-X multiplication
+ -- Scalar-X multiplication
Scale :: (Freeze m a, BLAS1 a, Scalable (Mutable m) a)
=> () -> a -> Expr m a -> Expr m a
- -- | vector x transposed vector => matrix
+ -- vector x transposed vector => matrix
VecT :: (Freeze v a, MVectorBLAS (Mutable v), BLAS2 a)
=> () -> Expr v a -> Expr v a -> Expr MatD.Matrix a
- -- | vector x conjugate transposed vector => matrix
+ -- vector x conjugate transposed vector => matrix
VecH :: (Freeze v a, MVectorBLAS (Mutable v), BLAS2 a)
=> () -> Expr v a -> Expr v a -> Expr MatD.Matrix a
- -- | Matrix-vector multiplication
+ -- Matrix-vector multiplication
MulMV :: ( MultMV (Mutable mat) a
, MVectorBLAS (Mutable v), G.Vector v a
, BLAS2 a
, Freeze mat a, Freeze v a
)
=> () -> Expr mat a -> Expr v a -> Expr v a
- -- | Transformed matrix-vector multiplication
+ -- Transformed matrix-vector multiplication
MulTMV :: ( MultTMV (Mutable mat) a
, MVectorBLAS (Mutable v), G.Vector v a
, BLAS2 a
, Freeze mat a, Freeze v a )
=> () -> Trans -> Expr mat a -> Expr v a -> Expr v a
- -- | Matrix-matrix multiplication for dense matrices
+ -- Matrix-matrix multiplication for dense matrices
MulMM :: BLAS3 a
=> ()
-> Trans -> Expr MatD.Matrix a
@@ -176,6 +180,9 @@ type Cont s = forall v a. Expr v a -> ST s (Mutable v s a)
-- Evaluate expression. Returned expression could be mutated in place
-- or unsafe-freezed.
+--
+-- To force GHC to evaluate recursive function trick described here is used:
+-- <http://unlines.wordpress.com/2009/11/05/tricking-ghc-into-evaluating-recursive-functions-at-compile-time/>
evalST :: (() -> Cont s) -> Expr m a -> ST s (Mutable m s a)
{-# INLINE evalST #-}
-- Reduce double scale.
@@ -301,10 +308,6 @@ evalST' _ = evalST evalST'
-- | Evaluate expression. If expression is known statically which is
-- the case if it was built using combinators from 'Numeric.BLAS' it
-- will evaluated at compile time.
---
--- To force GHC to evaluate recursive function trick described here
--- is used:
--- http://unlines.wordpress.com/2009/11/05/tricking-ghc-into-evaluating-recursive-functions-at-compile-time/
eval :: Freeze m a => Expr m a -> m a
{-# INLINE[1] eval #-}
eval x = runST $ do
View
@@ -7,21 +7,16 @@
-- Maintainer : Aleksey Khudyakov <alexey.skladnoy@gmail.com>
-- Stability : experimental
--
--- BLAS interface for mutable data structures.
---
--- This is more or less direct mapping of BLAS operation onto mutable
--- vectors and matrices. There is very little sugar on top of it. API
--- only hides pointers from plain view and provide little less cryptic
--- names.
+-- BLAS interface for mutable data structures. This is more or less
+-- direct mapping of BLAS operation onto mutable vectors and
+-- matrices. There is very little sugar on top of it. API only hides
+-- pointers from plain view and provide little less cryptic names.
+-- Unchecked variants are provided by module
+-- "Numeric.BLAS.Mutable.Unsafe".
module Numeric.BLAS.Mutable (
- -- * BLAS data types
- BLAS1
- , BLAS2
- , BLAS3
- , Trans(..)
-- * Level 1 BLAS (Vector-vector operations)
-- ** Low level data copying
- , copy
+ copy
, swap
, unsafeCopy
, unsafeSwap
@@ -45,6 +40,11 @@ module Numeric.BLAS.Mutable (
, crossHVV
-- * Level 3 BLAS (Matrix-matrix operations)
, multMM
+ -- * BLAS type classes and data types
+ , BLAS1
+ , BLAS2
+ , BLAS3
+ , Trans(..)
-- * Type classes and helpers
, MVectorBLAS(..)
, colsT
@@ -8,27 +8,19 @@
-- Maintainer : Aleksey Khudyakov <alexey.skladnoy@gmail.com>
-- Stability : experimental
--
--- BLAS interface for mutable data structures.
+-- BLAS interface for mutable data structures. This is more or less
+-- direct mapping of BLAS operation onto mutable vectors and
+-- matrices. There is very little sugar on top of it. API only hides
+-- pointers from plain view and provide a bit less cryptic names.
--
--- This is more or less direct mapping of BLAS operation onto mutable
--- vectors and matrices. There is very little sugar on top of it. API
--- only hides pointers from plain view and provide little less cryptic
--- names.
---
--- This module provides unsafe function that doesn't check that
--- dimensions of vectors and matrices match. These function have
--- /unsafe/ prefix. Some function do not need any checking so they
--- don't have prefix. Checked versions are provided by
--- 'Numeric.BLAS.Mutable' module.
+-- Functions which really need checks and could possible return
+-- garbage of even worse corrupt memory have /unsafe/
+-- prefix. Functions which are not really unsafe do not have such.
+-- Checked versions are provided by "Numeric.BLAS.Mutable" module.
module Numeric.BLAS.Mutable.Unsafe (
- -- * BLAS data types
- BLAS1
- , BLAS2
- , BLAS3
- , Trans(..)
-- * Level 1 BLAS (Vector-vector operations)
-- ** Low level data copying
- , unsafeCopy
+ unsafeCopy
, unsafeSwap
-- ** \"Pure\" functions
, unsafeDotProduct
@@ -46,6 +38,11 @@ module Numeric.BLAS.Mutable.Unsafe (
, unsafeCrossHVV
-- * Level 3 BLAS (Matrix-matrix operations)
, unsafeMultMM
+ -- * BLAS type classes and data types
+ , BLAS1
+ , BLAS2
+ , BLAS3
+ , Trans(..)
-- * Type classes and helpers
, MVectorBLAS(..)
, colsT

0 comments on commit 0becc85

Please sign in to comment.