NAME
Numeric::Vector - SIMD-accelerated numeric vectors
SYNOPSIS
# OO interface
use Numeric::Vector;
my $v = Numeric::Vector::new([1..8]);
my $w = Numeric::Vector::ones(8);
my $sum = $v->sum;
my $dot = $v->dot($w);
my $norm = $v->norm;
my $added = $v->add($w); # or $v + $w
my $scaled = $v->scale(2.5); # or $v * 2.5
$v->add_inplace($w); # $v += $w in-place
print $v->simd_info, "\n";
# Functional interface — import specific functions as nvec_*
use Numeric::Vector qw(new ones sum add dot);
my $v = nvec_new([1..8]);
my $w = nvec_ones(8);
my $s = nvec_sum($v);
my $r = nvec_add($v, $w);DESCRIPTION
Numeric::Vector provides SIMD-accelerated numeric vectors for Perl. It automatically selects the best available instruction set at compile time: ARM NEON, x86 AVX2, AVX, SSE2, or a plain scalar fallback. All vectors store double-precision (64-bit) floating-point values.
Overloaded operators (+, -, *, /), in-place variants (+=, -=, *=, /=), unary negation, abs, and string interpolation are all supported.
IMPORTING
By default use Numeric::Vector exports nothing. Pass a list of method names to import them as nvec_* functions into the current package:
use Numeric::Vector qw(new zeros ones fill sum mean add mul scale dot norm);
my $v = nvec_new([1..1000]);
my $w = nvec_zeros(1000);
nvec_add($v, $w); # same as $v->add($w)
my $s = nvec_sum($v); # same as $v->sumEvery name in the import list corresponds to an existing method. Requesting an unknown name is a compile-time error:
use Numeric::Vector qw(frobnicate); # dies: unknown function 'frobnicate'The import mechanism is implemented entirely in XS and installs true subroutine aliases (not wrappers), so there is no call overhead beyond the XS dispatch that would occur anyway.
CONSTRUCTORS
new
my $v = Numeric::Vector::new(\@array);Create a vector from an arrayref of numbers.
zeros
my $v = Numeric::Vector::zeros($n);Create a vector of $n zeros.
ones
my $v = Numeric::Vector::ones($n);Create a vector of $n ones.
fill
my $v = Numeric::Vector::fill($n, $value);Create a vector of $n elements all set to $value.
range
my $v = Numeric::Vector::range($start, $stop);
my $v = Numeric::Vector::range($start, $stop, $step);Create a vector of evenly-spaced values from $start up to (but not including) $stop, advancing by $step (default 1).
linspace
my $v = Numeric::Vector::linspace($start, $stop, $n);Create a vector of $n evenly-spaced values between $start and $stop inclusive.
random
my $v = Numeric::Vector::random($n);Create a vector of $n uniform random values in [0, 1).
ELEMENT ACCESS
get
my $val = $v->get($index);Return the element at $index. Croaks if out of bounds.
set
$v->set($index, $value);Set the element at $index to $value. Croaks if out of bounds or if the vector is read-only.
len
my $n = $v->len;Return the number of elements.
to_array
my $aref = $v->to_array;Return a new Perl arrayref containing all elements.
copy
my $w = $v->copy;Return a deep copy of the vector.
slice
my $w = $v->slice($from, $to);Return a new vector containing elements at indices $from through $to inclusive.
fill_range
$v->fill_range($start, $len, $value);Set $len consecutive elements starting at $start to $value. Negative $start counts from the end. Modifies in-place.
ARITHMETIC
All arithmetic methods return a new vector and leave the original unchanged unless the method name ends in _inplace.
add
my $c = $a->add($b); # or $a + $bElement-wise addition. Vectors must have the same length.
sub
my $c = $a->sub($b); # or $a - $bElement-wise subtraction. Vectors must have the same length.
mul
my $c = $a->mul($b); # or $a * $b (vector * vector)Element-wise multiplication. Vectors must have the same length.
div
my $c = $a->div($b); # or $a / $bElement-wise division. Vectors must have the same length.
scale
my $c = $v->scale($scalar); # or $v * $scalarMultiply every element by $scalar.
add_scalar
my $c = $v->add_scalar($scalar);Add $scalar to every element.
pow
my $c = $v->pow($exp);Raise every element to the power $exp.
neg
my $c = $v->neg; # or -$vNegate every element.
abs
my $c = $v->abs; # or abs($v)Absolute value of every element.
axpy
$y->axpy($a, $x); # y = a*x + y (in-place)Scale $x by the scalar $a and add to $y in-place (classic BLAS DAXPY operation). $x and $y must have the same length.
IN-PLACE ARITHMETIC
These methods mutate the vector and return $self.
add_inplace
$a->add_inplace($b); # or $a += $bElement-wise addition in-place.
sub_inplace
$a->sub_inplace($b); # or $a -= $bElement-wise subtraction in-place.
mul_inplace
$a->mul_inplace($b); # or $a *= $b (vector * vector)Element-wise multiplication in-place.
div_inplace
$a->div_inplace($b); # or $a /= $bElement-wise division in-place.
scale_inplace
$v->scale_inplace($scalar); # or $v *= $scalarMultiply every element by $scalar in-place.
add_scalar_inplace
$v->add_scalar_inplace($scalar);Add $scalar to every element in-place.
clamp_inplace
$v->clamp_inplace($min, $max);Clamp every element to [$min, $max] in-place.
fma_inplace
$c->fma_inplace($a, $b); # c = a*b + c (in-place)Fused multiply-add: multiply corresponding elements of $a and $b and add the result to $c in-place. All three vectors must have the same length.
MATH FUNCTIONS
Each method returns a new vector with the function applied element-wise.
sqrt
my $c = $v->sqrt;exp
my $c = $v->exp;log
my $c = $v->log;Natural logarithm.
log10
my $c = $v->log10;log2
my $c = $v->log2;floor
my $c = $v->floor;ceil
my $c = $v->ceil;round
my $c = $v->round;Round to the nearest integer (half-up).
sign
my $c = $v->sign;Returns -1.0, 0.0, or 1.0 for each element.
clip
my $c = $v->clip($min, $max);Return a new vector with each element clamped to [$min, $max].
TRIGONOMETRY
sin
my $c = $v->sin;cos
my $c = $v->cos;tan
my $c = $v->tan;asin
my $c = $v->asin;acos
my $c = $v->acos;atan
my $c = $v->atan;sinh
my $c = $v->sinh;cosh
my $c = $v->cosh;tanh
my $c = $v->tanh;REDUCTIONS
sum
my $s = $v->sum;Sum of all elements.
product
my $p = $v->product;Product of all elements.
mean
my $m = $v->mean;Arithmetic mean.
variance
my $var = $v->variance;Population variance (divides by N).
std
my $sd = $v->std;Population standard deviation (square root of variance).
median
my $med = $v->median;Median value. Does not modify the vector.
min
my $m = $v->min;Minimum element value.
max
my $m = $v->max;Maximum element value.
argmin
my $idx = $v->argmin;Index of the minimum element.
argmax
my $idx = $v->argmax;Index of the maximum element.
dot
my $d = $a->dot($b);Dot (inner) product. Vectors must have the same length.
norm
my $n = $v->norm;L2 (Euclidean) norm: sqrt(sum(x_i^2)).
normalize
my $u = $v->normalize;Return a unit vector (L2 norm = 1). Returns a zero vector if the norm is zero.
distance
my $d = $a->distance($b);Euclidean distance between two vectors. Vectors must have the same length.
cosine_similarity
my $sim = $a->cosine_similarity($b);Cosine similarity in [-1, 1]. Returns 0 if either vector has zero norm. Vectors must have the same length.
COMPARISONS
Each method returns a new vector of 0.0/1.0 values.
eq
my $mask = $a->eq($b);Element-wise ==. Returns 1.0 where equal, 0.0 elsewhere.
ne
my $mask = $a->ne($b);Element-wise !=. Returns 1.0 where not equal.
lt
my $mask = $a->lt($b);Element-wise <.
le
my $mask = $a->le($b);Element-wise <=.
gt
my $mask = $a->gt($b);Element-wise >.
ge
my $mask = $a->ge($b);Element-wise >=.
BOOLEAN REDUCTIONS
any
my $bool = $v->any;Returns true if any element is non-zero.
all
my $bool = $v->all;Returns true if all elements are non-zero.
count
my $n = $v->count;Count of non-zero elements.
PREDICATES
isnan
my $mask = $v->isnan;Returns a vector of 1.0 where the element is NaN, 0.0 elsewhere.
isinf
my $mask = $v->isinf;Returns a vector of 1.0 where the element is infinite, 0.0 elsewhere.
isfinite
my $mask = $v->isfinite;Returns a vector of 1.0 where the element is finite (not NaN or Inf), 0.0 elsewhere.
SELECTION AND TRANSFORMATION
where
my $w = $v->where($mask);Return a new vector containing only the elements of $v where the corresponding element of $mask is non-zero.
concat
my $w = $a->concat($b);Return a new vector that is the concatenation of $a and $b.
reverse
my $w = $v->reverse;Return a new vector with elements in reverse order.
sort
my $w = $v->sort;Return a new vector with elements sorted in ascending order.
argsort
my $idx = $v->argsort;Return a vector of indices that would sort the vector in ascending order.
cumsum
my $w = $v->cumsum;Return a new vector of cumulative sums.
cumprod
my $w = $v->cumprod;Return a new vector of cumulative products.
diff
my $w = $v->diff;Return a new vector of first differences (v[i+1] - v[i]). The result has length len - 1; returns an empty vector if len < 2.
DIAGNOSTICS
simd_info
print $v->simd_info;Returns a string describing the SIMD instruction set compiled in (e.g. "AVX2", "NEON", "scalar").
OVERLOADED OPERATORS
$a + $b # add (vector+vector or vector+scalar)
$a - $b # sub
$a * $b # mul (vector*vector or vector*scalar)
$a / $b # div
$a += $b # add_inplace
$a -= $b # sub_inplace
$a *= $b # mul_inplace
$a /= $b # div_inplace
-$v # neg
abs($v) # abs
"$v" # stringify (space-separated values)
$a == $b # true if all elements equal (scalar bool)
$a != $b # true if any elements differ (scalar bool)AUTHOR
LNATION <email@lnation.org>
LICENSE AND COPYRIGHT
Copyright 2026 LNATION.
This software is licensed under the Artistic License 2.0.