#array #matrix #tensor #vector #matrix-vector #memory-layout

dimensionals

Rust native generic, flexible n-dimensional array

4 releases

0.2.1 Jun 20, 2024
0.2.0 Jun 20, 2024
0.1.1 Jun 14, 2024
0.1.0 Jun 14, 2024

#325 in Math

MIT license

54KB
1K SLoC

License Crates.io Docs CI

dimensionals

Dimensionals is a Rust library for working with n-dimensional data. It provides a flexible and efficient multidimensional array implementation with a generic storage backend.

Motivations

The key motivations behind Dimensionals are:

  • A concise, idiomatic Rust API that leverages Rust's type system and ownership model.
  • High performance through efficient memory layout and cache-friendly traversals.
  • Extensibility via a generic storage backend, allowing for custom storage strategies.
  • A foundation for a generic compute pipeline that can target GPUs and utilize SIMD instructions.

Features

  • Generic over an element type, number of dimensions, and storage backend
  • Iterators, slices, indexing, and other standard Rust traits
  • Ergonomic and idiomatic std::ops implementations for arithmetic operations
  • Convenient macros for vector and matrix creation

Usage

Add this to your Cargo.toml:

[dependencies]
dimensionals = "0.1.0"

Then, use the crate in your Rust code:

use dimensionals::{matrix, Dimensional, LinearArrayStorage};

fn main() {
    let m: Dimensional<i32, LinearArrayStorage<i32, 2>, 2> = matrix![
        [1, 2, 3],
        [4, 5, 6]
    ];
    assert_eq!(m[[0, 0]], 1);
    assert_eq!(m[[1, 1]], 5);
}

For more examples and usage details, see the API documentation.

Roadmap

The following features and improvements are planned for future releases:

  • Arithmetic operations for 1D and 2D arrays
  • SIMD support for improved performance on CPU.
  • GPU support for offloading computations to compatible GPUs.
  • Comprehensive scalar, vector, matrix, and tensor algebra operations.
  • Reshaping and appending operations for easy data manipulation.
  • Additional storage backends for optimized memory usage in various scenarios.
  • Integration with popular Rust scientific computing libraries.

Performance

The LinearArrayStorage backend stores elements in a contiguous Vec<T> and computes element indices on the fly. This provides good cache locality for traversals, but may not be optimal for sparse or very high dimensional arrays.

Alternative storage backends can be implemented by defining a type that implements the DimensionalStorage trait.

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on the GitHub repository.

License

This project is licensed under the MIT License.

Acknowledgements

This project is inspired by and builds upon ideas from several existing multidimensional array libraries in Rust and other languages.

Contact

Warlock Labs - https://github.com/warlock-labs

Project Link: https://github.com/warlock-labs/dimensionals

Dependencies

~150KB