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.

Added in version 1.0.0.

__init__([copy])#

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

Parameters:

copy – The buffer to copy from.

Added in version 1.0.0.

get_ptr()#

Get the underlying pointer to the data.

Added in version 1.0.0.

clear_ptr()#

Set the pointer in the buffer to the null pointer. This helps to test code when invalid addresses are passed in.

Added in version 1.0.0.

get_ndim() → int#

Get the number of dimensions.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.

get_itemsize() → int#

Get the number of bytes in an item.

Added in version 1.0.0.

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.

Added in version 1.0.0.

get_format() → str#

Gets the format string.

Added in version 1.0.0.

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.

Added in version 1.0.0.

get_dims() → list[int]#

Get the dimensions or shape of the buffer.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.

get_strides() → list[int]#

Get the strides of the buffer in bytes.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.

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.

Added in version 1.0.0.