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


-- | relatively useful fractal functions
--   
--   A library for analysis and exploration of fractals, providing angled
--   internal addresses, external ray tracing, nucleus and bond point
--   finding, and iterations for images of the Mandelbrot Set.
@package ruff
@version 0.3.2


-- | 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 squared.
magnitude2 :: Num r => Complex r -> 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 Data r => Data (Complex r)
instance NearZero r => NearZero (Complex r)
instance (Ord r, Floating r) => Floating (Complex r)
instance Fractional r => Fractional (Complex r)
instance Num r => Num (Complex r)


-- | Generic (slow) 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 (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 (slow) 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 (coordinates 100 100 ((-1.861):+0) (0.001)) 1000000000
--   </pre>
simpleImage :: (Ord r, Floating r) => Coordinates 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>.
--   
--   <pre>
--   putStr . unicode . border $ complexImage (coordinates 100 100 ((-1.861):+0) (0.001)) 1000000000
--   </pre>
complexImage :: (Ord r, Real r, Floating r) => Coordinates r -> Int -> UArray (Int, Int, Channel) 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 -> Coordinates 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

-- | Channels in an image.
data Channel

-- | continuous dwell
EscapeTime :: Channel

-- | normalized to pixel spacing
DistanceEstimate' :: Channel

-- | in [-pi,pi]
FinalAngle :: Channel

-- | Image bounds and coordinates.
type Coordinates r = (((Int, Int), (Int, Int)), [(Tuple2 Int Int, Complex r)])

-- | Convert a distance estimate image to a near-boundary bit array. The
--   input image must have a DistanceEstimate' channel.
border :: UArray (Int, Int, Channel) Float -> UArray (Int, Int) Bool
instance Typeable Channel
instance Eq Channel
instance Ord Channel
instance Enum Channel
instance Bounded Channel
instance Ix Channel
instance Read Channel
instance Show Channel
instance Data Channel


-- | Mu-atom period, nucleus and bond point finding.
module Fractal.RUFF.Mandelbrot.Nucleus

-- | Find the period of the lowest period nucleus inside a square.
--   
--   The algorithm is based on Robert Munafo's page, <i>Finding the Period
--   of a mu-Atom</i> <a>http://mrob.com/pub/muency/period.html</a>.
findPeriod :: (Floating r, Ord r) => Integer -> r -> Complex r -> Maybe Integer

-- | Given the period and approximate location, successively refine this
--   estimate to a nucleus.
--   
--   The algorithm is based on Robert Munafo's page <i>Newton-Raphson
--   method</i> <a>http://mrob.com/pub/muency/newtonraphsonmethod.html</a>.
findNucleus :: (Floating r, Fractional r) => Integer -> Complex r -> [Complex r]

-- | Given the period and nucleus, find succesive refinements to the bond
--   point at a given internal angle.
--   
--   The algorithm is based on ideas from
--   <a>http://mrob.com/pub/muency/derivative.html</a>.
findBond :: (Floating r, Fractional r) => Integer -> Complex r -> r -> [Complex r]

-- | Given the period and nucleus, find an interior point at a given
--   internal angle and radius in (0,1].
findInternal :: (Floating r, Fractional r) => Integer -> Complex r -> r -> r -> [Complex r]


-- | 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

-- | Convert to human readable form.
prettyAngle :: Angle -> String

-- | Convert to human readable form.
prettyAngles :: [Angle] -> String

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

-- | Knead character representation.
kneadChar :: Knead -> Char

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

-- | Kneading sequence as a string. The <a>Aperiodic</a> case is truncated
--   arbitrarily.
prettyKneading :: Kneading -> String

-- | 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]

-- | 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

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

-- | Internal address as a string.
prettyInternalAddress :: InternalAddress -> String

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

-- | 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

-- | Angled internal address as a string.
prettyAngledInternalAddress :: AngledInternalAddress -> String

-- | 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

-- | Split an angled internal address at the last island.
splitAddress :: AngledInternalAddress -> (AngledInternalAddress, [Angle])

-- | The inverse of <a>splitAddress</a>.
joinAddress :: AngledInternalAddress -> [Angle] -> AngledInternalAddress

-- | The period of an angled internal address.
addressPeriod :: AngledInternalAddress -> Integer

-- | Parse an angle.
parseAngle :: String -> Maybe Angle

-- | Parse a list of angles.
parseAngles :: String -> Maybe [Angle]

-- | Parse a kneading element.
parseKnead :: String -> Maybe Knead

-- | Parse a non-aperiodic kneading sequence.
parseKneading :: String -> Maybe Kneading

-- | Parse an internal address.
parseInternalAddress :: String -> Maybe InternalAddress

-- | Parse an angled internal address, accepting some unambiguous
--   abbreviations.
parseAngledInternalAddress :: 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


-- | External angles define external rays which can be traced back from the
--   circle at infinity to parameters near the boundary of the Mandelbrot
--   Set. Conversely, parameters near the boundary of the Mandelbrot Set
--   can be traced outwards to compute external angles.
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>
--   
--   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>.
externalRay :: (Ord r, Floating r) => r -> Int -> r -> Angle -> [Complex r]

