TTShape#

class TTShape#

Tile tensor shape. Contains meta data defining packing details of a tile tensor. Printable to a string in tile tensor shape notation.

add_dim(*args, **kwargs)#

Overloaded function.

add_dim(self: pyhelayers.TTShape, dim: pyhelayers.TTDim, place: int = -1) -> None
add_dim(self: pyhelayers.TTShape, original_size: int, tile_size: int, num_duplicated: int = 1, are_unused_slots_unkown: bool = False, is_interleaved: bool = False, is_complex_packed: bool = False) -> None

apply_compatibility_adjustments(self: pyhelayers.TTShape, other: pyhelayers.TTShape, action_type: pyhelayers.ActionType) → None#

are_all_dims_incomplete(self: pyhelayers.TTShape) → bool#

assert_compatible(self: pyhelayers.TTShape, other: pyhelayers.TTShape, action_type: pyhelayers.ActionType = <ActionType.OTHER_ACTION_TYPE: 2>, text: str = '') → None#

clear_unknowns(self: pyhelayers.TTShape) → None#

contains_unknown_unused_slots(self: pyhelayers.TTShape) → bool#

get_dim(*args, **kwargs)#

Overloaded function.

get_dim(self: pyhelayers.TTShape, dim: int) -> pyhelayers.TTDim
get_dim(self: pyhelayers.TTShape, dim: int) -> pyhelayers.TTDim

get_external_sizes(self: pyhelayers.TTShape) → numpy.ndarray[numpy.int32]#

get_incomplete_tile_sizes_and_interleaved(self: pyhelayers.TTShape) → pyhelayers.TTShape#

get_num_dims(self: pyhelayers.TTShape) → int#

get_num_slots_in_tile(self: pyhelayers.TTShape) → int#

get_num_used_tiles(self: pyhelayers.TTShape) → int#

get_original_sizes(self: pyhelayers.TTShape, include_duplications: bool = False) → numpy.ndarray[numpy.int32]#

get_rotate_offset_of_dim(self: pyhelayers.TTShape, i: int) → int#

get_sub_shape(self: pyhelayers.TTShape, first: int, last: int) → pyhelayers.TTShape#

Returns a sub-TTShape of dimensions [first,last).

Parameters:

first (int) – The start index of the first dimension.
last (int) – The ending index of the required sub shape.

Returns:

The sub shape of dimensions [first, last)

Return type:

TTShape

get_tile_sizes(self: pyhelayers.TTShape) → numpy.ndarray[numpy.int32]#

get_with_duplicated_dim(self: pyhelayers.TTShape, dim: int) → pyhelayers.TTShape#

Get a copy of current ttshape with the specified dimension fully duplicated along tile size.

Parameters:: dim (int) – Dimension to duplicate

get_with_duplicated_dims(self: pyhelayers.TTShape, dims_to_duplicate: numpy.ndarray[numpy.int32]) → pyhelayers.TTShape#

Get a copy of current ttshape with the specified dimensions fully duplicated along tile size.

Parameters:: dims_to_duplicate (pyarray<int>) – Dimensions to duplicate

insert_dim_at(self: pyhelayers.TTShape, dim: pyhelayers.TTDim, pos: int) → None#

Inserts a dimension at given position. If it is inserted at pos i, current dimension at i becomes i+1.

Parameters:

dim (TTDim) – Dimension to add.
pos (int) – Position to insert to.

is_compatible(self: pyhelayers.TTShape, other: pyhelayers.TTShape, actionType: pyhelayers.ActionType = <ActionType.OTHER_ACTION_TYPE: 2>) → bool#

is_degenerate_tile_dim(self: pyhelayers.TTShape, dim: int) → bool#

is_diagonalized(self: pyhelayers.TTShape) → bool#

Returns whether this shape is diagonalized in its first two: dimensions.

is_incomplete(self: pyhelayers.TTShape) → bool#

is_rotatable(self: pyhelayers.TTShape, dim: int) → bool#

set_all_unused_slots_unknown(self: pyhelayers.TTShape) → None#: Turns on the unknown flag for all dimensions which have unused slots.

