HMath.Complex

Module index · Numerical conventions

Description

Checked finite complex arithmetic over Data.Complex. Angles are radians, positive rotations are counterclockwise, and logarithms/powers use the principal branch (argument in (-pi,pi], with IEEE signed-zero behavior inherited from Data.Complex). Poles, zero reciprocals, and nonfinite results are errors. Matrices use the existing row-major M.Matrix; FFTs use the existing negative forward-exponent convention. The reference matrix budget is 256 per dimension.

On this page

API	Purpose
Complex	A data type representing complex numbers.
complex	Construct a finite number from real and imaginary parts.
realPart	Extracts the real part of a complex number.
imagPart	Extracts the imaginary part of a complex number.
magnitude	The non-negative magnitude of a complex number.
phase	The phase of a complex number, in the range (-pi, pi].
conjugate	The conjugate of a complex number.
reciprocal	Reciprocal using scaled division to avoid squaring a large norm.
add	Checked sum.
subtractComplex	Checked difference.
multiply	Checked product.
divide	Smith scaled division.
power	Principal complex power. 0^0 is 1; other zero-base exponents must be positive real.
Elementary	Elementary functions with principal inverse-function branches.
Exp	Declaration and type contract below.
Log	Declaration and type contract below.
Sqrt	Declaration and type contract below.
Sin	Declaration and type contract below.
Cos	Declaration and type contract below.
Tan	Declaration and type contract below.
Sinh	Declaration and type contract below.
Cosh	Declaration and type contract below.
Tanh	Declaration and type contract below.
Asin	Declaration and type contract below.
Acos	Declaration and type contract below.
Atan	Declaration and type contract below.
Asinh	Declaration and type contract below.
Acosh	Declaration and type contract below.
Atanh	Declaration and type contract below.
elementary	Apply an elementary function, rejecting poles and nonfinite results.
fromPolar	Polar construction with nonnegative finite radius.
toPolar	Radius and principal phase; the phase of zero is defined by Data.Complex.
rotate	Counterclockwise rotation in the complex plane.
complexMatrix	Checked finite complex matrix, at most 256 rows and columns.
multiplyMatrices	Matrix multiplication with finite-result validation.
conjugateTranspose	Hermitian transpose with finite-input validation.
complexFFT	Existing checked mixed-radix/Bluestein forward FFT.
complexIFFT	Existing checked inverse FFT, normalized by sample count.

Documentation

Complex

data Complex a #

A data type representing complex numbers.

You can read about complex numbers on wikipedia.

In haskell, complex numbers are represented as a :+ b which can be thought of as representing \(a + bi\). For a complex number z, abs z is a number with the magnitude of z, but oriented in the positive real direction, whereas signum z has the phase of z, but unit magnitude. Apart from the loss of precision due to IEEE754 floating point numbers, it holds that z == abs z * signum z.

Note that Complex's instances inherit the deficiencies from the type parameter's. For example, Complex Float's Ord instance has similar problems to Float's.

As can be seen in the examples, the Foldable and Traversable instances traverse the real part first.

Examples

Expand

>>> (5.0 :+ 2.5) + 6.5
11.5 :+ 2.5

>>> abs (1.0 :+ 1.0) - sqrt 2.0
0.0 :+ 0.0

>>> abs (signum (4.0 :+ 3.0))
1.0 :+ 0.0

>>> foldr (:) [] (1 :+ 2)
[1,2]

>>> mapM print (1 :+ 2)
1
2

Instances

Instances details

