Math::NumSeq::PlanePathCoord(3) sequence of coordinate values from a PlanePath module

SYNOPSIS


use Math::NumSeq::PlanePathCoord;
my $seq = Math::NumSeq::PlanePathCoord->new
(planepath => 'SquareSpiral',
coordinate_type => 'X');
my ($i, $value) = $seq->next;

DESCRIPTION

This is a tie-in to make a "NumSeq" sequence giving coordinate values from a "Math::PlanePath". The NumSeq ``i'' index is the PlanePath ``N'' value.

The "coordinate_type" choices are as follows. Generally they have some sort of geometric interpretation or are related to fractions X/Y.

    "X"            X coordinate
    "Y"            Y coordinate
    "Min"          min(X,Y)
    "Max"          max(X,Y)
    "MinAbs"       min(abs(X),abs(Y))
    "MaxAbs"       max(abs(X),abs(Y))
    "Sum"          X+Y sum
    "SumAbs"       abs(X)+abs(Y) sum
    "Product"      X*Y product
    "DiffXY"       X-Y difference
    "DiffYX"       Y-X difference (negative of DiffXY)
    "AbsDiff"      abs(X-Y) difference
    "Radius"       sqrt(X^2+Y^2) radial distance
    "RSquared"     X^2+Y^2 radius squared
    "TRadius"      sqrt(X^2+3*Y^2) triangular radius
    "TRSquared"    X^2+3*Y^2 triangular radius squared
    "IntXY"        int(X/Y) division rounded towards zero
    "FracXY"       frac(X/Y) division rounded towards zero
    "BitAnd"       X bitand Y
    "BitOr"        X bitor Y
    "BitXor"       X bitxor Y
    "GCD"          greatest common divisor X,Y
    "Depth"        tree_n_to_depth()
    "SubHeight"    tree_n_to_subheight()
    "NumChildren"  tree_n_num_children()
    "NumSiblings"  not including self
    "RootN"        the N which is the tree root
    "IsLeaf"       0 or 1 whether a leaf node (no children)
    "IsNonLeaf"    0 or 1 whether a non-leaf node (has children)
                     also called an "internal" node

Min and Max

``Min'' and ``Max'' are the minimum or maximum of X and Y. The geometric interpretation of ``Min'' is to select X at any point above the X=Y diagonal or Y for any point below. Conversely ``Max'' is Y above and X below. On the X=Y diagonal itself X=Y=Min=Max.

    Max=Y      / X=Y diagonal
    Min=X   | /
            |/
         ---o----
           /|
          / |     Max=X
         /        Min=Y

Min and Max can also be interpreted as counting which gnomon shaped line the X,Y falls on.

    | | | |     Min=gnomon           2 ------------.  Max=gnomon
    | | | |                          1 ----------. |
    | | | |      ...                 0 --------o | |
    | | |  ------ 1                 -1 ------. | | |
    | | o-------- 0                 ...      | | | |
    |  ---------- -1                         | | | |
     ------------ -2                         | | | |

MinAbs

MinAbs = min(abs(X),abs(Y)) can be interpreted geometrically as counting gnomons successively away from the origin. This is like Min above, but within the quadrant containing X,Y.

         | | | | |          MinAbs=gnomon counted away from the origin
         | | | | |
    2 ---  | | |  ---- 2
    1 -----  |  ------ 1
    0 -------o-------- 0
    1 -----  |  ------ 1
    2 ---  | | |  ---- 2
         | | | | |
         | | | | |

MaxAbs

MaxAbs = max(abs(X),abs(Y)) can be interpreted geometrically as counting successive squares around the origin.

    +-----------+       MaxAbs=which square
    | +-------+ |
    | | +---+ | |
    | | | o | | |
    | | +---+ | |
    | +-------+ |
    +-----------+

For example Math::PlanePath::SquareSpiral loops around in squares and so its MaxAbs is unchanged until it steps out to the next bigger square.

Sum and Diff

``Sum''=X+Y and ``DiffXY''=X-Y can be interpreted geometrically as coordinates on 45-degree diagonals. Sum is a measure up along the leading diagonal and DiffXY down an anti-diagonal,

    \           /
     \   s=X+Y /
      \       ^\
       \     /  \
        \ | /    v
         \|/      * d=X-Y
       ---o----
         /|\
        / | \
       /  |  \
      /       \
     /         \
    /           \

Or ``Sum'' can be thought of as a count of which anti-diagonal stripe contains X,Y, or a projection onto the X=Y leading diagonal.

           Sum
    \     = anti-diag
     2      numbering          / / / /   DiffXY
    \ \       X+Y            -1 0 1 2   = diagonal
     1 2                     / / / /      numbering
    \ \ \                  -1 0 1 2         X-Y
     0 1 2                   / / /
      \ \ \                 0 1 2

DiffYX

``DiffYX'' = Y-X is simply the negative of DiffXY. It's included to give positive values on paths which are above the X=Y leading diagonal. For example DiffXY is positive in "CoprimeColumns" which is below X=Y, whereas DiffYX is positive in "CellularRule" which is above X=Y.

SumAbs

``SumAbs'' = abs(X)+abs(Y) is similar to the projection described above for Sum or Diff, but SumAbs projects onto the central diagonal of whichever quadrant contains the X,Y. Or equivalently it's a numbering of anti-diagonals within that quadrant, so numbering which diamond shape the X,Y falls on.

         |
        /|\       SumAbs = which diamond X,Y falls on
       / | \
      /  |  \
    -----o-----
      \  |  /
       \ | /
        \|/
         |

