Crate ndarray

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.

To get started, functionality is provided in the following core types:

  • 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.
  • A reference type, ArrayRef, that contains most of the functionality for reading and writing to arrays.
  • A reference type, LayoutRef, that contains most of the functionality for reading and writing to array layouts: their shape and strides.

§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.

Modules§

docdocsrs
Standalone documentation pages.
iter
Producers, iterables and iterators.
linalg
Linear algebra.
parallelrayon
Parallelization features for ndarray.
prelude
ndarray prelude.

Macros§

array
Create an Array with one, two, three, four, five, or six 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.

Structs§

ArrayBase
An n-dimensional array.
ArrayRef
A reference to an n-dimensional array whose data is safe to read and write.
Axis
An axis index.
AxisDescription
Description of the axis, its length and its stride.
Dim
Dimension description.
IxDynImpl
Dynamic dimension or index type.
LayoutRef
A reference to the layout of an n-dimensional array.
Linspacestd
An iterator of a sequence of evenly spaced floats.
Logspacestd
An iterator of a sequence of logarithmically spaced number.
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.
RawRef
A reference to an n-dimensional array whose data is not safe to read or write.
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.
MeshIndex
The indexing order for meshgrid; see there for more details.
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
A trait to specify when one dimension is strictly larger than another.
Dimension
Array shape and index trait.
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.
NdFloatstd
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.
linspacestd
Return an iterator of evenly spaced floats.
logspacestd
An iterator of a sequence of logarithmically spaced numbers.
meshgrid
Create coordinate matrices from coordinate vectors.
rangestd
Return an iterator of floats from a to b (exclusive), incrementing by step.
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.

Type Aliases§

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
ArrayRef0
zero-dimensional array reference
ArrayRef1
one-dimensional array reference
ArrayRef2
two-dimensional array reference
ArrayRef3
three-dimensional array reference
ArrayRef4
four-dimensional array reference
ArrayRef5
five-dimensional array reference
ArrayRef6
six-dimensional array reference
ArrayRefD
dynamic-dimensional array reference
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)
LayoutRef0
zero-dimensional layout reference
LayoutRef1
one-dimensional layout reference
LayoutRef2
two-dimensional layout reference
LayoutRef3
three-dimensional layout reference
LayoutRef4
four-dimensional layout reference
LayoutRef5
five-dimensional layout reference
LayoutRef6
six-dimensional layout reference
LayoutRefD
dynamic-dimensional layout reference
RawArrayView
A read-only array view without a lifetime.
RawArrayViewMut
A mutable array view without a lifetime.