ndarray

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

Please read the API documentation on docs.rs__

__ https://docs.rs/ndarray/

|buildstatus| |crates|_

.. |buildstatus| image:: https://travis-ci.org/bluss/rust-ndarray.svg?branch=master .. _buildstatus: https://travis-ci.org/bluss/rust-ndarray

.. |crates| image:: http://meritbadge.herokuapp.com/ndarray .. _crates: https://crates.io/crates/ndarray

Highlights

• Generic 1, 2, ..., n-dimensional arrays
• Owned arrays and array views
• 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.

Status and Lookout

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

• Performance:

  • Prefer higher order methods and arithmetic operations on arrays first, then iteration, and as a last priority using indexed algorithms.
  • Efficient floating point matrix multiplication even for very large matrices; can optionally use BLAS to improve it further.

Crate Feature Flags

The following crate feature flags are available. They are configured in your Cargo.toml.

• rustc-serialize

  • Optional, compatible with Rust stable
  • Enables serialization support for rustc-serialize 0.3

• serde-1

  • Optional, compatible with Rust stable
  • Enables serialization support for serde 1.0

• blas

  • Optional and experimental, compatible with Rust stable
  • Enable transparent BLAS support for matrix multiplication. Uses blas-sys for pluggable backend, which needs to be configured separately.

How to use with cargo

::

[dependencies]
ndarray = "0.10.0"

How to enable blas integration. Depend on blas-sys directly to pick a blas provider. Note that only end-user projects (not libraries) should select provider::

[dependencies]
ndarray = { version = "0.10.0", features = ["blas"] }
blas-sys = { version = "0.6", default-features = false, features = ["openblas"] }

Recent Changes (ndarray)