set_diagonalized(self: pyhelayers.TTShape, val: bool) → None#: Set the diagonalized flag of this shape. Diagonalized shapes must satisfy: - At least 2 dims - Dims 0-1 not duplicated, interleaved, or complex packed. - Original size of dim 0 must be divisible by tileSize[0]*tileSize[1] :param val: New value.

set_original_sizes(self: pyhelayers.TTShape, org_sizes: numpy.ndarray[numpy.int32], keep_interleaved_external_sizes: bool = False) → None#

tile_layout_to_string(self: pyhelayers.TTShape) → str#

class TTShape : public helayers::SaveableBasic#

Tile tensor shape.

Contains meta data defining packing details of a tile tensor. Printable to a string in tile tensor shape notation

Public Functions

inline TTShape()#: Constructs an empty object.

inline TTShape(const std::vector<TTDim> &v)#

Constructs a TTShape with given list of TTDim specification.

Parameters:: v – Dimension specifications.

TTShape(std::initializer_list<DimInt> tshape)#

Initialize a ttshape Example usage: TTShape myShape({16,32,8});.

Construct a new TTShape object with just tile dimension sizes defined. In this state it is incomplete (since it has no original sizes) but it can be used for packing tensors.

Parameters:: tshape – Tile shape

TTShape(const std::vector<DimInt> &tshape)#

Construct a new TTShape object with just tile dimension sizes defined.

In this state it is incomplete (since it has no original sizes) but it can be used for packing tensors.

Parameters:: tshape – Tile shape

inline ~TTShape()#

TTShape getWithDuplicatedDims(std::initializer_list<DimInt> dimsToDuplicate) const#

Returns a copy of current ttshape with each of the specified dimensions fully duplicated along tile size.

Parameters:: dimsToDuplicate – List of dimension indices to duplicate

TTShape getWithDuplicatedDims(const std::vector<DimInt> &dimsToDuplicate) const#

Returns a copy of current ttshape with each of the specified dimensions fully duplicated along tile size.

Parameters:: dimsToDuplicate – List of dimension indices to duplicate

TTShape getWithDuplicatedDim(DimInt dim) const#

Returns a copy of current ttshape with the specified dimension fully duplicated along tile size.

Parameters:: dim – Dimension index to duplicate

TTShape getIncompleteTileSizesAndInterleaved() const#

Returns a ttshape containing just the tile shape of this object, as well as the interleaved flag and the interleaved external size in case of non-default size.

The returned ttshape is in incomplete state, but can be used for packing tensors.

inline const TTDim &getDim(DimInt dim) const#

Returns a dimension specification.

Parameters:: dim – Dimension index

inline TTDim &getDim(DimInt dim)#

Returns a dimension specification.

Parameters:: dim – Dimension index

inline const TTDim &getDimUnsafe(DimInt dim) const#

Returns a dimension specification without validating index range.

Use getDim() instead, unless this method needs to be called repeatedly many times with values known to be valid.

Parameters:: dim – Dimension index

TTShape getSubShape(DimInt first, DimInt last) const#

Returns a sub-ttshape of dimensions [first,last)

Parameters:

first – First dimension index (inclusive)
last – Last dimension index (exclusive)

Throws:

invalid_argument – If indices are illegal, or if trying to slice one of the first two dimensions of a diagonal shape.

void setOriginalSizes(std::initializer_list<DimInt> orgSizes, bool keepInterleavedExternalSizes = false)#

Set the original sizes of all dimensions.

Usually used for incomplete shapes. If some dimensions are complete, their original size is overriden.

Parameters:

orgSizes – Original sizes vector
keepInterleavedExternalSizes – See keepInterleavedExternalSize in TTDim::setOriginalSize.

void setOriginalSizes(const std::vector<DimInt> &orgSizes, bool keepInterleavedExternalSizes = false)#

Set the original sizes of all dimensions.

Usually used for incomplete shapes. If some dimensions are complete, their original size is overriden.

Parameters:

orgSizes – Original sizes vector
keepInterleavedExternalSizes – See keepInterleavedExternalSize in TTDim::setOriginalSize.

