Provided by: libmath-vector-real-perl_0.18-3_all bug

NAME

       Math::Vector::Real - Real vector arithmetic in Perl

SYNOPSIS

         use Math::Vector::Real;

         my $v = V(1.1, 2.0, 3.1, -4.0, -12.0);
         my $u = V(2.0, 0.0, 0.0,  1.0,   0.3);

         printf "abs(%s) = %d\n", $v, abs($b);
         my $dot = $u * $v;
         my $sub = $u - $v;
         # etc...

DESCRIPTION

       A simple pure perl module to manipulate vectors of any dimension.

       The function "V", always exported by the module, allows one to create new vectors:

         my $v = V(0, 1, 3, -1);

       Vectors are represented as blessed array references. It is allowed to manipulate the
       arrays directly as far as only real numbers are inserted (well, actually, integers are
       also allowed because from a mathematical point of view, integers are a subset of the real
       numbers).

       Example:

         my $v = V(0.0, 1.0);

         # extending the 2D vector to 3D:
         push @$v, 0.0;

         # setting some component value:
         $v->[0] = 23;

       Vectors can be used in mathematical expressions:

         my $u = V(3, 3, 0);
         $p = $u * $v;       # dot product
         $f = 1.4 * $u + $v; # scalar product and vector addition
         $c = $u x $v;       # cross product, only defined for 3D vectors
         # etc.

       The currently supported operations are:

         + * /
         - (both unary and binary)
         x (cross product for 3D vectors)
         += -= *= /= x=
         == !=
         "" (stringfication)
         abs (returns the norm)
         atan2 (returns the angle between two vectors)

       That, AFAIK, are all the operations that can be applied to vectors.

       When an array reference is used in an operation involving a vector, it is automatically
       upgraded to a vector. For instance:

         my $v = V(1, 2);
         $v += [0, 2];

   Extra methods
       Besides the common mathematical operations described above, the following methods are
       available from the package.

       Note that all these methods are non destructive returning new objects with the result.

       $v = Math::Vector::Real->new(@components)
           Equivalent to "V(@components)".

       $zero = Math::Vector::Real->zero($dim)
           Returns the zero vector of the given dimension.

       $v = Math::Vector::Real->cube($dim, $size)
           Returns a vector of the given dimension with all its components set to $size.

       $u = Math::Vector::Real->axis_versor($dim, $ix)
           Returns a unitary vector of the given dimension parallel to the axis with index $ix
           (0-based).

           For instance:

             Math::Vector::Real->axis_versor(5, 3); # V(0, 0, 0, 1, 0)
             Math::Vector::Real->axis_versor(2, 0); # V(1, 0)

       @b = Math::Vector::Real->canonical_base($dim)
           Returns the canonical base for the vector space of the given dimension.

       $u = $v->versor
           Returns the versor for the given vector.

           It is equivalent to:

             $u = $v / abs($v);

       $wrapped = $w->wrap($v)
           Returns the result of wrapping the given vector in the box (hyper-cube) defined by $w.

           Long description:

           Given the vector "W" and the canonical base "U1, U2, ...Un" such that "W = w1*U1 +
           w2*U2 +...+ wn*Un". For every component "wi" we can consider the infinite set of
           affine hyperplanes perpendicular to "Ui" such that they contain the point "j * wi *
           Ui" being "j" an integer number.

           The combination of all the hyperplanes defined by every component define a grid that
           divides the space into an infinite set of affine hypercubes. Every hypercube can be
           identified by its lower corner indexes "j1, j2, ..., jN" or its lower corner point
           "j1*w1*U1 + j2*w2*U2 +...+ jn*wn*Un".

           Given the vector "V", wrapping it by "W" is equivalent to finding where it lays
           relative to the lower corner point of the hypercube inside the grid containing it:

             Wrapped = V - (j1*w1*U1 + j2*w2*U2 +...+ jn*wn*Un)

             such that ji*wi <= vi <  (ji+1)*wi

       $max = $v->max_component
           Returns the maximum of the absolute values of the vector components.

       $min = $v->min_component
           Returns the minimum of the absolute values of the vector components.

       $d2 = $b->norm2
           Returns the norm of the vector squared.

       $d = $v->dist($u)
           Returns the distance between the two vectors.

       $d = $v->dist2($u)
           Returns the distance between the two vectors squared.

       $d = $v->manhattan_norm
           Returns the norm of the vector calculated using the Manhattan metric.

       $d = $v->manhattan_dist($u)
           Returns the distance between the two vectors using the Manhattan metric.

       $d = $v->chebyshev_norm
           Returns the norm of the vector calculated using the Chebyshev metric (note that this
           method is an alias for "max_component".

       $d = $v->chebyshev_dist($u)
           Returns the distance between the two vectors using the Chebyshev metric.

       ($bottom, $top) = Math::Vector::Real->box($v0, $v1, $v2, ...)
           Returns the two corners of the axis-aligned minimum bounding box
           <http://en.wikipedia.org/wiki/Minimum_bounding_box#Axis-aligned_minimum_bounding_box>
           (or hyperrectangle <http://en.wikipedia.org/wiki/Hyperrectangle>) for the given
           vectors.

           In scalar context returns the difference between the two corners (the box diagonal
           vector).

       $p = $v->nearest_in_box($w0, $w1, ...)
           Returns the vector nearest to $v from the axis-aligned minimum box bounding the given
           set of vectors.

           For instance, given a point $v and an axis-aligned rectangle defined by two opposite
           corners ($c0 and $c1), this method can be used to find the point nearest to $v from
           inside the rectangle:

             my $n = $v->nearest_in_box($c0, $c1);

           Note that if $v lays inside the box, the nearest point is $v itself. Otherwise it will
           be a point from the box hyper-surface.

       $d2 = $v->dist2_to_box($w0, $w1, ...)
           Calculates the square of the minimal distance between the vector $v and the minimal
           axis-aligned box containing all the vectors "($w0, $w1, ...)".

       $d2 = $v->max_dist2_to_box($w0, $w1, ...)
           Calculates the square of the maximum distance between the vector $v and the minimal
           axis-aligned box containing all the vectors "($w0, $w1, ...)".

       $d = $v->chebyshev_dist_to_box($w0, $w1, ...)
           Calculates the minimal distance between the vector $v and the minimal axis-aligned box
           containing all the vectors "($w0, $w1, ...)"  using the Chebyshev metric.

       $d2 = Math::Vector::Real->dist2_between_boxes($a0, $a1, $b0, $b1)
           Returns the square of the minimum distance between any two points belonging to the
           boxes defined by "($a0, $a1)" and "($b0, $b1)" respectively.

       $d2 = Math::Vector::Real->max_dist2_between_boxes($a0, $a1, $b0, $b1)
           Returns the square of the maximum distance between any two points belonging
           respectively to the boxes defined by "($a0, $a1)" and "($b0, $b1)".

       $d2 = $v->dist2_to_segment($a0, $a1)
           Returns the square of the minimum distance between the given point $v and the line
           segment defined by the vertices $a0 and $a1.

       $d2 = Math::Vector::Real->dist2_between_segments($a0, $a1, $b0, $b1)
           Returns the square of the distance between the line segment defined by the vertices
           $a0 and $a1 and the one defined by the vertices $b0 and $b1.

           Degenerated cases where the length of any segment is (too close to) 0 are not
           supported.

       $v->set($u)
           Equivalent to "$v = $u" but without allocating a new object.

           Note that this method is destructive.

       $d = $v->max_component_index
           Returns the index of the vector component with the maximum size.

       $r = $v->first_orthant_reflection
           Given the set of vectors formed by $v and all its reflections around the axis-aligned
           hyperplanes, this method returns the one lying on the first orthant.

           See also [http://en.wikipedia.org/wiki/Reflection_%28mathematics%29|reflection] and
           [http://en.wikipedia.org/wiki/Orthant|orthant].

       ($p, $n) = $v->decompose($u)
           Decompose the given vector $u in two vectors: one parallel to $v and another normal.

           In scalar context returns the normal vector.

       $v = Math::Vector::Real->sum(@v)
           Returns the sum of all the given vectors.

       @b = Math::Vector::Real->complementary_base(@v)
           Returns a base for the subspace complementary to the one defined by the base @v.

           The vectors on @v must be linearly independent. Otherwise a division by zero error may
           pop up or probably due to rounding errors, just a wrong result may be generated.

       @b = $v->normal_base
           Returns a set of vectors forming an orthonormal base for the hyperplane normal to $v.

           In scalar context returns just some unitary vector normal to $v.

           Note that this two expressions are equivalent:

             @b = $v->normal_base;
             @b = Math::Vector::Real->complementary_base($v);

       ($i, $j, $k) = $v->rotation_base_3d
           Given a 3D vector, returns a list of 3 vectors forming an orthonormal base where $i
           has the same direction as the given vector $v and "$k = $i x $j".

       @r = $v->rotate_3d($angle, @s)
           Returns the vectors @u rotated around the vector $v an angle $angle in radians in
           anticlockwise direction.

           See <http://en.wikipedia.org/wiki/Rotation_operator_(vector_space)>.

       @s = $center->select_in_ball($radius, $v1, $v2, $v3, ...)
           Selects from the list of given vectors those that lay inside the n-ball determined by
           the given radius and center ($radius and $center respectively).

   Zero vector handling
       Passing the zero vector to some methods (i.e. "versor", "decompose", "normal_base", etc.)
       is not acceptable. In those cases, the module will croak with an "Illegal division by
       zero" error.

       "atan2" is an exceptional case that will return 0 when any of its arguments is the zero
       vector (for consistency with the "atan2" builtin operating over real numbers).

       In any case note that, in practice, rounding errors frequently cause the check for the
       zero vector to fail resulting in numerical instabilities.

       The correct way to handle this problem is to introduce in your code checks of this kind:

         if ($v->norm2 < $epsilon2) {
           croak "$v is too small";
         }

       Or even better, reorder the operations to minimize the chance of instabilities if the
       algorithm allows it.

   Math::Vector::Real::XS
       The module Math::Vector::Real::XS reimplements most of the methods available from this
       module in XS. "Math::Vector::Real" automatically loads and uses it when it is available.

SEE ALSO

       Math::Vector::Real::Random extends this module with random vector generation methods.

       Math::GSL::Vector, PDL.

       There are other vector manipulation packages in CPAN (Math::Vec, Math::VectorReal,
       Math::Vector), but they can only handle 3 dimensional vectors.

SUPPORT

       In order to report bugs you can send me and email to the address that appears below or use
       the CPAN RT bug-tracking system available at <http://rt.cpan.org>.

       The source for the development version of the module is hosted at GitHub:
       <https://github.com/salva/p5-Math-Vector-Real>.

   My wishlist
       If you like this module and you're feeling generous, take a look at my wishlist:
       <http://amzn.com/w/1WU1P6IR5QZ42>

COPYRIGHT AND LICENSE

       Copyright (C) 2009-2012, 2014-2017 by Salvador FandiƱo (sfandino@yahoo.com)

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of
       Perl 5 you may have available.