Vector — Numeric Vector

Overview

Vector<T> is the dynamic-size numeric vector template class in sangi. StaticVector<T,N> is the compile-time fixed-size variant. Both are header-only and require no additional library linking.

• Expression templates — Expressions such as a + 2.0 * b produce no intermediate objects and are evaluated in a single loop at the point of assignment
• SIMD auto-vectorization — SIMD packet evaluation via PacketTraits<T> (SSE/AVX2). 4-accumulator unrolling maximizes memory bandwidth
• Block operations — Zero-copy views via head, tail, segment (Eigen-style)
• BLAS Level-1 fused — axpy and axpby execute in a single loop
• VectorMap — Zero-copy view over external memory (equivalent to Eigen::Map)

Header

#include <math/core/vector.hpp>

Header-only. No library linking required.

Class Summary

All reside in namespace sangi. Both Vector and StaticVector inherit from VecExpr<Derived> (CRTP) and participate in expression templates.

Vector<T> Class

Constructors

Vector<double> v1;                        // Empty vector
Vector<double> v2(5);                     // Size 5, zero-initialized
Vector<double> v3(5, 1.0);               // Size 5, all elements 1.0
Vector<double> v4{1.0, 2.0, 3.0};        // Initializer list

Element Access

Vector<double> v{10, 20, 30};
double a = v[0];      // 10 (Debug-only assert bounds check)
double b = v.at(1);   // 20 (exception-based bounds check)
v[2] = 99;            // Assignment

Iterators

Capacity

Arithmetic Operations

Vector<double> a{1, 2, 3}, b{4, 5, 6};
Vector<double> c = a + b;        // Prefer explicit Vector over auto to force ET evaluation
Vector<double> d = a - b;
Vector<double> e = 2.0 * a;
Vector<double> f = a / 2.0;
// Run output:
//   c = {5, 7, 9}
//   d = {-3, -3, -3}
//   e = {2, 4, 6}
//   f = {0.5, 1, 1.5}

Expression Template Operations

The following binary operators return expression template nodes and are evaluated in bulk at the point of assignment. No intermediate Vector is created.

Vector<double> a{1, 2, 3}, b{4, 5, 6}, c{7, 8, 9};
// Evaluated without intermediate buffers (expression templates)
Vector<double> result = 2.0 * a + b - 0.5 * c;

Dot Product / Norms

Vector<double> a{1, 2, 3}, b{4, 5, 6};
double d  = dot(a, b);
double n  = norm(a);
double n1 = norm_l1(a);
double ni = norm_linf(a);
double n3 = norm_lp(a, 3.0);
// Run output:
//   dot(a,b)     = 32
//   norm(a)      = 3.74165738677394   (= sqrt(14), 15 digits)
//   norm_l1(a)   = 6
//   norm_linf(a) = 3
//   norm_lp(a,3) = 3.30192724889463   (= (1+8+27)^(1/3) = 36^(1/3))

Normalization

Vector<double> v{3, 4};
auto u = normalized(v);
// Run output: u = {0.6, 0.8}, norm(u) = 1 (unit vector)

Block Operations

Returns zero-copy views (VectorView / ConstVectorView). Writes through the view are reflected in the original vector.

Vector<double> v{10, 20, 30, 40, 50};
auto h = v.head(2);          // zero-copy view
auto t = v.tail(2);
auto s = v.segment(1, 3);
// Run output: head(2)={10, 20}, tail(2)={40, 50}, segment(1,3)={20, 30, 40}
// Note: writing through a view (e.g. s[0] = 99) also modifies the original v

Miscellaneous

StaticVector<T,N> Class

A compile-time fixed-size vector. Internal storage is std::array<T,N>. No heap allocation, ideal for small vectors (3D coordinates, quaternions, etc.).

Constructors

API

Provides the same interface as Vector<T>.

• Element access: operator[], at, data
• Iterators: begin, end, cbegin, cend
• Capacity: size() (constexpr), empty()
• Arithmetic: +=, -=, *=, /= (vector-vector + scalar + expression template)
• Dot product / Norms: dot, norm, norm_l1, norm_linf, norm_lp
• Normalization: normalized, normalize
• Block operations: head, tail, segment
• Miscellaneous: zero()

