chrissimpkins / vectora

A Rust library for n-dimensional vector computation with real and complex scalar data

A Rust library for vector computation

Test Status

About

Vectora is a library for n-dimensional vector computation with real and complex scalar types. The main library entry point is the Vector struct. Please see the Gettting Started Guide for a detailed library API overview with examples.

User documentation

User documentation is available at https://docs.rs/vectora.

Minimum Rust Version Compatibility Policy

This project parameterizes generics by constants and relies on the constant generics feature support stabilized in Rust v1.51.0.

The minimum supported rustc version is believed to be v1.51.0.

Include Vectora in Your Project

Import the library in the [dependencies] section of your Cargo.toml file:

Cargo.toml

[dependencies]
vectora = "0.8.1"

Developer documentation

Contributing

Issues

The issue tracker is available on the GitHub repository. Don't be shy. Please report any issues that you identify so that we can address them.

Source contributions

Contributions are welcomed. Submit your changes as a GitHub pull request. Please add new tests for source contributions that our current test suite does not cover.

Clone the repository

git clone https://github.com/chrissimpkins/vectora.git

Testing

The project is tested with the latest GitHub Actions macOS, Linux (Ubuntu), and Windows environment runners using the stable and beta rustc toolchains.

Unit and doc test suite

Edit the source files, then run the unit and doc test suite locally with the command:

cargo test

Unit tests only

cargo test --lib

Doc tests only

cargo test --doc

Clippy lints

Clippy lints are not executed with the above commands. Use the following to lint Rust source files with clippy:

cargo clippy -- -D warnings

Fuzzing

This crate supports cargo fuzz + libFuzzer based fuzzing with the nightly rustc toolchain in supported environments.

Install the rustc nightly toolchain.

Then, install cargo-fuzz with:

cargo +nightly install -f cargo-fuzz

Edit the fuzz target source in the fuzz/fuzz_vectora.rs file and begin fuzzing with the command:

cargo +nightly fuzz run fuzz_vectora

Please see the Fuzzing with cargo-fuzz chapter of the Rust Fuzz book for additional documentation.

Documentation contributions

The docs.rs documentation is authored in the Rust source files. Edit the text and build a local version of the project documentation for review with the command:

cargo doc

The documentation index.html page can be found on the following relative path from the repository's root: target/doc/vectora/index.html.

Submit your doc edits as a GitHub pull request.

Changes

Please see CHANGELOG.md.

License

Vectora is released under the Apache License, v2.0.

vectora's Issues

Add M × N matrix scalar multiplication support

Requirements:

• any M by N matrix size
• any supported T numeric scalar type

Properties:

• Associative: where c, d are scalar values and A is a matrix, (cd)A=c(dA)
• Distributive: where c,d are scalar values and A, B are matrices with the same dimension c(A+B)=cA+cB and (c+d)A=cA+dA
• Multiplicative identity: where 1 is the scalar value 1 and A is a matrix 1A=A
• Multiplicative property with zero: where 0 is the scalar value 0, A is a matrix, and O is the zero matrix with the same dimensions as A: 0⋅A=O

Add M × N matrix:matrix addition support

Requirements:

• left hand side and right hand side matrix column and row lengths must be the same

Properties:

• commutative (A + B = B + A)
• associative ((A + B) + C = A + (B + C))
• additive identity with zero matrix (A + 0)
• additive inverse (A + -A)

Add M × N Matrix type and matrix arithmetic support

I am thinking about how to approach higher-level abstractions of finite vector spaces as collections of Vector.

Motivating case: a Bezier closed contour defined as an ordered list of 2-tuple of x, y coordinates in a Cartesian coordinate system.

This begins to head into more extensive linear algebra support terrain.

Update README documentation links with docs.rs

Vectora is a library for n-dimensional vector computation. The main library entry point is the Vector struct. Please see the Gettting Started guide for a detailed library API overview with examples.

The library entry point and Getting Started guide URL need to be updated once we push to crates.io and have the first docs.rs documentation build.

Add lossless complex number Vector real and integer part type casts with From trait

related #4

Add lossless uint -> uint, uint -> iint, iint -> iint, uint -> float, iint -> float, and float -> float type casts.

Add unchecked Vector methods

