NAME

PDL::RandVar -- Random number sequences.

VERSION

This document refers to version 1.0 of RandVar

SYNOPSIS

  use PDL::RandVar;

  $m = new PDL::RandVar(<dims>,<options>)

DESCRIPTION

This package implements random variable streams with various options. It provides a uniform interface to (hopefully, eventually) a wide variety of random and pseudo-random number generators. The base class uses a uniformly distributed engine (currently just perl's own rand function), and subclasses generate different distributions.

Once you've declared a random variable, you can get out samples with the explicit ->sample method. Eventually, sampling will be made implicit, so that you can just include random variables in expressions when you want a sample per element of the expression, or use ->sample for more complex sampling.

RandVar is designed for easy subclassing. You need only implement ->sample and ->new to get a new class.

When you ``use PDL::RandVar'' you also get some standard subclasses. They're pretty cheap to load. When you use RandVar, the following classes are also automagically loaded (and have their own documentation):

RandVar::Sobol: Subrandom sequences that help some types of algorithm converge faster.
RandVar::Histogram: Arbitarily distributed random variables.
RandVar::Gaussian: Gaussian distributions.

History

  0.01     4-Dec-2001 -- Basic functionality (CED)
  1.0      9-Jan-2002 -- seems to work OK (CED)

Author, license, no warranty

This file copyright(C) 2001, 2002 Craig DeForest (cdeforest@solar.stanford.edu) This software/documentation may be distributed under the same terms as PDL itself (license available at http://pdl.perl.org). This package comes with NO WARRANTY.

Bugs:

At the moment, repeatability by seeding is not implemented. More work needs to be done to get reproducible sequences.

To Do:

Implement repeatable sequences

(see Bugs)

Make RVs act more like pdls

ideally you ought to be able to declare a variable as a RandVar, and then use it in expressions to get samples automagically on-demand, without explicitly calling ->sample, ie ($a * $randvar) ought to do the Right Thing. The random variable ought to draw as many samples as needed for context (e.g. zeroes(100,200)+$randvar out to get 20,000 samples); if you want fewer, you can fall back on ->sample to specify how many (e.g. zeroes(100,200)+$randvar->sample(100) gets 100 samples and automagically threads over the 200 dimension).

This gets implemented at the top level -- subclasses need only implement sample() and RandVar should handle the rest.

Tie in the Gnu library

The gnu random variable functions are extensive and just need tiny wrappers to turn into subclasses.

FUNCTIONS

new

Construct a uniformly distributed random variable.

  Signature: (size())

  $a = new RandVar(<size>,<opt>);

Options:


=item range

2xn piddle containing min and max values for each dimension of the R.V.

seed: A number to use as the seed. If omitted, then the system clock is used. (Not implemented at this level but placed here as a hook)

  $xyrand = new RandVar(2,{range=>pdl([$xmin,$xmax],[$ymin,$ymax])});
  $newxy = sample $xyrand;

Return one or more samples of the random variable

This is a pretty stoopid implementation -- it just calls the perl rand() function a bunch of times and is here primarily to get the ball rolling on the object.

 Signature: sample(n(),[o]out(d,n))


 You can pass in an output pdl to avoid having to reallocate each time.

  $out = <RandVar>->sample(<n>);

  $rv = new RandVar;
  $samps = $rv->sample(10);

You get back an <n>x<d> array, where <n> is the number of samples you ask for and <d> is the dimension of the random variable. This may seeem transposed but it allows you to drop the last dimension if your variable is a scalar.

PDL::RandVar -- Random number sequences.