Mathematical Operations

Numerics.NET provides methods for all common operations on tensors. Where applicable, overloaded operator methods are supplied for languages that support them, including element-wise operators in F#. In addition, a series of instance methods have been defined. These provide more efficient use of resources. All instance methods return a reference to the (modified) instance. This enables their use in compound expressions.

All standard operations are performed elementwise. In particular, both multiplication and division are performed elementwise and do not perform matrix products or solve natrix equations.

All operations can be performed on any combination of tensor types. The return value is always an instance of type Tensor<T>. The actual return value is of a derived type that is chosen for optimal performance.

Operators

If the corresponding operation on scalars has an operator, then the same operator can be used to perform the operation on corresponding elements of two tensors.

var a = Tensor.CreateFromArray([1, 2, 3]);
var b = Tensor.CreateFromArray([2, 3, 4]);
var c = a + b;
// c -> [ 3, 5, 7 ]
var d = -a;
// d -> [ -1, -2, -3 ]

Dim a = Tensor.CreateFromArray({ 1, 2, 3 })
Dim b = Tensor.CreateFromArray({ 2, 3, 4 })
Dim c = a + b
' c -> [ 3, 5, 7 ]
Dim d = -a
' d -> [ -1, -2, -3 ]

No code example is currently available or this language may not be supported.

let a = Tensor.CreateFromArray([|1; 2; 3|])
let b = Tensor.CreateFromArray([|2; 3; 4|])
let c = a + b
// c -> [ 3, 5, 7 ]
let d = -a
// d -> [ -1, -2, -3 ]
//

For binary operations, one of the operands can be a scalar. In this case, the scalar is treated as if it is a tensor with the same value everywhere and of the same shape as the other operand.

var e = a + 4;
// e -> [ 5, 6, 7 ]

Dim e = a + 4
' e -> [ 5, 6, 7 ]

No code example is currently available or this language may not be supported.

let e = a + 4
// e -> [ 5, 6, 7 ]
//

Static methods

Every operation has a static method in the Tensor class that names the operation, for example Tensor.Add<T>(Tensor<T>, Tensor<T>, Tensor<T>, Tensor<Boolean>, TensorElementOrder). These methods take the element type of the tensors as a generic type argument. In nearly all cases, the element type can be inferred and the type argument can be omitted.

They take the arguments of the operation as required parameters, which may be followed by a number of optional arguments:

result

A tensor that is to hold the result of the operation. The default is null. If given, the tensor must have compatible dimensions.

mask

A boolean tensor that specifies the locations where the operation should be performed. The shape of this tensor must be compatible with the other arguments and (if present) the result. Only locations where this tensor is true are included in the operation. Otherwise, the result is unchanged.

order

When the result is omitted or null, this argument specifies the desired layout of the result. The default is C-style (row-major) order.

These methods are useful to reuse an existing tensor instance, to avoid unnecessary memory allocation.

Tensor.Add(a, b, d);
// d -> [ 3, 5, 7 ]
var mask = Tensor.CreateFromArray([true, false, true]);
Tensor.Add(a, 4, e, mask: mask);
// e -> [ 5, 2, 7 ]

Tensor.Add(a, b, d)
' d -> [ 3, 5, 7 ]
Dim mask = Tensor.CreateFromArray({ true, false, true })
Tensor.Add(a, 4, e, mask := mask)
' e -> [ 5, 2, 7 ]

No code example is currently available or this language may not be supported.

ignore (Tensor.Add(a, b, d))
// d -> [ 3, 5, 7 ]
let mask = Tensor.CreateFromArray([| true; false; true |])
ignore (Tensor.Add(a, 4, e, mask))
// e -> [ 5, 2, 7 ]
//

In-place operations

C# and Visual Basic do not support overloading of compound assignment operators like +=. Instead, an expression like a += b is interpreted as a = a + b. For tensors, this means that a new tensor is created and assigned to the variable in the left-hand side. It is often more efficient to explicitly specify that the operation should be performed in-place.

