Einsums Python Testing Utilities#

In order to make testing Einsums smoother, several utilities have been added to push Einsums to its limits.

class einsums.core.BadBuffer#

This class is a minimal implementation of a Python buffer object. However, it allows users to set its properties arbitrarily. This allows us to test code paths that are normally not allowed if the data in an object is validated properly, thus improving code coverage.

__init__([copy])#

Create a new buffer object. Optionally, copy the data from another regular buffer object.

Parameters:: copy – The buffer to copy from.

get_ptr()#: Get the underlying pointer to the data.

clear_ptr()#: Set the pointer in the buffer to the null pointer. This helps to test code when invalid addresses are passed in.

get_ndim() → int#: Get the number of dimensions.

set_ndim(ndim: int)#

Set the number of dimensions. This will resize the strides and shape to fit, as well as the data to match the new strides and shape.

Parameters:: ndim – The new number of dimensions.

set_ndim_noresize(ndim: int)#

Set the number of dimensions, but don’t resize anything else. This leaves the buffer in an invalid state. This is intentional, as this is a tool for testing invalid code paths.

Parameters:: ndim – The new number of dimensions.

get_itemsize() → int#: Get the number of bytes in an item.

set_itemszie(itemsize: int)#

Set the item size. This will leave the buffer in an invalid state.

Parameters:: itemsize – The new size of the items.

get_format() → str#: Gets the format string.

set_format(fmt: str)#

Set the format string. The recommendation from the developers is to use the string 'X' as an invalid scalar type, and 'ZX' as an invalid complex type. We also recommend 'y' and 'Y' for a signed and unsigned invalid integer type respectively. Code should not check for these types explicitly. Instead, they should be handled in general by any error handling code. This will leave the buffer in an invalid state.

Parameters:: str – The new format string.

get_dims() → list[int]#: Get the dimensions or shape of the buffer.

set_dims(dims: list[int])#: Set the dimensions of the buffer. This does not update any of the other data, leaving the buffer in an invalid state.

set_dim(axis: int, dim: int)#

Sets the dimension on a given axis. This does not update any of the other data, leaving the buffer in an invalid state.

Parameters:

axis – The axis to update.
dim – The new dimension.

Raises:

IndexError – When axis is outside of the size of the dimension array.

get_strides() → list[int]#: Get the strides of the buffer in bytes.

set_strides(strides: list[int])#: Set the strides of the buffer in bytes. This does not update any of the other data, leaving the buffer in an invalid state.

set_stride(axis: int, stride: int)#

Sets the stride in bytes on a given axis. This does not update any of the other data, leaving the buffer in an invalid state.

Parameters:

axis – The axis to update.
stride – The new stride.

Raises:

IndexError – When axis is outside of the size of the stride array.

change_dims_size(new_size: int)#

Resizes the dimension array. This does not initialize any values added on to the end. This will leave the buffer in an invalid state. This also doesn’t change any other data.

Parameters:: new_size – The new size for the dimension array.

change_strides_size(new_size: int)#

Resizes the stride array. This does not initialize any values added on to the end. This will leave the buffer in an invalid state. This also doesn’t change any other data.

Parameters:: new_size – The new size for the stride array.

einsums.core.throw_hip(status: int[, throw_success: bool = False])#

Throws a HIP status exception. If status == 0, it will not throw einsums.gpu_except.Success unless throw_sucess == True.

Parameters:

status – The status value to use for the exception.
throw_success – Whether to throw an exception when passed the success condition.

einsums.core.throw_hipblas(status: int[, throw_success: bool = False])#

Throws a hipBlas status exception. If status == 0, it will not throw einsums.gpu_except.blasSuccess unless throw_sucess == True.

Parameters:

status – The status value to use for the exception.
throw_success – Whether to throw an exception when passed the success condition.

einsums.core.throw_hipsolver(status: int[, throw_success: bool = False])#

Throws a hipSolver status exception. If status == 0, it will not throw einsums.gpu_except.solverSuccess unless throw_sucess == True.

Parameters:

status – The status value to use for the exception.
throw_success – Whether to throw an exception when passed the success condition.