ndarray Documentation

File: README.rst Copy Chapter

ndarray

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

Please read the API documentation on docs.rs__
or take a look at the quickstart tutorial <./README-quick-start.md>_.

__ https://docs.rs/ndarray/

|build_status|_ |crates|_ |matrix-chat|_ |irc|_

.. |build_status| image:: https://github.com/rust-ndarray/ndarray/actions/workflows/ci.yaml/badge.svg
:alt: CI build status
.. _build_status: https://github.com/rust-ndarray/ndarray/actions

.. |crates| image:: https://img.shields.io/crates/v/ndarray.svg
:alt: ndarray at crates.io
.. _crates: https://crates.io/crates/ndarray

.. |matrix-chat| image:: https://img.shields.io/badge/Matrix-%23rust--sci%3Amatrix.org-lightgrey
:alt: Matrix chat at #rust-sci:matrix.org
.. _matrix-chat: https://matrix.to/#/#rust-sci:matrix.org

.. |irc| image:: https://img.shields.io/badge/IRC-%23rust--sci%20on%20OFTC-lightgrey
:alt: IRC at #rust-sci on OFTC
.. _irc: https://webchat.oftc.net/?channels=rust-sci

Highlights Copy Chapter

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

Installation Copy Chapter

From a shell in your project folder, run cargo add ndarray to add the latest version.

Status and Lookout Copy Chapter

• 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 Copy Chapter

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 this in your Cargo.toml:

    ::

    [dependencies]
    ndarray = { version = "0.x.y", default-features = false }

  • 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

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

• matrixmultiply-threading

  • Enable the threading feature in the matrixmultiply package

• portable-atomic-critical-section

  • Whether portable-atomic should use critical-section

How to enable BLAS integration Copy Chapter

Blas integration is an optional add-on. Without BLAS, ndarray uses the
matrixmultiply crate for matrix multiplication for f64 and f32
arrays (and it's always enabled as a fallback since it supports matrices of
arbitrary strides in both dimensions).

Depend and link to blas-src directly to pick a blas provider. Ndarray
presently requires a blas provider that provides the cblas-sys interface. If
further feature selection is wanted or needed then you might need to depend directly on
the backend crate's source too. The backend version must be the one that
blas-src also depends on.

An example configuration using system openblas is shown below. Note that only
end-user projects (not libraries) should select provider::

[dependencies]
ndarray = { version = "0.x.y", features = ["blas"] }
blas-src = { version = "0.10", features = ["openblas"] }
openblas-src = { version = "0.10", features = ["cblas", "system"] }

Using system-installed dependencies can save a long time building dependencies.
An example configuration using (compiled) netlib is shown below anyway::

[dependencies]
ndarray = { version = "0.x.y", features = ["blas"] }
blas-src = { version = "0.10.0", default-features = false, features = ["netlib"] }

When this is done, your program must also link to blas_src by using it or
explicitly including it in your code::

extern crate blas_src;

The following versions have been verified to work together. For ndarray 0.15 or later,
there is no tight coupling to the blas-src version, so version selection is more flexible.

=========== ============ ================ ==============
ndarray blas-src openblas-src netlib-src
=========== ============ ================ ==============
0.16 0.10 0.10 0.8
0.15 0.8 0.10 0.8
0.15 0.7 0.9 0.8
0.14 0.6.1 0.9.0
0.13 0.2.0 0.6.0
=========== ============ ================ ==============

BLAS on MSRV Copy Chapter

Although ndarray currently maintains an MSRV via rust-version, this is separate from the MSRV (either stated or real) of the various BLAS providers.
So, while ndarray may be compatible with older toolchains, the BLAS providers it depends on may not be.

Recent Changes Copy Chapter

See RELEASES.md <./RELEASES.md>_.

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.