MonadZip Complex	Since: base-4.15.0.0
Instance details Defined in Data.Complex Methods mzip :: Complex a -> Complex b -> Complex (a, b) # mzipWith :: (a -> b -> c) -> Complex a -> Complex b -> Complex c # munzip :: Complex (a, b) -> (Complex a, Complex b) #
Foldable1 Complex	Since: base-4.18.0.0
Instance details Defined in Data.Foldable1 Methods fold1 :: Semigroup m => Complex m -> m # foldMap1 :: Semigroup m => (a -> m) -> Complex a -> m # foldMap1' :: Semigroup m => (a -> m) -> Complex a -> m # toNonEmpty :: Complex a -> NonEmpty a # maximum :: Ord a => Complex a -> a # minimum :: Ord a => Complex a -> a # head :: Complex a -> a # last :: Complex a -> a # foldrMap1 :: (a -> b) -> (a -> b -> b) -> Complex a -> b # foldlMap1' :: (a -> b) -> (b -> a -> b) -> Complex a -> b # foldlMap1 :: (a -> b) -> (b -> a -> b) -> Complex a -> b # foldrMap1' :: (a -> b) -> (a -> b -> b) -> Complex a -> b #
Eq1 Complex	>>> eq1 (1 :+ 2) (1 :+ 2) True >>> eq1 (1 :+ 2) (1 :+ 3) False Since: base-4.16.0.0
Instance details Defined in Data.Functor.Classes Methods liftEq :: (a -> b -> Bool) -> Complex a -> Complex b -> Bool #
Read1 Complex	>>> readPrec_to_S readPrec1 0 "(2 % 3) :+ (3 % 4)" :: [(Complex Rational, String)] [(2 % 3 :+ 3 % 4,"")] Since: base-4.16.0.0
Instance details Defined in Data.Functor.Classes Methods liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (Complex a) # liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [Complex a] # liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (Complex a) # liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [Complex a] #
Show1 Complex	>>> showsPrec1 0 (2 :+ 3) "" "2 :+ 3" Since: base-4.16.0.0
Instance details Defined in Data.Functor.Classes Methods liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> Complex a -> ShowS # liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [Complex a] -> ShowS #
Applicative Complex	Since: base-4.9.0.0
Instance details Defined in Data.Complex Methods pure :: a -> Complex a # (<*>) :: Complex (a -> b) -> Complex a -> Complex b # liftA2 :: (a -> b -> c) -> Complex a -> Complex b -> Complex c # (*>) :: Complex a -> Complex b -> Complex b # (<*) :: Complex a -> Complex b -> Complex a #
Functor Complex	Since: base-4.9.0.0
Instance details Defined in Data.Complex Methods fmap :: (a -> b) -> Complex a -> Complex b # (<$) :: a -> Complex b -> Complex a #
Monad Complex	Since: base-4.9.0.0
Instance details Defined in Data.Complex Methods (>>=) :: Complex a -> (a -> Complex b) -> Complex b # (>>) :: Complex a -> Complex b -> Complex b # return :: a -> Complex a #
MonadFix Complex	Since: base-4.15.0.0
Instance details Defined in Data.Complex Methods mfix :: (a -> Complex a) -> Complex a #
Foldable Complex	Since: base-4.9.0.0
Instance details Defined in Data.Complex Methods fold :: Monoid m => Complex m -> m # foldMap :: Monoid m => (a -> m) -> Complex a -> m # foldMap' :: Monoid m => (a -> m) -> Complex a -> m # foldr :: (a -> b -> b) -> b -> Complex a -> b # foldr' :: (a -> b -> b) -> b -> Complex a -> b # foldl :: (b -> a -> b) -> b -> Complex a -> b # foldl' :: (b -> a -> b) -> b -> Complex a -> b # foldr1 :: (a -> a -> a) -> Complex a -> a # foldl1 :: (a -> a -> a) -> Complex a -> a # toList :: Complex a -> [a] # null :: Complex a -> Bool # length :: Complex a -> Int # elem :: Eq a => a -> Complex a -> Bool # maximum :: Ord a => Complex a -> a # minimum :: Ord a => Complex a -> a # sum :: Num a => Complex a -> a # product :: Num a => Complex a -> a #
Traversable Complex	Since: base-4.9.0.0
Instance details Defined in Data.Complex Methods traverse :: Applicative f => (a -> f b) -> Complex a -> f (Complex b) # sequenceA :: Applicative f => Complex (f a) -> f (Complex a) # mapM :: Monad m => (a -> m b) -> Complex a -> m (Complex b) # sequence :: Monad m => Complex (m a) -> m (Complex a) #
Generic1 Complex
Instance details Defined in Data.Complex Associated Types type Rep1 Complex Since: base-4.9.0.0 Instance details Defined in Data.Complex type Rep1 Complex = D1 ('MetaData "Complex" "Data.Complex" "base" 'False) (C1 ('MetaCons ":+" ('InfixI 'NotAssociative 6) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) Par1 :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) Par1)) Methods from1 :: Complex a -> Rep1 Complex a # to1 :: Rep1 Complex a -> Complex a #
Data a => Data (Complex a)	Since: base-2.1
Instance details Defined in Data.Complex Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Complex a -> c (Complex a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Complex a) # toConstr :: Complex a -> Constr # dataTypeOf :: Complex a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Complex a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Complex a)) # gmapT :: (forall b. Data b => b -> b) -> Complex a -> Complex a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Complex a -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Complex a -> r # gmapQ :: (forall d. Data d => d -> u) -> Complex a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Complex a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Complex a -> m (Complex a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Complex a -> m (Complex a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Complex a -> m (Complex a) #
RealFloat a => Floating (Complex a)	Since: base-2.1
Instance details Defined in Data.Complex Methods pi :: Complex a # exp :: Complex a -> Complex a # log :: Complex a -> Complex a # sqrt :: Complex a -> Complex a # (**) :: Complex a -> Complex a -> Complex a # logBase :: Complex a -> Complex a -> Complex a # sin :: Complex a -> Complex a # cos :: Complex a -> Complex a # tan :: Complex a -> Complex a # asin :: Complex a -> Complex a # acos :: Complex a -> Complex a # atan :: Complex a -> Complex a # sinh :: Complex a -> Complex a # cosh :: Complex a -> Complex a # tanh :: Complex a -> Complex a # asinh :: Complex a -> Complex a # acosh :: Complex a -> Complex a # atanh :: Complex a -> Complex a # log1p :: Complex a -> Complex a # expm1 :: Complex a -> Complex a # log1pexp :: Complex a -> Complex a # log1mexp :: Complex a -> Complex a #
Storable a => Storable (Complex a)	Since: base-4.8.0.0
Instance details Defined in Data.Complex Methods sizeOf :: Complex a -> Int # alignment :: Complex a -> Int # peekElemOff :: Ptr (Complex a) -> Int -> IO (Complex a) # pokeElemOff :: Ptr (Complex a) -> Int -> Complex a -> IO () # peekByteOff :: Ptr b -> Int -> IO (Complex a) # pokeByteOff :: Ptr b -> Int -> Complex a -> IO () # peek :: Ptr (Complex a) -> IO (Complex a) # poke :: Ptr (Complex a) -> Complex a -> IO () #
Generic (Complex a)
Instance details Defined in Data.Complex Associated Types type Rep (Complex a) Since: base-4.9.0.0 Instance details Defined in Data.Complex type Rep (Complex a) = D1 ('MetaData "Complex" "Data.Complex" "base" 'False) (C1 ('MetaCons ":+" ('InfixI 'NotAssociative 6) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a))) Methods from :: Complex a -> Rep (Complex a) x # to :: Rep (Complex a) x -> Complex a #
RealFloat a => Num (Complex a)	Since: base-2.1
Instance details Defined in Data.Complex Methods (+) :: Complex a -> Complex a -> Complex a # (-) :: Complex a -> Complex a -> Complex a # (*) :: Complex a -> Complex a -> Complex a # negate :: Complex a -> Complex a # abs :: Complex a -> Complex a # signum :: Complex a -> Complex a # fromInteger :: Integer -> Complex a #
Read a => Read (Complex a)	Since: base-2.1
Instance details Defined in Data.Complex Methods readsPrec :: Int -> ReadS (Complex a) # readList :: ReadS [Complex a] # readPrec :: ReadPrec (Complex a) # readListPrec :: ReadPrec [Complex a] #
RealFloat a => Fractional (Complex a)	Since: base-2.1
Instance details Defined in Data.Complex Methods (/) :: Complex a -> Complex a -> Complex a # recip :: Complex a -> Complex a # fromRational :: Rational -> Complex a #
Show a => Show (Complex a)	Since: base-2.1
Instance details Defined in Data.Complex Methods showsPrec :: Int -> Complex a -> ShowS # show :: Complex a -> String # showList :: [Complex a] -> ShowS #
Eq a => Eq (Complex a)	Since: base-2.1
Instance details Defined in Data.Complex Methods (==) :: Complex a -> Complex a -> Bool # (/=) :: Complex a -> Complex a -> Bool #
Field (Complex Double) Source #
Instance details Defined in HMath.API.Algebra Methods invert :: Complex Double -> Either MathError (Complex Double) Source #
FloatingPoint (Complex Double) Source #
Instance details Defined in HMath.API.Algebra Methods machineEpsilon :: proxy (Complex Double) -> Double Source # finiteScalar :: Complex Double -> Bool Source #
Numeric (Complex Double) Source #
Instance details Defined in HMath.API.Algebra Methods rational :: Rational -> Either MathError (Complex Double) Source #
Ring (Complex Double) Source #
Instance details Defined in HMath.API.Algebra Methods zero :: Complex Double Source # one :: Complex Double Source # plus :: Complex Double -> Complex Double -> Complex Double Source # times :: Complex Double -> Complex Double -> Complex Double Source # negative :: Complex Double -> Complex Double Source # integer :: Integer -> Complex Double Source #
Scalar (Complex Double) Source #
Instance details Defined in HMath.API.Algebra Methods conjugateScalar :: Complex Double -> Complex Double Source #
Element (Complex Double) Source #
Instance details Defined in HMath.Interchange.Array Methods elementType :: proxy (Complex Double) -> DType Source # putElement :: Endian -> Complex Double -> Put Source # getElement :: Endian -> Get (Complex Double) Source #
Element (Complex Float) Source #
Instance details Defined in HMath.Interchange.Array Methods elementType :: proxy (Complex Float) -> DType Source # putElement :: Endian -> Complex Float -> Put Source # getElement :: Endian -> Get (Complex Float) Source #
type Rep1 Complex	Since: base-4.9.0.0
Instance details Defined in Data.Complex type Rep1 Complex = D1 ('MetaData "Complex" "Data.Complex" "base" 'False) (C1 ('MetaCons ":+" ('InfixI 'NotAssociative 6) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) Par1 :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) Par1))
type Rep (Complex a)	Since: base-4.9.0.0
Instance details Defined in Data.Complex type Rep (Complex a) = D1 ('MetaData "Complex" "Data.Complex" "base" 'False) (C1 ('MetaCons ":+" ('InfixI 'NotAssociative 6) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a)))

complex

complex :: Double -> Double -> Either MathError (Complex Double) Source #

Construct a finite number from real and imaginary parts.

realPart

realPart :: Complex a -> a #

Extracts the real part of a complex number.

Examples

Expand

>>> realPart (5.0 :+ 3.0)
5.0

>>> realPart ((5.0 :+ 3.0) * (2.0 :+ 3.0))
1.0

imagPart

imagPart :: Complex a -> a #

Extracts the imaginary part of a complex number.

Examples

Expand

>>> imagPart (5.0 :+ 3.0)
3.0

>>> imagPart ((5.0 :+ 3.0) * (2.0 :+ 3.0))
21.0

magnitude

magnitude :: RealFloat a => Complex a -> a #

The non-negative magnitude of a complex number.

Examples

Expand

>>> magnitude (1.0 :+ 1.0)
1.4142135623730951

>>> magnitude (1.0 + 0.0)
1.0

>>> magnitude (0.0 :+ (-5.0))
5.0

phase

phase :: RealFloat a => Complex a -> a #

The phase of a complex number, in the range (-pi, pi]. If the magnitude is zero, then so is the phase.

Examples

Expand

>>> phase (0.5 :+ 0.5) / pi
0.25

>>> phase (0 :+ 4) / pi
0.5

conjugate

conjugate :: Num a => Complex a -> Complex a #

The conjugate of a complex number.

conjugate (conjugate x) = x

Examples

Expand

>>> conjugate (3.0 :+ 3.0)
3.0 :+ (-3.0)

>>> conjugate ((3.0 :+ 3.0) * (2.0 :+ 2.0))
0.0 :+ (-12.0)

reciprocal

reciprocal :: Complex Double -> Either MathError (Complex Double) Source #

Reciprocal using scaled division to avoid squaring a large norm.

add

add :: Complex Double -> Complex Double -> Either MathError (Complex Double) Source #

Checked sum.

subtractComplex

subtractComplex :: Complex Double -> Complex Double -> Either MathError (Complex Double) Source #

Checked difference.

multiply

multiply :: Complex Double -> Complex Double -> Either MathError (Complex Double) Source #

Checked product.

divide

divide :: Complex Double -> Complex Double -> Either MathError (Complex Double) Source #

Smith scaled division. A zero divisor is rejected.

power

power :: Complex Double -> Complex Double -> Either MathError (Complex Double) Source #

Principal complex power. 0^0 is 1; other zero-base exponents must be positive real.

Elementary

data Elementary Source #

Elementary functions with principal inverse-function branches.

Constructors

Exp
Log
Sqrt
Sin
Cos
Tan
Sinh
Cosh
Tanh
Asin
Acos
Atan
Asinh
Acosh
Atanh

Instances

Instances details

Show Elementary Source #
Instance details Defined in HMath.Complex Methods showsPrec :: Int -> Elementary -> ShowS # show :: Elementary -> String # showList :: [Elementary] -> ShowS #
Eq Elementary Source #
Instance details Defined in HMath.Complex Methods (==) :: Elementary -> Elementary -> Bool # (/=) :: Elementary -> Elementary -> Bool #

elementary

elementary :: Elementary -> Complex Double -> Either MathError (Complex Double) Source #

Apply an elementary function, rejecting poles and nonfinite results.

fromPolar

fromPolar :: Double -> Double -> Either MathError (Complex Double) Source #

Polar construction with nonnegative finite radius.

toPolar

toPolar :: Complex Double -> Either MathError (Double, Double) Source #

Radius and principal phase; the phase of zero is defined by Data.Complex.

rotate

rotate :: Double -> Complex Double -> Either MathError (Complex Double) Source #

Counterclockwise rotation in the complex plane.

complexMatrix

complexMatrix :: Int -> Int -> [Complex Double] -> Either MathError (Matrix (Complex Double)) Source #

Checked finite complex matrix, at most 256 rows and columns.

multiplyMatrices

multiplyMatrices :: Matrix (Complex Double) -> Matrix (Complex Double) -> Either MathError (Matrix (Complex Double)) Source #

Matrix multiplication with finite-result validation.

conjugateTranspose

conjugateTranspose :: Matrix (Complex Double) -> Either MathError (Matrix (Complex Double)) Source #

Hermitian transpose with finite-input validation.

complexFFT

complexFFT :: [Complex Double] -> Either MathError [Complex Double] Source #

Existing checked mixed-radix/Bluestein forward FFT.

complexIFFT

complexIFFT :: [Complex Double] -> Either MathError [Complex Double] Source #

Existing checked inverse FFT, normalized by sample count.