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


-- | relatively useful fractal functions
--   
--   A library for analysis and exploration of fractals. This initial
--   version provides angled internal addresses, external ray tracing, and
--   iterations for images of the Mandelbrot Set.
@package ruff
@version 0.1


-- | Strict tuples.
module Fractal.RUFF.Types.Tuple

-- | Strict <a>Tuple2</a> type.
data Tuple2 l r
Tuple2 :: !l -> !r -> Tuple2 l r
instance Typeable2 Tuple2
instance (Read l, Read r) => Read (Tuple2 l r)
instance (Show l, Show r) => Show (Tuple2 l r)
instance (Eq l, Eq r) => Eq (Tuple2 l r)
instance (Ord l, Ord r) => Ord (Tuple2 l r)
instance (Data l, Data r) => Data (Tuple2 l r)


-- | Complex numbers without the <a>RealFloat</a> constraint.
module Fractal.RUFF.Types.Complex

-- | Complex number type without the <a>RealFloat</a> constraint.
data Complex r
(:+) :: !r -> !r -> Complex r

-- | Complex number with magnitude 1 and the given phase.
cis :: Floating r => r -> Complex r

-- | Complex number with the given magnitude and phase.
mkPolar :: Floating r => r -> r -> Complex r

-- | Extract the real part.
realPart :: Complex r -> r

-- | Extract the imaginary part.
imagPart :: Complex r -> r

-- | Complex conjugate.
conjugate :: Num r => Complex r -> Complex r

-- | Complex magnitude.
magnitude :: Floating r => Complex r -> r

-- | Complex phase.
phase :: (Ord r, Floating r) => Complex r -> r

-- | Convert to polar form.
polar :: (Ord r, Floating r) => Complex r -> (r, r)
instance Typeable1 Complex
instance Read r => Read (Complex r)
instance Show r => Show (Complex r)
instance Eq r => Eq (Complex r)
instance Ord r => Ord (Complex r)
instance Data r => Data (Complex r)
instance Fractional r => Fractional (Complex r)
instance Num r => Num (Complex r)


-- | Generic functions to iterate points.
module Fractal.RUFF.Mandelbrot.Iterate

-- | Iteration mode.
data Mode
Simple :: Mode
EscapeTime :: Mode
DistanceEstimate :: Mode

-- | Iteration state.
data Iterate u r
IterSimple :: !Complex r -> !Complex r -> !u -> Iterate u r
itc :: Iterate u r -> !Complex r
itz :: Iterate u r -> !Complex r
iterUser :: Iterate u r -> !u
IterEscapeTime :: !Complex r -> !Complex r -> !Int -> !u -> Iterate u r
itc :: Iterate u r -> !Complex r
itz :: Iterate u r -> !Complex r
itn :: Iterate u r -> !Int
iterUser :: Iterate u r -> !u
IterDistanceEstimate :: !Complex r -> !Complex r -> !Complex r -> !Int -> !u -> Iterate u r
itc :: Iterate u r -> !Complex r
itz :: Iterate u r -> !Complex r
itdz :: Iterate u r -> !Complex r
itn :: Iterate u r -> !Int
iterUser :: Iterate u r -> !u

-- | Iteration output.
data Output u r
OutSimple :: !u -> Output u r
outUser :: Output u r -> !u
OutEscapeTime :: !r -> !r -> !u -> Output u r
escapeTime :: Output u r -> !r
finalAngle :: Output u r -> !r
outUser :: Output u r -> !u
OutDistanceEstimate :: !r -> !r -> !r -> !u -> Output u r
escapeTime :: Output u r -> !r
finalAngle :: Output u r -> !r
distanceEstimate :: Output u r -> !r
outUser :: Output u r -> !u

-- | Iteration initial state.
initial :: Num r => Mode -> u -> Complex r -> Iterate u r

-- | Iteration engine.
iterate :: (Ord r, Floating r) => Int -> Iterate u r -> Either (Iterate u r) (Output u r)

