![]() |
Eigen
5.0.1-dev+master
|
The macro eigen_assert is defined to be eigen_plain_assert by default, and eigen_plain_assert essentially behaves like the standard assert. Having Eigen's own layer instead of using assert directly lets Eigen handle device code (assertions in GPU kernels are disabled unless explicitly enabled) and avoid ODR pitfalls caused by __FILE__ expanding differently across translation units; see Eigen/src/Core/util/Assert.h for the details.
Both eigen_assert and eigen_plain_assert are defined in Macros.h. Defining eigen_assert indirectly gives you a chance to change its behavior. You can redefine this macro if you want to do something else such as throwing an exception, and fall back to its default behavior with eigen_plain_assert. The code below tells Eigen to throw an std::runtime_error:
Assertions cost run time and can be turned off. You can suppress eigen_assert by defining EIGEN_NO_DEBUG before including Eigen headers. EIGEN_NO_DEBUG is undefined by default unless NDEBUG is defined.
Coefficient-count checks against matrix rows or columns reject provably incompatible fixed dimensions at compile time, including in release builds. This applies to diagonal products, factorization workspaces and rank updates. Unknown dimensions retain debug runtime checks, also when EIGEN_NO_STATIC_ASSERT disables static diagnostics. Invalid fixed-size calls that previously compiled and asserted only at runtime can therefore fail to compile.
In the Eigen library, there are many conditions that can and should be detected at compile time. For instance, we use static assertions to prevent the code below from compiling.
Static assertions are defined in StaticAssert.h. EIGEN_STATIC_ASSERT(CONDITION,MSG) expands to the native static_assert:
CONDITION must be a compile-time boolean expression. MSG is not evaluated: it is stringified into the diagnostic, which is why the messages are written ALL_CAPS_AND_THEY_ARE_SHOUTING, as in YOU_TRIED_CALLING_A_VECTOR_METHOD_ON_A_MATRIX. Use one of the existing messages where it fits; see StaticAssert.h for the established names.
Because it expands to a declaration, EIGEN_STATIC_ASSERT can be used wherever a declaration is allowed, including class scope — see for instance log1p_impl in MathFunctions.h.
There are other macros derived from EIGEN_STATIC_ASSERT to enhance readability. Their names are self-explanatory.
Because Eigen handles both fixed-size and dynamic-size expressions, some conditions cannot be clearly determined at compile time. We classify them into strict assertions and permissive assertions.
These assertions fail if the condition may not be met. For example, MatrixXd may not be a vector, so it fails EIGEN_STATIC_ASSERT_VECTOR_ONLY.
These assertions fail if the condition cannot be met. For example, MatrixXd and Matrix4d may have the same size, so they pass EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE.
See StaticAssert.h for details such as what messages they throw.
If EIGEN_NO_STATIC_ASSERT is defined, the static assertions are removed entirely:
They are not downgraded to run-time checks, so the misuse they guard against is reported neither at compile time nor at run time unless the operation also has a runtime assertion. EIGEN_NO_STATIC_ASSERT is undefined by default.
Shared shape checks reject statically incompatible coefficient counts and product inner dimensions at compile time, including in release builds. Checks proven valid do not read dimensions at runtime. Matching rows and columns (including directional concatenation checks) follow the same rule. Vector adaptation and scalar extraction likewise reject provably invalid shapes, while allowing dynamically sized inputs that satisfy their preconditions at runtime. Square-only preconditions remain runtime checks, elided when the matrix is proven square. This preserves runtime-guarded calls on rectangular fixed-size types in C++14. Solver right-hand sides are checked against the appropriate fixed dimension, including the reversed row/column rule for transposed solves. Nonempty-input checks remain runtime-only so C++14 code can guard reductions on fixed empty expressions. They are elided for inputs proven nonempty. Empty dense sum() and prod() remain valid and return their respective identity values. Empty lpNorm<Infinity>() and hypotNorm() likewise remain valid and return zero. For an empty vector, stableNormalized() returns an empty vector and stableNormalize() is a no-op; the internal maximum-absolute-value reduction used by stable normalization has identity zero. An empty vector's homogeneous() expression is not empty: it contains the appended coefficient one, so its sum() and prod() return one rather than asserting on the underlying empty vector. These identity reductions are valid for fixed-size empty inputs in C++14 as well as dynamic inputs. Tensor shape checks reject different ranks or incompatible fixed extents. Equal rank alone never proves equality of runtime extents. Unknown dimensions are checked by debug assertions; maximum storage capacities are not treated as actual dimensions. Row and column vectors may have equal coefficient counts.
With EIGEN_NO_STATIC_ASSERT, these shared checks retain their debug runtime fallback. Defining EIGEN_NO_DEBUG disables the default runtime assertions, not the static diagnostics. This stricter validation can reject invalid code that previously compiled and only asserted when executed in a debug build.