• 0.10.10

  • Fix crash with zero size arrays in the fallback matrix multiplication code (#365) by @jturner314

• 0.10.9

  • Fix crash in Array::from_shape_fn when creating an f-order array with zero elements (#361) by @jturner314

• 0.10.8

  • Add method .insert_axis() to arrays and array views by @jturner314

• 0.10.7

  • Add method .is_empty() to arrays and array views by @iamed2
  • Support optional trailing commas in the array![] macro by Alex Burka
  • Added an example of permuting/sorting along an axis to the sources

• 0.10.6

  • Tweak the implementation for (bounds checked) indexing of arrays ([] operator). The new code will have the optimizer elide the bounds checks in more situations.

• 0.10.5

  • Add method .into_dimensionality::<D>() for dimensionality conversion (From IxDyn to fixed size and back).
  • New names .sum_axis and .mean_axis for sum and mean functions. Old names deprecated to make room for scalar-returning methods, making a proper convention.
  • Fix deserialization using ron (#345) by @Libbum

• 0.10.4

  • Fix unused mut warnings in azip!() macro
  • Fix bug #340 by @lloydmeta; uses blas gemm for more memory layouts of column matrices. Only relevant if using blas.

• 0.10.3

  • Fix docs.rs doc build

• 0.10.2

  • Support trailing commas in the s![] macro
  • Some documentation improvements for the introduction, for azip!() and other places.
  • Added two more examples in the source

• 0.10.1

  • Add method .into_dyn() to convert to a dynamic dimensionality array or array view. By @bobogei81123
  • Edit docs for the fact that type alias pages now show methods. See the doc pages for Array and ArrayView and the other aliases.
  • Edit docs for Zip

• 0.10.0

  • Upgrade to Serde 1.0. Crate feature name is serde-1.
  • Require Rust 1.18. The pub(crate) feature is that important.

• 0.9.1

  • Fix Array::from_shape_fn to give correct indices for f-order shapes
  • Fix Array::from_shape_fn to panic correctly on shape size overflow

• 0.9.0 Release Announcement__

  • Add Zip::indexed
  • New methods genrows/_mut, gencolumns/_mut, lanes/_mut that return iterable producers (producer means Zip compatibile).
  • New method .windows() by @Robbepop, returns an iterable producer
  • New function general_mat_vec_mul (with fast default and blas acceleration)
  • Zip::apply and fold_while now take self as the first argument
  • indices/_of now return iterable producers (not iterator)
  • No allocation for short IxDyn.
  • Remove Ix, Ixs from the prelude
  • Remove deprecated Axis::axis method (use .index())
  • Rename .whole_chunks to .exact_chunks.
  • Remove .inner_iter in favour of the new .genrows() method.
  • Iterators and similar structs are now scoped under ndarray::iter
  • IntoNdProducer now has the Item associated type
  • Owned array storage types are now encapsulated in newtypes
  • FoldWhile got the method is_done.
  • Arrays now implement formatting trait Binary if elements do
  • Internal changes. NdProducer generalized. Dimension gets the Smaller type parameter. Internal traits have the private marker now.
  • # (alternate) in formatting does nothing now.
  • Require Rust 1.15

__ https://bluss.github.io//rust/2017/04/09/ndarray-0.9/

• 0.8.4

  • Use Zip in .all_close() (performance improvement)
  • Use #[inline] on a function used for higher dimensional checked indexing (performance improvement for arrays of ndim >= 3)
  • .subview() has a more elaborate panic message

• 0.8.3

  • Fix a bug in Zip / NdProducer if an array of at least 3 dimensions was contig but not c- nor f-contig.
  • WholeChunksIter/Mut now impl Send/Sync as appropriate
  • Misc cleanup and using dimension-reducing versions of inner_iter internally. Remove a special case in zip_mut_with that only made it slower (1D not-contig arrays).

• 0.8.2

  • Add more documentation and an example for dynamic dimensions: see IxDyn__. IxDyn will have a representation change next incompatible version. Use it as a type alias for best forward compatibility.
  • Add iterable and producer .whole_chunks_mut(size).
  • Fix a bug in whole_chunks: it didn't check the dimensionality of the requested chunk size properly (an IxDyn-only bug).
  • Improve performance of zip_mut_with (and thus all binary operators) for block slices of row major arrays.
  • AxisChunksIter creation sped up and it implements Clone.
  • Dimension mismatch in Zip has a better panic message.

  __ https://bluss.github.io/rust-ndarray/master/ndarray/type.IxDyn.html

• 0.8.1

  • Add Zip and macro azip!() which implement lock step function application across elements from one up to six arrays (or in general producers)

  • Apart from array views, axis iterators and the whole chunks iterable are also producers

  • Add constructor Array::uninitialized

  • Add iterable and producer .whole_chunks(size)
  • Implement a prettier Debug for Si.
  • Fix Array::default so that it panics as documented if the size of the array would wrap around integer type limits.
  • Output more verbose panics for errors when slicing arrays (only in debug mode).

• 0.8.0

  • Update serde dependency to 0.9
  • Remove deprecated type alias OwnedArray (use Array)
  • Remove deprecated .assign_scalar() (use fill)

• 0.7.3

  • Add macro array![] for creating one-, two-, or three-dimensional arrays (with ownership semantics like vec![])
  • Array now implements Clone::clone_from() specifically, so that its allocation is (possibly) reused.
  • Add .to_vec() for one-dimensional arrays
  • Add RcArray::into_owned(self) -> Array.
  • Add crate categories

• 0.7.2

  • Add array methods .remove_axis(), .merge_axes() and .invert_axis()
  • Rename Axis’ accessor axis to index, old name is deprecated.

• 0.7.1

  • Fix two bugs in Array::clone(); it did not support zero-size elements like (), and for some negatively strided arrays it did not update the first element offset correctly.
  • Add .axes() which is an iterator over the axes of an array, yielding its index, length and stride.
  • Add method .max_stride_axis().

• 0.6.10

  • Fix two bugs in Array::clone(); it did not support zero-size elements like (), and for some negatively strided arrays it did not update the first element offset correctly.

• 0.7.0

  • Big overhaul of dimensions: Add type Dim with aliases Ix1, Ix2, Ix3, ... etc for specific dimensionalities. Instead of Ix for dimension use Ix1, instead of (Ix, Ix) use Ix2, and so on.
  • The dimension type Dim supports indexing and arithmetic. See Dimension trait for new methods and inherited traits.
  • Constructors and methods that take tuples for array sizes, like Array::zeros, Array::from_shape_vec, .into_shape() and so on will continue to work with tuples.
  • The array method .raw_dim() returns the shape description D as it is. .dim() continues to return the dimension as a tuple.
  • Renamed iterators for consistency (each iterator is named for the method that creates it, for example .iter() returns Iter).
  • The index iterator is now created with free functions indices or indices_of.
  • Expanded the ndarray::prelude module with the dimensionality-specific type aliases, and some other items
  • LinalgScalar and related features no longer need to use Any for static type dispatch.
  • Serialization with serde now supports binary encoders like bincode and others.
  • .assign_scalar() was deprecated and replaced by .fill(), which takes an element by value.
  • Require Rust 1.13

• 0.6.9

  • Implement ExactSizeIterator for the indexed iterators

• 0.6.8

  • Fix a bug in a partially consumed elements iterator's .fold(). (Note that users are recommended to not use the elements iterator, but the higher level functions which are the maps, folds and other methods of the array types themselves.)

• 0.6.7

  • Improve performance of a lot of basic operations for arrays where the innermost dimension is not contiguous (.fold(), .map(), .to_owned(), arithmetic operations with scalars).
  • Require Rust 1.11

• 0.6.6

  • Add dimensionality specific type aliases: Array0, Array1, Array2, ... and so on (there are many), also Ix0, Ix1, Ix2, ....
  • Add constructor Array::from_shape_fn(D, |D| -> A).
  • Improve performance of Array::default, and .fold() for noncontiguous array iterators.

• 0.6.5

  • Add method .into_raw_vec() to turn an Array into the its underlying element storage vector, in whatever element order it is using.

• 0.6.4

  • Add method .map_axis() which is used to flatten an array along one axis by mapping it to a scalar.

• 0.6.3

  • Work around compilation issues in nightly (issue #217)
  • Add Default implementations for owned arrays

• 0.6.2

  • Add serialization support for serde 0.8, under the crate feature name serde

• 0.6.1

  • Add unsafe array view constructors ArrayView::from_shape_ptr for read-only and read-write array views. These make it easier to create views from raw pointers.

• 0.6.0

  • Rename OwnedArray to Array. The old name is deprecated.
  • Remove deprecated constructor methods. Use zeros, fromelem, fromshapevec or fromshapevecunchecked instead.
  • Remove deprecated in place arithmetic methods like iadd et.c. Use += et.c. instead.
  • Remove deprecated method mat_mul, use dot instead.
  • Require Rust 1.9

• 0.5.2

  • Use num-traits, num-complex instead of num.

• 0.5.1

  • Fix theoretical well-formedness issue with Data trait

• 0.5.0

  • Require Rust 1.8 and enable +=, -=, and the other assign operators. All iadd, iadd_scalar and similar methods are now deprecated.
  • ndarray now has a prelude: use ndarray::prelude::*;.
  • Constructors fromelem, zeros, fromshape_vec now all support passing a custom memory layout. A lot of specific constructors were deprecated.
  • Add method .select(Axis, &[Ix]) -> OwnedArray, to create an array from a non-contiguous pick of subviews along an axis.
  • Rename .mat_mul() to just .dot() and add a function general_mat_mul for matrix multiplication with scaling into an existing array.
  • Change .fold() to use arbitrary order.
  • See below for more details

• 0.5.0-alpha.2

  • Fix a namespace bug in the stack![] macro.
  • Add method .select() that can pick an arbitrary set of rows (for example) into a new array.

• 0.4.9

  • Fix a namespace bug in the stack![] macro.
  • Add deprecation messages to .iadd() and similar methods (use += instead).

• 0.5.0-alpha.1

  • Add .swap(i, j) for swapping two elements
  • Add a prelude module use ndarray::prelude::*;
  • Add ndarray::linalg::generalmatmul which computes C ← α A B + β C, i.e matrix multiplication into an existing array, with optional scaling.
  • Add .fold_axis(Axis, folder)
  • Implement .into_shape() for f-order arrays

• 0.5.0-alpha.0

  • Requires Rust 1.8. Compound assignment operators are now enabled by default.
  • Rename .mat_mul() to .dot(). The same method name now handles dot product and matrix multiplication.
  • Remove deprecated items: rawdata, rawdata_mut, allclose, zeros, Array. Docs for 0.4. lists the replacements.
  • Remove deprecated crate features: rblas, assign_ops
  • A few consuming arithmetic ops with ArrayViewMut were removed (this was missed in the last version).
  • Change .fold() to use arbitrary order. Its specification and implementation has changed, to pick the most appropriate element traversal order depending on memory layout.

• 0.4.8

  • Fix an error in .dot() when using BLAS and arrays with negative stride.

• 0.4.7

  • Add dependency matrixmultiply to handle matrix multiplication for floating point elements. It supports matrices of general stride and is a great improvement for performance. See PR #175.

• 0.4.6

  • Fix bug with crate feature blas; it would not compute matrix multiplication correctly for arrays with negative or zero stride.
  • Update blas-sys version (optional dependency).

• 0.4.5

  • Add .all_close() which replaces the now deprecated .allclose(). The new method has a stricter protocol: it panics if the array shapes are not compatible. We don't want errors to pass silently.
  • Add a new illustration to the doc for .axis_iter().
  • Rename OuterIter, OuterIterMut to AxisIter, AxisIterMut. The old name is now deprecated.

• 0.4.4

  • Add mapping methods .mapv(), .mapv_into(), .map_inplace(), .mapv_inplace(), .visit(). The mapv versions have the transformation function receive the element by value (hence v).
  • Add method .scaled_add() (a.k.a axpy) and constructor from_vec_dim_f.
  • Add 2d array methods .rows(), .cols().
  • Deprecate method .fold() because it dictates a specific visit order.

• 0.4.3

  • Add array method .t() as a shorthand to create a transposed view.
  • Fix mat_mul so that it accepts arguments of different array kind
  • Fix a bug in mat_mul when using BLAS and multiplying with a column matrix (#154)

• 0.4.2

  • Add new BLAS integration used by matrix multiplication (selected with crate feature blas). Uses pluggable backend.
  • Deprecate module ndarray::blas and crate feature rblas. This module was moved to the crate ndarray-rblas.
  • Add array methods as_slice_memory_order, as_slice_memory_order_mut, as_ptr, as_mut_ptr.
  • Deprecate raw_data, raw_data_mut.
  • Add Send + Sync to NdFloat.
  • Arrays now show shape & stride in their debug formatter.
  • Fix a bug where from_vec_dim_stride did not accept arrays with unitary axes.
  • Performance improvements for contiguous arrays in non-c order when using methods to_owned, map, scalar_sum, assign_scalar, and arithmetic operations between array and scalar.
  • Some methods now return arrays in the same memory order of the input if the input is contiguous: to_owned, map, mat_mul (matrix multiplication only if both inputs are the same memory order), and arithmetic operations that allocate a new result.
  • Slight performance improvements in dot, mat_mul due to more efficient glue code for calling BLAS.
  • Performance improvements in .assign_scalar.

• 0.4.1

  • Mark iterators Send + Sync when possible.

• 0.4.0 Release Announcement__

  • New array splitting via .split_at(Axis, Ix) and .axis_chunks_iter()
  • Added traits NdFloat, AsArray and From for ArrayView which improve generic programming.
  • Array constructors panic when attempting to create an array whose element count overflows usize. (Would be a debug assertion for overflow before.)
  • Performance improvements for .map().
  • Added stack and macro stack![axis, arrays..] to concatenate arrays.
  • Added constructor OwnedArray::range(start, end, step).
  • The type alias Array was renamed to RcArray (and the old name deprecated).
  • Binary operators are not defined when consuming a mutable array view as the left hand side argument anymore.
  • Remove methods and items deprecated since 0.3 or earlier; deprecated methods have notes about replacements in 0.3 docs.
  • See below for full changelog through alphas.

__ http://bluss.github.io/rust/2016/03/06/ndarray-0.4/

• 0.4.0-alpha.8

  • In debug mode, indexing an array out of bounds now has a detailed message about index and shape. (In release mode it does not.)
  • Enable assign_ops feature automatically when it is supported (Rust 1.8 beta or later).
  • Add trait NdFloat which makes it easy to be generic over f32, f64.
  • Add From implementations that convert slices or references to arrays into array views. This replaces from_slice from a previous alpha.
  • Add AsArray trait, which is simply based on those From implementations.
  • Improve .map() so that it can autovectorize.
  • Use Axis argument in RemoveAxis too.
  • Require DataOwned in the raw data methods.
  • Merged error types into a single ShapeError, which uses no allocated data.

• 0.4.0-alpha.7

  • Fix too strict lifetime bound in arithmetic operations like &a @ &b.
  • Rename trait Scalar to ScalarOperand (and improve its docs).
  • Implement <<= and >>= for arrays.

• 0.4.0-alpha.6

  • All axis arguments must now be wrapped in newtype Axis.
  • Add method .split_at(Axis, Ix) to read-only and read-write array views.
  • Add constructors ArrayView{,Mut}::from_slice and array view methods are now visible in the docs.

• 0.4.0-alpha.5

  • Use new trait LinalgScalar for operations where we want type-based specialization. This shrinks the set of types that allow dot product, matrix multiply, mean.
  • Use BLAS acceleration transparently in .dot() (this is the first step).
  • Only OwnedArray and RcArray and not ArrayViewMut can now be used as consumed left hand operand for arithmetic operators. See arithmetic operations docs!__
  • Remove deprecated module linalg (it was already mostly empty)
  • Deprecate free function zeros in favour of static method zeros.

__ https://bluss.github.io/rust-ndarray/master/ndarray/struct.ArrayBase.html#arithmetic-operations

• 0.4.0-alpha.4

  • Rename Array to RcArray. Old name is deprecated.
  • Add methods OuterIter::split_at, OuterIterMut::split_at
  • Change arr0, arr1, arr2, arr3 to return OwnedArray. Add rcarr1, rcarr2, rcarr3 that return RcArray.

• 0.4.0-alpha.3

  • Improve arithmetic operations where the RHS is a broadcast 0-dimensional array.
  • Add read-only and read-write array views to the rblas integration. Added methods AsBlas::{blas_view_checked, blas_view_mut_checked, bv, bvm}.
  • Use hash_slice in Hash impl for arrays.

• 0.4.0-alpha.2

  • Add ArrayBase::reversed_axes which transposes an array.

• 0.4.0-alpha.1

  • Add checked and unchecked constructor methods for creating arrays from a vector and explicit dimension and stride, or with fortran (column major) memory order (marked f):

  • ArrayBase::from_vec_dim, from_vec_dim_stride, from_vec_dim_stride_unchecked,

  • from_vec_dim_unchecked_f, from_elem_f, zeros_f
  • View constructors ArrayView::from_slice_dim_stride, ArrayViewMut::from_slice_dim_stride.

  • Rename old ArrayBase::from_vec_dim to from_vec_dim_unchecked.

  • Check better for wraparound when computing the number of elements in a shape; this adds error cases that panic in from_elem, zeros etc, however the new check will only ever panic in cases that would trigger debug assertions for overflow in the previous versions!.

  • Add an array chunks iterator .axis_chunks_iter() and mutable version; it allows traversing the array in for example chunks of n rows at a time.
  • Remove methods and items deprecated since 0.3 or earlier; deprecated methods have notes about replacements in 0.3 docs.

• 0.3.1

  • Add .row_mut(), .column_mut()
  • Add .axis_iter(), .axis_iter_mut()

• 0.3.0

  • Second round of API & consistency update is done
  • 0.3.0 highlight: Index type Ix changed to usize.
  • 0.3.0 highlight: Operator overloading for scalar and array arithmetic.
  • 0.3.0 highlight: Indexing with a[[i, j, k]] syntax.
  • Add ArrayBase::eye(n)
  • See below for more info

• 0.3.0-alpha.4

  • Shrink array view structs by removing their redundant slice field (see #45). Changed the definition of the view type aliases.
  • .mat_mul() and .mat_mul_col() now return OwnedArray. Use .into_shared() if you need an Array.
  • impl ExactSizeIterator where possible for iterators.
  • impl DoubleEndedIterator for .outer_iter() (and _mut).

• 0.3.0-alpha.3

  • .subview() changed to return an array view, also added into_subview().
  • Add .outer_iter() and .outer_iter_mut() for iteration along the greatest axis of the array. Views also implement into_outer_iter() for “lifetime preserving” iterators.

• 0.3.0-alpha.2

  • Improve the strided last dimension case in zip_mut_with slightly (affects all binary operations).
  • Add .row(i), .column(i) for 2D arrays.
  • Deprecate .row_iter(), .col_iter().
  • Add method .dot() for computing the dot product between two 1D arrays.

• 0.3.0-alpha.1

  • Index type Ix changed to usize (#9). Gives better iterator codegen and 64-bit size arrays.
  • Support scalar operands with arithmetic operators.
  • Change .slice() and .diag() to return array views, add .into_diag().
  • Add ability to use fixed size arrays for array indexing, enabling syntax like a[[i, j]] for indexing.
  • Add .ndim()

• 0.2.0

  • First chapter of API and performance evolution is done \o/
  • 0.2.0 highlight: Vectorized (efficient) arithmetic operations
  • 0.2.0 highlight: Easier slicing using s![]
  • 0.2.0 highlight: Nicer API using views
  • 0.2.0 highlight: Bridging to BLAS functions.
  • See below for more info

• 0.2.0-alpha.9

  • Support strided matrices in rblas bridge, and fix a bug with non square matrices.
  • Deprecated all of module linalg.

• 0.2.0-alpha.8

  • Note: PACKAGE NAME CHANGED TO ndarray. Having package != crate ran into many quirks of various tools. Changing the package name is easier for everyone involved!
  • Optimized scalar_sum() so that it will vectorize for the floating point element case too.

• 0.2.0-alpha.7

  • Optimized arithmetic operations!

  • For c-contiguous arrays or arrays with c-contiguous lowest dimension they optimize very well, and can vectorize!

  • Add .inner_iter(), .inner_iter_mut()

  • Add .fold(), .zip_mut_with()
  • Add .scalar_sum()
  • Add example examples/life.rs

• 0.2.0-alpha.6

  • Add #[deprecated] attributes (enabled with new enough nightly)
  • Add ArrayBase::linspace, deprecate constructor range.

• 0.2.0-alpha.5

  • Add s![...], a slice argument macro.
  • Add aview_mut1(), zeros()
  • Add .diag_mut() and deprecate .diag_iter_mut(), .sub_iter_mut()
  • Add .uget(), .uget_mut() for unchecked indexing and deprecate the old names.
  • Improve ArrayBase::from_elem
  • Removed SliceRange, replaced by From impls for Si.

• 0.2.0-alpha.4

  • Slicing methods like .slice() now take a fixed size array of Si as the slice description. This allows more type checking to verify that the number of axes is correct.
  • Add experimental rblas integration.
  • Add into_shape() which allows reshaping any array or view kind.

• 0.2.0-alpha.3

  • Add and edit a lot of documentation

• 0.2.0-alpha.2

  • Improve performance for iterators when the array data is in the default memory layout. The iterator then wraps the default slice iterator and loops will autovectorize.
  • Remove method .indexed() on iterators. Changed Indexed and added ÌndexedMut.
  • Added .as_slice(), .as_mut_slice()
  • Support rustc-serialize

• 0.2.0-alpha

  • Alpha release!
  • Introduce ArrayBase, OwnedArray, ArrayView, ArrayViewMut
  • All arithmetic operations should accept any array type
  • Array continues to refer to the default reference counted copy on write array
  • Add .view(), .view_mut(), .to_owned(), .into_shared()
  • Add .slice_mut(), .subview_mut()

  • Some operations now return OwnedArray:

  • .map()

  • .sum()

  • .mean()

  • Add get, get_mut to replace the now deprecated at, at_mut.

  • Fix bug in assign_scalar

• 0.1.1

  • Add Array::default
  • Fix bug in rawdatamut

• 0.1.0

  • First release on crates.io
  • Starting point for evolution to come

License

Dual-licensed to be compatible with the Rust project.

Licensed under the Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0 or the MIT license http://opensource.org/licenses/MIT, at your option. This file may not be copied, modified, or distributed except according to those terms.