-- | Iterate over a list.
iterates :: (Functor m, Monad m, Ord r, Floating r) => Int -> [Iterate u r] -> (Output u r -> m ()) -> m [Iterate u r]
instance Typeable Mode
instance Typeable2 Iterate
instance Typeable2 Output
instance Read Mode
instance Show Mode
instance Eq Mode
instance Ord Mode
instance Enum Mode
instance Bounded Mode
instance Data Mode
instance (Read u, Read r) => Read (Iterate u r)
instance (Show u, Show r) => Show (Iterate u r)
instance (Eq u, Eq r) => Eq (Iterate u r)
instance (Ord u, Ord r) => Ord (Iterate u r)
instance (Data u, Data r) => Data (Iterate u r)
instance (Read u, Read r) => Read (Output u r)
instance (Show u, Show r) => Show (Output u r)
instance (Eq u, Eq r) => Eq (Output u r)
instance (Ord u, Ord r) => Ord (Output u r)
instance (Data u, Data r) => Data (Output u r)


-- | Generic functions to render images.
module Fractal.RUFF.Mandelbrot.Image

-- | Render an image with the <a>Simple</a> algorithm. The iteration count
--   is doubled until the image is good enough, or the fixed maximum
--   iteration count is reached.
--   
--   <pre>
--   putStr . unicode $ simpleImage 100 100 ((-1.861):+0) (0.001) 1000000000
--   </pre>
simpleImage :: (Ord r, Floating r) => Int -> Int -> Complex r -> r -> Int -> UArray (Int, Int) Bool

-- | Render an image with the <a>DistanceEstimate</a> algorithm. The
--   iteration count is doubled until the image is good enough, or the
--   fixed maximum iteration count is reached. The output values are
--   converted to <a>Float</a>.
complexImage :: (Ord r, Real r, Floating r) => Int -> Int -> Complex r -> r -> Int -> UArray (Int, Int, Int) Float

-- | Image rendering loop.
imageLoop :: (Ord r, Floating r) => STRef s Int -> a -> Int -> Int -> Bool -> Int -> [Iterate u r] -> (Output u r -> ST s ()) -> ST s a

-- | The parameter plane coordinates for an image, with bounds.
coordinates :: (Ord r, Floating r) => Int -> Int -> Complex r -> r -> (((Int, Int), (Int, Int)), [(Tuple2 Int Int, Complex r)])

-- | Convert a bit array to ascii graphics.
ascii :: UArray (Int, Int) Bool -> String

-- | Convert a bit array to unicode block graphics.
unicode :: UArray (Int, Int) Bool -> String


-- | External angles give rise to kneading sequences under the angle
--   doubling map. Internal addresses encode kneading sequences in
--   human-readable form, when extended to angled internal addresses they
--   distinguish hyperbolic components in a concise and meaningful way.
--   
--   The algorithms are mostly based on Dierk Schleicher's paper
--   <i>Internal Addresses Of The Mandelbrot Set And Galois Groups Of
--   Polynomials (version of February 5, 2008)</i>
--   <a>http://arxiv.org/abs/math/9411238v2</a>.
module Fractal.RUFF.Mandelbrot.Address

-- | Angle as a fraction of a turn, usually in [0, 1).
type Angle = Rational

-- | Angle doubling map.
double :: Angle -> Angle

-- | Wrap an angle into [0, 1).
wrap :: Angle -> Angle

-- | Elements of kneading sequences.
data Knead
Zero :: Knead
One :: Knead
Star :: Knead

-- | Kneading sequences. Note that the <a>Aperiodic</a> case has an
--   infinite list, which the <a>Pretty</a> instance truncates arbitrarily.
data Kneading
Aperiodic :: [Knead] -> Kneading
PrePeriodic :: [Knead] -> [Knead] -> Kneading
StarPeriodic :: [Knead] -> Kneading
Periodic :: [Knead] -> Kneading

-- | The kneading sequence for an external angle.
kneading :: Angle -> Kneading

