RandVar(3)						User Contributed Perl Documentation						RandVar(3)

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 ->sam-
       ple 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:

       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.

perl v5.8.0							    2002-05-16								RandVar(3)