-- | Compute the external ray outwards from a given parameter value. If the
--   result <tt>rs</tt> satisfies:
--   
--   <pre>
--   c = last rs
--   magnitude c &gt; radius
--   </pre>
--   
--   then the external angle is given by <tt>t</tt>:
--   
--   <pre>
--   a = phase c / (2 * pi)
--   t = a - fromIntegral (floor a)
--   </pre>
externalRayOut :: (Ord r, Floating r, RealFrac r) => Int -> r -> r -> Int -> r -> Complex r -> [Complex r]


-- | Mu-atom coordinate and address algorithms.
module Fractal.RUFF.Mandelbrot.Atom

-- | Mu-atom properties.
data MuAtom r
MuAtom :: !(Complex r) -> !Double -> !Double -> !Integer -> MuAtom r
muNucleus :: MuAtom r -> !(Complex r)
muSize :: MuAtom r -> !Double
muOrient :: MuAtom r -> !Double
muPeriod :: MuAtom r -> !Integer

-- | Progress updates for <a>findAtom</a>.
data FindAtom r
AtomSplitTodo :: FindAtom r
AtomSplitDone :: AngledInternalAddress -> [Angle] -> FindAtom r
AtomAnglesTodo :: FindAtom r
AtomAnglesDone :: !Rational -> !Rational -> FindAtom r
AtomRayTodo :: FindAtom r
AtomRay :: !Integer -> FindAtom r
AtomRayDone :: !(Complex r) -> FindAtom r
AtomNucleusTodo :: FindAtom r
AtomNucleus :: !Integer -> FindAtom r
AtomNucleusDone :: !(Complex r) -> FindAtom r
AtomBondTodo :: FindAtom r
AtomBond :: !Integer -> FindAtom r
AtomBondDone :: !(Complex r) -> FindAtom r
AtomSuccess :: !(MuAtom r) -> FindAtom r
AtomFailed :: FindAtom r

-- | Try to find an atom, providing progress updates.
findAtom :: (Floating r, NearZero r, Real r) => AngledInternalAddress -> [FindAtom r]

-- | Find the first success in the progress list.
findAtom' :: [FindAtom r] -> Maybe (MuAtom r)

-- | Find an atom from its address.
findAtom_ :: (Floating r, NearZero r, Real r) => AngledInternalAddress -> Maybe (MuAtom r)

-- | Progress updates for <a>findAddress</a>.
data FindAddress r
AddressCuspTodo :: FindAddress r
AddressCuspDone :: !(Complex r) -> FindAddress r
AddressDwellTodo :: FindAddress r
AddressDwell :: !Integer -> FindAddress r
AddressDwellDone :: !Integer -> FindAddress r
AddressRayOutTodo :: FindAddress r
AddressRayOut :: !Double -> FindAddress r
AddressRayOutDone :: !(Complex r) -> FindAddress r
AddressExternalTodo :: FindAddress r
AddressExternalDone :: !Rational -> FindAddress r
AddressAddressTodo :: FindAddress r
AddressSuccess :: AngledInternalAddress -> FindAddress r
AddressFailed :: FindAddress r

-- | Try to find an address, providing progress updates.
findAddress :: (Floating r, NearZero r, Real r, RealFrac r) => MuAtom r -> [FindAddress r]

-- | Find the first success in the progress list.
findAddress' :: [FindAddress r] -> Maybe AngledInternalAddress

-- | Find an address for a mu-atom.
findAddress_ :: (Floating r, NearZero r, Real r, RealFrac r) => MuAtom r -> Maybe AngledInternalAddress

-- | Progress updates for <a>locate</a>.
data Locate r
LocateScanTodo :: Locate r
LocateScan :: Locate r
LocateScanDone :: !Integer -> Locate r
LocateNucleusTodo :: Locate r
LocateNucleus :: !Integer -> Locate r
LocateNucleusDone :: !(Complex r) -> Locate r
LocateBondTodo :: Locate r
LocateBond :: !Integer -> Locate r
LocateBondDone :: !(Complex r) -> Locate r
LocateSuccess :: !(MuAtom r) -> Locate r
LocateFailed :: Locate r

-- | Try to find an atom close to a coordinate, providing progress updates.
locate :: (Floating r, NearZero r, Real r) => Complex r -> Double -> [Locate r]

-- | Find the first success in the progress list.
locate' :: [Locate r] -> Maybe (MuAtom r)

-- | Find an atom close to a coordinate.
locate_ :: (Floating r, NearZero r, Real r) => Complex r -> Double -> Maybe (MuAtom r)
instance Read r => Read (MuAtom r)
instance Show r => Show (MuAtom r)
instance Eq r => Eq (MuAtom r)
instance Read r => Read (FindAtom r)
instance Show r => Show (FindAtom r)
instance Eq r => Eq (FindAtom r)
instance Read r => Read (FindAddress r)
instance Show r => Show (FindAddress r)
instance Eq r => Eq (FindAddress r)
instance Read r => Read (Locate r)
instance Show r => Show (Locate r)
instance Eq r => Eq (Locate r)