Struct Array

pub struct Array { /* private fields */ }

An n-dimensional differentiable array. Stored in row-major order.

Examples

use corgi::array::*;

let a = arr![arr![1.0, 2.0, 3.0], arr![4.0, 5.0, 6.0]];
let b = arr![arr![3.0, 2.0, 1.0], arr![6.0, 5.0, 4.0]];

let mut p = &a * &b;
p.backward(None);

Implementations

impl Array

pub fn reciprocal(&self) -> Array

Computes the reciprocal of each value in the array.

pub fn powf(&self, exponent: Float) -> Array

Raises the array to the specified exponent.

pub fn ln(&self) -> Array

Computes the natural logarithm of all values of the array.

pub fn exp(&self) -> Array

Computes the exponential of all values of the array.

pub fn sum(&self, dimension_count: usize) -> Array

Sums along the last dimension_count dimensions.

pub fn sum_all(&self) -> Float

Sums all the values of the array.

impl Array

pub fn conv(&self, filters: &Array, stride_dimensions: (usize, usize)) -> Array

Computes the image convolution of the array with the filter.

impl Array

pub fn reshape(&self, dimensions: Vec<usize>) -> Array

Reshapes the array into different dimensions

pub fn axpy(alpha: Float, x: &Array, y: &Array) -> Array

Computes the element-wise alpha * x + y, for each matching dimension not multiplied.

pub fn matmul(a: (&Array, bool), b: (&Array, bool), c: Option<&Array>) -> Array

Computes matrix multiplications on two arrays, for each matching dimension not multiplied.

Arguments

a - The LHS matrix, and whether to transpose it: (a, a_transpose). b - The RHS matrix, and whether to transpose it: (b, b_transpose). c - The output matrix, if not initialized to a zeros matrix.

impl Array

pub fn relu(&self) -> Array

Computes the ReLU of the array, defined as max(0, x) for all elements x in the array.

pub fn sigmoid(&self) -> Array

Computes the sigmoid operation on each value of the array.

pub fn softmax(&self) -> Array

Computes the softmax of the array.

impl Array

pub fn dimensions(&self) -> &[usize]

Returns a copy of the dimensions of the array.

pub fn values(&self) -> &[Float]

Returns an immutable reference to the values of the array in row-major order.

pub fn gradient(&self) -> Ref<'_, Option<Array>>

Returns a reference to the gradient option of the array.

pub fn gradient_mut(&self) -> RefMut<'_, Option<Array>>

Returns a mutable reference to the gradient option of the array.

pub fn replace_gradient(&self) -> Option<Array>

Returns the owned gradient option of the array, replacing it with nothing.

pub fn tracked(self) -> Array

Enables tracking of operations for the backward pass, meaning the backward pass will compute, and store gradients for the current array, and any children arrays which are tracked.

An operation with any positive number of tracked children will always output a tracked array.

This does not persist through threads, or through being set on a clone, meaning any tracked clones will not affect tracking of the array, apart from clones of the clone.

Examples

// only the gradient for `b`, will be stored
let mut a = arr![1.0, 2.0, 3.0].untracked();
let b = arr![3.0, 2.0, 1.0].tracked();
let mut c = &a * &b;
c.backward(None);
assert_eq!(b.gradient().to_owned().unwrap(), arr![1.0, 2.0, 3.0]);

pub fn start_tracking(&self) -> bool

Starts tracking operations for a mutable reference to an array, returning the previous value.

pub fn untracked(self) -> Array

Prevents tracking of operations for the backward pass, meaning the backward pass will skip computation of gradients for the current array, and any children arrays.

Any operation with every child untracked will always output an untracked array, and will not store any subgraph information.

This does not persist through threads, or through being set on a clone, meaning any tracked clones will not affect tracking of the array, apart from clones of the clone.

Examples

// only the gradient for `b`, will be stored
let mut a = arr![1.0, 2.0, 3.0].untracked();
let b = arr![3.0, 2.0, 1.0].tracked();
let mut c = &a * &b;
c.backward(None);
assert_eq!(b.gradient().to_owned().unwrap(), arr![1.0, 2.0, 3.0]);

pub fn stop_tracking(&self) -> bool

Stops tracking operations for a mutable reference to an array, returning the previous value. Useful for temporarily updating parameters without requiring their gradients.

pub fn backward(&self, delta: Option<Array>)

Computes the backward pass, computing gradients for all descendants, and propagating consumer counts if requested.

Panics

Panics if the current node has children, but is not a differentiable function (is not a leaf).

pub fn op( arrays: &[&Array], op: ForwardOp, backward_op: Option<BackwardOp>, ) -> Array

Computes an operation on arrays.

Arguments

• arrays - The arrays to perform the operations on.
• op - The ForwardOp, which takes in the arrays, and outputs another array.
• backward_op - The BackwardOp, which takes in the arrays, and the delta, and outputs a new delta, with respect to each input. It is recommended that any array operations here are untracked, unless interested in higher order derivatives.

Examples

let mul: ForwardOp = Rc::new(|x: &[&Array]| {
    Array::from((x[0].dimensions().to_vec(), x[0].values().iter().zip(x[1].values()).map(|(x, y)| x * y).collect::<Vec<Float>>()))
});

