Provided by: libmath-planepath-perl_122-1_all bug

NAME

       Math::PlanePath::VogelFloret -- circular pattern like a sunflower

SYNOPSIS

        use Math::PlanePath::VogelFloret;
        my $path = Math::PlanePath::VogelFloret->new;
        my ($x, $y) = $path->n_to_xy (123);

        # other rotations
        $path = Math::PlanePath::VogelFloret->new
                  (rotation_type => 'sqrt2');

DESCRIPTION

       The is an implementation of Helmut Vogel's model for the arrangement of seeds in the head
       of a sunflower.  Integer points are on a spiral at multiples of the golden ratio phi =
       (1+sqrt(5))/2,

                       27       19
                                         24

                       14          11
                 22                         16
                              6                   29

           30           9           3
                                          8
                              1                   21
                 17              .
                           4
                                            13
              25                 2     5
                    12
                           7                      26
                                      10
                                            18
                    20       15

                                   23       31
                          28

       The polar coordinates for a point N are

           R = sqrt(N) * radius_factor
           angle = N / (phi**2)        in revolutions, 1==full circle
                 = N * -phi            modulo 1, with since 1/phi^2 = 2-phi
           theta = 2*pi * angle        in radians

       Going from point N to N+1 adds an angle 0.382 revolutions around (anti-clockwise, the
       usual spiralling direction), which means just over 1/3 of a circle.  Or equivalently it's
       -0.618 back (clockwise) which is phi=1.618 ignoring the integer part since that's a full
       circle -- only the fractional part determines the position.

       "radius_factor" is a scaling 0.6242 designed to put the closest points 1 apart.  The
       closest are N=1 and N=4.  See "Packing" below.

   Other Rotation Types
       An optional "rotation_type" parameter selects other possible floret forms.

           $path = Math::PlanePath::VogelFloret->new
                      (rotation_type => 'sqrt2');

       The current types are as follows.  The "radius_factor" for each keeps points at least 1
       apart so unit circles don't overlap.

           rotation_type   rotation_factor   radius_factor
             "phi"        2-phi   = 0.3820     0.624
             "sqrt2"      sqrt(2) = 0.4142     0.680
             "sqrt3"      sqrt(3) = 0.7321     0.756
             "sqrt5"      sqrt(5) = 0.2361     0.853

       The "sqrt2" floret is quite similar to phi, but doesn't pack as tightly.  Custom rotations
       can be made with "rotation_factor" and "rotation_factor" parameters,

           # R  = sqrt(N) * radius_factor
           # angle = N * rotation_factor     in revolutions
           # theta = 2*pi * angle            in radians
           #
           $path = Math::PlanePath::VogelFloret->new
                      (rotation_factor => sqrt(37),
                       radius_factor   => 2.0);

       Usually "rotation_factor" should be an irrational number.  A rational like P/Q merely
       results in Q many straight lines and doesn't spread the points enough to suit R=sqrt(N).
       Irrationals which are very close to simple rationals behave that way too.  (Of course all
       floating point values are implicitly rationals, but are fine within the limits of floating
       point accuracy.)

       The "noble numbers" (A+B*phi)/(C+D*phi) with A*D-B*C=1, A<B, C<D behave similar to the
       basic phi.  Their continued fraction expansion begins with some arbitrary values and then
       becomes a repeating "1" the same as phi.  The effect is some spiral arms near the origin
       then the phi-ness dominating for large N.

   Packing
       Each point is at an increasing distance sqrt(N) from the origin.  This sqrt based on how
       many unit figures will fit within that distance.  The area within radius R is

           T = pi * R^2        area of circle R

       so if N figures each of area A are packed into that space then the radius R is
       proportional to sqrt(N),

           N*A = T = pi * R^2
           R = sqrt(N) * sqrt(A/pi)

       The tightest possible packing for unit circles is a hexagonal honeycomb grid, each of area
       A = sqrt(3)/2 = 0.866.  That would be factor sqrt(A/pi) = 0.525.  The phi floret packing
       is not as tight as that, needing radius factor 0.624 as described above.

       Generally the tightness of the packing depends on the fractions which closely approximate
       the rotation factor.  If the terms of the continued fraction expansion are large then
       there's large regions of spiral arcs with gaps between.  The density in such regions is
       low and a big radius factor is needed to keep the points apart.  If the continued fraction
       terms are ever increasing then there may be no radius factor big enough to always keep the
       points a minimum distance apart ... or something like that.

       The terms of the continued fraction for phi are all 1 and is therefore, in that sense,
       among all irrationals, the value least well approximated by rationals.

                       1
           phi = 1 + ------
                     1 +  1
                         ------
                     ^   1 +  1
                     |       ---
                     |   ^   1 + 1
                     |   |      ----
                     |   |   ^  ...
              terms -+---+---+

       sqrt(3) is 1,2 repeating.  sqrt(13) is 3s repeating.

   Fibonacci and Lucas Numbers
       The Fibonacci numbers F(k) = 1,1,2,3,5,8,13,21, etc and Lucas number L(k) =
       2,1,3,4,7,11,18, etc form almost straight lines on the X axis of the phi floret.  This
       occurs because N*-phi is close to an integer for those N.  For example N=13 has angle
       13*-phi = -21.0344, the fractional part -0.0344 puts it just below the X axis.

       Both F(k) and L(k) grow exponentially (as phi^k) which soon outstrips the sqrt in the R
       radial distance so they become widely spaced apart along the X axis.

       For interest, or for reference, the angle F(k)*phi is in fact roughly the next Fibonacci
       number F(k+1), per the well-known limit F(k+1)/F(k) -> phi as k->infinity,

           angle = F(k)*-phi
                 = -F(k+1) + epsilon

       The Lucas numbers similarly with L(k)*phi close to L(k+1).  The "epsilon" approaches zero
       quickly enough in both cases that the resulting Y coordinate approaches zero.  This can be
       calculated as follows, writing

           beta = -1/phi =-0.618

       Since abs(beta)<1 the powers beta^k go to zero.

           F(k) = (phi^k - beta^k) / (phi - beta)    # an integer

           angle = F(k) * -phi
                 = - (phi*phi^k - phi*beta^k) / (phi - beta)
                 = - (phi^(k+1) - beta^(k+1)
                                + beta^(k+1) - phi*beta^k) / (phi - beta)
                 = - F(k+1) - (phi-beta)*beta^k / (phi - beta)
                 = - F(k+1) - beta^k

           frac(angle) = - beta^k = 1/(-phi)^k

       The arc distance away from the X axis at radius R=sqrt(F(k)) is then as follows,
       simplifying using phi*(-beta)=1 and phi - beta = sqrt(5).  The Y coordinate vertical
       distance is a little less than the arc distance.

           arcdist = 2*pi * R * frac(angle)
                   = 2*pi * sqrt((phi^k - beta^k)/sqrt(5)) * 1/(-phi)^k
                   = - (-1)^k * 2*pi * sqrt((1/phi^2k*phi^k - beta^3k)/sqrt(5))
                   = - (-1)^k * 2*pi * sqrt((1/phi^k - 1/(-phi)^3k)/sqrt(5))
                       -> 0 as k -> infinity

       Essentially the radius increases as phi^(k/2) but the angle frac decreases as (1/phi)^k so
       their product goes to zero.  The (-1)^k in the formula puts the points alternately just
       above and just below the X axis.

       The calculation for the Lucas numbers is very similar, with term +(beta^k) instead of
       -(beta^k) and an extra factor sqrt(5).

           L(k) = phi^k + beta^k

           angle = L(k) * -phi
                 = -phi*phi^k - phi*beta^k
                 = -phi^(k+1) - beta^(k+1) + beta^(k+1) - phi*beta^k
                 = -L(k) + beta^k * (beta - phi)
                 = -L(k) - sqrt(5) * beta^k

           frac(angle) = -sqrt(5) * beta^k = -sqrt(5) / (-phi)^k

           arcdist = 2*pi * R * frac(angle)
                   = 2*pi * sqrt(L(k)) * sqrt(5)*beta^k
                   = 2*pi * sqrt(phi^k + 1/(-phi)^k) * sqrt(5)*beta^k
                   = (-1)*k * 2*pi * sqrt(5) * sqrt((-beta)^2k * phi^k + beta^3k)
                   = (-1)*k * 2*pi * sqrt(5) * sqrt((-beta)^k + beta^3k)

   Spectrum
       The spectrum of a real number is its multiples, each rounded down to an integer.  For
       example the spectrum of phi is

           floor(phi), floor(2*phi), floor(3*phi), floor(4*phi), ...
           1,          3,            4,            6, ...

       When plotted on the Vogel floret these integers are all in the first 1/phi = 0.618 of the
       circle.

                          61    53
                    69       40       45    58
                       48          32          71
                 56       27                37
                    35          19    24       50
                 43       14       11             63
           64          22     6          16 29
                 30                 3          42
              51           9  1        8    21
           72       17     4     .                55
                 38
           59       25 12

                 46 33

              67

       This occurs because

           angle = N * 1/phi^2
                 = N * (1-1/phi)
                 = N * -1/phi                   # modulo 1
                 = floor(int*phi) * -1/phi      # N=spectrum
                 = (int*phi - frac) * -1/phi    # 0<frac<1
                 = int + frac*1/phi
                 = frac * 1/phi                 # modulo 1

       So the angle is a fraction from 0 to 1/phi=0.618 of a revolution.  In general for a
       "rotation_factor=t" with 0<t<1 the spectrum of 1/t falls within the first 0 to t angle.

   Fibonacci Word
       The Fibonacci word 0,1,0,0,1,0,1,0,0,1,etc is the least significant bit of the Zeckendorf
       base representation of i, starting from i=0.  Plotted at N=i on the "VogelFloret" gives

                     1       0
                 1     1 1   0   0            Fibonacci word
               1   1 1     0       0
                 1       1   0   0 0
           1   1   1 1 1   0   0 0   0
             1 1     1 1   0 0     0
           1   1 1   1   .       0 0 0
           1     1 1     0   0 0       0
               1       0   0   0 0   0
             1   1 0     0       0   0
               0   0 0   0 0   0 0   0
                   0   0     0 0
                       0   0

       This pattern occurs because the Fibonacci word, among its various possible definitions, is
       0 or 1 according to whether i+1 occurs in the spectrum of phi (1,3,4,6,8,etc) or not.  So
       for example at i=5 the value is 0 because i+1=6 is in the spectrum of phi, then at i=6 the
       value is 1 because i+1=7 is not.

       The "+1" for i to spectrum has the effect of rotating the spectrum pattern described above
       by -0.381 (one rotation factor back).  So the Fibonacci word "0"s are from angle -0.381 to
       -0.381+0.618=0.236 and the rest "1"s.  0.236 is close to 1/4, hence the "0"s to "1"s line
       just before the Y axis.

   Repdigits in Decimal
       Some of the decimal repdigits 11, 22, ..., 99, 111, ..., 999, etc make nearly straight
       radial lines on the phi floret.  For example 11, 66, 333, 888 make a line upwards to the
       right.

       11 and 66 are at the same polar angle because the difference is 55 and 55*phi = 88.9919 is
       nearly an integer meaning the angle is nearly unchanged when added.  Similarly 66 to 333
       difference 267 has 267*phi = 432.015, or 333 to 888 difference 555 has 555*phi = 898.009.
       The 55 is a Fibonacci number, the 123 between 99 and 222 is a Lucas number, and 267 =
       144+123 = F(12)+L(10).

       The differences 55 and 555 apply to pairs 22 and 77, 33 and 88, 666 and 1111, etc, making
       four straightish arms.  55 and 555 themselves are near the X axis.

       A separate spiral arm arises from 11111 falling moderately close to the X axis since
       11111*-phi = -17977.9756, or about 0.024 of a circle upwards.  The subsequent 22222,
       33333, 44444, etc make a little arc of nine values going upwards that much each time for a
       total about a quarter turn 9*0.024 = 0.219.

   Repdigits in Other Bases
       By choosing a radix so that "11" (or similar repunit) in that radix is close to the X
       axis, spirals like the decimal 11111 above can be created.  This includes when "11" in the
       base is a Fibonacci number or Lucas number, such as base 12 so "11" base 12 is 13.  If
       "11" is near the negative X axis then there's two spiral arms, one going out on the X
       negative side and one X positive, eg. base 16 has 0x11=17 which is near the negative X
       axis.  A four-arm shape can be formed similarly if "11" is near the Y axis, eg. base 107.

