#!/usr/bin/perl -w
#
# rand-exp-dist-vals -
#     generate a series of values of X, an exponentially
#     distributed continuous random variable 
#
# $Id: rand-exp-dist-vals,v 1.2 2001/08/29 14:36:45 thor Exp $
#
# Tom Moertel <tom-perl@moertel.com>
# 29 Aug 2001

use strict;
use File::Basename;


# parse command line

my $opt_cumulative;

if (@ARGV && $ARGV[0] =~ /--?c/) {
    $opt_cumulative = shift;
}

if (@ARGV != 2) {
    my $cmd = basename($0);
    print STDERR "Usage: $cmd [--cumulative] lambda count\n";
    exit 1;
}


# generate the output series

my ($lambda, $count) = @ARGV;
my $time = 0.0;

for (1 .. $count) {
    $time = 0.0 unless $opt_cumulative;
    $time -= log(1.0 - rand) / $lambda;
    print $time, "\n";
}



=head1 NAME

rand-exp-dist-vals - generate a series of values of X, an exponentially distributed continuous random variable 


=head1 SYNOPSIS

B<rand-exp-dist-vals> [B<--cumulative>] I<lambda> I<count>


=head1 DESCRIPTION

Generate a series of I<count> values of I<X>, an exponentially
distributed continuous random variable with parameter I<lambda>.  The
parameter I<lambda> is the average number of occurrences (per unit
time) of the event described by I<X>.  (One should note that the
parameter I<lambda> is also the reciprocal of the mean
inter-occurrence time.)

The output series is expressed in multiples of the unit time.  For
example, if the unit time is one hour, the output series is expressed
in hours.  Likewise, if the unit time is one day, the output series is
expressed in days.


=head1 OPTIONS

=over 4

=item B<--cumulative> (also B<-c>)

Generate cumulative values, i.e., every value is added to a running
total, and the running total is output at each step.

=back


=head1 ABOUT THE EXPONENTIAL DISTRIBUTION

The exponential probability distribution is useful for modeling
events that have the following characteristics:

=over 4

=item *

Each event is independent of any others.

=item *

The likelihood that an event will occur during a unit interval of time
is independent of the amount of time that has already passed (i.e.,
the distribution is memoryless).

=item *

The number of events that occur during a unit interval of time is
independent of the number that occurred in any previous interval.
(This follows from the previous two points.)

=back

The distribution is useful for modeling real-world phenomena such as
the time-to-next-failure of computer components or the time between
arrivals of HTTP requests on the world wide web.

Use the B<--cumulative> option to generate cumulative values,
which are more useful for modeling I<when> events occur rather than
the I<time between> events.  Hence, one could use B<--cumulative> to
model the time-I<of>-failure of computer components or the time I<of>
arrivals of HTTP requests (with respect to a starting time of I<T>=0).


=head1 RELATIONSHIP TO THE POISSON DISTRIBUTION

The exponential distribution with parameter I<lambda> is a continuous
probability distribution that describes the time between occurrences
of events with respect to a unit interval of time.  The Poisson
distribution with parameter I<lambda> is a related I<discrete>
probability distribution that describes the count of occurrences that
occur within a unit interval of time.  That is, the exponential
distribution describes the times of occurrences, and the Poisson
distribution describes the count of occurrences. In both distributions
the parameter I<lambda> is the average number of occurrences per unit
time.


=head1 EXAMPLE

It is known that during peak operating hours, a popular web site
receives 5.3 HTTP requests per second.  Generate a series of ten
arrival times that follow the same HTTP usage pattern.

B<  rand-exp-dist-vals> B<--cumulative> 5.3 10  

    0.00975019559953279
    0.0285626862236859
    0.33010601273769
    0.414458443129551
    0.753671189779822
    0.897259433629856
    0.900330739146326
    0.953400794896725
    0.959375493430572
    1.28777895028557

=head1 AUTHOR

Tom Moertel E<lt>tom-perl@moertel.comE<gt>

29 Aug 2001

$Id: rand-exp-dist-vals,v 1.2 2001/08/29 14:36:45 thor Exp $