Math::Series - Perl extension dealing with mathematic series
use Math::Series;
my $x_n = Math::Series->new( formula => 'n*x',
start_value => 1,
iteration_var => 'n',
previous_var => 'x',
start_index => 0,
cached => 1 );
print $x_n->next(), "\n" foreach 0..5;
# prints 1, 2, 6, 24...
print $x_n->at_index(3);
# prints 24
Math::Series defines a class for simple mathematic series with a recursive
definition such as "x_(n+1) = 1 / (x_n + 1)". Such a recursive
definition is treated as a sequence whose elements will be added to form a
series. You can refer to the previous sequence element as well as to the
current index in the series. Creation of a Math::Series object is described
below in the paragraph about the constructor.
Math::Series uses Math::Symbolic to parse and modify the recursive sequence
definitions. That means you specify the sequence as a string which is parsed
by Math::Symbolic. Alternatively, you can pass the constructor a
Math::Symbolic tree directly.
Because Math::Series uses Math::Symbolic for its implementation, all results
will be Math::Symbolic objects which may contain other variables than the
sequence variable and the iterator variable.
Each Math::Series object is an iterator to iterate over the elements of the
series starting at the first element (which was specified by the starting
element, the second argument to the
new() constructor). It offers
facilities to cache all calculated elements and access any element directly,
though unless the element has been cached in a previous calculation, this is
just a shortcut for repeated use of the iterator.
Every element in the series may only access its predecessor, not the elements
before that.
Math::Series defines the following package variables:
- $Math::Series::Parser
- This scalar contains a Parse::RecDescent parser to parse formulas. It is
derived from the Math::Symbolic::Parser grammar.
- $Math::Series::warnings
- This scalar indicates whether Math::Series should warn about the
performance implications of using the back() method on uncached
series. It defaults to true.
- new()
- The constructor for Math::Series objects. It takes named parameters. The
following parameters are required:
- formula
- The formula is the recursive definition of a sequence whose elements up to
the current element will be summed to form the current element of the
series. The formula may contain various Math::Symbolic variables that are
assigned a value elsewhere in your code, but it may also contain two
special variables: The number of the current iteration step, starting with
0, and the previous element of the series.
The formula may be specified as a string that can be parsed by a
Math::Symbolic parser or as a Math::Symbolic tree directly. Please refer
to the Math::Symbolic and Math::Symbolic::Parser man pages for
details.
- start_value
- This parameter defines the starting value for the series. It used as the
element in the series that is defined as the lowest series element by the
start_index parameter. The starting value may be a string that can be
parsed as a valid Math::Symbolic tree or a preconstructed Math::Symbolic
tree.
The following parameters are optional:
- iteration_var
- The iteration variable is the name of the variable in the Math::Symbolic
tree that refers to the current iteration step. It defaults to the
variable 'n'.
It must be a valid Math::Symbolic variable identifier. (That means it is
"/[A-Za-z][A-Za-z0-9_]*/".)
- previous_var
- The previous_var parameter sets the name of the variable that represents
the previous iteration step. It defaults to the name 'x' and must be a
valid Math::Symbolic variable identifier just like the iteration
variable.
- cached
- This parameter indicates whether or not to cache the calculated series'
elements for faster direct access. It defaults to true. At run-time, the
caching behaviour may be altered using the cached() method.
- start_index
- The lower boundary for the series' summation. It defaults to 0, but may be
set to any positive integer or zero.
- next()
- The next() method returns the next element of the series and
advances the iterator by one. This is the prefered method of walking down
a series' recursion.
- cached()
- Returns a true value if the series is currently being cached, false if it
isn't. By default, new objects have caching enabled. It is suggested that
you only disable caching if space is an issue and you will only walk the
series uni-directionally and only once.
cached() can be used to change the caching behaviour. If the first
argument is true, caching will be enabled. If it is false, caching will be
disabled.
- current_index()
- Returns the index of the current element. That is, the index of the
element that will be returned by the next call to the next()
method.
This method also allows (re-)setting the element that will be next returned
by the next() method. In that case, the first argument shoudl be
the appropriate index.
Returns undef and doesn't set the current index if the argument is below
0.
- at_index()
- This method returns the series element with the index denoted by the first
argument to the method. It does not change the state of the iterator. This
method is extremely slow for uncached series.
Returns undef for indices below the starting index.
- back()
- This methods returns the series element previously returned by the
next() method. Since it is extremely slow on uncached series, it
warns about this performance hit by default. To turn this warning off, set
the $Math::Series::warnings scalar to a false value.
This method decrements the current iterator series element.
Returns undef if the current index goes below the starting index.
Steffen Mueller, <series-module at steffen-mueller dot net<gt>
You may find the current versions of this module at http://steffen-mueller.net/
or on CPAN.
This module is based on Math::Sequence. Math::Symbolic and
Math::Symbolic::Parser for the kinds of formulas accepted by
Math::Series.