let mul_clone = Rc::clone(&mul);
let backward_op: BackwardOp = Rc::new(move |children, is_tracked, delta| {
    vec![
        if is_tracked[0] {
            Some(Array::op(&[&children[1], delta], Rc::clone(&mul_clone), None))
        } else {
            None
        },
        if is_tracked[1] {
            Some(Array::op(&[&children[0], delta], Rc::clone(&mul_clone), None))
        } else {
            None
        }
    ]
});

let a = arr![1.0, 2.0, 3.0].tracked();
let b = arr![3.0, 2.0, 1.0].tracked();
let product = Array::op(&vec![&a, &b], mul, Some(backward_op));
assert_eq!(product, arr![3.0, 4.0, 3.0]);
product.backward(None);
assert_eq!(product.gradient().to_owned().unwrap(), arr![1.0, 1.0, 1.0]);
assert_eq!(b.gradient().to_owned().unwrap(), arr![1.0, 2.0, 3.0]);
assert_eq!(a.gradient().to_owned().unwrap(), arr![3.0, 2.0, 1.0]);

Trait Implementations

impl AbsDiffEq for Array

type Epsilon = <f64 as AbsDiffEq>::Epsilon

Used for specifying relative comparisons.

fn default_epsilon() -> <Float as AbsDiffEq>::Epsilon

The default tolerance to use when testing values that are close together.

fn abs_diff_eq( &self, other: &Array, epsilon: <Float as AbsDiffEq>::Epsilon, ) -> bool

A test for equality that uses the absolute difference to compute the approximate equality of two numbers.

fn abs_diff_ne(&self, other: &Rhs, epsilon: Self::Epsilon) -> bool

The inverse of AbsDiffEq::abs_diff_eq.

impl Add<&Array> for &Array

type Output = Array

The resulting type after applying the + operator.

fn add(self, other: &Array) -> Self::Output

Performs the + operation.

impl Clone for Array

fn clone(&self) -> Array

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Array

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Div<&Array> for &Array

type Output = Array

The resulting type after applying the / operator.

fn div(self, other: &Array) -> Self::Output

Performs the / operation.

impl From<(Vec<usize>, Rc<Vec<f64>>)> for Array

fn from(items: (Vec<usize>, Rc<Vec<Float>>)) -> Self

Converts to this type from the input type.

impl From<(Vec<usize>, Vec<f64>)> for Array

Implementation to construct Array structs by using Vec<usize> as the dimensions, and Vec<Float> as the values.

Examples

let a = Array::from((vec![2, 3], vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]));
assert_eq!(a[vec![1, 2]], 6.0);

fn from(items: (Vec<usize>, Vec<Float>)) -> Self

Converts to this type from the input type.

impl From<Vec<Array>> for Array

Implementation to construct Array structs by flattening other contained Array structs, and keeping their dimensions.

Examples

let a = Array::from(vec![arr![1.0, 2.0, 3.0], arr![4.0, 5.0, 6.0]]);
assert_eq!(a[vec![1, 2]], 6.0);

fn from(contents: Vec<Array>) -> Self

Converts to this type from the input type.

impl From<Vec<f64>> for Array

Implementation to construct Array structs by using Vec<Float> as the values, and by keeping flat dimensions.

Examples

let a = Array::from(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
assert_eq!(a[vec![5]], 6.0);

fn from(values: Vec<Float>) -> Self

Converts to this type from the input type.

impl From<Vec<usize>> for Array

Implementation to construct Array structs by using Vec<usize> as the dimensions, and filling values with zeros.

Examples

let a = Array::from(vec![3, 2, 3]);
assert_eq!(a[vec![2, 1, 1]], 0.0);

fn from(dimensions: Vec<usize>) -> Self

Converts to this type from the input type.

impl Index<Vec<usize>> for Array

type Output = f64

The returned type after indexing.

fn index(&self, indices: Vec<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<usize> for Array

type Output = f64

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Into<Vec<f64>> for Array

fn into(self) -> Vec<Float>

Converts this type into the (usually inferred) input type.

impl Mul<&Array> for &Array

type Output = Array

The resulting type after applying the * operator.

fn mul(self, other: &Array) -> Self::Output

Performs the * operation.

impl Mul<&Array> for Float

type Output = Array

The resulting type after applying the * operator.

fn mul(self, other: &Array) -> Self::Output

Performs the * operation.

impl Mul<f64> for &Array

type Output = Array

The resulting type after applying the * operator.

fn mul(self, other: Float) -> Self::Output

Performs the * operation.

impl Neg for &Array

type Output = Array

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl PartialEq for Array

fn eq(&self, other: &Array) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RelativeEq for Array

fn default_max_relative() -> <Float as AbsDiffEq>::Epsilon

The default relative tolerance for testing values that are far-apart.

fn relative_eq( &self, other: &Array, epsilon: <Float as AbsDiffEq>::Epsilon, max_relative: <Float as AbsDiffEq>::Epsilon, ) -> bool

A test for equality that uses a relative comparison if the values are far apart.

fn relative_ne( &self, other: &Rhs, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

The inverse of RelativeEq::relative_eq.

impl Sub<&Array> for &Array

type Output = Array

The resulting type after applying the - operator.

fn sub(self, other: &Array) -> Self::Output

Performs the - operation.