cast

compression_safeguards.utils.cast

Utility functions to cast arrays to floating-point, binary, and total-order representations.

Classes:

  • ToFloatMode –

    Mode for losslessly converting numeric data to floating-point.

Functions:

  • to_float –

    Losslessly convert the array x to the floating-point data type ftype.

  • from_float –

    Reverses the conversion of the array x, converted using the

  • as_bits –

    Reinterprets the array a to its binary unsigned integer representation.

  • to_total_order –

    Reinterprets the array a to its total-order unsigned binary

  • from_total_order –

    Reverses the reinterpretation of the array a back from total-order

  • lossless_cast –

    Try to losslessly convert x to the provided dtype.

  • saturating_finite_float_cast –

    Try to convert the finite x to the provided floating-point dtype.

ToFloatMode

Bases: Enum

flowchart LR compression_safeguards.utils.cast.ToFloatMode[ToFloatMode] click compression_safeguards.utils.cast.ToFloatMode href "" "compression_safeguards.utils.cast.ToFloatMode"

Mode for losslessly converting numeric data to floating-point.

Methods:

lossless class-attribute instance-attribute 

lossless = auto()

Automatically select the smallest floating-point data type that can losslessly represent the input data.

Used by:

float16 class-attribute instance-attribute 

float16 = auto()

Use 16 bit floating-point precision, if lossless.

float32 class-attribute instance-attribute 

float32 = auto()

Use 32 bit floating-point precision, if lossless.

float64 class-attribute instance-attribute 

float64 = auto()

Use 64 bit floating-point precision, if lossless.

float128 class-attribute instance-attribute 

float128 = auto()

Use 128 bit floating-point precision, if lossless.

floating_point_dtype_for 

floating_point_dtype_for(
    dtype: dtype[T],
) -> dtype[floating]

Select the floating-point dtype for the input dtype.

Only data type supported by the safeguards (see Safeguards.supported_dtypes) are supported by this method.

The numpy_quaddtype package is used to provide a true 128 bit floating-point data type.

Parameters:
  • dtype (dtype[T]) –

    Data type of the input data.
Returns:
  • ftype( dtype[floating] ) –

    Floating-point data type that can losslessly represent all values from the input dtype.
Raises:
  • TypeError –

    if dtype cannot be losslessly cast to self.
Referenced by:

to_float 

to_float(
    x: ndarray[S, dtype[T]], ftype: dtype[F]
) -> ndarray[S, dtype[F]]

Losslessly convert the array x to the floating-point data type ftype.

ftype must be a floating-point data type that can represent all values of the data type of x without loss in precision:

  • For floating-point data, it is at least the input data type.

  • For integer data, it is a floating-point type with sufficient precision to represent all integer values, i.e. a type whose mantissa has more bits than the integer type. For the supported floating-point types, this corresponds to choosing a floating-point data type with a larger bit width (e.g. at least np.float64 for np.int32 or np.uint32 data).

The ToFloatMode.floating_point_dtype_for method can be used to select a floating-point data type that fits the above criteria.

Parameters:
  • x (ndarray[S, dtype[T]]) –

    The array to convert.

  • ftype (dtype[F]) –

    The floating-point data type to convert to, which must be able to losslessly represent all values of the data type of x.
Returns:
  • converted( ndarray[S, dtype[F]] ) –

    The converted array with the chosen floating-point data type.
Referenced by:

from_float 

from_float(
    x: ndarray[S, dtype[F]], dtype: dtype[T]
) -> ndarray[S, dtype[T]]

Reverses the conversion of the array x, converted using the to_float, back to the original dtype.

If the original dtype was floating-point with lower precision, the conversion is lossy.

If the original dtype was integer, the rounding conversion is lossy. Infinite values are clamped to the minimum/maximum integer values. NaN values are converted to integer zero.

Parameters:
  • x (ndarray[S, dtype[F]]) –

    The floating-point array to re-convert.

  • dtype (dtype[T]) –

    The original dtype.
Returns:
  • converted( ndarray[S, dtype[T]] ) –

    The re-converted array with the original dtype.

as_bits 

as_bits(
    a: ndarray[S, dtype[T]],
) -> ndarray[S, dtype[U]]

Reinterprets the array a to its binary unsigned integer representation.

Parameters:
Returns:
  • binary( ndarray[S, dtype[U]] ) –

    The binary unsigned integer representation of the array a.

to_total_order 

to_total_order(
    a: ndarray[S, dtype[T]],
) -> ndarray[S, dtype[U]]

Reinterprets the array a to its total-order unsigned binary representation.

In their total-order representation, the smallest value is mapped to unsigned zero, and the largest value is mapped to the largest unsigned value.

For floating-point values, this implementation is based on Michael Herf's FloatFlip function, see http://stereopsis.com/radix.html.

Parameters:
  • a (ndarray[S, dtype[T]]) –

    The array to reinterpret to its total-order.
Returns:
  • ordered( ndarray[S, dtype[U]] ) –

    The total-order unsigned binary representation of the array a.
Raises:
  • TypeSetError –

    if a is not a signed/unsigned integer or floating array.

from_total_order 

from_total_order(
    a: ndarray[S, dtype[U]], dtype: dtype[T]
) -> ndarray[S, dtype[T]]

Reverses the reinterpretation of the array a back from total-order unsigned binary to the provided dtype.

For floating-point values, this implementation is based on Michael Herf's IFloatFlip function, see http://stereopsis.com/radix.html.

Parameters:
  • a (ndarray[S, dtype[U]]) –

    The array to reverse-reinterpret back from its total-order.
Returns:
  • array( ndarray[S, dtype[T]] ) –

    The array with its original dtype.
Raises:
  • TypeSetError –

    if a is not an unsigned integer array.

  • TypeSetError –

    if dtype is not a signed/unsigned integer or floating data type.

lossless_cast 

lossless_cast(x: int | float | number | ndarray[S, dtype[number]], dtype: dtype[T]) -> ndarray[tuple[] | S, dtype[T]]

Try to losslessly convert x to the provided dtype.

A lossless conversion is one that can be reversed while preserving the original value. Integer values can be losslessly converted to integer or floating-point types with sufficient precision. Floating-point values can only be converted to floating-point types.

Parameters:
Returns:
  • converted( narray[tuple[] | S, dtype[T]] ) –

    The losslessly converted value or array with the given dtype.
Raises:
  • TypeError –

    if floating-point values are converted to an integer dtype.

  • ValueError –

    if not all values could be losslessly converted to dtype.

saturating_finite_float_cast 

saturating_finite_float_cast(x: int | float | number | ndarray[S, dtype[number]], dtype: dtype[F]) -> ndarray[tuple[] | S, dtype[F]]

Try to convert the finite x to the provided floating-point dtype. Under- and overflows are clamped to finite values.

Parameters:
  • x (int | float | ndarray[S, dtype[number]]) –

    The value or array to convert.

  • dtype (dtype[F]) –

    The floating-point dtype to which the value or array should be converted.
Returns:
  • converted( narray[tuple[] | S, dtype[F]] ) –

    The losslessly converted value or array with the given dtype.
Raises:
  • ValueError –

    if any values are non-finite, i.e. infinite or NaN.