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


-- | Continued fractions.
--   
--   A type and some functions for manipulating and evaluating continued
--   fractions.
@package continued-fractions
@version 0.9.1.1

module Math.ContinuedFraction

-- | A continued fraction. Constructed by <a>cf</a> or <a>gcf</a>.
data CF a

-- | Construct a continued fraction from its first term and the partial
--   denominators in its canonical form, which is the form where all the
--   partial numerators are 1.
--   
--   <tt>cf a [b,c,d]</tt> corresponds to <tt>a + (b / (1 + (c / (1 +
--   d))))</tt>, or to <tt>GCF a [(1,b),(1,c),(1,d)]</tt>.
cf :: a -> [a] -> CF a

-- | Construct a continued fraction from its first term, its partial
--   numerators and its partial denominators.
--   
--   <tt>gcf b0 [(a1,b1), (a2,b2), (a3,b3)]</tt> corresponds to <tt>b0 +
--   (a1 / (b1 + (a2 / (b2 + (a3 / b3)))))</tt>
gcf :: a -> [(a, a)] -> CF a

-- | Extract the partial denominators of a <a>CF</a>, normalizing it if
--   necessary so that all the partial numerators are 1.
asCF :: Fractional a => CF a -> (a, [a])

-- | Extract all the partial numerators and partial denominators of a
--   <a>CF</a>.
asGCF :: (Num a, Eq a) => CF a -> (a, [(a, a)])

-- | Truncate a <a>CF</a> to the specified number of partial numerators and
--   denominators.
truncateCF :: Int -> CF a -> CF a

-- | Apply an equivalence transformation, multiplying each partial
--   denominator with the corresponding element of the supplied list and
--   transforming subsequent partial numerators and denominators as
--   necessary. If the list is too short, the rest of the <a>CF</a> will be
--   unscaled.
equiv :: (Num a, Eq a) => [a] -> CF a -> CF a

-- | Apply an equivalence transformation that sets the partial numerators
--   of a <a>CF</a> to the specfied values. If the input list is too short,
--   the rest of the <a>CF</a> will be unscaled.
setNumerators :: (Fractional a, Eq a) => [a] -> CF a -> CF a

-- | Apply an equivalence transformation that sets the partial denominators
--   of a <a>CF</a> to the specfied values. If the input list is too short,
--   the rest of the <a>CF</a> will be unscaled.
setDenominators :: (Fractional a, Eq a) => [a] -> CF a -> CF a

-- | Computes the even and odd parts, respectively, of a <a>CF</a>. These
--   are new <a>CF</a>s that have the even-indexed and odd-indexed
--   convergents of the original, respectively.
partitionCF :: (Fractional a, Eq a) => CF a -> (CF a, CF a)

-- | Computes the even part of a <a>CF</a> (that is, a new <a>CF</a> whose
--   convergents are the even-indexed convergents of the original).
evenCF :: (Fractional a, Eq a) => CF a -> CF a

-- | Computes the odd part of a <a>CF</a> (that is, a new <a>CF</a> whose
--   convergents are the odd-indexed convergents of the original).
oddCF :: (Fractional a, Eq a) => CF a -> CF a

-- | Evaluate the convergents of a continued fraction using the fundamental
--   recurrence formula:
--   
--   A0 = b0, B0 = 1
--   
--   A1 = b1b0 + a1, B1 = b1
--   
--   A{n+1} = b{n+1}An + a{n+1}A{n-1}
--   
--   B{n+1} = b{n+1}Bn + a{n+1}B{n-1}
--   
--   The convergents are then Xn = An/Bn
convergents :: (Fractional a, Eq a) => CF a -> [a]

-- | Evaluate the convergents of a continued fraction using Steed's method.
--   Only valid if the denominator in the following recurrence for D_i
--   never goes to zero. If this method blows up, try <a>modifiedLentz</a>.
--   
--   D1 = 1/b1
--   
--   D{i} = 1 / (b{i} + a{i} * D{i-1})
--   
--   dx1 = a1 / b1
--   
--   dx{i} = (b{i} * D{i} - 1) * dx{i-1}
--   
--   x0 = b0
--   
--   x{i} = x{i-1} + dx{i}
--   
--   The convergents are given by <tt>scanl (+) b0 dxs</tt>
steed :: (Fractional a, Eq a) => CF a -> [a]

