/ 
Math-StochasticProcess-0.02
River stage zero No dependents
/ Math::StochasticProcess::Event::Tuple

NAME

Math::StochasticProcess::Event::Tuple - Boilerplate code deriving from Math::StochasticProcess::Event.

VERSION

Version 0.02

SYNOPSIS

A Math::StochasticProcess::RandomVariable represents a numerical random variable, a Tuple is a named set of such variables. See below for a worked example.

EXPORT

The only function that cab be exported is RESOLVED_VAR_NAME. This is a constant function returning the name of the special internal random variable, which tracks the state of the Events. You can also derive from this class and override it in a derived class, in which case it should not be exported.

FUNCTIONS

new

probability

The probability of having arrived at this event. Must return a number between 0 and 1 inclusive.

isResolved

A resolved event requires no further analysis and can ignore its internal variables.

iterate

As per Math::StochasticProcess::Event this is the key function. It must return a list of new Event objects, that are the possible iterands of the current event. The current Event object should not be modified. Obviously the probabilities must add up to the probability of the parent event. In this context it should use the copy method to generate new Events. So the code should look something like:

sub iterate {
    my $self = shift;
    my @results;
    if ($self->condition1()) {
        push @results, $self->copy(0.3, var1=>4);
        push @results, $self->copy(0.7, var1=>sub {return $_[0]+1;});
    }
    elsif ($self->condition2()) {
        push @results, $self->copy(0.6, var1=>5);
        push @results, $self->copy(0.2, var1=>sub {return $_[0]-1;});
        push @results, $self->copy(0.2, var1=>8);
    }
    else {
        push @results, $self->copy(0.6, RESOLVED_VAR_NAME()=>1);
        push @results, $self->copy(0.4, var2=>7);
    }
    return @results;
}

It also has a particular responsibility to set the RESOLVED_VAR_NAME() random variable as appropriate. You can either redefine the iterate function in a derived class (as above) or specify it as a callback in the constructor.

copy

This is effectively another constructor as it makes a modified copy of the object. The first argument is the conditional probability of transitioning from the parent event to the copy. The rest of the arguments are assumed to be a HASH mapping variables to their fate. If the value is a CODEREF then that is applied to the old value of the variable and the returned value becomes the new value of that random variable.

randomVariable

This is straightforward implementation of the inherited function, for which see Math::StochasticProcess::Event. It excludes internal random variables from the argumentless form, because they are internal. We allow them when asked for explicitly because it is useful.

RESOLVED_VAR_NAME

This function returns the name of the special RandomVariable used to track when an Event is resolved. You can either export it or use it an object-oriented way.

signature

A string that uniquely identifies the event. This is used to merge up equivalent events that have been arrived at by different routes. In this implementation, internal random variables do not figure in the signature if the Event is resolved.

merge

This method merges the second Event into the object. It is a requirement that the two Events have identical signatures. The probability of the combined Event should equal the sum of the two original Events.

debug

A string that provides full debug information.

EXAMPLE

This is the same example as in Math::StochasticProcess::Event but redone using the Tuple class.

#!/usr/bin/perl -w
use strict;
use warnings;

use Math::StochasticProcess;
use Math::StochasticProcess::Event;
use Math::StochasticProcess::Event::Tuple;
use Math::StochasticProcess::RandomVariable;
use FileHandle;

my $goal = $ARGV[0];

my $seed_event = Math::StochasticProcess::Event::Tuple->new
(
    random_variables=>
    {
        value=>Math::StochasticProcess::RandomVariable->new
                                                    (
                                                        value=>0,
                                                        internal=>1
                                                    ),
        rounds=>Math::StochasticProcess::RandomVariable->new
                                                    (
                                                        value=>0,
                                                        internal=>0
                                                    )
    },
    iterate_cb=>sub
    {
        my $self = shift;
        my @results;
        my $rounds = $self->randomVariable('rounds');
        my $value = $self->randomVariable('value');
        my $t = $value +7 - $goal;
        my $l = $t < 0 ? 6 : 6-$t;
        if ($t > 0) {
            push @results, $self->copy( $t/6,
                                        RESOLVED_VAR_NAME()=>1,
                                        rounds=>$rounds+1);
        }
        for(my $i = 1; $i <= $l; $i++) {
            push @results, $self->copy( 1/6,
                                        rounds=>$rounds+1,
                                        value=>$value+$i);
        }
        return @results;
    }
);
my $logfh = undef;


my $analysis = undef;
if (defined($ARGV[1])) {
    $logfh = FileHandle->new;
    open($logfh, ">$ARGV[1]") or die "could not open log file";
    $analysis = Math::StochasticProcess->new(
                            seed_event=>$seed_event,
                            tolerance=>0.0000000000000001,
                            hard_sanity_level=>0.0000001,
                            log_file_handle=>$logfh
                        );
}
else {
    $analysis = Math::StochasticProcess->new(
                            seed_event=>$seed_event,
                            tolerance=>0.0000000000000001,
                            hard_sanity_level=>0.0000001
                        );
}
$analysis->run();
my %event = $analysis->event();
my $expectedValue = $analysis->expectedValue('rounds');
print "Goal: $goal\n";
print "Expected number of rounds: $expectedValue\n";
my @keys = sort {(split(/\|/,$a))[0] <=> (split(/\|/,$b))[0]} keys %event;
foreach my $d (@keys) {
    my $rounds = $event{$d}->randomVariable('rounds');
    my $probability = $event{$d}->probability();
    print "Rounds: $rounds; Probability: $probability\n";
}

exit(0);

AUTHOR

Nicholas Bamber, <theabbot at silasthemonk.org.uk>

BUGS

Please report any bugs or feature requests to bug-math-stochasticprocess-event-tuple at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-StochasticProcess. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Math::StochasticProcess

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Nicholas Bamber, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.