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];
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
- Returns the maximum of the absolute values of the vector
components.
- $min = $v->min
- Returns the minimum of the absolute values of the vector
components.
- $d2 = $b->abs2
- 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.
- ($bottom, $top) = Math::Vector::Real->box($v0, $v1, $v2,
...)
- Returns the two corners of a hyper-box containing all the
given vectors.
- $v->set($u)
- Equivalent to "$v = $u" but without allocating a
new object.
Note that this method is destructive.
- $d = $v->max_component_index
- Return the index of the vector component with the maximum
size.
- ($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.
- @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 ortonormal 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)>.
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 a "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 almost always cause the
check for the zero vector to fail resulting in numerical instabilities.
The correct way to handle it is to introduce in your code checks of this kind:
if ($v->abs2 < $epsilon2) {
croak "$v is too small";
}
Or even better, reorder the operations to minimize the chance of instabilities
if the algorithm allows it.
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.
COPYRIGHT AND LICENSE¶
Copyright (C) 2009-2012 by Salvador Fandin~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.