219 lines
10 KiB
Factor
219 lines
10 KiB
Factor
! Copyright (C) 2019 HMC Clinic.
|
|
! See http://factorcode.org/license.txt for BSD license.
|
|
USING: arrays help.markup help.syntax lexer math sequences ;
|
|
IN: tensors
|
|
|
|
ARTICLE: "tensors" "Tensors"
|
|
"A " { $snippet "tensor" } " is a sequence of floating point numbers "
|
|
"shaped into an n-dimensional matrix. It supports fast, scalable matrix "
|
|
"operations such as matrix multiplication and transposition as well as a "
|
|
"number of element-wise operations. Words for working with tensors are found "
|
|
"in the " { $vocab-link "tensors" } " vocabulary." $nl
|
|
"More information about tensors can be found here:"
|
|
{ $subsections "creation" "manipulation" } ;
|
|
|
|
ARTICLE: "creation" "Creating Tensors"
|
|
"Tensors can be created by calling one of following constructors:"
|
|
{ $subsections zeros ones naturals arange (tensor) }
|
|
"They can be converted to/from the corresponding N-dimensional array with"
|
|
{ $subsections tensor>array >tensor }
|
|
"There is also a tensor parsing word"
|
|
{ $subsections POSTPONE: t{ } ;
|
|
|
|
ARTICLE: "manipulation" "Manipulating Tensors"
|
|
"The number of dimensions can be extracted with:"
|
|
{ $subsections dims }
|
|
"Tensors can be reshaped with:"
|
|
{ $subsections reshape flatten }
|
|
"Tensors can be combined element-wise with other tensors as well as numbers with:"
|
|
{ $subsections t+ t- t* t/ t% }
|
|
"Tensors support the following matrix operations:"
|
|
{ $subsections matmul transpose }
|
|
"Tensors also support the following concatenation operations:"
|
|
{ $subsections stack hstack vstack t-concat }
|
|
"Tensors implement all " { $vocab-link "sequences" } " operations." $nl
|
|
"Tensors can be indexed into using either numbers or arrays, for example:"
|
|
{ $example
|
|
"USING: prettyprint sequences tensors ;"
|
|
"t{ { 0.0 1.0 2.0 } { 3.0 4.0 5.0 } }"
|
|
"[ { 1 1 } swap nth ] [ 4 swap nth ] bi = ."
|
|
"t"
|
|
}
|
|
"If the array being used to index into the tensor has the wrong number "
|
|
"of dimensions, a " { $link dimension-mismatch-error } " will be thrown." ;
|
|
|
|
ARTICLE: "tensor-operators" "Tensor Operators" "Info here" ;
|
|
|
|
HELP: tensor
|
|
{ $class-description "A sequence of floating-point numbers consisting of an "
|
|
{ $snippet "underlying" } " C-style array and a " { $snippet "shape" } "." } ;
|
|
|
|
HELP: shape-mismatch-error
|
|
{ $values { "shape1" sequence } { "shape2" sequence } }
|
|
{ $description "Throws a " { $link shape-mismatch-error } "." }
|
|
{ $error-description "Thrown by element-wise operations such as " { $link t+ }
|
|
", " { $link t- } ", " { $link t* } ", " { $link t/ } ", and " { $link t% }
|
|
" as well as matrix operations such as " { $link matmul } " if two tensors are "
|
|
"passed and they cannot be combined as desired because of a difference in the "
|
|
"shape." } ;
|
|
|
|
HELP: non-positive-shape-error
|
|
{ $values { "shape" sequence } }
|
|
{ $description "Throws a " { $link non-positive-shape-error } "." }
|
|
{ $error-description "Thrown by operations such as " { $link zeros } ", "
|
|
{ $link ones } ", " { $link naturals } ", and " { $link reshape }
|
|
", which allow users to directly set the shape of a " { $link tensor }
|
|
", when the shape has zero or negative values." } ;
|
|
|
|
HELP: non-uniform-seq-error
|
|
{ $values { "seq" sequence } }
|
|
{ $description "Throws a " { $link non-uniform-seq-error } "." }
|
|
{ $error-description "Thrown by operations such as " { $link >tensor }
|
|
", which allow users to directly input the values of a " { $link tensor }
|
|
" as a nested sequence, when the subsequences have varying lengths." } ;
|
|
|
|
HELP: dimension-mismatch-error
|
|
{ $values { "tensor-dim" number } { "index-dim" number } }
|
|
{ $description "Throws a " { $link dimension-mismatch-error } "." }
|
|
{ $error-description "Thrown by indexing operations such as " { $link nth }
|
|
" and " { $link set-nth } " if the array being used to index has a different number "
|
|
"of dimensions than the tensor." } ;
|
|
|
|
HELP: t{
|
|
{ $syntax "t{ elements... }" }
|
|
{ $values { "elements" "a list of numbers" } }
|
|
{ $description "Initializes a tensor with the given elements."
|
|
" Preserves the shape of nested sequences. Assumes uniformly nested sequences." }
|
|
{ $errors "Throws a " { $link non-uniform-seq-error } " if the given "
|
|
"sequence have subsequences of varying lengths. Throws a "
|
|
{ $link lexer-error } " if the given sequence is not uniformly nested." } ;
|
|
|
|
HELP: (tensor)
|
|
{ $values { "shape" sequence } { "tensor" tensor } }
|
|
{ $description "Creates a tensor with shape " { $snippet "shape" }
|
|
" containing uninitialized values. Allows non-positive shapes." } ;
|
|
|
|
HELP: zeros
|
|
{ $values { "shape" sequence } { "tensor" tensor } }
|
|
{ $description "Initializes a tensor with shape " { $snippet "shape" }
|
|
" containing all 0s." }
|
|
{ $errors "Throws a " { $link non-positive-shape-error } " if the given "
|
|
"shape has zero or negative values." } ;
|
|
|
|
HELP: ones
|
|
{ $values { "shape" sequence } { "tensor" tensor } }
|
|
{ $description "Initializes a tensor with shape " { $snippet "shape" }
|
|
" containing all 1s." }
|
|
{ $errors "Throws a " { $link non-positive-shape-error } " if the given "
|
|
"shape has zero or negative values." } ;
|
|
|
|
HELP: arange
|
|
{ $values { "a" number } { "b" number } { "step" number } { "tensor" tensor } }
|
|
{ $description "Initializes a one-dimensional tensor with values in a range from "
|
|
{ $snippet "a" } " to " { $snippet "b" } " (inclusive) with step-size " { $snippet "step" } "." } ;
|
|
|
|
HELP: naturals
|
|
{ $values { "shape" sequence } { "tensor" tensor } }
|
|
{ $description "Initializes a tensor with shape " { $snippet "shape" }
|
|
" containing a range of values from 0 to " { $snippet "shape product" } "." }
|
|
{ $errors "Throws a " { $link non-positive-shape-error } " if the given "
|
|
"shape has zero or negative values." } ;
|
|
|
|
HELP: reshape
|
|
{ $values { "tensor" tensor } { "shape" sequence } }
|
|
{ $description "Reshapes " { $snippet "tensor" } " to have shape "
|
|
{ $snippet "shape" } "." }
|
|
{ $errors "Throws a " { $link non-positive-shape-error } " if the given "
|
|
"shape has zero or negative values." } ;
|
|
|
|
HELP: flatten
|
|
{ $values { "tensor" tensor } }
|
|
{ $description "Reshapes " { $snippet "tensor" } " so that it is one-dimensional." } ;
|
|
|
|
HELP: dims
|
|
{ $values { "tensor" tensor } { "n" integer } }
|
|
{ $description "Returns the dimension of " { $snippet "tensor" } "." } ;
|
|
|
|
HELP: >tensor
|
|
{ $values { "seq" sequence } { "tensor" tensor } }
|
|
{ $description "Turns a nested sequence " { $snippet "seq" }
|
|
" into a tensor of the corresponding shape. Assumes a uniformly nested sequence." }
|
|
{ $errors "Throws a " { $link non-uniform-seq-error } " if the given "
|
|
"sequence have subsequences of varying lengths. Throws a "
|
|
{ $link lexer-error } " if the given sequence is not uniformly nested." } ;
|
|
|
|
HELP: t+
|
|
{ $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
|
|
{ $description "Element-wise addition. Intakes two tensors or a tensor and a number (in either order)." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
|
|
"not (or cannot be broadcast to be) the same shape." } ;
|
|
|
|
HELP: t-
|
|
{ $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
|
|
{ $description "Element-wise subtraction. Intakes two tensors or a tensor and a number (in either order)." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
|
|
"not (or cannot be broadcast to be) the same shape." } ;
|
|
|
|
HELP: t*
|
|
{ $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
|
|
{ $description "Element-wise multiplication. Intakes two tensors or a tensor and a number (in either order)." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
|
|
"not (or cannot be broadcast to be) the same shape." } ;
|
|
|
|
HELP: t/
|
|
{ $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
|
|
{ $description "Element-wise division. Intakes two tensors or a tensor and a number (in either order)." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
|
|
"not (or cannot be broadcast to be) the same shape." } ;
|
|
|
|
HELP: t%
|
|
{ $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
|
|
{ $description "Element-wise modulo operator. Intakes two tensors or a tensor and a number (in either order)." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
|
|
"not (or cannot be broadcast to be) the same shape." } ;
|
|
|
|
HELP: tensor>array
|
|
{ $values { "tensor" tensor } { "seq" array } }
|
|
{ $description "Returns " { $snippet "tensor" } " as an n-dimensional array." } ;
|
|
|
|
HELP: matmul
|
|
{ $values { "tensor1" tensor } { "tensor2" tensor } { "tensor3" tensor } }
|
|
{ $description "Performs n-dimensional matrix multiplication on two tensors, where " { $snippet "tensor1" }
|
|
" has shape " { $snippet "...xmxn" } " and " { $snippet "tensor1" } " has shape " { $snippet "...xnxp" } "." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if the bottom two "
|
|
"dimensions of the tensors passed do not take the form " { $snippet "mxn" }
|
|
" and " { $snippet "nxp" } " and/or the top dimensions do not match." } ;
|
|
|
|
HELP: transpose
|
|
{ $values { "tensor" tensor } { "tensor'" tensor } }
|
|
{ $description "Performs n-dimensional matrix transposition on " { $snippet "tensor" } "." } ;
|
|
|
|
HELP: stack
|
|
{ $values { "seq" sequence } { "tensor" tensor } }
|
|
{ $description "Joins the sequences in " { $snippet "seq" } " along a new axis. "
|
|
{ $snippet "tensor" } " will have one more dimension than the arrays in " { $snippet "seq" } "." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
|
|
{ $snippet "seq" } " do not have the same shape."} ;
|
|
|
|
|
|
HELP: hstack
|
|
{ $values { "seq" sequence } { "tensor" tensor } }
|
|
{ $description "Joins the sequences in " { $snippet "seq" } " column-wise." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
|
|
{ $snippet "seq" } " do not have the same shape along all but the second axis."} ;
|
|
|
|
HELP: vstack
|
|
{ $values { "seq" sequence } { "tensor" tensor } }
|
|
{ $description "Joins the sequences in " { $snippet "seq" } " row-wise." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
|
|
{ $snippet "seq" } " do not have the same shape along all but the first axis."} ;
|
|
|
|
HELP: t-concat
|
|
{ $values { "seq" sequence } { "tensor" tensor } }
|
|
{ $description "Joins the sequences in " { $snippet "seq" } " along the first axis." }
|
|
{ $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
|
|
{ $snippet "seq" } " do not have the same shape along all but the first axis."} ;
|
|
|
|
|
|
ABOUT: "tensors"
|