Documentation
¶
Overview ¶
Package shapes defines Shape and DType and associated tools.
Shape represents the shape (rank, dimensions and DType) of either a Tensor or the expected shape of a node in a computation Graph. DType indicates the type of the unit element of a Tensor (or its representation as a node in a computation Graph).
Shape and DType are used both by the concrete tensor values (see tensor package) and when working on the computation graph (see graph package).
Go float16 support (commonly used by Nvidia GPUs) uses github.com/x448/float16 implementation, and bfloat16 uses a simple implementation in github.com/gomlx/gopjrt/dtypes/bfloat16.
## Glossary
- Rank: number of axes (dimensions) of a Tensor.
- Axis: is the index of a dimension on a multidimensional Tensor. Sometimes used interchangeably with Dimension, but here we try to refer to a dimension index as "axis" (plural axes), and its size as its dimension.
- Dimension: the size of a multi-dimensions Tensor in one of its axes. See example below:
- DType: the data type of the unit element in a tensor. Enumeration defined in github.com/gomlx/gopjrt/dtypes
- Scalar: is a shape where there are no axes (or dimensions), only a single value of the associated DType.
Example: The multi-dimensional array `[][]int32{{0, 1, 2}, {3, 4, 5}}` if converted to a Tensor would have shape `(int32)[2 3]`. We say it has rank 2 (so 2 axes), axis 0 has dimension 2, and axis 1 has dimension 3. This shape could be created with `shapes.Make(int32, 2, 3)`.
## Asserts
When coding ML models, one delicate part is keeping tabs on the shape of the nodes of the graphs -- unfortunately there is no compile-time checking of values, so validation only happens in runtime. To facilitate, and also to serve as code documentation, this package provides two variations of _assert_ functionality. Examples:
`AssertRank` and `AssertDims` checks that the rank and dimensions of the given
object (that has a `Shape` method) match, otherwise it panics. The `-1` means the dimension is unchecked (it can be anything).
```
func modelGraph(ctx *context.Context, spec any, inputs []*Node) ([]*Node) {
_ = spec // Not needed here, we know the dataset.
shapes.AssertRank(inputs, 2)
batchSize := inputs.Shape().Dimensions[0]
logits := layers.Dense(ctx, inputs[0], /* useBias= */ true, /* outputDim= */ 1)
shapes.AssertDims(logits, batchSize, -1)
return []*Node{logits}
}
```
If you don't want to panic, but instead return an error through the `graph.Graph`, you can use the `Node.AssertDims()` method. So it would look like `logits.AssertDims(batchSize, -1)`.
Index ¶
- Constants
- func Assert(shaped HasShape, dtype dtypes.DType, dimensions ...int)
- func AssertDims(shaped HasShape, dimensions ...int)
- func AssertRank(shaped HasShape, rank int)
- func AssertScalar(shaped HasShape)
- func CastAsDType(value any, dtype DType) any
- func CheckDims(shaped HasShape, dimensions ...int) error
- func CheckRank(shaped HasShape, rank int) error
- func CheckScalar(shaped HasShape) error
- func ConvertTo[T NumberNotComplex](value any) T
- func UnsafeSliceForDType(dtype DType, unsafePtr unsafe.Pointer, len int) any
- type HasShape
- type Shape
- func (s Shape) Assert(dtype dtypes.DType, dimensions ...int)
- func (s Shape) AssertDims(dimensions ...int)
- func (s Shape) AssertRank(rank int)
- func (s Shape) AssertScalar()
- func (s Shape) Check(dtype dtypes.DType, dimensions ...int) error
- func (s Shape) CheckDims(dimensions ...int) error
- func (s Shape) CheckRank(rank int) error
- func (s Shape) CheckScalar() error
- func (s Shape) Clone() (s2 Shape)
- func (s Shape) Equal(s2 Shape) bool
- func (s Shape) EqualDimensions(s2 Shape) bool
- func (s Shape) GobSerialize(encoder *gob.Encoder) (err error)
- func (s Shape) IsScalar() bool
- func (s Shape) IsTuple() bool
- func (s Shape) Memory() uintptr
- func (s Shape) Ok() bool
- func (s Shape) Rank() int
- func (s Shape) Shape() Shape
- func (s Shape) Size() (size int)
- func (s Shape) String() string
- func (s Shape) TupleSize() int
Constants ¶
const UncheckedAxis = int(-1)
UncheckedAxis can be used in CheckDims or AssertDims functions for an axis whose dimension doesn't matter.
Variables ¶
This section is empty.
Functions ¶
func Assert ¶ added in v0.11.0
Assert checks that the shape has the given dtype, dimensions and rank. A value of -1 in dimensions means it can take any value and is not checked.
It panics if it doesn't match.
func AssertDims ¶
AssertDims checks that the shape has the given dimensions and rank. A value of -1 in dimensions means it can take any value and is not checked.
It panics if it doesn't match.
See usage example in package shapes documentation.
func AssertRank ¶
AssertRank checks that the shape has the given rank.
It panics if it doesn't match.
See usage example in package shapes documentation.
func AssertScalar ¶
func AssertScalar(shaped HasShape)
AssertScalar checks that the shape is a scalar.
It panics if it doesn't match.
See usage example in package shapes documentation.
func CastAsDType ¶
CastAsDType casts a numeric value to the corresponding for the DType. If the value is a slice it will convert to a newly allocated slice of the given DType.
It doesn't work for complex numbers.
func CheckDims ¶
CheckDims checks that the shape has the given dimensions and rank. A value of -1 in dimensions means it can take any value and is not checked.
It returns an error if the rank is different or any of the dimensions.
func CheckRank ¶
CheckRank checks that the shape has the given rank.
It returns an error if the rank is different.
func CheckScalar ¶
CheckScalar checks that the shape is a scalar.
It returns an error if shape is not a scalar.
func ConvertTo ¶ added in v0.2.1
func ConvertTo[T NumberNotComplex](value any) T
ConvertTo converts any scalar (typically returned by `tensor.Local.Value()`) of the supported dtypes to `T`. Returns 0 if value is not a scalar or not a supported number (e.g: bool). It doesn't work for if T (the output type) is a complex number. If value is a complex number, it converts by taking the real part of the number and discarding the imaginary part.
Types ¶
type HasShape ¶
type HasShape interface {
Shape() Shape
}
HasShape is an interface for objects that have an associated Shape. `tensor.Tensor` (concrete tensor) and `graph.Node` (tensor representations in a computation graph), `context.Variable` and Shape itself implement the interface.
type Shape ¶
type Shape struct {
DType DType
Dimensions []int
TupleShapes []Shape // Shapes of the tuple, if this is a tuple.
}
Shape represents the shape of either a Tensor or the expected shape of the value from a computation node.
Use Make to create a new shape. See example in package shapes documentation.
func ConcatenateDimensions ¶
ConcatenateDimensions of two shapes. The resulting rank is the sum of both ranks. They must have the same dtype. If any of them is a scalar, the resulting shape will be a copy of the other. It doesn't work for Tuples.
func GobDeserialize ¶ added in v0.2.0
GobDeserialize a Shape. Returns new Shape or an error.
func Invalid ¶ added in v0.11.0
func Invalid() Shape
Invalid returns an invalid shape.
Invalid().IsOk() == false.
func Make ¶
Make returns a Shape structure filled with the values given. See MakeTuple for tuple shapes.
func (Shape) Assert ¶ added in v0.9.0
Assert checks that the shape has the given dtype, dimensions and rank. A value of -1 in dimensions means it can take any value and is not checked.
It panics if it doesn't match.
func (Shape) AssertDims ¶
AssertDims checks that the shape has the given dimensions and rank. A value of -1 in dimensions means it can take any value and is not checked.
It panics if it doesn't match.
See usage example in package shapes documentation.
func (Shape) AssertRank ¶
AssertRank checks that the shape has the given rank.
It panics if it doesn't match.
See usage example in package shapes documentation.
func (Shape) AssertScalar ¶
func (s Shape) AssertScalar()
AssertScalar checks that the shape is a scalar.
It panics if it doesn't match.
See usage example in package shapes documentation.
func (Shape) Check ¶ added in v0.9.0
Check that the shape has the given dtype, dimensions and rank. A value of -1 in dimensions means it can take any value and is not checked.
It returns an error if the dtype or rank is different or if any of the dimensions don't match.
func (Shape) CheckDims ¶
CheckDims checks that the shape has the given dimensions and rank. A value of -1 in dimensions means it can take any value and is not checked.
It returns an error if the rank is different or if any of the dimensions don't match.
func (Shape) CheckRank ¶
CheckRank checks that the shape has the given rank.
It returns an error if the rank is different.
func (Shape) CheckScalar ¶
CheckScalar checks that the shape is a scalar.
It returns an error if shape is not a scalar.
func (Shape) Equal ¶ added in v0.11.0
Equal compares two shapes for equality: dtype and dimensions are compared.
func (Shape) EqualDimensions ¶ added in v0.11.0
EqualDimensions compares two shapes for equality of dimensions. Dtypes can be different.
func (Shape) GobSerialize ¶ added in v0.2.0
GobSerialize shape in binary format.
func (Shape) IsScalar ¶
IsScalar returns whether the shape represents a scalar, that is there are no dimensions (rank==0).
func (Shape) Memory ¶ added in v0.2.0
Memory returns the memory used to store an array of the given shape, the same as the size in bytes. Careful, so far all types in Go and on device seem to use the same sizes, but future type this is not guaranteed.
func (Shape) Ok ¶
Ok returns whether this is a valid Shape. A "zero" shape, that is just instantiating it with Shape{} will be invalid.
func (Shape) Size ¶
Size returns the number of elements of DType are needed for this shape. It's the product of all dimensions.
Source Files