-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A subfield of the complex numbers for exact calculation.
--   
--   The cyclotomic numbers are a subset of the complex numbers that are
--   represented exactly, enabling exact computations and equality
--   comparisons. They contain the Gaussian rationals (complex numbers of
--   the form p + q i with p and q rational), as well as all complex roots
--   of unity. The cyclotomic numbers contain the square roots of all
--   rational numbers. They contain the sine and cosine of all rational
--   multiples of pi. The cyclotomic numbers form a field, being closed
--   under addition, subtraction, mutiplication, and division.
@package cyclotomic
@version 0.5.1


-- | The cyclotomic numbers are a subset of the complex numbers with the
--   following properties:
--   
--   <ol>
--   <li>The cyclotomic numbers are represented exactly, enabling exact
--   computations and equality comparisons.</li>
--   <li>The cyclotomic numbers contain the Gaussian rationals (complex
--   numbers of the form <tt>p</tt> + <tt>q</tt> <a>i</a> with <tt>p</tt>
--   and <tt>q</tt> rational). As a consequence, the cyclotomic numbers are
--   a dense subset of the complex numbers.</li>
--   <li>The cyclotomic numbers contain the square roots of all rational
--   numbers.</li>
--   <li>The cyclotomic numbers form a field: they are closed under
--   addition, subtraction, multiplication, and division.</li>
--   <li>The cyclotomic numbers contain the sine and cosine of all rational
--   multiples of pi.</li>
--   <li>The cyclotomic numbers can be thought of as the rational field
--   extended with <tt>n</tt>th roots of unity for arbitrarily large
--   integers <tt>n</tt>.</li>
--   </ol>
--   
--   Floating point numbers do not do well with equality comparison:
--   
--   <pre>
--   (sqrt 2 + sqrt 3)^2 == 5 + 2 * sqrt 6
--    -&gt; False
--   </pre>
--   
--   <a>Data.Complex.Cyclotomic</a> represents these numbers exactly,
--   allowing equality comparison:
--   
--   <pre>
--   (sqrtRat 2 + sqrtRat 3)^2 == 5 + 2 * sqrtRat 6
--    -&gt; True
--   </pre>
--   
--   <a>Cyclotomic</a>s can be exported as inexact complex numbers using
--   the <a>toComplex</a> function:
--   
--   <pre>
--   e 6
--    -&gt; -e(3)^2
--   real $ e 6
--    -&gt; 1/2
--   imag $ e 6
--    -&gt; -1/2*e(12)^7 + 1/2*e(12)^11
--   imag (e 6) == sqrtRat 3 / 2
--    -&gt; True
--   toComplex $ e 6
--    -&gt; 0.5000000000000003 :+ 0.8660254037844384
--   </pre>
--   
--   The algorithms for cyclotomic numbers are adapted from code by Martin
--   Schoenert and Thomas Breuer in the GAP project
--   <a>http://www.gap-system.org/</a> (in particular source files
--   gap4r4/src/cyclotom.c and gap4r4/lib/cyclotom.gi).
module Data.Complex.Cyclotomic

-- | A cyclotomic number.
data Cyclotomic

-- | The square root of -1.
i :: Cyclotomic

-- | The primitive <tt>n</tt>th root of unity. For example, <tt><a>e</a>(4)
--   = <a>i</a></tt> is the primitive 4th root of unity, and <a>e</a>(5) =
--   exp(2*pi*i/5) is the primitive 5th root of unity. In general, <a>e</a>
--   <tt>n</tt> = exp(2*pi*i/<tt>n</tt>).
e :: Integer -> Cyclotomic

-- | The square root of an <a>Integer</a>.
sqrtInteger :: Integer -> Cyclotomic

-- | The square root of a <a>Rational</a> number.
sqrtRat :: Rational -> Cyclotomic

-- | Sine function with argument in degrees.
sinDeg :: Rational -> Cyclotomic

-- | Cosine function with argument in degrees.
cosDeg :: Rational -> Cyclotomic

-- | Sine function with argument in revolutions.
sinRev :: Rational -> Cyclotomic

-- | Cosine function with argument in revolutions.
cosRev :: Rational -> Cyclotomic

-- | Make a Gaussian rational; <tt>gaussianRat p q</tt> is the same as
--   <tt>p + q * i</tt>.
gaussianRat :: Rational -> Rational -> Cyclotomic

-- | A complex number in polar form, with rational magnitude <tt>r</tt> and
--   rational angle <tt>s</tt> of the form <tt>r * exp(2*pi*i*s)</tt>;
--   <tt>polarRat r s</tt> is the same as <tt>r * e q ^ p</tt>, where <tt>s
--   = p/q</tt>. This function is the same as <a>polarRatRev</a>.
polarRat :: Rational -> Rational -> Cyclotomic

-- | A complex number in polar form, with rational magnitude and rational
--   angle in degrees.
polarRatDeg :: Rational -> Rational -> Cyclotomic

-- | A complex number in polar form, with rational magnitude and rational
--   angle in revolutions.
polarRatRev :: Rational -> Rational -> Cyclotomic

-- | Complex conjugate.
conj :: Cyclotomic -> Cyclotomic

-- | Real part of the cyclotomic number.
real :: Cyclotomic -> Cyclotomic

-- | Imaginary part of the cyclotomic number.
imag :: Cyclotomic -> Cyclotomic

-- | Is the cyclotomic a real number?
isReal :: Cyclotomic -> Bool

