1 /* Copyright 2018 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 // Library for comparing literals without taking a dependency on testing 17 // libraries. 18 19 #ifndef TENSORFLOW_COMPILER_XLA_LITERAL_COMPARISON_H_ 20 #define TENSORFLOW_COMPILER_XLA_LITERAL_COMPARISON_H_ 21 22 #include "tensorflow/compiler/xla/error_spec.h" 23 #include "tensorflow/compiler/xla/literal.h" 24 #include "tensorflow/core/lib/core/status.h" 25 26 namespace xla { 27 namespace literal_comparison { 28 29 // Returns ok if the given shapes have the same rank, dimension sizes, and 30 // primitive types. 31 Status EqualShapes(const Shape& expected, const Shape& actual); 32 33 // Returns ok if the expected and actual literals are (bitwise) equal for all 34 // elements in the literal. Also, asserts that the rank, dimensions sizes, and 35 // primitive type are equal. 36 Status Equal(const LiteralSlice& expected, const LiteralSlice& actual); 37 38 // Structure that contains the distribution of absolute and relative errors, 39 // bucketized into five buckets: [0.0001, 0.001, 0.01, 0.1, 1]. 40 // Useful to understand the distribution of errors and set the permissible 41 // error bounds in an ErrorSpec. 42 struct ErrorBuckets { 43 explicit ErrorBuckets(const std::vector<int64_t>& absolute_error_buckets = {}, 44 const std::vector<int64_t>& rel_error_buckets = {}) abs_error_bucketsErrorBuckets45 : abs_error_buckets(absolute_error_buckets), 46 rel_error_buckets(rel_error_buckets) {} 47 48 const std::vector<int64_t> abs_error_buckets; 49 const std::vector<int64_t> rel_error_buckets; 50 }; 51 52 using MiscompareCallback = std::function<void( 53 const LiteralSlice& expected, const LiteralSlice& actual, 54 const LiteralSlice& mismatches, const ShapeIndex& shape_index, 55 const ErrorBuckets& error_buckets)>; 56 57 // Inspects whether the expected and actual literals are within the given error 58 // bound for all elements. Also, inspects whether the rank, dimensions sizes, 59 // and dimension bounds are equivalent. 60 // 61 // Tuples are matched recursively. 62 // 63 // When comparing tensors of non-floating-point type, this inspects for exact 64 // equality, ignoring the ErrorSpec. 65 // 66 // If the shape of the literals is neither a complex/floating-point tensor nor a 67 // tuple which contains a complex/floating-point tensor, Near() is equivalent to 68 // Equal(). We don't raise an error in this case, because we want to allow 69 // callers to call Near() even if they have no preconceptions about the shapes 70 // being compared. 71 // 72 // If detailed_message is true, then the error message in the assertion result 73 // will contain a more detailed breakdown of mismatches. By default, we display 74 // a detailed message only for "large" inputs. 75 // 76 // If miscompare_callback is nullptr, Near will return an error on the first 77 // detected mismatch. 78 Status Near(const LiteralSlice& expected, const LiteralSlice& actual, 79 const ErrorSpec& error, std::optional<bool> detailed_message, 80 const MiscompareCallback& miscompare_callback); 81 82 // Calling ToString on a literal with over 100 million elements takes around 83 // 3 minutes. The utility of printing a literal with >1000 elements is 84 // questionable, especially when writing the Literal proto to disk is orders 85 // of magnitude faster. 86 std::string ToStringTruncated(const LiteralSlice& literal); 87 88 } // namespace literal_comparison 89 } // namespace xla 90 91 #endif // TENSORFLOW_COMPILER_XLA_LITERAL_COMPARISON_H_ 92