18.14. Utils

popxl.utils.host_cast_then_pow2scale(src, dtype=None, log2_scale=0)

Run a fused operation cast(X, dtype) * pow2(log2_scale) on the host.

This is a host-based utility function mainly intended to convert into PopXL’s NumPy-based representation for float8 data back into user data.

Parameters

  • src (ndarray) – A PopXL NumPy-based float8 data array to convert. This must be a NumPy array with with structured dtype popxl.utils.np_dtype_float8_143 (np.dtype([("float8_143", "u1")])) or popxl.utils.np_dtype_float8_152 (np.dtype([("float8_152", "u1")])). Other values are not currently supported.

  • dtype (dtypes.dtype) – The PopXL dtype representing the target array type. This must be one of popxl.float16, popxl.float32 or popxl.float64. Other values are not currently supported.

  • log2_scale (int) – The data is multiplied by pow2(log2_scale) after casting. This must be an int in the range [-32, 32). Other values are not currently supported.

Raises

RuntimeError – If parameters are not supported.

Returns

A NumPy array with dtype np.float16, np.float32 or np.float64.

Return type

np.ndarray

popxl.utils.host_pow2scale_then_cast(src, dtype=None, log2_scale=0, nan_on_overflow=True)

Run a fused operation cast(src * pow2(log2_scale), dtype) on the host.

This is a host-based utility function mainly intended to convert user data into PopXL’s NumPy-based representation for float8 data.

Parameters

  • src (ndarray) – The NumPy array of user data to convert. Torch tensors are automatically converted. This must be a NumPy array with dtype being np.float16, np.float32 or np.float64 (or torch equivalent). Other values are not supported.

  • dtype (dtypes.dtype) – The PopXL data type to convert to. This must be either either popxl.float8_143 or popxl.float8_152. Other values are not currently supported.

  • log2_scale (int) – The user’s data is multiplied by pow2(log2_scale) before casting. This must be an int in the range [-32, 32). Other values are not currently supported.

  • nan_on_overflow (bool) – If set, replace values that cannot be represented by the requested dtype with np.nan values.

Raises

RuntimeError – If parameters are not supported.

Returns

A NumPy array with structured dtype

popxl.utils.np_dtype_float8_143 (np.dtype([("float8_143", "u1")])) or popxl.utils.np_dtype_float8_152 (np.dtype([("float8_152", "u1")])) containing float8 data.

Return type

np.ndarray

popxl.utils.table_to_string(rows, delimiter=' | ', header=True)

Create a string that resembles a table from inputs rows.

Each item in rows represents a row which will be delimited with delimiter. Each row should exactly have the same length.

Example:

rows = [
    ["num", "foo", "name"],
    [3, "aaab", "args"],
    [4, "barrrr", "kwargs"],
    [3, "me", "inspect"],
    [-1, "who", "popxl"],
]
print(table_to_string(rows))

Output:

num | foo    | name
-----------------------
3   | aaab   | args
4   | barrrr | kwargs
3   | me     | inspect
-1  | who    | popxl
Parameters

  • rows (Sequence[Sequence]) – A row by column nested sequence. Each item needs to be a string or stringable

  • delimiter (str) – String used to delimit columns

  • header (bool) – If true, the first row is underlined

Returns

A string representation of the table

Return type

str

popxl.utils.to_numpy(x, dtype=None, downcast=True, copy=True, log2_scale=None, nan_on_overflow=None)

Convert a HostScalarTensor to a numpy array and copies the data if enabled.

If x is an np.memmap and copy is False, the following conditions must be satisfied (to ensure no copy is possible):

  • x does not require downcasting

  • dtype is None or equal to x.dtype

  • x is in C-array form.

The returned array in this case will be exactly x. It will still be an np.memmap.

Parameters

  • x (HostScalarTensor) – The data used to initialise the tensor. This can be an np.ndarray, torch.tensor or a value NumPy can use to construct an np.ndarray. If dtype is of float8 type this must be a np.float16, np.float32 or float64 type, torch equivalent, or native type equivalent. Other values are not supported.

  • dtype (Optional[dtypes.dtype]) – The data type of the tensor to be created. If not specified NumPy will infer the data type and downcast to 32 bits if necessary. For float8 dtypes automatic inference of dtype is not currently possible, please explicitly specify the dtype.

  • downcast (bool) – If True and no dtype is provided, 64-bit float/ints will be downcast to 32-bit variants. Defaults to True.

  • copy (bool) – If true the objects data is guaranteed to be copied.

  • log2_scale (int) – If dtype is either popxl.float8_143 or popxl.float8_152 then multiply the incoming data by pow2(log2_scale) before casting.

  • nan_on_overflow (bool) – If dtype is either popxl.float8_143 or popxl.float8_152 and this flag is set then replace values that cannot be represented by the requested dtype with np.nan values.

Raises

  • RuntimeError – If parameters are not supported.

  • TypeError – If dtype is of float8 type and x is not of type np.float16,

  • np.float32 or float64, torch equivalent, or native type equivalent. –

  • ValueError – If the data parameter is a np.memmap and it is either not

  • a C-array, has a dtype that requires downcasting, or the dtype parameter –

  • is not None and conflicts with data.dtype. –

Returns

A NumPy array.

Return type

np.ndarray