163 lines
5.3 KiB
ReStructuredText
163 lines
5.3 KiB
ReStructuredText
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/workflows/Continuous%20integration/badge.svg?branch=master
|
|
: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
|
|
----------
|
|
|
|
- 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`.
|
|
|
|
- ``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
|
|
|
|
- ``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
|
|
|
|
How to use with cargo
|
|
---------------------
|
|
|
|
::
|
|
|
|
[dependencies]
|
|
ndarray = "0.15.0"
|
|
|
|
How to enable blas integration
|
|
-----------------------------
|
|
|
|
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.15.0", features = ["blas"] }
|
|
blas-src = { version = "0.8", 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.15.0", features = ["blas"] }
|
|
blas-src = { version = "0.8.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.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
|
|
=========== ============ ================ ==============
|
|
|
|
Recent Changes
|
|
--------------
|
|
|
|
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.
|
|
|