-- | Evaluate the convergents of a continued fraction using Lentz's method.
--   Only valid if the denominators in the following recurrence never go to
--   zero. If this method blows up, try <a>modifiedLentz</a>.
--   
--   C1 = b1 + a1 / b0
--   
--   D1 = 1/b1
--   
--   C{n} = b{n} + a{n} / C{n-1}
--   
--   D{n} = 1 / (b{n} + a{n} * D{n-1})
--   
--   The convergents are given by <tt>scanl (*) b0 (zipWith (*) cs ds)</tt>
lentz :: (Fractional a, Eq a) => CF a -> [a]

-- | Evaluate the convergents of a continued fraction using Lentz's method,
--   mapping the terms in the final product to a new group before
--   performing the final multiplications. A useful group, for example,
--   would be logarithms under addition. In <tt>lentzWith f op inv</tt>,
--   the arguments are:
--   
--   <ul>
--   <li><tt>f</tt>, a group homomorphism (eg, <a>log</a>) from
--   {<tt>a</tt>,(*),<a>recip</a>} to the group in which you want to
--   perform the multiplications.</li>
--   <li><tt>op</tt>, the group operation (eg., (+)).</li>
--   <li><tt>inv</tt>, the group inverse (eg., <a>negate</a>).</li>
--   </ul>
--   
--   The <a>lentz</a> function, for example, is given by the identity
--   homomorphism: <tt>lentz</tt> = <tt>lentzWith id (*) recip</tt>.
--   
--   The original motivation for this function is to allow computation of
--   the natural log of very large numbers that would overflow with the
--   naive implementation in <a>lentz</a>. In this case, the arguments
--   would be <a>log</a>, (+), and <a>negate</a>, respectively.
--   
--   In cases where terms of the product can be negative (i.e., the
--   sequence of convergents contains negative values), the following
--   definitions could be used instead:
--   
--   <pre>
--   signLog x = (signum x, log (abs x))
--   addSignLog (xS,xL) (yS,yL) = (xS*yS, xL+yL)
--   negateSignLog (s,l) = (s, negate l)
--   </pre>
lentzWith :: (Fractional a, Eq a) => (a -> b) -> (b -> b -> b) -> (b -> b) -> CF a -> [b]

-- | Evaluate the convergents of a continued fraction using Lentz's method,
--   (see <a>lentz</a>) with the additional rule that if a denominator ever
--   goes to zero, it will be replaced by a (very small) number of your
--   choosing, typically 1e-30 or so (this modification was proposed by
--   Thompson and Barnett).
--   
--   Additionally splits the resulting list of convergents into sublists,
--   starting a new list every time the 'modification' is invoked.
modifiedLentz :: (Fractional a, Eq a) => a -> CF a -> [[a]]

-- | <a>modifiedLentz</a> with a group homomorphism (see <a>lentzWith</a>,
--   it bears the same relationship to <a>lentz</a> as this function does
--   to <a>modifiedLentz</a>, and solves the same problems). Alternatively,
--   <a>lentzWith</a> with the same modification to the recurrence as
--   <a>modifiedLentz</a>.
modifiedLentzWith :: (Fractional a, Eq a) => (a -> b) -> (b -> b -> b) -> (b -> b) -> a -> CF a -> [[b]]

-- | Euler's formula for computing <tt>sum (scanl1 (*) xs)</tt>. Successive
--   convergents of the resulting <a>CF</a> are successive partial sums in
--   the series.
sumPartialProducts :: Num a => [a] -> CF a
instance GHC.Show.Show a => GHC.Show.Show (Math.ContinuedFraction.CF a)
instance GHC.Base.Functor Math.ContinuedFraction.CF