-- | The period of a kneading sequence, or <a>Nothing</a> when it isn't
--   periodic.
period :: Kneading -> Maybe Integer

-- | Unwrap a kneading sequence to an infinite list.
unwrap :: Kneading -> [Knead]

-- | Internal addresses are a non-empty sequence of strictly increasing
--   integers beginning with '1'.
data InternalAddress
InternalAddress :: [Integer] -> InternalAddress

-- | Construct an <a>InternalAddress</a> from a kneading sequence.
internalAddress :: Kneading -> Maybe InternalAddress

-- | A star-periodic kneading sequence's upper and lower associated
--   kneading sequences.
associated :: Kneading -> Maybe (Kneading, Kneading)

-- | The upper associated kneading sequence.
upper :: Kneading -> Maybe Kneading

-- | The lower associated kneading sequence.
lower :: Kneading -> Maybe Kneading

-- | Construct a valid <a>InternalAddress</a>, checking the precondition.
internalFromList :: [Integer] -> Maybe InternalAddress

-- | Extract the sequence of integers.
internalToList :: InternalAddress -> [Integer]

-- | Angled internal addresses have angles between each integer in an
--   internal address.
data AngledInternalAddress
Unangled :: Integer -> AngledInternalAddress
Angled :: Integer -> Angle -> AngledInternalAddress -> AngledInternalAddress

-- | The angled internal address corresponding to an external angle.
angledInternalAddress :: Angle -> Maybe AngledInternalAddress

-- | Builds a valid <a>AngledInternalAddress</a> from a list, checking the
--   precondition that only the last 'Maybe Angle' should be
--   <a>Nothing</a>, and the <a>Integer</a> must be strictly increasing.
angledFromList :: [(Integer, Maybe Angle)] -> Maybe AngledInternalAddress

-- | Convert an <a>AngledInternalAddress</a> to a list.
angledToList :: AngledInternalAddress -> [(Integer, Maybe Angle)]

-- | The pair of external angles whose rays land at the root of the
--   hyperbolic component described by the angled internal address.
externalAngles :: AngledInternalAddress -> Maybe (Rational, Rational)

-- | Discard angle information from an internal address.
stripAngles :: AngledInternalAddress -> InternalAddress

-- | Parse an angled internal address, accepting some unambiguous
--   abbreviations.
parse :: String -> Maybe AngledInternalAddress
instance Typeable Knead
instance Typeable Kneading
instance Typeable InternalAddress
instance Typeable AngledInternalAddress
instance Read Knead
instance Show Knead
instance Eq Knead
instance Ord Knead
instance Enum Knead
instance Bounded Knead
instance Data Knead
instance Read Kneading
instance Show Kneading
instance Eq Kneading
instance Ord Kneading
instance Data Kneading
instance Read InternalAddress
instance Show InternalAddress
instance Eq InternalAddress
instance Ord InternalAddress
instance Data InternalAddress
instance Read AngledInternalAddress
instance Show AngledInternalAddress
instance Eq AngledInternalAddress
instance Ord AngledInternalAddress
instance Data AngledInternalAddress
instance Pretty AngledInternalAddress
instance Pretty InternalAddress
instance Pretty Kneading
instance Pretty Knead


-- | External angles define external rays which can be traced back from the
--   circle at infinity to the boundary of the Mandelbrot Set.
--   
--   The algorithm is based on Tomoki Kawahira's paper <i>An algorithm to
--   draw external rays of the Mandelbrot set</i>
--   <a>http://www.math.nagoya-u.ac.jp/~kawahira/programs/mandel-exray.pdf</a>.
module Fractal.RUFF.Mandelbrot.Ray

-- | Compute the external ray for an external angle with a given accuracy,
--   sharpness and starting radius. For example:
--   
--   <pre>
--   externalRay 1e-10 8 (2**24) (1/3)
--   </pre>
externalRay :: (Ord r, Floating r) => r -> Int -> r -> Angle -> [Complex r]