To this end, most operations have an instance method in the Tensor<T> class that names the operation and has an InPlace suffix, for example Tensor<T>.AddInPlace(T, Tensor<Boolean>). These methods perform the operation in-place, directly on the instance they are called on, and also return the instance. In-place operations support a condition argument.

a.AddInPlace(4);
// a -> [ 5, 6, 7 ]
b.NegateInPlace(mask: mask);
// b -> [ -2, 3, -4 ]

a.AddInPlace(4)
' a -> [ 5, 6, 7 ]
b.NegateInPlace(mask := mask)
' b -> [ -2, 3, -4 ]

No code example is currently available or this language may not be supported.

ignore (a.AddInPlace(4))
// a -> [ 5, 6, 7 ]
ignore (b.NegateInPlace(mask=mask))
// b -> [ -2, 3, -4 ]
//

Relational operators

Relational operators require some special attention because their meaning is somewhat ambiguous.

The == and != (or <>) operators retain their usual meaning. Two tensors compare as equal if they have the same shape and all corresponding elements are equal. Otherwise they compare as not equal.

To obtain an elementwise comparison that compares corresponding elements and returns a tensor of boolean values, use the EqualTo or the NotEqualTo method.

Other relational operators (<, <=, >, >=) operate elementwise and return a tensor of boolean values.

a = Tensor.CreateFromArray([5, 6, 7]);
b = Tensor.CreateFromArray([3, 5, 7]);
var x = a == b;
// x -> false
var y = Tensor.EqualTo(a, b);
// y -> [ false, false, true ]
var z = a > b;
// a -> [ true, true, false ]

a = Tensor.CreateFromArray({ 5, 6, 7 })
b = Tensor.CreateFromArray({ 3, 5, 7 })
Dim x = a = b
' x -> false
Dim y = Tensor.EqualTo(a, b)
' y -> [ false, false, true ]
Dim z = a > b
' a -> [ true, true, false ]

No code example is currently available or this language may not be supported.

let a = Tensor.CreateFromArray([| 5; 6; 7 |])
let b = Tensor.CreateFromArray([| 3; 5; 7 |])
let x = a = b
// x -> false
let y = Tensor.EqualTo(a, b)
// y -> [ false, false, true ]
let z = a > b
// a -> [ true, true, false ]
//

Mixing operand types

Operations on tensors are generally defined only for tensors with the same element type. In some cases it can be useful to mix operands of different types. For example, you may want to add a tensor of integers to a tensor of floating-point numbers. This can be done by explicitly converting one of the operands to the other type using the As method. This method returns a new tensor of the specified type that shares its storage with the original tensor and converts the elements only as needed.

var t1 = Tensor.CreateFromArray([0.5, 1.5, 2.5]);
a = Tensor.CreateFromArray([1, 2, 3]);
var t2 = t1 + a.As<double>();
// t2 -> [ 1.5, 3.5, 5.5 ]

Dim t1 = Tensor.CreateFromArray({ 0.5, 1.5, 2.5 })
a = Tensor.CreateFromArray({1, 2, 3})
Dim t2 = t1 + a.As(Of double)()
' t2 -> [ 1.5, 3.5, 5.5 ]

No code example is currently available or this language may not be supported.

let t1 = Tensor.CreateFromArray([| 0.5; 1.5; 2.5 |])
let a = Tensor.CreateFromArray([| 1; 2; 3 |])
let t2 = t1 + a.As<double>()
// t2 -> [ 1.5, 3.5, 5.5 ]
//

Besides the usual binary operators, several common compound operations are supported. The following tables list the main methods for addition and subtraction:

Arithmetic Operators

Relational operators

The operators in this section are all element-wise. They return a Boolean tensor with the result of comparing the corresponding elements of two tensors, or the corresponding element of a tensor and a fixed scalar. Also listed here are the Max(a, b) and Min(a, b) methods, which follow the same pattern.

Each relational method comes in three flavors: one comparing a tensor to a tensor, one comparing a scalar to a tensor, and one comparing a tensor to a scalar. The table below lists the main functions.

Basic functions

The table below lists a number of basic functions that don't qualify as operators but also aren't elementary functions.

Elementary functions

The table below lists the elementary functions available for tensors.