FUNCTIONS

       See "FUNCTIONS" in Math::PlanePath for behaviour common to all path classes.

       "$path = Math::PlanePath::VogelFloret->new ()"
       "$path = Math::PlanePath::VogelFloret->new (key => value, ...)"
           Create and return a new path object.

           The default is Vogel's phi floret.  Optional parameters can vary the pattern,

               rotation_type   => string, choices above
               rotation_factor => number
               radius_factor   => number

           The available "rotation_type" values are listed above (see "Other Rotation Types").
           "radius_factor" can be given together with "rotation_type" to have its rotation, but
           scale the radius differently.

           If a "rotation_factor" is given then the default "radius_factor" is not specified yet.
           Currently it's 1.0, but perhaps something suiting at least the first few N positions
           would be better.

       "($x,$y) = $path->n_to_xy ($n)"
           Return the X,Y coordinates of point number $n on the path.

           $n can be any value "$n >= 0" and fractions give positions on the spiral in between
           the integer points, though the principle interest for the floret is where the integers
           fall.

           For "$n < 0" the return is an empty list, it being considered there are no negative
           points in the spiral.

       "$rsquared = $path->n_to_rsquared ($n)"
           Return the radial distance R^2 of point $n, or "undef" if there's no point $n.  As per
           the formulas above this is simply

               $n * $radius_factor**2

       "$n = $path->xy_to_n ($x,$y)"
           Return an integer point number for coordinates "$x,$y".  Each integer N is considered
           the centre of a circle of diameter 1 and an "$x,$y" within that circle returns N.

           The builtin "rotation_type" choices are scaled so no two points are closer than 1
           apart so the circles don't overlap, but they also don't cover the plane and if "$x,$y"
           is not within one of those circles then the return is "undef".

           With "rotation_factor" and "radius_factor" parameters it's possible for unit circles
           to overlap.  In the current code the return is the largest N covering "$x,$y", but
           perhaps that will change.

       "$str = $path->figure ()"
           Return "circle".

OEIS

       Entries in Sloane's Online Encyclopedia of Integer Sequences related to this path include

           <http://oeis.org/A000201> (etc)

           A000201    spectrum of phi, N in first 0.618 of circle
           A003849    Fibonacci word, values 0,1

SEE ALSO

       Math::PlanePath, Math::PlanePath::SacksSpiral, Math::PlanePath::TheodorusSpiral

       Math::NumSeq::FibonacciWord, Math::NumSeq::Fibbinary

HOME PAGE

       <http://user42.tuxfamily.org/math-planepath/index.html>

LICENSE

       Copyright 2010, 2011, 2012, 2013, 2014, 2015 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/>.