# NAME

Math::NumSeq::Polygonal -- polygonal numbers, triangular, square, pentagonal, etc

# SYNOPSIS

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

# 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 k>=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``

## Second Kind

Option `pairs => '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.

## Both Kinds

`pairs => '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), ...``

## Average

Option `pairs => '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.

# FUNCTIONS

See "FUNCTIONS" in Math::NumSeq for behaviour common to all sequence classes.

`\$seq = Math::NumSeq::Polygonal->new ()`
`\$seq = Math::NumSeq::Polygonal->new (pairs => \$str)`

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

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

## Random Access

`\$value = \$seq->ith(\$i)`

Return the `\$i`'th polygonal value, of the given `pairs` type.

`\$bool = \$seq->pred(\$value)`

Return true if `\$value` is a polygonal number, of the given `pairs` type.

`\$i = \$seq->value_to_i_estimate(\$value)`

Return an estimate of the i corresponding to `\$value`.