-- | The Roots.Simple module contains root-finding algorithms. That
--   is, procedures to (numerically) find solutions to the equation,
--
--   > f(x) = 0
--
--   where f is assumed to be continuous on the interval of interest.
--

module Roots.Simple
where

import qualified Roots.Fast as F


-- | Does the (continuous) function @f@ have a root on the interval
--   [a,b]? If f(a) <] 0 and f(b) ]> 0, we know that there's a root in
--   [a,b] by the intermediate value theorem. Likewise when f(a) >= 0
--   and f(b) <= 0.
--
--   Examples:
--
--   >>> let f x = x**3
--   >>> has_root f (-1) 1 Nothing
--   True
--
--   This fails if we don't specify an @epsilon@, because cos(-2) ==
--   cos(2) doesn't imply that there's a root on [-2,2].
--
--   >>> has_root cos (-2) 2 Nothing
--   False
--   >>> has_root cos (-2) 2 (Just 0.001)
--   True
--
has_root :: (Fractional a, Ord a, Ord b, Num b)
         => (a -> b) -- ^ The function @f@
         -> a       -- ^ The \"left\" endpoint, @a@
         -> a       -- ^ The \"right\" endpoint, @b@
         -> Maybe a -- ^ The size of the smallest subinterval
                   --   we'll examine, @epsilon@
         -> Bool
has_root f a b epsilon =
  F.has_root f a b epsilon Nothing Nothing




-- | We are given a function @f@ and an interval [a,b]. The bisection
--   method checks finds a root by splitting [a,b] in half repeatedly.
--
--   If one is found within some prescribed tolerance @epsilon@, it is
--   returned. Otherwise, the interval [a,b] is split into two
--   subintervals [a,c] and [c,b] of equal length which are then both
--   checked via the same process.
--
--   Returns 'Just' the value x for which f(x) == 0 if one is found,
--   or Nothing if one of the preconditions is violated.
--
--   Examples:
--
--   >>> bisect cos 1 2 0.001
--   Just 1.5712890625
--
--   >>> bisect sin (-1) 1 0.001
--   Just 0.0
--
bisect :: (Fractional a, Ord a, Num b, Ord b)
       => (a -> b) -- ^ The function @f@ whose root we seek
       -> a       -- ^ The \"left\" endpoint of the interval, @a@
       -> a       -- ^ The \"right\" endpoint of the interval, @b@
       -> a       -- ^ The tolerance, @epsilon@
       -> Maybe a
bisect f a b epsilon =
  F.bisect f a b epsilon Nothing Nothing