void assertOriginalSizes(const std::vector<DimInt> &orgSizes) const#

Validates the original sizes of the shape are as expected.

Parameters:: orgSizes – Expected original sizes. If a zero value is passed for a certain dimension, it means this dimension should be skipped when verifying its size.
Throws:: invalid_argument – If assertion fails.

bool isIncomplete() const#

Returns whether object is in incomplete state.

Incomplete ttshape are missing some details but have the tile shape, and can be used for packing tensors.

bool areAllDimsIncomplete() const#

Returns true if all dimensions are incomplete.

See isIncomplete()

DimInt getNumIncompleteDims() const#

Returns number of dimensions marked as incomplete.

See isIncomplete()

bool isCompatible(const TTShape &other, ActionType at = OTHER_ACTION_TYPE) const#

Returns true if this ttshape is compatible with other.

Compatibility means elementwise binary operators can be applied.

Parameters:

other – Other ttshape to test with
at – Action type to check compatibility for. Affects complex packed dimensions. Default is set to most restrictive setting.

void assertCompatible(const TTShape &other, ActionType at = OTHER_ACTION_TYPE, const std::string &text = "") const#

Asserts that other ttshape is compatible with this.

See isCompatible().

Parameters:

other – Other shape to test with
at – Action type to check compatibility for. Affects complex packed dimensions. Default is set to most restrictive setting.
text – Text to include in error

Throws:

invalid_argument – if not compatible

void applyCompatibilityAdjustments(const TTShape &other, ActionType at)#

Update current shape to the result of applying a binary elementwise operator on this and other shape.

The two shapes are assumed to be compatible.

Parameters:

other – Other input shape.
at – Action type used

void addDim(const TTDim &dim, int place = -1)#

Add a dimension to this ttshape.

Parameters:

dim – Dimension to add.
place – Place of the new dimension, default is last.

void removeDim(DimInt dim)#

Removes a dim from this ttshape.

Number of dims before calling the function must be at least 3.

Parameters:

dim – Dim to remove

Throws:

runtime_error – If dim doesn’t exists
runtime_error – If number of dims is less than 3

void reorderDims(const std::vector<DimInt> &dimOrder)#

Reorders the dimensions of this ttshape.

Parameters:: dimOrder – New order of dimensions

inline DimInt getNumDims() const#: Returns dimension number.

std::vector<DimInt> getOriginalSizes(bool includeDuplications = false) const#

Returns the original shape.

Parameters:: includeDuplications – If true, the returned list contains number of duplicates for each duplicated dimension, otherwise 1 is returned for these dimensions.

std::vector<DimInt> getTileSizes() const#: Returns the tile shape.

bool isBatchPacking(DimInt numDims = -1) const#

Returns true if all tile sizes are one except the last.

Optionally, it conditions on number of dimensions.

Parameters:: numDims – Required number of dimensions or -1 if can be any.

std::vector<DimInt> getExternalSizes() const#: Returns the external shape.

DimInt getNumUsedTiles() const#: Returns the number of tiles required by this ttshape.

DimInt getNumSlotsInTile() const#: Returns the number of slots in each tile.

DimInt getNumOriginalSlots() const#: Returns the number of slots in the original tensor represented by this shape.

DimInt getRotateOffsetOfDim(DimInt i) const#

Returns the rotation offset of a flattened tile to achieve rotation over the given dimension.

Parameters:: i – Dimension to rotate

bool containsUnknownUnusedSlots() const#: Returns true if any dimension has unknown values in unused slots.

void clearUnknowns()#: Remove all unknown values in unused slots.

void setAllUnusedSlotsUnknown()#: Turns on the unknown flag for all dimensions which have unused slots.

void removeDuplications()#: Removes duplicated slots for all dimensions which have duplicated slots, by setting the original size to 1.

void setAllInterleaved()#: Turns on the interleaved flag for all dimensions which are currently not interleaved.

void insertDimAt(const TTDim &dim, DimInt pos)#

Inserts a dimension at given position.

If it is inserted at pos i, current dimension at i becomes i+1.

Parameters:

dim – Dimension to add
pos – Position to insert to.