As an example, the "DiamondSpiral" path loops around on such diamonds, so its SumAbs is unchanged until completing a loop and stepping out to the next bigger.

SumAbs is also a ``taxi-cab'' or ``Manhattan'' distance, being how far to travel through a square-grid city to get to X,Y.

    SumAbs = taxi-cab distance, by any square-grid travel
    +-----o       +--o          o
    |             |             |
    |          +--+       +-----+
    |          |          |
    *          *          *

If a path is entirely X>=0,Y>=0 in the first quadrant then Sum and SumAbs are identical.

AbsDiff

``AbsDiff'' = abs(X-Y) can be interpreted geometrically as the distance away from the X=Y diagonal, measured at right-angles to that line.

     d=abs(X-Y)
           ^    / X=Y line
            \  /
             \/
             /\
            /  \
          |/    \
        --o--    \
         /|       v
        /           d=abs(X-Y)

If a path is entirely below the X=Y line, so X>=Y, then AbsDiff is the same as DiffXY. Or if a path is entirely above the X=Y line, so Y>=X, then AbsDiff is the same as DiffYX.

Radius and RSquared

Radius and RSquared are per "$path->n_to_radius()" and "$path->n_to_rsquared()" respectively (see ``Coordinate Methods'' in Math::PlanePath).

TRadius and TRSquared

``TRadius'' and ``TRSquared'' are designed for use with points on a triangular lattice as per ``Triangular Lattice'' in Math::PlanePath. For points on the X axis TRSquared is the same as RSquared but off the axis Y is scaled up by factor sqrt(3).

Most triangular paths use ``even'' points X==Y mod 2 and for them TRSquared is always even. Some triangular paths such as "KochPeaks" have an offset from the origin and use ``odd'' points X!=Y mod 2 and for them TRSquared is odd.

IntXY and FracXY

``IntXY'' = int(X/Y) is the quotient from X divide Y rounded to an integer towards zero. This is like the integer part of a fraction, for example X=9,Y=4 is 9/4 = 2+1/4 so IntXY=2. Negatives are reckoned with the fraction part negated too, so -2 1/4 is -2-1/4 and thus IntXY=-2.

Geometrically IntXY gives which wedge of slope 1, 2, 3, etc the point X,Y falls in. For example IntXY is 3 for all points in the wedge 3Y<=X<4Y.

                               X=Y    X=2Y   X=3Y   X=4Y
    *  -2  *  -1  *   0  |  0   *  1   *  2   *   3  *
       *     *     *     |     *     *     *     *
          *    *    *    |    *    *    *    *
             *   *   *   |   *   *   *   *
                *  *  *  |  *  *  *  *
                   * * * | * * * *
                      ***|****
    ---------------------+----------------------------
                       **|**
                     * * | * *
                   *  *  |  *  *
                 *   *   |   *   *
               *    *    |    *    *
         2   *  1  *  0  |  0  * -1  *  -2

``FracXY'' is the fraction part which goes with IntXY. In all cases

    X/Y = IntXY + FracXY

IntXY rounds towards zero so the remaining FracXY has the same sign as IntXY.

BitAnd, BitOr, BitXor

``BitAnd'', ``BitOr'' and ``BitXor'' treat negative X or negative Y as infinite twos-complement 1-bits, which means for example X=-1,Y=-2 has X bitand Y = -2.

    ...11111111    X=-1
    ...11111110    Y=-2
    -----------
    ...11111110    X bitand Y = -2

This twos-complement is per "Math::BigInt" (which has bitwise operations in Perl 5.6 and up). The code here arranges the same on ordinary scalars.

If X or Y are not integers then the fractional parts are treated bitwise too, but currently only to limited precision.

FUNCTIONS

See ``FUNCTIONS'' in Math::NumSeq for behaviour common to all sequence classes.
"$seq = Math::NumSeq::PlanePathCoord->new (planepath => $name, coordinate_type => $str)"
Create and return a new sequence object. The options are

    planepath          string, name of a PlanePath module
    planepath_object   PlanePath object
    coordinate_type    string, as described above

"planepath" can be either the module part such as ``SquareSpiral'' or a full class name ``Math::PlanePath::SquareSpiral''.

"$value = $seq->ith($i)"
Return the coordinate at N=$i in the PlanePath.
"$i = $seq->i_start()"
Return the first index $i in the sequence. This is the position "rewind()" returns to.

This is "$path->n_start()" from the PlanePath, since the i numbering is the N numbering of the underlying path. For some of the "Math::NumSeq::OEIS" generated sequences there may be a higher "i_start()" corresponding to a higher starting point in the OEIS, though this is slightly experimental.

"$str = $seq->oeis_anum()"
Return the A-number (a string) for $seq in Sloane's Online Encyclopedia of Integer Sequences, or return "undef" if not in the OEIS or not known.

Known A-numbers are also presented through "Math::NumSeq::OEIS::Catalogue". This means PlanePath related OEIS sequences can be created with "Math::NumSeq::OEIS" by giving their A-number in the usual way for that module.

LICENSE

Copyright 2011, 2012, 2013, 2014 Kevin Ryde

This file is part of Math-PlanePath.

Math-PlanePath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Math-PlanePath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Math-PlanePath. If not, see <http://www.gnu.org/licenses/>.