Crate ndarray[][src]

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.

  • std
  • Rust standard library (enabled by default)
  • This crate can be used without the standard library by disabling the default std feature. To do so, use default-features = false in your Cargo.toml.
  • The geomspace linspace logspace range std var var_axis and std_axis methods are only available when std is enabled.
  • serde
    • Enables serialization support for serde 1.x
  • rayon
    • Enables parallel iterators, parallelized methods and par_azip!.
    • Implies std
  • approx
    • Enables implementations of traits from the approx crate.
  • blas
    • Enable transparent BLAS support for matrix multiplication. Uses blas-src for pluggable backend, which needs to be configured separately (see the README).
  • matrixmultiply-threading
    • Enable the threading feature in the matrixmultiply package

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

doc

Standalone documentation pages.

iter

Producers, iterables and iterators.

linalg

Linear algebra.

parallel

Parallelization features for ndarray.

prelude

ndarray prelude.

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.

par_azip

Parallelized array zip macro: lock step function application across several arrays and producers.

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.

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.

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

ArcArray

An array where the data has shared ownership and is copy on write.

ArcArray1

one-dimensional shared ownership array

ArcArray2

two-dimensional shared ownership array

Array

An array that owns its data uniquely.

Array0

zero-dimensional array

Array1

one-dimensional array

Array2

two-dimensional array

Array3

three-dimensional array

Array4

four-dimensional array

Array5

five-dimensional array

Array6

six-dimensional array

ArrayD

dynamic-dimensional array

ArrayView

A read-only array view.

ArrayView0

zero-dimensional array view

ArrayView1

one-dimensional array view

ArrayView2

two-dimensional array view

ArrayView3

three-dimensional array view

ArrayView4

four-dimensional array view

ArrayView5

five-dimensional array view

ArrayView6

six-dimensional array view

ArrayViewD

dynamic-dimensional array view

ArrayViewMut

A read-write array view.

ArrayViewMut0

zero-dimensional read-write array view

ArrayViewMut1

one-dimensional read-write array view

ArrayViewMut2

two-dimensional read-write array view

ArrayViewMut3

three-dimensional read-write array view

ArrayViewMut4

four-dimensional read-write array view

ArrayViewMut5

five-dimensional read-write array view

ArrayViewMut6

six-dimensional read-write array view

ArrayViewMutD

dynamic-dimensional read-write array view

CowArray

An array with copy-on-write behavior.

Ix

Array index type

Ix0

zero-dimensionial

Ix1

one-dimensional

Ix2

two-dimensional

Ix3

three-dimensional

Ix4

four-dimensional

Ix5

five-dimensional

Ix6

six-dimensional

IxDyn

dynamic-dimensional

Ixs

Array index type (signed)

RawArrayView

A read-only array view without a lifetime.

RawArrayViewMut

A mutable array view without a lifetime.