DoubleTensor#
- class DoubleTensor#
A thin wrapper over a boost::numeric::ublas::tensor<double> object. Uses the first-order convention.
- add_scalar(self: pyhelayers.DoubleTensor, val: float) None#
Adds given scalar to all elements.
- Parameters:
val (double) – the scalar to add.
- assert_equals(self: pyhelayers.DoubleTensor, other: pyhelayers.DoubleTensor, title: str, eps: float = 1e-05, relative: bool = False) float#
Verifies this tensor equals other tensor. Returns the mean squared error (MSE).
- Parameters:
other (DoubleTensor) – The other tensor to verify equality to.
title (string) – A title to print in case the assertion fails.
eps (double) – The maximal diff allowed in each slot between this and other. Defaults to 1e-5.
relative (boolean) – Whether to apply comparison with respect to relative difference between values. Defaults to false.
- to_numpy(self: pyhelayers.DoubleTensor) numpy.ndarray[numpy.float64]#
Converts a DoubleTensor to a numpy array.
-
class DoubleTensor#
A tensor of doubles.
Uses the first-order convention.
Public Functions
-
DoubleTensor()#
Construct an empty tensor.
-
DoubleTensor(std::initializer_list<DimInt> shape)#
Construct a zeroed tensor with given shape.
- Parameters:
shape – shape
-
DoubleTensor(const std::vector<DimInt> &shape)#
Construct a zeroed tensor with given shape.
- Parameters:
shape – shape
-
void init(const std::vector<DimInt> &shape, const std::vector<double> &vals, bool firstOrder = true)#
Initialized tensor with given shape and values.
- Parameters:
shape – New shape to set
vals – Vals to fill tensor with.
firstOrder – Indicates whether supplied values are in first-order. Note that internally they’ll be stored according to internal convention.
-
void init(const std::vector<DimInt> &shape, double val)#
Initialized tensor with given shape and value.
- Parameters:
shape – New shape to set
val – A single value to fill tensor with in all slots.
-
void reshape(const std::vector<DimInt> &shape, bool allowChangingNumberOfElements = false, bool firstOrder = true)#
Reshapes tensor.
- Parameters:
shape – shape
allowChangingNumberOfElements – If true then reshaping may change number of elements. Default is false.
firstOrder – Whether to reshape using first order convention
-
void reshape(std::initializer_list<DimInt> shape, bool allowChangingNumberOfElements = false, bool firstOrder = true)#
Reshapes tensor.
- Parameters:
shape – shape
allowChangingNumberOfElements – If true then reshaping may change number of elements. Default is false.
firstOrder – Whether to reshape using first order convention
-
void reorderDims(const std::vector<DimInt> &dimOrder)#
Reorders the dimensions of this tensor.
For example, given {1,2,0}, the current second dimension will become first, the current third dimension will become second, and the current first dimension will become last.
- Parameters:
dimOrder – New order of dimensions
-
void init(const std::vector<double> &vals, bool firstOrder = true)#
Populates existing tensor with values.
The tensor can have any number of dimensions, and its shape is maintained. Caller can specify whether input vector is in the first-order convention or not. Internally it is stored according to the internal convention.
- Parameters:
vals – a vector with the values to populate. size of vector must equal the size of tensor
firstOrder – whether vals is given in the first order convention or last order.
-
void init(const std::vector<std::vector<double>> &matrix)#
Populates existing 2D tensor with values from a matrix.
- Parameters:
matrix – a matrix with the values to populate. size of matrix must equal the size of the 2D tensor
-
void initRandom()#
Populates existing tensor with random values in [-0.5, 0.5].
-
void initRandom(double min, double max, double sparseRate = 0)#
Populates existing tensor with random values in the range [min, max)
- Parameters:
min – A lower limit for the random values.
max – An upper limit for the random values.
sparseRate – The rate of zeroed values. Must be in the range of [0,1]. For example, 0 means no values will be set to zero, while 0.3 means ~30% of the values will be set to zero and ~70% will get values in the range of [min,max).
-
void addDim(DimInt dim, DimInt size = 1)#
Adds a new dimension to the tensor.
The result is a tensor with number of dimensions increased by one. The added dimension is being padded with zeros.
- Parameters:
dim – the dimension to add. Must be at the start or between or end of the existing dimensions. Any existing dimensions with index equal or greater will have their index be advanced in 1.
size – the size of the new dimension.
-
void removeDim(DimInt dim)#
Removes a dim from this tensor.
Only for dim with size 1.
- Parameters:
dim – Dim to remove
- Throws:
runtime_error – If dim doesn’t exists
runtime_error – If dim is not of size 1
-
void resizeDim(DimInt dim, DimInt newSize)#
Resizes an existing dimension.
If the size is being increased, the resized dimension is being padded with zeros.
- Parameters:
dim – the dimension to resize.
newSize – the new desired size
-
void duplicateOverDim(DimInt dim)#
Duplicates the values of a specified existing dimension.
The values will be taken from the slot at index 0.
- Parameters:
dim – the dimension to duplicate over
-
void argMinOverDim(DimInt dim)#
Computes arg-min over a given dimension.
After this operation the dimension size will be 1, and it will contain the index of the previous minimal value.
- Parameters:
dim – the dimension to run arg-min over
-
std::streamoff save(std::ostream &stream) const#
Save this object to a binary stream.
- Parameters:
stream – stream to write to
-
std::streamoff load(std::istream &stream)#
Load this object from a binary stream.
- Parameters:
stream – stream to load from
-
void nicePrint(std::ostream &out = std::cout, bool withShape = true) const#
Prints the tensor nicely formatted.
For tensor with one or two non-trivial dims, it is printed as a table with right-aligned numbers according to PrintOptions::tableCellWidth.
For other tensors the printout is the same as debugPrint.
- Parameters:
out – output stream to print to
withShape – when true, the shape of the tensor is printed as well. Note that if the tensor can’t be printed in tabular form, the shape is always printed and this argument is ignored.
-
void debugPrint(const std::string &title, int verbose = 0, std::ostream &out = std::cout) const#
Prints state for debugging.
- Parameters:
title – Title to print alongside state
verbose – Verbosity of printout
out – output stream to print to
-
void calcConvolution(DoubleTensor &res, const DoubleTensor &filters, const std::optional<DoubleTensor> &biases = std::nullopt, DimInt strideX = 1, DimInt strideY = 1, const Padding2d &padding = Padding2d(), bool sumOverChannels = true) const#
Perform convolution of this object with filters.
Expects this object to be a 4-dimensional tensor: [X,Y,CHANNELS,BATCH] The filters should be [FILTERX,FILTERY,CHANNELS,FILTERS] The biases can be any tensor with FILTERS number of elements. The result will be [OUTX,OUTY,FILTERS,BATCH]
- Parameters:
res – Resulting tensor
filters – Filters
biases – Biases (optional)
strideX – Stride on the X axis (first dimension)
strideY – Stride on the Y axis (second dimension)
padding – The padding values (default, all zeros)
sumOverChannels – Default true. If false, then expecting one filter, and the result will be [OUTX,OUTY,CHANNELS,BATCH]. Bias is expected to have CHANNELS number of elements.
-
void calcSumPooling(DoubleTensor &res, DimInt filterX, DimInt filterY, DimInt strideX = 1, DimInt strideY = 1, const Padding2d &padding = Padding2d()) const#
Perform sum-pooling of this object.
Expects this object to be a 4-dimensional tensor: [X,Y,CHANNELS,BATCH] The sum-pooling is done over a (filterRows X filterCols) filter. The result will be [OUTX,OUTY,FILTERS,BATCH]
- Parameters:
res – Resulting tensor
filterX – Width of filter on the X axis (first dimension) to sum over
filterY – Width of filter on the Y axis (second dimension) to sum over
strideX – Stride on the X axis (first dimension)
strideY – Stride on the Y axis (second dimension)
padding – The padding values (default, all zeros)
-
void calcAveragePooling(DoubleTensor &res, DimInt filterX, DimInt filterY, DimInt strideX = 1, DimInt strideY = 1, const Padding2d &padding = Padding2d()) const#
Perform average-pooling of this object.
Expects this object to be a 4-dimensional tensor: [X,Y,CHANNELS,BATCH] The average-pooling is done over a (filterRows X filterCols) filter. The result will be [OUTX,OUTY,FILTERS,BATCH]
- Parameters:
res – Resulting tensor
filterX – Width of filter on the X axis (first dimension) to average over
filterY – Width of filter on the Y axis (second dimension) to average over
strideX – Stride on the X axis (first dimension)
strideY – Stride on the Y axis (second dimension)
padding – The padding values (default, all zeros)
-
void batchNorm(DimInt dim, const std::vector<double> &means, const std::vector<double> &vars, const std::vector<double> &scales, const std::vector<double> &biases, double eps)#
Perform batch normalization on this object.
The object can be at any shape. This operation does not change the shape of the object.
- Parameters:
dim – The features dimension. Must exist in this object. Its size must equal the size of the vectors of means, vars, scales and biases.
means – A vector with the mean of each feature along the features dimension.
vars – A vector with the variance of each feature along the features dimension.
scales – A vector with the scale of each feature along the features dimension.
biases – A vector with the bias of each feature along the features dimension.
eps – The epsilon value to use for the normalization, to avoid dividing by zero.
-
void flatten(DimInt axis, bool firstOrder = true)#
Flattens this N-dimensional tensor into a 2D tensor of shape: [d_0 X d_1 X …
X d_axis-1, d_axis X … X d_N-1]
- Parameters:
axis – The axis to flatten by.
firstOrder – Whether to flatten using first order convention
-
inline uint64_t size() const#
Returns number of elements in tensor.
-
inline DimInt getDimSize(DimInt dim) const#
Returns size for specific dimension.
- Parameters:
dim – Dimension to query
-
std::vector<DimInt> getShape() const#
Returns shape.
Note: allocates a new vector. Don’t use in efficiency-critical code.
-
std::string getShapeAsString() const#
Returns the string representation of this object’s shape.
-
void assertShapeEquals(const std::vector<DimInt> &shape) const#
Asserts given shape equals tensor’s shape.
- Parameters:
shape – Shape. If a zero value is passed for a certain dimension, it means this dimension should be skipped when verifying its size
- Throws:
runtime_error – If assertion fails
-
DoubleTensor getMultiDimSlice(const std::vector<DimInt> &starts, const std::vector<DimInt> &ends, const std::vector<DimInt> &axes) const#
Returns a slice of the tensor at the given axes in the given indexes.
- Parameters:
starts – The start indexes (corresponding to axes).
ends – The end indexes (exclusive, corresponding to axes).
axes – The axes to slice along.
-
DoubleTensor getSlice(DimInt dim, DimInt startIndex, DimInt sliceDepth = 1) const#
Returns a slice of the tensor in specific dimension.
Result has the same number of dimensions as the original tensor.
- Parameters:
dim – the dimension to slice along. Specifying negative value will count from the last dim backwards (-1 for the last dim, -2 for the previous one etc.).
startIndex – the index to start slicing at along the dimension
sliceDepth – the depth/size of the slice along the dimension
-
std::vector<std::shared_ptr<DoubleTensor>> getSlices(DimInt dim, DimInt sliceDepth = 1) const#
Returns slices of all the values in the tensor in specific dimension.
Result is a vector of slices that together make up the entire tensor. Each slice has the same number of dimensions as the original tensor.
- Parameters:
dim – the dimension to slice along. Specifying negative value will count from the last dim backwards (-1 for the last dim, -2 for the previous one etc.).
sliceDepth – the depth/size of each slice along the dimension. The last slice may have smaller size.
-
void fillSlice(DimInt dim, DimInt index, double val)#
Fills the specified slice with the given value.
- Parameters:
dim – The dimension of the slice. Specifying negative value will count from the last dim backwards (-1 for the last dim, -2 for the previous one etc.).
index – The index of the slice along “dim”.
val – The value to fill with.
-
void putSlice(DimInt dim, DimInt startIndex, const DoubleTensor &slice)#
Put a tensor slice into an existing tensor.
Putting the slice will override existing values in indexes positioned where the slice will be put, and the tensor size along the provided dimension will be increased if needed.
- Parameters:
dim – an existing dimension to put the slice in. Specifying negative value will count from the last dim backwards (-1 for the last dim, -2 for the previous one etc.).
startIndex – the index to start positioning the slice in along the dimension. specifying -1 will append slice after last current index.
slice – the slice to put. must be a tensor with the same number of dimensions as this, and with sizes of dimensions exactly matching the sizes of this except for the provided dimension to put the slice in, that might be at any size.
-
void removeSlice(DimInt dim, DimInt startIndex, DimInt sliceDepth = 1)#
Removes the specified slice from this DoubleTensor, in place.
The removed slice starts at startIndex of the given dimension and ends at startIndex + sliceDepth - 1.
- Parameters:
dim – the dimension to slice along. Specifying negative value will count from the last dim backwards (-1 for the last dim, -2 for the previous one etc.).
startIndex – the index to start slicing at along the dimension
sliceDepth – the depth/size of the slice along the dimension
-
template<class ...DimInts>
inline const double &at(DimInt i, DimInts... is) const# Returns the element at specified indices.
-
template<class ...DimInts>
inline double &at(DimInt i, DimInts... is)# Returns the element at specified indices.
-
void transpose(DimInt firstDim = 0, DimInt secondDim = 1)#
Flips the order of the given two dimensions.
Default is the first two dimensions. For a 2d matrix, this means the transposed matrix. Requires at least 2 dimensions.
- Parameters:
firstDim – The first dimension.
secondDim – The second dimension.
-
void rotateAlongDim(DimInt dim)#
Rotates the content of this DoubleTensor along the specified dimension.
- Parameters:
dim – The dimension to rotate along
-
std::vector<double> getFlattened(bool firstOrder = true) const#
Returns tensor content as flat vector.
- Parameters:
firstOrder – Whether to populate the vector using first order convention
-
double sumOfElements()#
Returns the sum of all elements in the tensor.
-
void elementAdd(const DoubleTensor &other)#
Performs element-wise add of other into this.
- Parameters:
other – the tensor to add into this. must have the same shape as this.
-
void elementSub(const DoubleTensor &other)#
Performs element-wise subtract of other from this.
- Parameters:
other – the tensor to subtract from this. must have the same shape as this.
-
void elementMultiply(const DoubleTensor &other)#
Performs element-wise multiplication of other into this.
- Parameters:
other – the tensor to multiply into this. must have the same shape as this.
-
void elementInverse()#
Performs element-wise inverse of this.
-
void matrixMultiply(const DoubleTensor &other)#
Calculates the result of matrix multiplication of this and other in-place.
Both this and other tensor can be either 2D or 3D. If they are 3D, the third dimension is considered the batch dimension. The output will have a batch dimension of either inputs have it. If both inputs have the batch dimension, we require it to be the same.
- Parameters:
other – the matrix to multiply with this.
-
void matrixMultiplyLeft(const DoubleTensor &other)#
Same as matrixMultiply, but computes other*this, and stores results in this.
See matrixMultiply()
- Parameters:
other – the matrix to multiply with this on the left.
-
void getMatrixMultiply(const DoubleTensor &other, DoubleTensor &res) const#
Sets in res the result of matrix-multiplication of this and other.
Both this and other tensor can be either 2D or 3D. If they are 3D, the third dimension is considered the batch dimension. If they are 3D they both need to be 3D with the same batch dimension, and so is the output.
- Parameters:
other – Other matrix to multiply with.
res – Output tensor
-
void addVector(const DoubleTensor &vector)#
Calculates the result of adding a vector to this vector.
The other vector is a 2D tensor of sizes [a,1] and this vector is a 3D tensor of sizes [a,1,batch]. The result is a 3D tensor of sizes [a,1,batch].
- Parameters:
vector – the 2D vector to add to this.
-
void addScalar(double val)#
Adds given scalar to all elements.
- Parameters:
val – Value to add
-
void subtractScalar(double val)#
Subtracts given scalar to all elements.
- Parameters:
val – Value to subtract
-
void multiplyScalar(double val)#
Multiplies all elements by a given scalar.
- Parameters:
val – Value to multiply by
-
void multiplyScalarsDimWise(DimInt dim, const std::vector<double> &vals)#
Multiplies all elements by a scalar, where with respect to a given dimension, every “slice” along that dimension will be multiplied by a different scalar.
For example, if the given dimension is dimension 0 and its size is 3, a vector of 3 scalars [s0,s1,s2] should be provided. All the slots in the result tensor at index 0/1/2 along dimension 0 will be multiplied by the scalar s0/s1/s2, respectively.
- Parameters:
dim – The given dimension.
vals – The scalars to multiply by.
-
void elementPolyEval(const std::vector<double> &coeffs)#
Performs element-wise polynomial computation into this.
- Parameters:
coeffs – the coefficients of the polynomial, in the order: c[0],c[1],…,c[n]
-
void sign()#
Returns an element-wise indication of the sign of a number into this.
-
double maxAbs() const#
Returns the maximal absolute value in the tensor.
-
void assertSameShape(const DoubleTensor &other, const std::string &title = "", DimInt skippedDim = -1) const#
Asserts
otherhas the same shape asthis, except an optional skipped dimension that is allowed to have a different size (-1 to compare all dimensions).- Parameters:
other – Other tensor to test with
title – Optional title for error printouts
skippedDim – Optional dimension to skip
-
double assertEquals(const DoubleTensor &other, const std::string &title = "", double eps = 1e-5, bool relative = false) const#
Verifies this tensor equals other tensor.
Returns the mean squared error (MSE).
- Parameters:
other – The other tensor to verify equality to.
title – A title to print in case the assertion fails.
eps – The maximal diff allowed in each slot between this and other. A negative value indicates not to throw an exception, and use this function just for its return value.
relative – Whether to apply comparison with respect to relative difference between values. Defaults to false.
-
double testMse(const DoubleTensor &expectedVals, const std::string &title = "", double eps = -1) const#
Computes the MSE (Mean Square Error) with expected values.
If title!=””, prints results to cout. If eps>=0, asserts MSE<=eps
- Parameters:
expectedVals – tensor input to compare
title – If not empty, will be output to cout along with MSE
eps – If non-negative, an exception will be thrown if MSE>eps
-
void calculateError(const DoubleTensor &other, double &mse, double &maxAbsDiff, DimInt &maxAbsDiffIndex, double &maxRelDiff, DimInt &maxRelDiffIndex) const#
Calculates the error between this and other DoubleTensor.
- Parameters:
other – The other DoubleTensor.
mse – The mean square error will be stored here.
maxDiff – The maximal absolute error will be stored here.
maxDiffIndex – The index of the maximal absolute error (in the flattened tensor) will be stored here.
maxRelDiff – The maximal relative error will be stored here. The relative error between a and b is computed as |a-b|/std::max(|a|,|b|).
maxRelDiffIndex – The index of the maximal relative error (in the flattened tensor) will be stored here.
-
std::vector<DimInt> getNonTrivialDims() const#
Returns a list of dimension indices whose sizes are larger than 1.
-
void changeOrder(DimInt numDims)#
Changes the order of this tensor by adding or removing degenerate dims (sized 1) at its end.
- Parameters:
numDims – The desired new order.
-
void castToInt()#
Casts the values of this into integer values.
Notice that the casted values are still kept in a tensor of values of type double.
-
void castToBool()#
Casts the values of this into boolean values.
Notice that the casted values are still kept in a tensor of values of type double.
Public Static Functions
Joins together the given slices in specific dimension into a single tensor.
- Parameters:
slices – The slices to join. All slices must have the same shape except a different size along “dim” dimension which is allowed.
dim – the dimension to join along. Specifying negative value will count from the last dim backwards (-1 for the last dim, -2 for the previous one etc.).
-
static std::vector<DimInt> getNonTrivialDims(const std::vector<DimInt> &dimSizes)#
Returns the indices of the input dimension sizes list of all elements whose size is larger than 1.
- Parameters:
dimSizes – Input list of dimension sizes.
-
DoubleTensor()#