Crate ndarray

source ·
Expand description

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.
  • Requires Rust 1.49 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 version 0.4 of the [approx] crate.
  • approx-0_5: Implementations of traits from version 0.5 of 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.

Modules

Macros

  • array
    Create an Array with one, two or three dimensions.
  • azip
    Array zip macro: lock step function application across several arrays and producers.
  • concatenate
    Concatenate arrays along the given axis.
  • s
    Slice argument constructor.
  • stack
    Stack arrays along the new axis.
  • stack_new_axisDeprecated
    Stack arrays along the new axis.

Structs

  • ArrayBase
    An n-dimensional array.
  • Axis
    An axis index.
  • AxisDescription
    Description of the axis, its length and its stride.
  • Dim
    Dimension description.
  • IxDynImpl
    Dynamic dimension or index type.
  • MathCell
    A transparent wrapper of Cell<T> which is identical in every way, except it will implement arithmetic operators as well.
  • NewAxis
    Token to represent a new axis in a slice description.
  • OwnedArcRepr
    ArcArray’s representation.
  • OwnedRepr
    Array’s representation.
  • RawViewRepr
    Array pointer’s representation.
  • Shape
    A contiguous array shape of n dimensions.
  • ShapeError
    An error related to array shape or layout.
  • Slice
    A slice (range with step size).
  • SliceInfo
    Represents all of the necessary information to perform a slice.
  • StrideShape
    An array shape of n dimensions in c-order, f-order or custom strides.
  • ViewRepr
    Array view’s representation.
  • Zip
    Lock step function application across several arrays or other producers.

Enums

  • CowRepr
    CowArray’s representation.
  • ErrorKind
    Error code for an error related to array shape or layout.
  • FoldWhile
    Value controlling the execution of .fold_while on Zip.
  • Order
    Array order
  • SliceInfoElem
    A slice (range with step), an index, or a new axis token.

Traits

  • AsArray
    Argument conversion into an array view
  • AssignElem
    A producer element that can be assigned to once
  • Data
    Array representation trait.
  • DataMut
    Array representation trait.
  • DataOwned
    Array representation trait.
  • DataShared
    Array representation trait.
  • DimAdd
    Adds the two dimensions at compile time.
  • DimMax
  • Dimension
    Array shape and index trait.
  • FixedInitializer
    Fixed-size array used for array initialization
  • IndexLonger
    Extra indexing methods for array views
  • IntoDimension
    Argument conversion a dimension.
  • IntoNdProducer
    Argument conversion into a producer.
  • LinalgScalar
    Elements that support linear algebra operations.
  • MultiSliceArg
    Slicing information describing multiple mutable, disjoint slices.
  • NdFloat
    Floating-point element types f32 and f64.
  • NdIndex
    Tuple or fixed size arrays that can be used to index an array.
  • NdProducer
    A producer of an n-dimensional set of elements; for example an array view, mutable array view or an iterator that yields chunks.
  • RawData
    Array representation trait.
  • RawDataClone
    Array representation trait.
  • RawDataMut
    Array representation trait.
  • RawDataSubst
    Array representation trait.
  • RemoveAxis
    Array shape with a next smaller dimension.
  • ScalarOperand
    Elements that can be used as direct operands in arithmetic with arrays.
  • ShapeArg
    Array shape argument with optional order parameter
  • ShapeBuilder
    A trait for Shape and D where D: Dimension that allows customizing the memory layout (strides) of an array shape.
  • SliceArg
    A type that can slice an array of dimension D.

Functions

  • Dim
    Create a new dimension value.
  • Ix0
    Create a zero-dimensional index
  • Ix1
    Create a one-dimensional index
  • Ix2
    Create a two-dimensional index
  • Ix3
    Create a three-dimensional index
  • Ix4
    Create a four-dimensional index
  • Ix5
    Create a five-dimensional index
  • Ix6
    Create a six-dimensional index
  • IxDyn
    Create a dynamic-dimensional index
  • arr0
    Create a zero-dimensional array with the element x.
  • arr1
    Create a one-dimensional array with elements from xs.
  • arr2
    Create a two-dimensional array with elements from xs.
  • arr3
    Create a three-dimensional array with elements from xs.
  • aview0
    Create a zero-dimensional array view borrowing x.
  • aview1
    Create a one-dimensional array view with elements borrowing xs.
  • aview2
    Create a two-dimensional array view with elements borrowing xs.
  • aview_mut1
    Create a one-dimensional read-write array view with elements borrowing xs.
  • aview_mut2
    Create a two-dimensional read-write array view with elements borrowing xs.
  • concatenate
    Concatenate arrays along the given axis.
  • indices
    Create an iterable of the array shape shape.
  • indices_of
    Return an iterable of the indices of the passed-in array.
  • rcarr1
    Create a one-dimensional array with elements from xs.
  • rcarr2
    Create a two-dimensional array with elements from xs.
  • rcarr3
    Create a three-dimensional array with elements from xs.
  • stack
    Stack arrays along the new axis.
  • stack_new_axisDeprecated
    Stack arrays along the new axis.

Type Definitions