eb

compression_safeguards.safeguards.pointwise.qoi.eb

Pointwise quantity of interest (QoI) error bound safeguard.

Classes:

PointwiseQuantityOfInterestErrorBoundSafeguard 

PointwiseQuantityOfInterestErrorBoundSafeguard(
    qoi: PointwiseQuantityOfInterestExpression,
    type: str | ErrorBound,
    eb: int | float | str | Parameter,
    qoi_dtype: str | ToFloatMode = lossless,
)

Bases: PointwiseSafeguard

flowchart LR compression_safeguards.safeguards.pointwise.qoi.eb.PointwiseQuantityOfInterestErrorBoundSafeguard[PointwiseQuantityOfInterestErrorBoundSafeguard] compression_safeguards.safeguards.pointwise.abc.PointwiseSafeguard[PointwiseSafeguard] compression_safeguards.safeguards.abc.Safeguard[Safeguard] compression_safeguards.safeguards.pointwise.abc.PointwiseSafeguard --> compression_safeguards.safeguards.pointwise.qoi.eb.PointwiseQuantityOfInterestErrorBoundSafeguard compression_safeguards.safeguards.abc.Safeguard --> compression_safeguards.safeguards.pointwise.abc.PointwiseSafeguard click compression_safeguards.safeguards.pointwise.qoi.eb.PointwiseQuantityOfInterestErrorBoundSafeguard href "" "compression_safeguards.safeguards.pointwise.qoi.eb.PointwiseQuantityOfInterestErrorBoundSafeguard" click compression_safeguards.safeguards.pointwise.abc.PointwiseSafeguard href "" "compression_safeguards.safeguards.pointwise.abc.PointwiseSafeguard" click compression_safeguards.safeguards.abc.Safeguard href "" "compression_safeguards.safeguards.abc.Safeguard"

The PointwiseQuantityOfInterestErrorBoundSafeguard guarantees that the pointwise error type on a derived pointwise quantity of interest (QoI) is less than or equal to the provided bound eb.

The quantity of interest is specified as a non-constant expression, in string form, over the pointwise value x. For example, to bound the error on the square of x, set qoi="square(x)" (or qoi="x**2").

If the derived quantity of interest for an element evaluates to an infinite value, this safeguard guarantees that the quantity of interest on the corrected value produces the exact same infinite value. For a NaN quantity of interest, this safeguard guarantees that the quantity of interest on the corrected value is also NaN, but does not guarantee that it has the same bit pattern.

The error bound can be verified by evaluating the QoI in the floating-point data type selected by qoi_dtype parameter using the evaluate_qoi method.

Please refer to the PointwiseQuantityOfInterestExpression for the EBNF grammar that specifies the language in which the quantities of interest are written.

The implementation was originally inspired by:

Pu Jiao, Sheng Di, Hanqi Guo, Kai Zhao, Jiannan Tian, Dingwen Tao, Xin Liang, and Franck Cappello. (2022). Toward Quantity-of-Interest Preserving Lossy Compression for Scientific Data. Proceedings of the VLDB Endowment. 16, 4 (December 2022), 697-710. Available from: doi:10.14778/3574245.3574255.

Parameters:
  • qoi (PointwiseExpr) –

    The non-constant expression for computing the derived quantity of interest over a pointwise value x.

  • type (str | ErrorBound) –

    The type of error bound on the quantity of interest that is enforced by this safeguard.

  • eb (int | float | str | Parameter) –

    The value of or late-bound parameter name for the error bound on the quantity of interest that is enforced by this safeguard.

    The error bound is applied relative to the values of the quantity of interest evaluated on the original data.

  • qoi_dtype (str | ToFloatMode, default: lossless ) –

    The floating-point data type in which the quantity of interest is evaluated. By default, the smallest floating-point data type that can losslessly represent all input data values is chosen.
Raises:
  • TypeCheckError –

    if any parameter has the wrong type.

  • SyntaxError –

    if the qoi is not a valid pointwise quantity of interest expression.

  • ValueError –

    if type does not name a valid error bound, or the qoi_dtype does not name a valid floating-point data type.

  • ValueError –

    if eb is an invalid error bound value for the error bound type.

Methods:

kind class-attribute 

kind: str = 'qoi_eb_pw'

late_bound property 

late_bound: Set[Parameter]

The set of late-bound parameters that this safeguard has.

Late-bound parameters are only bound when checking and applying the safeguard, in contrast to the normal early-bound parameters that are configured during safeguard initialisation.

Late-bound parameters can be used for parameters that depend on the specific data that is to be safeguarded.

evaluate_qoi 

evaluate_qoi(
    data: ndarray[S, dtype[T]], late_bound: Bindings
) -> ndarray[S, dtype[F]]

Evaluate the derived quantity of interest on the data in the floating-point data type selected by the qoi_dtype parameter.

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

    Data for which the quantity of interest is evaluated.

  • late_bound (Bindings) –

    Bindings for late-bound constants in the quantity of interest.
Returns:
  • qoi( ndarray[S, dtype[F]] ) –

    Evaluated quantity of interest, in floating-point.
