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


-- | Compute Maximum Entropy Distributions
--   
--   Use this package to compute maximum entropy distributions given a list
--   of values and list of constraints.
--   
--   Here is a the example from Probability the Logic of Science
--   
--   <pre>
--   maxent ([1,2,3], [average 1.5])
--   </pre>
--   
--   Right [0.61, 0.26, 0.11]
--   
--   The classic dice example
--   
--   <pre>
--   maxent ([1,2,3,4,5,6], [average 4.5])
--   </pre>
--   
--   Right [.05, .07, 0.11, 0.16, 0.23, 0.34]
@package maxent
@version 0.2.0.0


-- | The maximum entropy method, or MAXENT, is variational approach for
--   computing probability distributions given a list of moment, or
--   expected value, constraints.
--   
--   Here are a link for background info. On the idea of maximum entropy in
--   general:
--   <a>http://en.wikipedia.org/wiki/Principle_of_maximum_entropy</a>
--   
--   Use this package to compute discrete maximum entropy distributions
--   over a list of values and list of constraints.
--   
--   Here is a the example from Probability the Logic of Science
--   
--   <pre>
--   maxent ([1,2,3], [average 1.5])
--   </pre>
--   
--   Right [0.61, 0.26, 0.11]
--   
--   The classic dice example
--   
--   <pre>
--   maxent ([1,2,3,4,5,6], [average 4.5])
--   </pre>
--   
--   Right [.05, .07, 0.11, 0.16, 0.23, 0.34]
--   
--   One can use different constraints besides the average value there.
--   
--   As for why you want to maximize the entropy to find the probability
--   constraint, I will say this for now. In the case of the average
--   constraint it is a kin to choosing a integer partition with the most
--   interger compositions. I doubt that makes any sense, but I will try to
--   explain more with a blog post soon.
module MaxEnt

-- | Constraint type. A function and the constant it equals.
--   
--   Think of it as the pair <tt>(f, c)</tt> in the constraint
--   
--   <pre>
--   Σ pₐ f(a, xₐ) = c
--   </pre>
--   
--   such that we are summing over all values and <tt>a</tt> is the index.
--   
--   For example, for a variance constraint the <tt>f</tt> would be <tt>(\_
--   x -&gt; x*x)</tt> and <tt>c</tt> would be the variance.
type Constraint a = (ExpectationFunction a, a)

-- | A function that takes an index and value and returns a value. See
--   <a>average</a> and <a>variance</a> for examples.
type ExpectationFunction a = Int -> a -> a
constraint :: Floating a => ExpectationFunction a -> a -> Constraint a
average :: Floating a => a -> Constraint a
variance :: Floating a => a -> Constraint a

-- | The main entry point for computing discrete maximum entropy
--   distributions.
maxent :: (forall a. Floating a => ([a], [Constraint a])) -> Either (Result, Statistics) [Double]