#array #matrix #multi-dimensional #matrix-operations #blas #multidimensional-array #higher-order

no-std ndarray

An n-dimensional array for general elements and for numerics. Lightweight array views and slicing; views support chunking and splitting.

90 releases

0.16.1 Aug 14, 2024
0.15.6 Jul 30, 2022
0.15.4 Nov 23, 2021
0.15.3 Jun 5, 2021
0.3.0-alpha.1 Dec 27, 2015

#9 in Data structures

Download history 156158/week @ 2024-07-15 174856/week @ 2024-07-22 162230/week @ 2024-07-29 165524/week @ 2024-08-05 170234/week @ 2024-08-12 174768/week @ 2024-08-19 173423/week @ 2024-08-26 170539/week @ 2024-09-02 175136/week @ 2024-09-09 171444/week @ 2024-09-16 181898/week @ 2024-09-23 179833/week @ 2024-09-30 197460/week @ 2024-10-07 207901/week @ 2024-10-14 208536/week @ 2024-10-21 194643/week @ 2024-10-28

819,869 downloads per month
Used in 2,026 crates (1,065 directly)

MIT/Apache

1MB
17K SLoC

ndarray implements an n-dimensional container for general elements and for numerics.

In n-dimensional we include for example 1-dimensional rows or columns, 2-dimensional matrices, and higher dimensional arrays. If the array has n dimensions, then an element in the array is accessed by using that many indices. Each dimension is also called an axis.

Highlights

  • Generic n-dimensional array
  • Slicing, also with arbitrary step size, and negative indices to mean elements from the end of the axis.
  • Views and subviews of arrays; iterators that yield subviews.
  • Higher order operations and arithmetic are performant
  • Array views can be used to slice and mutate any [T] data using ArrayView::from and ArrayViewMut::from.
  • Zip for lock step function application across two or more arrays or other item producers (NdProducer trait).

lib.rs:

The ndarray crate provides an n-dimensional container for general elements and for numerics.

In n-dimensional we include, for example, 1-dimensional rows or columns, 2-dimensional matrices, and higher dimensional arrays. If the array has n dimensions, then an element in the array is accessed by using that many indices. Each dimension is also called an axis.

  • ArrayBase: The n-dimensional array type itself.
    It is used to implement both the owned arrays and the views; see its docs for an overview of all array features.
  • The main specific array type is Array, which owns its elements.

Highlights

  • Generic n-dimensional array
  • Slicing, also with arbitrary step size, and negative indices to mean elements from the end of the axis.
  • Views and subviews of arrays; iterators that yield subviews.
  • Higher order operations and arithmetic are performant
  • Array views can be used to slice and mutate any [T] data using ArrayView::from and ArrayViewMut::from.
  • [Zip] for lock step function application across two or more arrays or other item producers (NdProducer trait).

Crate Status

  • Still iterating on and evolving the crate

    • The crate is continuously developing, and breaking changes are expected during evolution from version to version. We adopt the newest stable rust features if we need them.
    • Note that functions/methods/traits/etc. hidden from the docs are not considered part of the public API, so changes to them are not considered breaking changes.
  • Performance:

    • Prefer higher order methods and arithmetic operations on arrays first, then iteration, and as a last priority using indexed algorithms.
    • The higher order functions like .map(), .map_inplace(), .zip_mut_with(), [Zip] and azip!() are the most efficient ways to perform single traversal and lock step traversal respectively.
    • Performance of an operation depends on the memory layout of the array or array view. Especially if it's a binary operation, which needs matching memory layout to be efficient (with some exceptions).
    • Efficient floating point matrix multiplication even for very large matrices; can optionally use BLAS to improve it further.
  • MSRV: Requires Rust 1.64 or later

Crate Feature Flags

The following crate feature flags are available. They are configured in your Cargo.toml. See doc::crate_feature_flags for more information.

  • std: Rust standard library-using functionality (enabled by default)
  • serde: serialization support for serde 1.x
  • rayon: Parallel iterators, parallelized methods, the parallel module and par_azip!.
  • approx Implementations of traits from the approx crate.
  • blas: transparent BLAS support for matrix multiplication, needs configuration.
  • matrixmultiply-threading: Use threading from matrixmultiply.

Documentation

  • The docs for ArrayBase provide an overview of the n-dimensional array type. Other good pages to look at are the documentation for the s![] and azip!() macros.

  • If you have experience with NumPy, you may also be interested in ndarray_for_numpy_users.

The ndarray ecosystem

ndarray provides a lot of functionality, but it's not a one-stop solution.

ndarray includes matrix multiplication and other binary/unary operations out of the box. More advanced linear algebra routines (e.g. SVD decomposition or eigenvalue computation) can be found in ndarray-linalg.

The same holds for statistics: ndarray provides some basic functionalities (e.g. mean) but more advanced routines can be found in ndarray-stats.

If you are looking to generate random arrays instead, check out ndarray-rand.

For conversion between ndarray, nalgebra and image check out nshare.

Dependencies

~0.4–1.3MB
~26K SLoC