Raises:
  • TypeError –

    if the data could not be losslessly cast to qoi_dtype.

  • LateBoundParameterResolutionError –

    if any of the qoi's late-bound constants is not contained in the bindings.

  • ValueError –

    if any late-bound constant could not be broadcast to the data's shape.

  • TypeError –

    if any late-bound constant is floating-point but the data is integer.

  • ValueError –

    if not all values for all late-bound constants could be losslessly converted to the data's type.
Referenced by:

check_pointwise 

check_pointwise(
    data: ndarray[S, dtype[T]],
    approximation: ndarray[S, dtype[T]],
    *,
    late_bound: Bindings,
    where: Literal[True] | ndarray[S, dtype[bool]] = True,
) -> ndarray[S, dtype[bool]]

Check which elements in the approximation array satisfy the error bound for the quantity of interest on the data.

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

    Original data array, relative to which the approximation is checked.

  • approximation (ndarray[S, dtype[T]]) –

    Approximation of the data array.

  • late_bound (Bindings) –

    Bindings for late-bound parameters, including for this safeguard.

  • where (Literal[True] | ndarray[S, dtype[bool]], default: True ) –

    Only check at data points where the condition is True.
Returns:
  • ok( ndarray[S, dtype[bool]] ) –

    Pointwise, True if the check succeeded for this element.
Raises:
  • TypeError –

    if the data could not be losslessly cast to qoi_dtype.

  • LateBoundParameterResolutionError –

    if any of the qoi's late-bound constants is not contained in the bindings.

  • ValueError –

    if any late-bound constant could not be broadcast to the data's shape.

  • TypeError –

    if any late-bound constant is floating-point but the data is integer.

  • ValueError –

    if not all values for all late-bound constants could be losslessly converted to the data's type.

  • LateBoundParameterResolutionError –

    if the error bound eb is late-bound but its late-bound parameter is not in late_bound.

  • ValueError –

    if the late-bound eb could not be broadcast to the data's shape.

  • ValueError –

    if the late-bound eb is non-finite, i.e. infinite or NaN, or an invalid error bound value for the error bound type.

compute_safe_intervals 

compute_safe_intervals(
    data: ndarray[S, dtype[T]],
    *,
    late_bound: Bindings,
    where: Literal[True] | ndarray[S, dtype[bool]] = True,
) -> IntervalUnion[T, int, int]

Compute the intervals in which the error bound is upheld with respect to the quantity of interest on the data.

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

    Data for which the safe intervals should be computed.

  • late_bound (Bindings) –

    Bindings for late-bound parameters, including for this safeguard.

  • where (Literal[True] | ndarray[S, dtype[bool]], default: True ) –

    Only compute the safe intervals at pointwise checks where the condition is True.
Returns:
  • intervals( IntervalUnion[T, int, int] ) –

    Union of intervals in which the error bound is upheld.
Raises:
  • TypeError –

    if the data could not be losslessly cast to qoi_dtype.

  • LateBoundParameterResolutionError –

    if any of the qoi's late-bound constants is not contained in the bindings.

  • ValueError –

    if any late-bound constant could not be broadcast to the data's shape.

  • TypeError –

    if any late-bound constant is floating-point but the data is integer.

  • ValueError –

    if not all values for all late-bound constants could be losslessly converted to the data's type.

  • LateBoundParameterResolutionError –

    if the error bound eb is late-bound but its late-bound parameter is not in late_bound.

  • ValueError –

    if the late-bound eb could not be broadcast to the data's shape.

  • ValueError –

    if the late-bound eb is non-finite, i.e. infinite or NaN, or an invalid error bound value for the error bound type.

compute_footprint 

compute_footprint(
    foot: ndarray[S, dtype[bool]],
    *,
    late_bound: Bindings,
    where: Literal[True] | ndarray[S, dtype[bool]] = True,
) -> ndarray[S, dtype[bool]]

Compute the footprint of the foot array, e.g. for expanding data points into the pointwise checks that they contribute to.

The footprint is equivalent to foot & where.

Parameters:
  • foot (ndarray[S, dtype[bool]]) –

    Array for which the footprint is computed.

  • late_bound (Bindings) –

    Bindings for late-bound parameters, including for this safeguard.

  • where (Literal[True] | ndarray[S, dtype[bool]], default: True ) –

    Only compute the footprint at pointwise checks where the condition is True.
Returns:

compute_inverse_footprint 

compute_inverse_footprint(
    foot: ndarray[S, dtype[bool]],
    *,
    late_bound: Bindings,
    where: Literal[True] | ndarray[S, dtype[bool]] = True,
) -> ndarray[S, dtype[bool]]

Compute the inverse footprint of the foot array, e.g. for expanding pointwise check fails into the points that could have contributed to the failures.

The inverse footprint is equivalent to foot & where.

Parameters:
  • foot (ndarray[S, dtype[bool]]) –

    Array for which the inverse footprint is computed.

  • late_bound (Bindings) –

    Bindings for late-bound parameters, including for this safeguard.

  • where (Literal[True] | ndarray[S, dtype[bool]], default: True ) –

    Only compute the inverse footprint at pointwise checks where the condition is True.
Returns:

get_config 

get_config() -> dict[str, JSON]

Returns the configuration of the safeguard.

Returns:
  • config( dict[str, JSON] ) –

    Configuration of the safeguard.