The data validity checks that were used in the default implementation (added in #49) significantly slow the calculation of a harmonic mean with f32 and f64 data (Criterion benchmarks added in the same PR).

Consider adding an unchecked version that is more performant and assumes data validation by the user. Perhaps under an optional feature and not part of the default crate distribution. Panics will occur with zero values. Use of values < 0.0 will not panic, but return f32 or f64 values that are not valid geometric means.

A refactor to:

let sum_of_reciprocal = self.components.iter().copied().map(|x| x.powi(-1)).sum::<T>();

in place of the #49 approach improves execution time from:

Vector mean_harmonic method: f64 5D Vector
                        time:   [4.6057 ns 4.6161 ns 4.6294 ns]
                        change: [+0.0120% +0.2572% +0.5116%] (p = 0.04 < 0.05)
                        Change within noise threshold.
Found 5 outliers among 100 measurements (5.00%)
  5 (5.00%) high severe

to:

Vector mean_harmonic method: f64 5D Vector
                        time:   [542.75 ps 543.07 ps 543.48 ps]
                        change: [-88.222% -88.193% -88.164%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 11 outliers among 100 measurements (11.00%)
  3 (3.00%) high mild
  8 (8.00%) high severe

The f32 benchmark changes are comparable.

Test environment:

MBP 16" 2021
Apple M1 Max
32GB RAM
macOS 12.1

related #44
related #8

Add M × N matrix : vector addition support

Requirements:

• matrix and vector column and row lengths must be the same

Properties:

commutative (A + B = B + A)
associative ((A + B) + C = A + (B + C))
additive identity with zero matrix (A + 0)
additive inverse (A + -A)

Questions:

• how do we approach the Vector shape? Always a column vector?

Add Vector enumerate method

Add support for an enumerate method that returns an Iterator over tuples of (index number, reference to Vector item at the respective index number).

Support scalar real integer and float multiplication with Complex Vector types

Add support for scalar multiplication * operator overload that scales the real and imaginary parts with a real integer or float scalar value. The scalar type must be the same type as that used for the real and imaginary parts of the num::Complex number.

This will support:

• num::Complex * all int types
• num::Complex * all float types

and supplements the num::Complex number * num::Complex number multiplication operator overload that was added in #14.

Add big unsigned integer support

support num::BigUint types

Implement PartialEq trait for complex numbers with floating point real and imaginary parts

related #4

Add Vector<f32, N> to Vector<f64, N> lossless type cast support with From trait

This only requires the addition of the following macro:

impl_vector_from_vector!(f32, f64);

Implement AbsDiffEq trait for Vector of complex number with floating point real and imaginary parts

related #4

Add M × N matrix : vector subtraction support

Requirements:

Left hand side Matrix and right hand side Vector must have the same row and column dimensions.

Properties:

anti-commutative: A - B = -(B - A)
non-associative (order of subtraction operations matters)
subtraction with additive identity matrix (zero matrix) yields the same matrix

Questions:

• how do we approach the Vector shape? Always a column vector?

Broaden Vector numeric type cast support

Broaden numeric type cast support with to_[TYPE] methods that are defined in the num::ToPrimitive trait. These methods will return Option<Vector<[TYPE], N>> with None returned when the cast does not fall within the range of scalars supported by the type.

Add complex number support to Vector type

Complex numbers can currently be expressed as 2-Vectors of real and imaginary parts. It might be useful to support Vector collections of complex numbers as defined by the num crate Complex type. This should be partially implemented already with our generic approach. Requires additional research and tests. Focus on the areas of the source with Float rather than Num trait bounds.

Add minimum rustc version compatibility policy

I think that our min version support will be as of v1.51.0 when const generic support was stabilized.

Add `matrix!` macro for initialization of `Matrix` structs with array-like syntax

Add a matrix! macro that supports the following Matrix struct initialization idioms:

With row vectors that define each ordered scalar value

let m = matrix!(
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
);

With row vectors that use an array-like repetition pattern

The following will make a 3 x 5 Matrix filled with 1's.

let m = matrix!(
    [1; 5],
    [1; 5],
    [1; 5]
);

This macro will take row vectors only.

Add M × N Matrix : Matrix multiplication support

Requirements:

for matrices A (=lhs) and B (=rhs):

• the column number in A must match the row number in B

Properties

for matrices A, B, and C:

• not commutative: AB ≠ BA)
• associative: (AB)C = A(BC)
• left distributive: A(B + C) = AB + AC
• right distributive: (B + C)A = BA + CA
• multiplication by zero matrix yields zero matrix: A0 = 0A = 0

Add examples

Add Vector element-wise sum method support

Add a method that sums the numbers contained by a Vector.

Implement PartialEq trait for complex numbers with integer real and imaginary parts

related #4

Reduce Cargo.toml keyword number

crates.io accepts a maximum of 5 keywords

Add Vector method that returns pretty-print formatted data contents

Add Vector max method

Return the element-wise max value in a data set

Add big signed integer support

Support num::BigInt types

Implement FromPrimitive trait support for Vector type

Docs: https://docs.rs/num/latest/num/cast/trait.FromPrimitive.html

Add Vector element-wise product method support

Add a method that returns the product of all elements contained in a Vector.

Implement UlpsEq trait for Vector of complex number with floating point real and imaginary parts

related #4

Analyze performance with inlined Vector methods

related #8

Add benchmarks

Add Criterion benchmarks to the project

Add `vector` macro for initialization of `Vector` with argument-defined type and length

The approach will be similar to that used by the standard lib vec! macro for Vec types and will support the following initialization syntax:

Comma-delimited list of numbers with the same type

use vectora::vector;

use num::Complex;

let v_int = vector![1, 2, 3];
let v_float = vector![1.0, 2.0, 3.0];
let v_complex = vector![Complex::new(1, 2), Complex::new(-1, -2), Complex::new(-1, 2)];

[NUM; LEN] expansion syntax

use vectora::vector;

use num::Complex;

let v_int: Vector<i32, 3> = vector![1; 3];
let v_float: Vector<f64, 3> = vector![1.0; 3];
let v_complex: Vector<Complex<i32>, 3> = vector![Complex::new(1, 2); 3];

Implement ToPrimitive trait support for Vector type

Docs: https://docs.rs/num/latest/num/cast/trait.ToPrimitive.html

Add M × N additive inverse Matrix support

Add `try_vector` macro for initialization of a `Vector` with fallible data collection types

This approach will take a single data collection argument type that is supported by the Vector TryFrom trait implementations. These are data collection types that may not have known length at compile time.

The approach with a std lib Vec type will be:

let stdlib_vec = vec![1, 2, 3];
let v: Vector<i32, 3> = try_vector!(stdlib_vec).unwrap();

The macro will return an error when the std lib Vec length differs from the requested Vector length:

let stdlib_vec = vec![1, 2, 3, 4, 5];

// expected length 3, received length 5
let res: Result<Vector<i32, 3>, _> = try_vector!(stdlib_vec);

assert!(res.is_err());

Implement RelativeEq trait for Vector of complex number with floating point real and imaginary parts

related #4

Add parallel feature

Add optional feature support for rayon-based parallel iterators over, and parallel slices of, Vector scalar data.

Add Vector min method

Return the element-wise min value in a data set

Add Vector element-wise measures of central tendency statistics support for floating point numbers

• arithmetic mean (#47)
• geometric mean (#48)
• harmonic mean (#49)
• median (#51)
• mode (will not implement for now)

Add Vector element-wise variance and standard deviation statistics support

• sample and population variance (#54)
• sample and population std deviation (#55)

Add M × N matrix:matrix subtraction support

Requirements:

• left hand side and right hand side matrices must have the same row and column dimensions

Properties:

• anti-commutative: A - B = -(B - A)
• non-associative (order of subtraction operations matters in contrast to matrix addition)
• subtraction with additive identity matrix (zero matrix) yields the same matrix

Add floating point Vector approximate equivalence support for customizable absolute, relative epsilon, and units in last place (ULPs) comparisons

The default [Vector] == [Vector] operator overload approach uses the approx crate default relative epsilon floating point approximate eq implementation. This defines the epsilon and max relative values for the user. The goals of the operator overload are simplicity and coverage of a broad range of common float Vector type comparison use cases.

Let's broaden support to include more floating point comparison approaches, and greater flexibility by allowing the user to define custom parameters for these comparisons according to their needs.

Will broaden our relative epsilon eq approach to support:

• definition of epsilon value
• definition of max relative value

This will work through a new method. The == operator overload strategy will remain unchanged.

Will add:

• absolute eq comparisons with support for custom epsilon definitions
• units in last place (ULPs) eq comparisons with support for custom epsilon and max ULPs definitions