1. bergsoe
  2. papl


papl / src / PaplSampler.mli

  Copyright (c) 2012 Anders Lau Olsen.
  See LICENSE file for terms and conditions.
(** Sampling of values

    A {b sampler} is a stream of values of some type. The streams are imperative
    data structures. Samplers are used throughout the implementation of sampling
    based planning algorithms.

    A sampler ['a t] is a type synonym for the enumeration type ['a BatEnum.t]
    of the Batteries Included library. The library module defines a number of
    useful functions for manipulating enumerations, such as maps and folds, and
    functions for constructing enumerations for different types of sequence data
    (see for example [BatList]).

type 'a pair_t = 'a * 'a
type rng_t = PaplRandom.rng_t

(** {2 Types} *)

type 'a t = 'a BatEnum.t
(** A sampler is an enumeration. *)

type range_t = float * float
(** Real value ranges.

    A pair [(a, b)] represents the values [x] for which [a <= x <= b].

type int_range_t = int * int
(** Integer ranges.

    The pair [(i, j)] represents the integer values [x] for which [i <= x < j].

(** {2 Combinators} *)

val map2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
(** Map a function onto the values of two samplers.

    The sampler [s = map2 f sa sb] returns values [f a b] where [a] and [b] are
    sampled from [sa] and [sb].

    If either [sa] or [sb] becomes empty, then [s] is empty too.

    If [f] doesn't like the values [a] and [b] it can prematurely signal the end
    of the stream by raising [BatEnum.No_more_elements].

val pair : 'a t -> 'a pair_t t
(** Pairs of values extracted from a single-element sampler.

    [pair s] is equivalent to [product2 s s].

val product2 : 'a t -> 'b t -> ('a * 'b) t
(** The cartesian product of 2 samplers.

    The sampler [s = product2 sa sb] returns tuples [(a, b)] where [a] is
    sampled from [sa] and [b] is sampled from [sb].

    If either [sa] or [sb] becomes empty, then [s] is empty too.

val product3 : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t
(** The cartesian product of 3 samplers.

    The sampler [s = product3 sa sb sb] returns tuples [(a, b, c)] where [a] is
    sampled from [sa], [b] is sampled from [sb], and [c] is sampled from [sc].

    If either [sa], [sb] or [sc] becomes empty, then [s] is empty too.

val intersperse : 'a t -> int -> 'a t -> 'a t
(** An interspersed sampler.

    The sampler [sxy = intersperse sx n sy] repeatedly retrieves one value [x1]
    from [sx] followed by [n] values [y1, ..., yn] retrieved from [sy]. If [x1]
    could not be retrieved from [sx], then [sxy] is empty too.

    - If [sx] is empty, then so is [sxy].

    - If [n == 0], then [sxy] and [sx] are equivalent.

    - If [sy] becomes empty, then sampling proceeds as if [n == 0].

val constrain : 'a t -> 'a PaplConstraint.t -> 'a t
(** Constraining the elements of a sampler.

    The sampler [constrain s c] is the stream of elements of [s] that are
    accepted by [c].

    [constrain s c] is equivalent to [BatEnum.filter (PaplConstraint.accept c) s].

val constrain_option : 'a t -> 'a PaplConstraint.t -> 'a option t
(** Constraining the elements of a sampler.

    The sampler [constrain s c] returns [Some x] for every [x] of [s] that is
    accepted by [c] and [None] for those that are not.

val constrain_with_default : 'a t -> 'a PaplConstraint.t -> 'a t -> 'a t
(** Replace elements that are constrained with elements from another sampler.

    The sampler [s' = constrain_with_default s c sd] replaces each element of
    [s] that does not satisfy [c] with an element from [sd].

    - If [s] becomes empty then [s'] is empty.

    - If [sd] becomes empty then [s'] becomes equivalent to [constrain s c].

    - [s'] does not check if the default elements [sd] satisfy [c].

val round_robin : 'a t t -> 'a t
(** Round-robin sampling of samplers.

    The sampler [s' = round_robin samplers] cyclically retrieves samplers [s]
    from [samplers] and returns an element from that sampler. If [s] is empty,
    the sampler is skipped, and the next samplers are tried instead. [s'] is
    empty when all of the samplers of [samplers] are empty.

(** {2 Random sampling} *)

val distribute_by_weight :
  ?rng:rng_t ->
  (float * 'a) list ->
  'a t
(** Sampling of elements distributed by weight.

    The sampler [s = distribute_by_weight pairs] returns values [x] from an
    enumeration of pairs [(w, x)]. A value [x] is sampled with a probability
    proportional to its weight relative to the total weight of all pairs.
    Weights must be non-negative.

val uniform : ?rng:rng_t -> range_t -> float t
(** Random uniform sampling of a range.

    The sampler [random_uniform range] uniformly samples the range [range].

    If the range is empty then the sampler is empty.

val get_uniform : ?rng:rng_t -> range_t -> float
(** A single value sampled uniformly at random from a range.

    If the range is empty then an exception is raised.

val uniform_int : ?rng:rng_t -> int_range_t -> int t
(** Random sampling of ranges.

    The sampler [s = uniform_int range] returns integers sampled uniformly at
    random from [range].

    If the range is empty then [s] is empty.

val gaussian : ?rng:rng_t -> unit -> float t
(** Normal distributed numbers with mean 0 and variance 1.

(** {2 Utilities} *)

val mean_and_variance : float t -> float * float
   [(mean, variance) = mean_and_variance stream] is the sample mean and sample
   variance of the elements of [stream].

   If [stream] has fewer than [2] elements, an exception is raised.