extra/tensors/tensors-docs.factor

   1 ! Copyright (C) 2019 HMC Clinic.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: arrays help.markup help.syntax lexer math sequences ;
   4 IN: tensors
   5
   6 ARTICLE: "tensors" "Tensors"
   7 "A " { $snippet "tensor" } " is a sequence of floating point numbers "
   8 "shaped into an n-dimensional matrix. It supports fast, scalable matrix "
   9 "operations such as matrix multiplication and transposition as well as a "
  10 "number of element-wise operations. Words for working with tensors are found "
  11 "in the " { $vocab-link "tensors" } " vocabulary." $nl
  12 "More information about tensors can be found here:"
  13 { $subsections "creation" "manipulation" } ;
  14
  15 ARTICLE: "creation" "Creating Tensors"
  16 "Tensors can be created by calling one of following constructors:"
  17 { $subsections zeros ones naturals arange (tensor) }
  18 "They can be converted to/from the corresponding N-dimensional array with"
  19 { $subsections tensor>array >tensor }
  20 "There is also a tensor parsing word"
  21 { $subsections POSTPONE: t{ } ;
  22
  23 ARTICLE: "manipulation" "Manipulating Tensors"
  24 "The number of dimensions can be extracted with:"
  25 { $subsections dims }
  26 "Tensors can be reshaped with:"
  27 { $subsections reshape flatten }
  28 "Tensors can be combined element-wise with other tensors as well as numbers with:"
  29 { $subsections t+ t- t* t/ t% }
  30 "Tensors support the following matrix operations:"
  31 { $subsections matmul transpose }
  32 "Tensors also support the following concatenation operations:"
  33 { $subsections stack hstack vstack t-concat }
  34 "Tensors implement all " { $vocab-link "sequences" } " operations." $nl
  35 "Tensors can be indexed into using either numbers or arrays, for example:"
  36 { $example
  37     "USING: prettyprint sequences tensors ;"
  38     "t{ { 0.0 1.0 2.0 } { 3.0 4.0 5.0 } }"
  39     "[ { 1 1 } swap nth ] [ 4 swap nth ] bi = ."
  40     "t"
  41 }
  42 "If the array being used to index into the tensor has the wrong number "
  43 "of dimensions, a " { $link dimension-mismatch-error } " will be thrown." ;
  44
  45 ARTICLE: "tensor-operators" "Tensor Operators" "Info here" ;
  46
  47 HELP: tensor
  48 { $class-description "A sequence of floating-point numbers consisting of an "
  49 { $snippet "underlying" } " C-style array and a " { $snippet "shape" } "." } ;
  50
  51 HELP: shape-mismatch-error
  52 { $values { "shape1" sequence } { "shape2" sequence } }
  53 { $description "Throws a " { $link shape-mismatch-error } "." }
  54 { $error-description "Thrown by element-wise operations such as " { $link t+ }
  55 ", " { $link t- } ", " { $link t* } ", " { $link t/ } ", and " { $link t% }
  56 " as well as matrix operations such as " { $link matmul } " if two tensors are "
  57 "passed and they cannot be combined as desired because of a difference in the "
  58 "shape." } ;
  59
  60 HELP: non-positive-shape-error
  61 { $values { "shape" sequence } }
  62 { $description "Throws a " { $link non-positive-shape-error } "." }
  63 { $error-description "Thrown by operations such as " { $link zeros } ", "
  64 { $link ones } ", " { $link naturals } ", and " { $link reshape }
  65 ", which allow users to directly set the shape of a " { $link tensor }
  66 ", when the shape has zero or negative values." } ;
  67
  68 HELP: non-uniform-seq-error
  69 { $values { "seq" sequence } }
  70 { $description "Throws a " { $link non-uniform-seq-error } "." }
  71 { $error-description "Thrown by operations such as " { $link >tensor }
  72 ", which allow users to directly input the values of a " { $link tensor }
  73 " as a nested sequence, when the subsequences have varying lengths." } ;
  74
  75 HELP: dimension-mismatch-error
  76 { $values { "tensor-dim" number } { "index-dim" number } }
  77 { $description "Throws a " { $link dimension-mismatch-error } "." }
  78 { $error-description "Thrown by indexing operations such as " { $link nth }
  79 " and " { $link set-nth } " if the array being used to index has a different number "
  80 "of dimensions than the tensor." } ;
  81
  82 HELP: t{
  83 { $syntax "t{ elements... }" }
  84 { $values { "elements" "a list of numbers" } }
  85 { $description "Initializes a tensor with the given elements."
  86 " Preserves the shape of nested sequences. Assumes uniformly nested sequences." }
  87 { $errors "Throws a " { $link non-uniform-seq-error } " if the given "
  88 "sequence have subsequences of varying lengths. Throws a "
  89 { $link lexer-error } " if the given sequence is not uniformly nested." } ;
  90
  91 HELP: (tensor)
  92 { $values { "shape" sequence } { "tensor" tensor } }
  93 { $description "Creates a tensor with shape " { $snippet "shape" }
  94 " containing uninitialized values. Allows non-positive shapes." } ;
  95
  96 HELP: zeros
  97 { $values { "shape" sequence } { "tensor" tensor } }
  98 { $description "Initializes a tensor with shape " { $snippet "shape" }
  99 " containing all 0s." }
 100 { $errors "Throws a " { $link non-positive-shape-error } " if the given "
 101 "shape has zero or negative values." } ;
 102
 103 HELP: ones
 104 { $values { "shape" sequence } { "tensor" tensor } }
 105 { $description "Initializes a tensor with shape " { $snippet "shape" }
 106 " containing all 1s." }
 107 { $errors "Throws a " { $link non-positive-shape-error } " if the given "
 108 "shape has zero or negative values." } ;
 109
 110 HELP: arange
 111 { $values { "a" number } { "b" number } { "step" number } { "tensor" tensor } }
 112 { $description "Initializes a one-dimensional tensor with values in a range from "
 113     { $snippet "a" } " to " { $snippet "b" } " (inclusive) with step-size " { $snippet "step" } "." } ;
 114
 115 HELP: naturals
 116 { $values { "shape" sequence } { "tensor" tensor } }
 117 { $description "Initializes a tensor with shape " { $snippet "shape" }
 118 " containing a range of values from 0 to " { $snippet "shape product" } "." }
 119 { $errors "Throws a " { $link non-positive-shape-error } " if the given "
 120 "shape has zero or negative values." } ;
 121
 122 HELP: reshape
 123 { $values { "tensor" tensor } { "shape" sequence } }
 124 { $description "Reshapes " { $snippet "tensor" } " to have shape "
 125 { $snippet "shape" } "." }
 126 { $errors "Throws a " { $link non-positive-shape-error } " if the given "
 127 "shape has zero or negative values." } ;
 128
 129 HELP: flatten
 130 { $values { "tensor" tensor } }
 131 { $description "Reshapes " { $snippet "tensor" } " so that it is one-dimensional." } ;
 132
 133 HELP: dims
 134 { $values { "tensor" tensor } { "n" integer } }
 135 { $description "Returns the dimension of " { $snippet "tensor" } "." } ;
 136
 137 HELP: >tensor
 138 { $values { "seq" sequence } { "tensor" tensor } }
 139 { $description "Turns a nested sequence " { $snippet "seq" }
 140 " into a tensor of the corresponding shape. Assumes a uniformly nested sequence." }
 141 { $errors "Throws a " { $link non-uniform-seq-error } " if the given "
 142 "sequence have subsequences of varying lengths. Throws a "
 143 { $link lexer-error } " if the given sequence is not uniformly nested." } ;
 144
 145 HELP: t+
 146 { $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
 147 { $description "Element-wise addition. Intakes two tensors or a tensor and a number (in either order)." }
 148 { $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
 149 "not (or cannot be broadcast to be) the same shape." } ;
 150
 151 HELP: t-
 152 { $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
 153 { $description "Element-wise subtraction. Intakes two tensors or a tensor and a number (in either order)." }
 154 { $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
 155 "not (or cannot be broadcast to be) the same shape." } ;
 156
 157 HELP: t*
 158 { $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
 159 { $description "Element-wise multiplication. Intakes two tensors or a tensor and a number (in either order)." }
 160 { $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
 161 "not (or cannot be broadcast to be) the same shape." } ;
 162
 163 HELP: t/
 164 { $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
 165 { $description "Element-wise division. Intakes two tensors or a tensor and a number (in either order)." }
 166 { $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
 167 "not (or cannot be broadcast to be) the same shape." } ;
 168
 169 HELP: t%
 170 { $values { "x" { $or tensor number } } { "y" { $or tensor number } } { "tensor" tensor } }
 171 { $description "Element-wise modulo operator. Intakes two tensors or a tensor and a number (in either order)." }
 172 { $errors "Throws a " { $link shape-mismatch-error } " if passed two tensors that are "
 173 "not (or cannot be broadcast to be) the same shape." } ;
 174
 175 HELP: tensor>array
 176 { $values { "tensor" tensor } { "seq" array } }
 177 { $description "Returns " { $snippet "tensor" } " as an n-dimensional array." } ;
 178
 179 HELP: matmul
 180 { $values { "tensor1" tensor } { "tensor2" tensor } { "tensor3" tensor } }
 181 { $description "Performs n-dimensional matrix multiplication on two tensors, where " { $snippet "tensor1" }
 182     " has shape " { $snippet "...xmxn" } " and " { $snippet "tensor1" } " has shape " { $snippet "...xnxp" } "." }
 183 { $errors "Throws a " { $link shape-mismatch-error } " if the bottom two "
 184 "dimensions of the tensors passed do not take the form " { $snippet "mxn" }
 185 " and " { $snippet "nxp" } " and/or the top dimensions do not match." } ;
 186
 187 HELP: transpose
 188 { $values { "tensor" tensor } { "tensor'" tensor } }
 189 { $description "Performs n-dimensional matrix transposition on " { $snippet "tensor" } "." } ;
 190
 191 HELP: stack
 192 { $values { "seq" sequence } { "tensor" tensor } }
 193 { $description "Joins the sequences in " { $snippet "seq" } " along a new axis. "
 194 { $snippet "tensor" } " will have one more dimension than the arrays in " { $snippet "seq" } "." }
 195 { $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
 196 { $snippet "seq" } " do not have the same shape." } ;
 197
 198
 199 HELP: hstack
 200 { $values { "seq" sequence } { "tensor" tensor } }
 201 { $description "Joins the sequences in " { $snippet "seq" } " column-wise." }
 202 { $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
 203 { $snippet "seq" } " do not have the same shape along all but the second axis." } ;
 204
 205 HELP: vstack
 206 { $values { "seq" sequence } { "tensor" tensor } }
 207 { $description "Joins the sequences in " { $snippet "seq" } " row-wise." }
 208 { $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
 209 { $snippet "seq" } " do not have the same shape along all but the first axis." } ;
 210
 211 HELP: t-concat
 212 { $values { "seq" sequence } { "tensor" tensor } }
 213 { $description "Joins the sequences in " { $snippet "seq" } " along the first axis." }
 214 { $errors "Throws a " { $link shape-mismatch-error } " if the sequences in "
 215 { $snippet "seq" } " do not have the same shape along all but the first axis." } ;
 216
 217
 218 ABOUT: "tensors"