size() is constexpr, so the size is determined at compile time. capacity, reserve, resize, shrink_to_fit, and clear are not provided.

Free Functions

The following free functions work with both Vector<T> and StaticVector<T,N>.

Dot Product / Norms

norm and norm2 also accept VecExpr<E> (expression template nodes) directly, computing the norm via packet evaluation without materialization.

Cross Product

StaticVector<double, 3> i{1, 0, 0}, j{0, 1, 0};
auto k = cross(i, j);
// Run output: k = {0, 0, 1} (= z axis unit vector)
// Right-handed: cross(x, y) = z (i × j = k)

BLAS Level-1 Fused Functions

No temporary objects are created; processing is done in a single loop. The compiler's SIMD auto-vectorization is effective.

axpy and axpby have overloads for both Vector<T> and StaticVector<T,N>.

Vector<double> x{1, 2, 3}, y{10, 20, 30};
axpy(2.0, x, y);            // y += 2*x
// Run output: y = {12, 24, 36}

Vector<double> a{1, 2, 3}, b{4, 5, 6}, r(3);
axpby(2.0, a, 3.0, b, r);   // r = 2a + 3b
// Run output: r = {14, 19, 24}

VectorMap / ConstVectorMap

View classes that wrap external contiguous memory as a vector without copying. Equivalent to Eigen::Map.

VectorMap<T>

ConstVectorMap<T>

double raw[] = {1.0, 2.0, 3.0};
sangi::VectorMap<double> v(raw, 3);
v[1] = 5.0;
// Run output: raw[1] is overwritten to 5.0 (write-through to original buffer)

double data[] = {1, 2, 3, 4, 5};
ConstVectorMap<double> view(data, 5);   // read-only zero-copy view
// Note: dot() does not accept ConstVectorMap directly; convert to Vector first:
Vector<double> view_vec = view;          // implicit conversion copies
double s = dot(view_vec, view_vec);
// Run output: s = 55 (= 1+4+9+16+25)

Usage Examples

#include <math/core/vector.hpp>
#include <iostream>
using namespace sangi;

int main() {
    // Constructors
    Vector<double> a{1.0, 2.0, 3.0};
    Vector<double> b{4.0, 5.0, 6.0};

    // Expression templates — no intermediate objects
    Vector<double> c = a + 2.0 * b;  // {9, 12, 15}

    // Dot product / Norms
    std::cout << "dot(a,b) = " << dot(a, b) << std::endl;
    std::cout << "norm(a)  = " << norm(a) << std::endl;
    std::cout << "norm_l1  = " << norm_l1(a) << std::endl;
    std::cout << "norm_inf = " << norm_linf(a) << std::endl;
    // Output: dot=32, norm=3.74165738677394 (=sqrt(14)), norm_l1=6, norm_inf=3

    // Normalization
    Vector<double> u = normalized(a);
    std::cout << "norm(normalized(a)) = " << norm(u) << std::endl;
    // Output: 1 (unit vector after normalization)

    // StaticVector + cross product
    StaticVector<double, 3> xv{1.0, 0.0, 0.0};
    StaticVector<double, 3> yv{0.0, 1.0, 0.0};
    auto z = cross(xv, yv);
    std::cout << "cross = [" << z[0] << ", " << z[1] << ", " << z[2] << "]" << std::endl;
    // Output: cross = [0, 0, 1]

    // Block operations
    Vector<double> v{10.0, 20.0, 30.0, 40.0, 50.0};
    auto h = v.head(3);       // zero-copy view
    auto t = v.tail(2);
    auto s = v.segment(1, 3);
    // View contents: head={10,20,30}, tail={40,50}, segment={20,30,40}

    // BLAS Level-1
    Vector<double> p{1.0, 2.0, 3.0};
    Vector<double> q{4.0, 5.0, 6.0};
    axpy(2.0, p, q);  // q += 2*p
    // Output: q = {6, 9, 12}

    // VectorMap (external memory view)
    double raw[] = {1.0, 2.0, 3.0};
    VectorMap<double> map(raw, 3);
    map[0] = 99.0;
    // Output: raw[0] = 99.0 (write-back to the original buffer)
}