Copyright  (c) George Ungureanu 2020 

License  BSDstyle (see the file LICENSE) 
Maintainer  ugeorge@kth.se 
Stability  experimental 
Portability  portable 
Safe Haskell  Safe 
Language  Haskell2010 
Extensions 

This module defines the Probability layer, and is concerned in modeling aspects of uncertainty in values. For a brief presentation of the theoretical background of this layer, the atom approach, but also an incentive to use this layer in CPS design, please consult [Ungureanu20a].
The idea of this layer is wrapping certain values in a Dist
type which represents
a probabilistic distribution of values, and lift any function operatin on values in
the Probability layer. As a practical implementation, the Dist
type contains a
recipe to obtain a distributed value \(\in\alpha\) from a random experiment
\(\in\mathbf{1}\), i.e. a function \(\mathbf{1}\rightarrow\alpha\), using numerical
methods. As such any layered system involves lazy propagation (i.e. functional
compositions) of recipes which get evaluated once we need to plot/trace the "final"
behavior. In this respect it is very similar to the ForSyDe.Atom.MoC.CT DSL.
Currently the Probability layer exports the following types of distributions, each defined in its own submodule:
 ForSyDe.Atom.Prob.Uniform defines the uniform (i.e. random, square) distribution.
 ForSyDe.Atom.Prob.Normal defines the normal (i.e. Gaussian) distribution.
Useful links:
 ForSyDe.Atom contains general guidelines for using the API
 the naming convention rules on how to interpret the function names based on their number of inputs and outputs.
Synopsis
 data Dist a where
 (%.) :: (a > b) > Dist a > Dist b
 (%*) :: Dist (a > b) > Dist a > Dist b
 samples :: StdGen > Dist a > [a]
 sample :: StdGen > Dist c > c
 samplesn :: StdGen > Int > Dist a > [a]
 trans22 :: (a1 > a2 > (a3, b)) > Dist a1 > Dist a2 > (Dist a3, Dist b)
 newtype Histogram = Hist {}
 histogram :: (Ord a, Num a, Real a) => a > a > Rational > [a] > Histogram
Distribution type
Unlike all the other layers, all the subdomains of the Probability layer share
the same enabling type Dist
, the only thing differing being the numerical recipe
to obtain a distributed value.
To make full advantage of Haskell's lazyness and its native libraries for random
number generation (e.g. System.Random) we represent recipes in the most generic
form as functions \(\mathbf{1}\rightarrow[\alpha]\) from a seed (here StdGen
) to
an infinite list containing all possible values in a random sequence. Any
practical simulation/tracing thus needs to limit this list to a finite number of
experiments.
Atoms
Since the layer's type is unique, atoms are presented as regular functions, not as type class methods.
(%.) :: (a > b) > Dist a > Dist b Source #
The map
atom. It lifts an abitrary function \(f\) from a layer below and
creates a random variable \(\mathbf{y}=f(\mathbf{x})\) by mapping every point from
the original random variable according to \(f\).
(%*) :: Dist (a > b) > Dist a > Dist b Source #
The applicative atom. Transforms one random variable distribution to another by mapping samples.
samples :: StdGen > Dist a > [a] Source #
Returns all possible values of a random variable as an infinite list of values.
Patterns
sample :: StdGen > Dist c > c Source #
Samples a random variable by running one experiment trial defined by a certain distribution.
samplesn :: StdGen > Int > Dist a > [a] Source #
Samples a random variable by running n experiment trials defined by a certain distribution. This is equivalent to running a Monte Calro experiment on n samples.
trans22 :: (a1 > a2 > (a3, b)) > Dist a1 > Dist a2 > (Dist a3, Dist b) Source #
This pattern transforms a (set of) random distribution(s) into another (set) by composing their recipes with an arbitrary function. In other words it lifts an arbitrary function to the Probability layer.
Constructors: trans[18][14]
Utilities
Histogram representation as a zipped list of bins, each bin paired with its center value.
:: (Ord a, Num a, Real a)  
=> a  value of leftmost bin (minimum covered) 
> a  value of rightmost bin (maximum covered) 
> Rational  step 
> [a]  set of experiments 
> Histogram  histogram 
Returns the histogram of (a list of) experiments.
>>>
let xs = [1..10] ++ [4..7]
>>>
histogram 1 10 2 xs
{(1.0,1) (3.0,2) (5.0,4) (7.0,4) (9.0,2)}