void splitDimTile(DimInt pos, DimInt size1, DimInt size2)#

Splits a dimension to 2 new dimensions by splitting the tile size.

The product of the 2 new tile sizes should be the same as the tile size in the dimension that is split. The original size remain entirely within the second resulting dimension, and therefore it must be not larger than size2. The first resulting dimension will have original size of 1. For example, the second dim in the shape [10/4,11/256,12/4] can be split to get [10/4,1/8,11/32,12/4] by calling splitDimTile(1,8,32).

Parameters:

pos – The dimension to split.
size1 – The size of the first part.
size2 – The size of the second part.

bool isDegenerateTileDim(DimInt dim) const#

Returns true if given dimension has a degenerate tile size.

Parameters:: dim – Input dimension.

bool isRotatable(DimInt dim) const#

Returns true if this dimension can be rotated efficiently using rotation operators only (without masking).

This implies for example that this dimension will be duplicated if it is summed using rotate-and-sum. A dimension is rotatable if all dimensions before it are either fully duplicated or have a degenerate tile size.

Parameters:: dim – Input dimension.

DimInt getNumComplexPackedDims() const#: Returns number of dimensions marked as complex packed.

DimInt getComplexPackedDim() const#: Returns the first complex packed dimension index, or -1 if none.

inline bool isDiagonalized() const#: Returns whether this shape is diagonalized in its first two dimensions.

void setDiagonalized(bool val)#

Set the diagonalized flag of this shape.

Diagonalized shapes must satisfy:

At least 2 dims
Dims 0-1 not duplicated, interleaved, or complex packed.

Parameters:: val – New value.

bool includesDuplicatedSlots() const#

Returns true if this TTShape includes duplicated slots and false otherwise.

This TTShape is considered to contain duplicated slots if at least one of its dimensions includes duplicated slots.

inline bool isEmpty() const#: Returns whether this TTShape is empty.

virtual void debugPrint(const std::string &title = "", Verbosity verbosity = VERBOSITY_REGULAR, std::ostream &out = std::cout) const override#

Prints the content of this object.

Parameters:

title – Text to add to the print
verbosity – Verbosity level
out – Output stream

std::string tileLayoutToString() const#

Returns tile shape in string representation: ( t1 x t2 x …

x tk )

virtual std::streamoff save(std::ostream &stream) const override#

Saves this object to a stream in binary form.

Returns the number of bytes written to the output stream.

Parameters:: stream – [in] output stream to write to

virtual std::streamoff load(std::istream &stream) override#

Loads this object from the given stream.

Returns the number of bytes read from the input stream.

Parameters:: stream – [in] input stream to read from

void reportError(const std::string &error, DimInt atDim = -1) const#

Report an error has occurred related to this shape.

This call throws an exception giving relevant details and supplied error message.

Parameters:

error – Error to report.
atDim – Optional specification of dimension index

Throws:

invalid_argument –

void reportError(const std::string &error, const TTShape &expected) const#

Report an error has occurred: this shape is different from an expected one.

This call throws an exception giving relevant details and supplied error message.

Parameters:

error – Error to report.
expected – Expected shape.

Throws:

invalid_argument –

void reportError(const std::string &error, DimInt dimIndex, const TTDim &expected) const#

Report an error has occurred: a dimension in this shape is different from an expected one.

This call throws an exception giving relevant details and supplied error message.

Parameters:

error – Error to report.
dimIndex – dimension of erroneous dimension
expected – Expected dimension.

Throws:

invalid_argument –

void validate() const#: Validates this shape is complete and valid.

void validateDimExists(DimInt dim) const#

Validates the given dimension exists in this shape.

Parameters:: dim – The given dimension.

void allowDimPacking(DimInt dim, const std::vector<TTDimTilingMethod> &allowedMethods, const std::vector<TTDimFlag> &allowedFlags, const std::string &opName = "") const#

Verifies the features used by the given dim are included in the given lists.

Parameters:

dim – Dimension index to check.
allowedMethods – List of allowed tiling methods.
allowedFlags – List of allowed flags.
opName – Name of operator requesting this check, for error messages.