view release on metacpan or  search on metacpan

lib/Math/NumSeq/Polygonal.pm  view on Meta::CPAN

=head1 SYNOPSIS

 use Math::NumSeq::Polygonal;
 my $seq = Math::NumSeq::Polygonal->new (polygonal => 7);
 my ($i, $value) = $seq->next;

=head1 DESCRIPTION

The sequence of polygonal numbers.  The 3-gonals are the triangular numbers
i*(i+1)/2, the 4-gonals are squares i*i, the 5-gonals are pentagonals
(3i-1)*i/2, etc.

In general the k-gonals for kE<gt>=3 are

    P(i) = (k-2)/2 * i*(i+1) - (k-3)*i

The values are how many points are in a triangle, square, pentagon, hexagon,
etc of side i.  For example the triangular numbers,

                                         d
                             c          c d
                b           b c        b c d
    a          a b         a b c      a b c d

    i=1        i=2         i=3        i=4
    value=1    value=3     value=6    value=10

Or the squares,

                                      d d d d
                           c c c      c c c d
               b b         b b c      b b c d
    a          a b         a b c      a b c d

    i=1        i=2         i=3        i=4
    value=1    value=4     value=9    value=16

Or pentagons (which should be a pentagonal grid, so skewing a bit here),

                                              d
                                            d   d
                               c          d  c    d
                             c   c      d  c   c    d
                  b        c  b    c     c  b    c d
                b   b       b   b c       b   b c d
    a            a b         a b c         a b c d

    i=1        i=2         i=3          i=4
    value=1    value=5     value=12     value=22

The letters "a", "b" "c" show the extra added onto the previous figure to
grow its points.  Each side except two are extended.  In general the
k-gonals increment by k-2 sides of i points, plus 1 at the end of the last
side, so

   P(i+1) = P(i) + (k-2)*i + 1

=head2 Second Kind

Option C<pairs =E<gt> 'second'> gives the polygonals of the second kind,
which are the same formula but with a negative i.

    S(i) = P(-i) = (k-2)/2 * i*(i-1) + (k-3)*i

The result is still positive values, bigger than the plain P(i).  For
example the pentagonals are 0,1,5,12,22,etc and the second pentagonals are
0,2,7,15,26,etc.

=head2 Both Kinds

C<pairs =E<gt> 'both'> gives the firsts and seconds interleaved.  P(0) and
S(0) are both 0 and that value is given just once at i=0, so

    0, P(1), S(1), P(2), S(2), P(3), S(3), ...

=head2 Average

Option C<pairs =E<gt> 'average'> is the average of the first and second,
which ends up being simply a multiple of the perfect squares,

    A(i) = (P(i)+S(i))/2
         = (k-2)/2 * i*i

This is an integer if k is even, or k odd and i is even.  If k and i both
odd then it's an 0.5 fraction.

=head1 FUNCTIONS

See L<Math::NumSeq/FUNCTIONS> for behaviour common to all sequence classes.

=over 4

=item C<$seq = Math::NumSeq::Polygonal-E<gt>new ()>

=item C<$seq = Math::NumSeq::Polygonal-E<gt>new (pairs =E<gt> $str)>

Create and return a new sequence object.  The default is the polygonals of
the "first" kind, or the C<pairs> option (a string) can be

    "first"
    "second"
    "both"
    "average"

=back

=head2 Random Access

=over

=item C<$value = $seq-E<gt>ith($i)>

Return the C<$i>'th polygonal value, of the given C<pairs> type.

=item C<$bool = $seq-E<gt>pred($value)>

Return true if C<$value> is a polygonal number, of the given C<pairs> type.

=item C<$i = $seq-E<gt>value_to_i_estimate($value)>

Return an estimate of the i corresponding to C<$value>.