-- | Is the cyclotomic a rational?
isRat :: Cyclotomic -> Bool

-- | Is the cyclotomic a Gaussian rational?
isGaussianRat :: Cyclotomic -> Bool

-- | Export as an inexact complex number.
toComplex :: RealFloat a => Cyclotomic -> Complex a

-- | Export as an inexact real number if possible.
toReal :: RealFloat a => Cyclotomic -> Maybe a

-- | Return an exact rational number if possible.
toRat :: Cyclotomic -> Maybe Rational

-- | The golden ratio, <tt>(1 + √5)/2</tt>.
goldenRatio :: Cyclotomic

-- | Discrete Fourier transform, <tt>X_k = sum_{n=0}^{N-1} x_n cdot e^{-i 2
--   pi frac{k}{N} n}</tt>.
dft :: [Cyclotomic] -> [Cyclotomic]

-- | Inverse discrete Fourier transform, <tt>x_n = frac{1}{N}
--   sum_{k=0}^{N-1} X_k cdot e^{i 2 pi frac{k}{N} n}</tt>.
dftInv :: [Cyclotomic] -> [Cyclotomic]

-- | Solutions to the quadratic equation a x^2 + b x + c = 0. Returns
--   <a>Nothing</a> if a == 0.
rootsQuadEq :: Rational -> Rational -> Rational -> Maybe (Cyclotomic, Cyclotomic)

-- | Heron's formula for the area of a triangle with side lengths a, b, c.
heron :: Rational -> Rational -> Rational -> Cyclotomic
instance GHC.Classes.Eq Data.Complex.Cyclotomic.Cyclotomic
instance GHC.Num.Num Data.Complex.Cyclotomic.Cyclotomic
instance GHC.Real.Fractional Data.Complex.Cyclotomic.Cyclotomic
instance GHC.Show.Show Data.Complex.Cyclotomic.Cyclotomic


-- | The real cyclotomic numbers are a subset of the real numbers with the
--   following properties:
--   
--   <ol>
--   <li>The real cyclotomic numbers are represented exactly, enabling
--   exact computations and equality comparisons.</li>
--   <li>The real cyclotomic numbers contain the rationals. As a
--   consequence, the real cyclotomic numbers are a dense subset of the
--   real numbers.</li>
--   <li>The real cyclotomic numbers contain the square roots of all
--   nonnegative rational numbers.</li>
--   <li>The real cyclotomic numbers form a field: they are closed under
--   addition, subtraction, multiplication, and division.</li>
--   <li>The real cyclotomic numbers contain the sine and cosine of all
--   rational multiples of pi (equivalently, the sine and cosine of any
--   rational number of degrees or any rational number of
--   revolutions).</li>
--   </ol>
--   
--   Floating point numbers do not do well with equality comparison:
--   
--   <pre>
--   (sqrt 2 + sqrt 3)^2 == 5 + 2 * sqrt 6
--    -&gt; False
--   </pre>
--   
--   <a>Data.Number.RealCyclotomic</a> represents these numbers exactly,
--   allowing equality comparison:
--   
--   <pre>
--   (sqrtRat 2 + sqrtRat 3)^2 == 5 + 2 * sqrtRat 6
--    -&gt; True
--   </pre>
--   
--   <a>RealCyclotomic</a>s can be exported as inexact real numbers using
--   the <a>toReal</a> function:
--   
--   <pre>
--   sqrtRat 2
--    -&gt; e(8) - e(8)^3
--   toReal $ sqrtRat 2
--    -&gt; 1.414213562373095
--   </pre>
--   
--   This module is based on the module <a>Cyclotomic</a>. Usually you
--   would only import one of the modules <a>RealCyclotomic</a> or
--   <a>Cyclotomic</a>, depending on whether you wanted only real numbers
--   (this module) or complex numbers (the other). Functions such as
--   <tt>sqrtRat</tt>, <tt>sinDeg</tt>, <tt>cosDeg</tt> are defined in both
--   modules, with different type signatures, so their names will conflict
--   if both modules are imported.
module Data.Number.RealCyclotomic

-- | A real cyclotomic number.
data RealCyclotomic

-- | The square root of a <a>Rational</a> number.
sqrtRat :: Rational -> RealCyclotomic

-- | Sine function with argument in degrees.
sinDeg :: Rational -> RealCyclotomic

-- | Cosine function with argument in degrees.
cosDeg :: Rational -> RealCyclotomic

-- | Sine function with argument in revolutions.
sinRev :: Rational -> RealCyclotomic

-- | Cosine function with argument in revolutions.
cosRev :: Rational -> RealCyclotomic

-- | Is the cyclotomic a rational?
isRat :: RealCyclotomic -> Bool

-- | Return an exact rational number if possible.
toRat :: RealCyclotomic -> Maybe Rational

-- | Export as an inexact real number.
toReal :: RealFloat a => RealCyclotomic -> a

-- | The golden ratio, <tt>(1 + √5)/2</tt>.
goldenRatio :: RealCyclotomic

-- | Heron's formula for the area of a triangle with side lengths a, b, c.
heron :: Rational -> Rational -> Rational -> RealCyclotomic
instance GHC.Classes.Eq Data.Number.RealCyclotomic.RealCyclotomic
instance GHC.Num.Num Data.Number.RealCyclotomic.RealCyclotomic
instance GHC.Real.Fractional Data.Number.RealCyclotomic.RealCyclotomic
instance GHC.Show.Show Data.Number.RealCyclotomic.RealCyclotomic
