.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Math::Vector::Real 3pm"
.TH Math::Vector::Real 3pm "2022-10-22" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Math::Vector::Real \- Real vector arithmetic in Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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\en", $v, abs($b);
\&  my $dot = $u * $v;
\&  my $sub = $u \- $v;
\&  # etc...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A simple pure perl module to manipulate vectors of any dimension.
.PP
The function \f(CW\*(C`V\*(C'\fR, always exported by the module, allows one to create
new vectors:
.PP
.Vb 1
\&  my $v = V(0, 1, 3, \-1);
.Ve
.PP
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).
.PP
Example:
.PP
.Vb 1
\&  my $v = V(0.0, 1.0);
\&
\&  # extending the 2D vector to 3D:
\&  push @$v, 0.0;
\&
\&  # setting some component value:
\&  $v\->[0] = 23;
.Ve
.PP
Vectors can be used in mathematical expressions:
.PP
.Vb 5
\&  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.
.Ve
.PP
The currently supported operations are:
.PP
.Vb 8
\&  + * /
\&  \- (both unary and binary)
\&  x (cross product for 3D vectors)
\&  += \-= *= /= x=
\&  == !=
\&  "" (stringfication)
\&  abs (returns the norm)
\&  atan2 (returns the angle between two vectors)
.Ve
.PP
That, \s-1AFAIK,\s0 are all the operations that can be applied to vectors.
.PP
When an array reference is used in an operation involving a vector, it
is automatically upgraded to a vector. For instance:
.PP
.Vb 2
\&  my $v = V(1, 2);
\&  $v += [0, 2];
.Ve
.SS "Extra methods"
.IX Subsection "Extra methods"
Besides the common mathematical operations described above, the
following methods are available from the package.
.PP
Note that all these methods are non destructive returning new objects
with the result.
.ie n .IP "$v = Math::Vector::Real\->new(@components)" 4
.el .IP "\f(CW$v\fR = Math::Vector::Real\->new(@components)" 4
.IX Item "$v = Math::Vector::Real->new(@components)"
Equivalent to \f(CW\*(C`V(@components)\*(C'\fR.
.ie n .IP "$zero = Math::Vector::Real\->zero($dim)" 4
.el .IP "\f(CW$zero\fR = Math::Vector::Real\->zero($dim)" 4
.IX Item "$zero = Math::Vector::Real->zero($dim)"
Returns the zero vector of the given dimension.
.ie n .IP "$v = Math::Vector::Real\->cube($dim, $size)" 4
.el .IP "\f(CW$v\fR = Math::Vector::Real\->cube($dim, \f(CW$size\fR)" 4
.IX Item "$v = Math::Vector::Real->cube($dim, $size)"
Returns a vector of the given dimension with all its components set to
\&\f(CW$size\fR.
.ie n .IP "$u = Math::Vector::Real\->axis_versor($dim, $ix)" 4
.el .IP "\f(CW$u\fR = Math::Vector::Real\->axis_versor($dim, \f(CW$ix\fR)" 4
.IX Item "$u = Math::Vector::Real->axis_versor($dim, $ix)"
Returns a unitary vector of the given dimension parallel to the axis
with index \f(CW$ix\fR (0\-based).
.Sp
For instance:
.Sp
.Vb 2
\&  Math::Vector::Real\->axis_versor(5, 3); # V(0, 0, 0, 1, 0)
\&  Math::Vector::Real\->axis_versor(2, 0); # V(1, 0)
.Ve
.ie n .IP "@b = Math::Vector::Real\->canonical_base($dim)" 4
.el .IP "\f(CW@b\fR = Math::Vector::Real\->canonical_base($dim)" 4
.IX Item "@b = Math::Vector::Real->canonical_base($dim)"
Returns the canonical base for the vector space of the given
dimension.
.ie n .IP "$u = $v\->versor" 4
.el .IP "\f(CW$u\fR = \f(CW$v\fR\->versor" 4
.IX Item "$u = $v->versor"
Returns the versor for the given vector.
.Sp
It is equivalent to:
.Sp
.Vb 1
\&  $u = $v / abs($v);
.Ve
.ie n .IP "$wrapped = $w\->wrap($v)" 4
.el .IP "\f(CW$wrapped\fR = \f(CW$w\fR\->wrap($v)" 4
.IX Item "$wrapped = $w->wrap($v)"
Returns the result of wrapping the given vector in the box
(hyper-cube) defined by \f(CW$w\fR.
.Sp
Long description:
.Sp
Given the vector \f(CW\*(C`W\*(C'\fR and the canonical base \f(CW\*(C`U1, U2, ...Un\*(C'\fR such
that \f(CW\*(C`W = w1*U1 + w2*U2 +...+ wn*Un\*(C'\fR. For every component \f(CW\*(C`wi\*(C'\fR we
can consider the infinite set of affine hyperplanes perpendicular to
\&\f(CW\*(C`Ui\*(C'\fR such that they contain the point \f(CW\*(C`j * wi * Ui\*(C'\fR being \f(CW\*(C`j\*(C'\fR an
integer number.
.Sp
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 \f(CW\*(C`j1, j2, ..., jN\*(C'\fR or its lower corner point \f(CW\*(C`j1*w1*U1 +
j2*w2*U2 +...+ jn*wn*Un\*(C'\fR.
.Sp
Given the vector \f(CW\*(C`V\*(C'\fR, wrapping it by \f(CW\*(C`W\*(C'\fR is equivalent to finding
where it lays relative to the lower corner point of the hypercube
inside the grid containing it:
.Sp
.Vb 1
\&  Wrapped = V \- (j1*w1*U1 + j2*w2*U2 +...+ jn*wn*Un)
\&
\&  such that ji*wi <= vi <  (ji+1)*wi
.Ve
.ie n .IP "$max = $v\->max_component" 4
.el .IP "\f(CW$max\fR = \f(CW$v\fR\->max_component" 4
.IX Item "$max = $v->max_component"
Returns the maximum of the absolute values of the vector components.
.ie n .IP "$min = $v\->min_component" 4
.el .IP "\f(CW$min\fR = \f(CW$v\fR\->min_component" 4
.IX Item "$min = $v->min_component"
Returns the minimum of the absolute values of the vector components.
.ie n .IP "$d2 = $b\->norm2" 4
.el .IP "\f(CW$d2\fR = \f(CW$b\fR\->norm2" 4
.IX Item "$d2 = $b->norm2"
Returns the norm of the vector squared.
.ie n .IP "$d = $v\->dist($u)" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->dist($u)" 4
.IX Item "$d = $v->dist($u)"
Returns the distance between the two vectors.
.ie n .IP "$d = $v\->dist2($u)" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->dist2($u)" 4
.IX Item "$d = $v->dist2($u)"
Returns the distance between the two vectors squared.
.ie n .IP "$d = $v\->manhattan_norm" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->manhattan_norm" 4
.IX Item "$d = $v->manhattan_norm"
Returns the norm of the vector calculated using the Manhattan metric.
.ie n .IP "$d = $v\->manhattan_dist($u)" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->manhattan_dist($u)" 4
.IX Item "$d = $v->manhattan_dist($u)"
Returns the distance between the two vectors using the Manhattan metric.
.ie n .IP "$d = $v\->chebyshev_norm" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->chebyshev_norm" 4
.IX Item "$d = $v->chebyshev_norm"
Returns the norm of the vector calculated using the Chebyshev metric
(note that this method is an alias for \f(CW\*(C`max_component\*(C'\fR.
.ie n .IP "$d = $v\->chebyshev_dist($u)" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->chebyshev_dist($u)" 4
.IX Item "$d = $v->chebyshev_dist($u)"
Returns the distance between the two vectors using the Chebyshev metric.
.ie n .IP "($bottom, $top) = Math::Vector::Real\->box($v0, $v1, $v2, ...)" 4
.el .IP "($bottom, \f(CW$top\fR) = Math::Vector::Real\->box($v0, \f(CW$v1\fR, \f(CW$v2\fR, ...)" 4
.IX Item "($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.
.Sp
In scalar context returns the difference between the two corners (the
box diagonal vector).
.ie n .IP "$p = $v\->nearest_in_box($w0, $w1, ...)" 4
.el .IP "\f(CW$p\fR = \f(CW$v\fR\->nearest_in_box($w0, \f(CW$w1\fR, ...)" 4
.IX Item "$p = $v->nearest_in_box($w0, $w1, ...)"
Returns the vector nearest to \f(CW$v\fR from the axis-aligned minimum box
bounding the given set of vectors.
.Sp
For instance, given a point \f(CW$v\fR and an axis-aligned rectangle
defined by two opposite corners (\f(CW$c0\fR and \f(CW$c1\fR), this method can be
used to find the point nearest to \f(CW$v\fR from inside the rectangle:
.Sp
.Vb 1
\&  my $n = $v\->nearest_in_box($c0, $c1);
.Ve
.Sp
Note that if \f(CW$v\fR lays inside the box, the nearest point is \f(CW$v\fR
itself. Otherwise it will be a point from the box hyper-surface.
.ie n .IP "$d2 = $v\->dist2_to_box($w0, $w1, ...)" 4
.el .IP "\f(CW$d2\fR = \f(CW$v\fR\->dist2_to_box($w0, \f(CW$w1\fR, ...)" 4
.IX Item "$d2 = $v->dist2_to_box($w0, $w1, ...)"
Calculates the square of the minimal distance between the vector \f(CW$v\fR
and the minimal axis-aligned box containing all the vectors \f(CW\*(C`($w0,
$w1, ...)\*(C'\fR.
.ie n .IP "$d2 = $v\->max_dist2_to_box($w0, $w1, ...)" 4
.el .IP "\f(CW$d2\fR = \f(CW$v\fR\->max_dist2_to_box($w0, \f(CW$w1\fR, ...)" 4
.IX Item "$d2 = $v->max_dist2_to_box($w0, $w1, ...)"
Calculates the square of the maximum distance between the vector \f(CW$v\fR
and the minimal axis-aligned box containing all the vectors \f(CW\*(C`($w0,
$w1, ...)\*(C'\fR.
.ie n .IP "$d = $v\->chebyshev_dist_to_box($w0, $w1, ...)" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->chebyshev_dist_to_box($w0, \f(CW$w1\fR, ...)" 4
.IX Item "$d = $v->chebyshev_dist_to_box($w0, $w1, ...)"
Calculates the minimal distance between the vector \f(CW$v\fR and the
minimal axis-aligned box containing all the vectors \f(CW\*(C`($w0, $w1, ...)\*(C'\fR
using the Chebyshev metric.
.ie n .IP "$d2 = Math::Vector::Real\->dist2_between_boxes($a0, $a1, $b0, $b1)" 4
.el .IP "\f(CW$d2\fR = Math::Vector::Real\->dist2_between_boxes($a0, \f(CW$a1\fR, \f(CW$b0\fR, \f(CW$b1\fR)" 4
.IX Item "$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 \f(CW\*(C`($a0, $a1)\*(C'\fR and
\&\f(CW\*(C`($b0, $b1)\*(C'\fR respectively.
.ie n .IP "$d2 = Math::Vector::Real\->max_dist2_between_boxes($a0, $a1, $b0, $b1)" 4
.el .IP "\f(CW$d2\fR = Math::Vector::Real\->max_dist2_between_boxes($a0, \f(CW$a1\fR, \f(CW$b0\fR, \f(CW$b1\fR)" 4
.IX Item "$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 \f(CW\*(C`($a0, $a1)\*(C'\fR and
\&\f(CW\*(C`($b0, $b1)\*(C'\fR.
.ie n .IP "$d2 = $v\->dist2_to_segment($a0, $a1)" 4
.el .IP "\f(CW$d2\fR = \f(CW$v\fR\->dist2_to_segment($a0, \f(CW$a1\fR)" 4
.IX Item "$d2 = $v->dist2_to_segment($a0, $a1)"
Returns the square of the minimum distance between the given point
\&\f(CW$v\fR and the line segment defined by the vertices \f(CW$a0\fR and \f(CW$a1\fR.
.ie n .IP "$d2 = Math::Vector::Real\->dist2_between_segments($a0, $a1, $b0, $b1)" 4
.el .IP "\f(CW$d2\fR = Math::Vector::Real\->dist2_between_segments($a0, \f(CW$a1\fR, \f(CW$b0\fR, \f(CW$b1\fR)" 4
.IX Item "$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 \f(CW$a0\fR and \f(CW$a1\fR and the one defined by the vertices
\&\f(CW$b0\fR and \f(CW$b1\fR.
.Sp
Degenerated cases where the length of any segment is (too close to) 0
are not supported.
.ie n .IP "$v\->set($u)" 4
.el .IP "\f(CW$v\fR\->set($u)" 4
.IX Item "$v->set($u)"
Equivalent to \f(CW\*(C`$v = $u\*(C'\fR but without allocating a new object.
.Sp
Note that this method is destructive.
.ie n .IP "$d = $v\->max_component_index" 4
.el .IP "\f(CW$d\fR = \f(CW$v\fR\->max_component_index" 4
.IX Item "$d = $v->max_component_index"
Returns the index of the vector component with the maximum size.
.ie n .IP "$r = $v\->first_orthant_reflection" 4
.el .IP "\f(CW$r\fR = \f(CW$v\fR\->first_orthant_reflection" 4
.IX Item "$r = $v->first_orthant_reflection"
Given the set of vectors formed by \f(CW$v\fR and all its reflections
around the axis-aligned hyperplanes, this method returns the one lying
on the first orthant.
.Sp
See also
[http://en.wikipedia.org/wiki/Reflection_%28mathematics%29|reflection]
and [http://en.wikipedia.org/wiki/Orthant|orthant].
.ie n .IP "($p, $n) = $v\->decompose($u)" 4
.el .IP "($p, \f(CW$n\fR) = \f(CW$v\fR\->decompose($u)" 4
.IX Item "($p, $n) = $v->decompose($u)"
Decompose the given vector \f(CW$u\fR in two vectors: one parallel to \f(CW$v\fR
and another normal.
.Sp
In scalar context returns the normal vector.
.ie n .IP "$v = Math::Vector::Real\->sum(@v)" 4
.el .IP "\f(CW$v\fR = Math::Vector::Real\->sum(@v)" 4
.IX Item "$v = Math::Vector::Real->sum(@v)"
Returns the sum of all the given vectors.
.ie n .IP "@b = Math::Vector::Real\->complementary_base(@v)" 4
.el .IP "\f(CW@b\fR = Math::Vector::Real\->complementary_base(@v)" 4
.IX Item "@b = Math::Vector::Real->complementary_base(@v)"
Returns a base for the subspace complementary to the one defined by
the base \f(CW@v\fR.
.Sp
The vectors on \f(CW@v\fR 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.
.ie n .IP "@b = $v\->normal_base" 4
.el .IP "\f(CW@b\fR = \f(CW$v\fR\->normal_base" 4
.IX Item "@b = $v->normal_base"
Returns a set of vectors forming an orthonormal base for the hyperplane
normal to \f(CW$v\fR.
.Sp
In scalar context returns just some unitary vector normal to \f(CW$v\fR.
.Sp
Note that this two expressions are equivalent:
.Sp
.Vb 2
\&  @b = $v\->normal_base;
\&  @b = Math::Vector::Real\->complementary_base($v);
.Ve
.ie n .IP "($i, $j, $k) = $v\->rotation_base_3d" 4
.el .IP "($i, \f(CW$j\fR, \f(CW$k\fR) = \f(CW$v\fR\->rotation_base_3d" 4
.IX Item "($i, $j, $k) = $v->rotation_base_3d"
Given a 3D vector, returns a list of 3 vectors forming an orthonormal
base where \f(CW$i\fR has the same direction as the given vector \f(CW$v\fR and
\&\f(CW\*(C`$k = $i x $j\*(C'\fR.
.ie n .IP "@r = $v\->rotate_3d($angle, @s)" 4
.el .IP "\f(CW@r\fR = \f(CW$v\fR\->rotate_3d($angle, \f(CW@s\fR)" 4
.IX Item "@r = $v->rotate_3d($angle, @s)"
Returns the vectors \f(CW@u\fR rotated around the vector \f(CW$v\fR an
angle \f(CW$angle\fR in radians in anticlockwise direction.
.Sp
See <http://en.wikipedia.org/wiki/Rotation_operator_(vector_space)>.
.ie n .IP "@s = $center\->select_in_ball($radius, $v1, $v2, $v3, ...)" 4
.el .IP "\f(CW@s\fR = \f(CW$center\fR\->select_in_ball($radius, \f(CW$v1\fR, \f(CW$v2\fR, \f(CW$v3\fR, ...)" 4
.IX Item "@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 (\f(CW$radius\fR and
\&\f(CW$center\fR respectively).
.SS "Zero vector handling"
.IX Subsection "Zero vector handling"
Passing the zero vector to some methods (i.e. \f(CW\*(C`versor\*(C'\fR, \f(CW\*(C`decompose\*(C'\fR,
\&\f(CW\*(C`normal_base\*(C'\fR, etc.) is not acceptable. In those cases, the module
will croak with an \*(L"Illegal division by zero\*(R" error.
.PP
\&\f(CW\*(C`atan2\*(C'\fR is an exceptional case that will return 0 when any of its
arguments is the zero vector (for consistency with the \f(CW\*(C`atan2\*(C'\fR builtin
operating over real numbers).
.PP
In any case note that, in practice, rounding errors frequently cause
the check for the zero vector to fail resulting in numerical
instabilities.
.PP
The correct way to handle this problem is to introduce in your code
checks of this kind:
.PP
.Vb 3
\&  if ($v\->norm2 < $epsilon2) {
\&    croak "$v is too small";
\&  }
.Ve
.PP
Or even better, reorder the operations to minimize the chance of
instabilities if the algorithm allows it.
.SS "Math::Vector::Real::XS"
.IX Subsection "Math::Vector::Real::XS"
The module Math::Vector::Real::XS reimplements most of the methods
available from this module in \s-1XS.\s0 \f(CW\*(C`Math::Vector::Real\*(C'\fR automatically
loads and uses it when it is available.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Math::Vector::Real::Random extends this module with random vector
generation methods.
.PP
Math::GSL::Vector, \s-1PDL\s0.
.PP
There are other vector manipulation packages in \s-1CPAN\s0 (Math::Vec,
Math::VectorReal, Math::Vector), but they can only handle 3
dimensional vectors.
.SH "SUPPORT"
.IX Header "SUPPORT"
In order to report bugs you can send me and email to the address that
appears below or use the \s-1CPAN RT\s0 bug-tracking system available at
<http://rt.cpan.org>.
.PP
The source for the development version of the module is hosted at
GitHub: <https://github.com/salva/p5\-Math\-Vector\-Real>.
.SS "My wishlist"
.IX Subsection "My wishlist"
If you like this module and you're feeling generous, take a look at my
wishlist: <http://amzn.com/w/1WU1P6IR5QZ42>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2009\-2012, 2014\-2017 by Salvador Fandiño
(sfandino@yahoo.com)
.PP
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.