If you are familiar with Python Numpy, do check out this For Numpy User Doc after you go through this tutorial.
You can use play.integer32.com to immediately try out the examples.
You can create your first 2x3 floating-point ndarray as such:
use ndarray::prelude::*;
fn main() {
let a = array![
[1.,2.,3.],
[4.,5.,6.],
];
assert_eq!(a.ndim(), 2); // get the number of dimensions of array a
assert_eq!(a.len(), 6); // get the number of elements in array a
assert_eq!(a.shape(), [2, 3]); // get the shape of array a
assert_eq!(a.is_empty(), false); // check if the array has zero elements
println!("{:?}", a);
}This code will create a simple array, then print it to stdout as such:
[[1.0, 2.0, 3.0],
[4.0, 5.0, 6.0]], shape=[2, 3], strides=[3, 1], layout=C (0x1), const ndim=2
Now let's create more arrays. A common operation on matrices is to create a matrix full of 0's of certain dimensions. Let's try to do that with dimensions (3, 2, 4) using the Array::zeros function:
use ndarray::prelude::*;
use ndarray::Array;
fn main() {
let a = Array::zeros((3, 2, 4).f());
println!("{:?}", a);
}Unfortunately, this code does not compile.
| let a = Array::zeros((3, 2, 4).f());
| - ^^^^^^^^^^^^ cannot infer type for type parameter `A`
Indeed, note that the compiler needs to infer the element type and dimensionality from context only. In this case the compiler does not have enough information. To fix the code, we can explicitly give the element type through turbofish syntax, and let it infer the dimensionality type:
use ndarray::prelude::*;
use ndarray::Array;
fn main() {
let a = Array::<f64, _>::zeros((3, 2, 4).f());
println!("{:?}", a);
}This code now compiles to what we wanted:
[[[0.0, 0.0, 0.0, 0.0],
[0.0, 0.0, 0.0, 0.0]],
[[0.0, 0.0, 0.0, 0.0],
[0.0, 0.0, 0.0, 0.0]],
[[0.0, 0.0, 0.0, 0.0],
[0.0, 0.0, 0.0, 0.0]]], shape=[3, 2, 4], strides=[1, 3, 6], layout=F (0x2), const ndim=3
We could also specify its dimensionality explicitly Array::<f64, Ix3>::zeros(...), withIx3 standing for 3D array type. Phew! We achieved type safety. If you tried changing the code above to Array::<f64, Ix3>::zeros((3, 2, 4, 5).f());, which is not of dimension 3 anymore, Rust's type system would gracefully prevent you from compiling the code.
The from_elem method allows initializing an array of given dimension to a specific value of any type:
use ndarray::{Array, Ix3};
fn main() {
let a = Array::<bool, Ix3>::from_elem((3, 2, 4), false);
println!("{:?}", a);
}linspace - Create a 1-D array with 11 elements with values 0., …, 5.
use ndarray::prelude::*;
use ndarray::{Array, Ix3};
fn main() {
let a = Array::<f64, _>::linspace(0., 5., 11);
println!("{:?}", a);
}The output is:
[0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0], shape=[11], strides=[1], layout=C | F (0x3), const ndim=1
Common array initializing methods include range, logspace, eye, ones...
Basic operations on arrays are all element-wise; you need to use specific methods for operations such as matrix multiplication (see later section).
use ndarray::prelude::*;
use ndarray::Array;
use std::f64::INFINITY as inf;
fn main() {
let a = array![
[10.,20.,30., 40.,],
];
let b = Array::range(0., 4., 1.); // [0., 1., 2., 3, ]
assert_eq!(&a + &b, array![[10., 21., 32., 43.,]]); // Allocates a new array. Note the explicit `&`.
assert_eq!(&a - &b, array![[10., 19., 28., 37.,]]);
assert_eq!(&a * &b, array![[0., 20., 60., 120.,]]);
assert_eq!(&a / &b, array![[inf, 20., 15., 13.333333333333334,]]);
}Note that (for any binary operator @):
&A @ &Aproduces a newArrayB @ AconsumesB, updates it with the result, and returns itB @ &AconsumesB, updates it with the result, and returns itC @= &Aperforms an arithmetic operation in place
Try removing all the & sign in front of a and b in the last example: it will not compile anymore because of those rules.
For more info checkout https://docs.rs/ndarray/latest/ndarray/struct.ArrayBase.html#arithmetic-operations
Some operations have _axis appended to the function name: they generally take in a parameter of type Axis as one of their inputs,
such as sum_axis:
use ndarray::{aview0, aview1, arr2, Axis};
fn main() {
let a = arr2(&[[1., 2., 3.],
[4., 5., 6.]]);
assert!(
a.sum_axis(Axis(0)) == aview1(&[5., 7., 9.]) &&
a.sum_axis(Axis(1)) == aview1(&[6., 15.]) &&
a.sum_axis(Axis(0)).sum_axis(Axis(0)) == aview0(&21.) &&
a.sum_axis(Axis(0)).sum_axis(Axis(0)) == aview0(&a.sum())
);
}use ndarray::prelude::*;
use ndarray::Array;
fn main() {
let a = array![
[10.,20.,30., 40.,],
];
let b = Array::range(0., 4., 1.); // b = [0., 1., 2., 3, ]
println!("a shape {:?}", &a.shape());
println!("b shape {:?}", &b.shape());
let b = b.into_shape_with_order((4,1)).unwrap(); // reshape b to shape [4, 1]
println!("b shape after reshape {:?}", &b.shape());
println!("{}", a.dot(&b)); // [1, 4] x [4, 1] -> [1, 1]
println!("{}", a.t().dot(&b.t())); // [4, 1] x [1, 4] -> [4, 4]
}The output is:
a shape [1, 4]
b shape [4]
b shape after reshape [4, 1]
[[200]]
[[0, 10, 20, 30],
[0, 20, 40, 60],
[0, 30, 60, 90],
[0, 40, 80, 120]]
One-dimensional arrays can be indexed, sliced and iterated over, much like numpy arrays
use ndarray::prelude::*;
use ndarray::Array;
fn main() {
let a = Array::range(0., 10., 1.);
let mut a = a.mapv(|a: f64| a.powi(3)); // numpy equivlant of `a ** 3`; https://doc.rust-lang.org/nightly/std/primitive.f64.html#method.powi
println!("{}", a);
println!("{}", a[[2]]);
println!("{}", a.slice(s![2]));
println!("{}", a.slice(s![2..5]));
a.slice_mut(s![..6;2]).fill(1000.); // numpy equivlant of `a[:6:2] = 1000`
println!("{}", a);
for i in a.iter() {
print!("{}, ", i.powf(1./3.))
}
}The output is:
[0, 1, 8, 27, 64, 125, 216, 343, 512, 729]
8
8
[8, 27, 64]
[1000, 1, 1000, 27, 1000, 125, 216, 343, 512, 729]
9.999999999999998, 1, 9.999999999999998, 3, 9.999999999999998, 4.999999999999999, 5.999999999999999, 6.999999999999999, 7.999999999999999, 8.999999999999998,
For more info about iteration see Loops, Producers, and Iterators
Let's try a iterating over a 3D array with elements of type isize. This is how you index it:
use ndarray::prelude::*;
fn main() {
let a = array![
[[ 0, 1, 2], // a 3D array 2 x 2 x 3
[ 10, 12, 13]],
[[100,101,102],
[110,112,113]]
];
let a = a.mapv(|a: isize| a.pow(1)); // numpy equivalent of `a ** 1`;
// This line does nothing except illustrating mapv with isize type
println!("a -> \n{}\n", a);
println!("`a.slice(s![1, .., ..])` -> \n{}\n", a.slice(s![1, .., ..]));
println!("`a.slice(s![.., .., 2])` -> \n{}\n", a.slice(s![.., .., 2]));
println!("`a.slice(s![.., 1, 0..2])` -> \n{}\n", a.slice(s![.., 1, 0..2]));
println!("`a.iter()` ->");
for i in a.iter() {
print!("{}, ", i) // flat out to every element
}
println!("\n\n`a.outer_iter()` ->");
for i in a.outer_iter() {
print!("row: {}, \n", i) // iterate through first dimension
}
}The output is:
a ->
[[[0, 1, 2],
[10, 12, 13]],
[[100, 101, 102],
[110, 112, 113]]]
`a.slice(s![1, .., ..])` ->
[[100, 101, 102],
[110, 112, 113]]
`a.slice(s![.., .., 2])` ->
[[2, 13],
[102, 113]]
`a.slice(s![.., 1, 0..2])` ->
[[10, 12],
[110, 112]]
`a.iter()` ->
0, 1, 2, 10, 12, 13, 100, 101, 102, 110, 112, 113,
`a.outer_iter()` ->
row: [[0, 1, 2],
[10, 12, 13]],
row: [[100, 101, 102],
[110, 112, 113]],
The shape of an array can be changed with the into_shape_with_order or to_shape method.
use ndarray::prelude::*;
use ndarray::Array;
use std::iter::FromIterator;
// use ndarray_rand::RandomExt;
// use ndarray_rand::rand_distr::Uniform;
fn main() {
// Or you may use ndarray_rand crate to generate random arrays
// let a = Array::random((2, 5), Uniform::new(0., 10.));
let a = array![
[3., 7., 3., 4.],
[1., 4., 2., 2.],
[7., 2., 4., 9.]];
println!("a = \n{:?}\n", a);
// use trait FromIterator to flatten a matrix to a vector
let b = Array::from_iter(a.iter());
println!("b = \n{:?}\n", b);
let c = b.into_shape_with_order([6, 2]).unwrap(); // consume b and generate c with new shape
println!("c = \n{:?}", c);
}The output is:
a =
[[3.0, 7.0, 3.0, 4.0],
[1.0, 4.0, 2.0, 2.0],
[7.0, 2.0, 4.0, 9.0]], shape=[3, 4], strides=[4, 1], layout=C (0x1), const ndim=2
b =
[3.0, 7.0, 3.0, 4.0, 1.0, 4.0, 2.0, 2.0, 7.0, 2.0, 4.0, 9.0], shape=[12], strides=[1], layout=C | F (0x3), const ndim=1
c =
[[3.0, 7.0],
[3.0, 4.0],
[1.0, 4.0],
[2.0, 2.0],
[7.0, 2.0],
[4.0, 9.0]], shape=[6, 2], strides=[2, 1], layout=C (0x1), const ndim=2
The stack! and concatenate! macros are helpful for stacking/concatenating
arrays. The stack! macro stacks arrays along a new axis, while the
concatenate! macro concatenates arrays along an existing axis:
use ndarray::prelude::*;
use ndarray::{concatenate, stack, Axis};
fn main() {
let a = array![
[3., 7., 8.],
[5., 2., 4.],
];
let b = array![
[1., 9., 0.],
[5., 4., 1.],
];
println!("stack, axis 0:\n{:?}\n", stack![Axis(0), a, b]);
println!("stack, axis 1:\n{:?}\n", stack![Axis(1), a, b]);
println!("stack, axis 2:\n{:?}\n", stack![Axis(2), a, b]);
println!("concatenate, axis 0:\n{:?}\n", concatenate![Axis(0), a, b]);
println!("concatenate, axis 1:\n{:?}\n", concatenate![Axis(1), a, b]);
}The output is:
stack, axis 0:
[[[3.0, 7.0, 8.0],
[5.0, 2.0, 4.0]],
[[1.0, 9.0, 0.0],
[5.0, 4.0, 1.0]]], shape=[2, 2, 3], strides=[6, 3, 1], layout=Cc (0x5), const ndim=3
stack, axis 1:
[[[3.0, 7.0, 8.0],
[1.0, 9.0, 0.0]],
[[5.0, 2.0, 4.0],
[5.0, 4.0, 1.0]]], shape=[2, 2, 3], strides=[3, 6, 1], layout=c (0x4), const ndim=3
stack, axis 2:
[[[3.0, 1.0],
[7.0, 9.0],
[8.0, 0.0]],
[[5.0, 5.0],
[2.0, 4.0],
[4.0, 1.0]]], shape=[2, 3, 2], strides=[1, 2, 6], layout=Ff (0xa), const ndim=3
concatenate, axis 0:
[[3.0, 7.0, 8.0],
[5.0, 2.0, 4.0],
[1.0, 9.0, 0.0],
[5.0, 4.0, 1.0]], shape=[4, 3], strides=[3, 1], layout=Cc (0x5), const ndim=2
concatenate, axis 1:
[[3.0, 7.0, 8.0, 1.0, 9.0, 0.0],
[5.0, 2.0, 4.0, 5.0, 4.0, 1.0]], shape=[2, 6], strides=[1, 2], layout=Ff (0xa), const ndim=2
More to see here ArrayView::split_at
use ndarray::prelude::*;
use ndarray::Axis;
fn main() {
let a = array![
[6., 7., 6., 9., 0., 5., 4., 0., 6., 8., 5., 2.],
[8., 5., 5., 7., 1., 8., 6., 7., 1., 8., 1., 0.]];
let (s1, s2) = a.view().split_at(Axis(0), 1);
println!("Split a from Axis(0), at index 1:");
println!("s1 = \n{}", s1);
println!("s2 = \n{}\n", s2);
let (s1, s2) = a.view().split_at(Axis(1), 4);
println!("Split a from Axis(1), at index 4:");
println!("s1 = \n{}", s1);
println!("s2 = \n{}\n", s2);
}The output is:
Split a from Axis(0), at index 1:
s1 =
[[6, 7, 6, 9, 0, 5, 4, 0, 6, 8, 5, 2]]
s2 =
[[8, 5, 5, 7, 1, 8, 6, 7, 1, 8, 1, 0]]
Split a from Axis(1), at index 4:
s1 =
[[6, 7, 6, 9],
[8, 5, 5, 7]]
s2 =
[[0, 5, 4, 0, 6, 8, 5, 2],
[1, 8, 6, 7, 1, 8, 1, 0]]
Rust has ownership, so we cannot simply update an element of an array while we have a shared view of it. This brings guarantees & helps having more robust code.
use ndarray::prelude::*;
use ndarray::{Array, Axis};
fn main() {
let mut a = Array::range(0., 12., 1.).into_shape_with_order([3 ,4]).unwrap();
println!("a = \n{}\n", a);
{
let (s1, s2) = a.view().split_at(Axis(1), 2);
// with s as a view sharing the ref of a, we cannot update a here
// a.slice_mut(s![1, 1]).fill(1234.);
println!("Split a from Axis(0), at index 1:");
println!("s1 = \n{}", s1);
println!("s2 = \n{}\n", s2);
}
// now we can update a again here, as views of s1, s2 are dropped already
a.slice_mut(s![1, 1]).fill(1234.);
let (s1, s2) = a.view().split_at(Axis(1), 2);
println!("Split a from Axis(0), at index 1:");
println!("s1 = \n{}", s1);
println!("s2 = \n{}\n", s2);
}The output is:
a =
[[0, 1, 2, 3],
[4, 5, 6, 7],
[8, 9, 10, 11]]
Split a from Axis(0), at index 1:
s1 =
[[0, 1],
[4, 5],
[8, 9]]
s2 =
[[2, 3],
[6, 7],
[10, 11]]
Split a from Axis(0), at index 1:
s1 =
[[0, 1],
[4, 1234],
[8, 9]]
s2 =
[[2, 3],
[6, 7],
[10, 11]]
As the usual way in Rust, a clone() call will
make a copy of your array:
use ndarray::prelude::*;
use ndarray::Array;
fn main() {
let mut a = Array::range(0., 4., 1.).into_shape_with_order([2 ,2]).unwrap();
let b = a.clone();
println!("a = \n{}\n", a);
println!("b clone of a = \n{}\n", a);
a.slice_mut(s![1, 1]).fill(1234.);
println!("a updated...");
println!("a = \n{}\n", a);
println!("b clone of a = \n{}\n", b);
}The output is:
a =
[[0, 1],
[2, 3]]
b clone of a =
[[0, 1],
[2, 3]]
a updated...
a =
[[0, 1],
[2, 1234]]
b clone of a =
[[0, 1],
[2, 3]]
Notice that using clone() (or cloning) an Array type also copies the array's elements. It creates an independently owned array of the same type.
Cloning an ArrayView does not clone or copy the underlying elements - it only clones the view reference (as it happens in Rust when cloning a & reference).
Arrays support limited broadcasting, where arithmetic operations with array operands of different sizes can be carried out by repeating the elements of the smaller dimension array.
use ndarray::prelude::*;
fn main() {
let a = array![
[1., 1.],
[1., 2.],
[0., 3.],
[0., 4.]];
let b = array![[0., 1.]];
let c = array![
[1., 2.],
[1., 3.],
[0., 4.],
[0., 5.]];
// We can add because the shapes are compatible even if not equal.
// The `b` array is shape 1 × 2 but acts like a 4 × 2 array.
assert!(c == a + b);
}See .broadcast() for a more detailed description.
And here is a short example of it:
use ndarray::prelude::*;
fn main() {
let a = array![
[1., 2.],
[3., 4.],
];
let b = a.broadcast((3, 2, 2)).unwrap();
println!("shape of a is {:?}", a.shape());
println!("a is broadcased to 3x2x2 = \n{}", b);
}The output is:
shape of a is [2, 2]
a is broadcased to 3x2x2 =
[[[1, 2],
[3, 4]],
[[1, 2],
[3, 4]],
[[1, 2],
[3, 4]]]
Please checkout these docs for more information