Assertions

Assertions

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.

Redefining assertions

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:

#include <stdexcept>
#undef eigen_assert
#define eigen_assert(x) \
  if (!(x)) { throw (std::runtime_error("Put your message here")); }

Disabling assertions

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.

Static assertions

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.

Matrix3d()  + Matrix4d();   // adding matrices of different sizes
Matrix4cd() * Vector3cd();  // invalid product known at compile time

Static assertions are defined in StaticAssert.h. EIGEN_STATIC_ASSERT(CONDITION,MSG) expands to the native static_assert:

#define EIGEN_STATIC_ASSERT(X,MSG) static_assert(X, #MSG);

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.

Derived static assertions

There are other macros derived from EIGEN_STATIC_ASSERT to enhance readability. Their names are self-explanatory.

• EIGEN_STATIC_ASSERT_FIXED_SIZE(TYPE) - passes if TYPE is fixed size.
• EIGEN_STATIC_ASSERT_DYNAMIC_SIZE(TYPE) - passes if TYPE is dynamic size.
• EIGEN_STATIC_ASSERT_LVALUE(Derived) - fails if Derived is read-only.
• EIGEN_STATIC_ASSERT_ARRAYXPR(Derived) - passes if Derived is an array expression.
• EIGEN_STATIC_ASSERT_SAME_XPR_KIND(Derived1, Derived2) - fails if the two expressions are an array one and a matrix one.

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.

Strict 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.

• EIGEN_STATIC_ASSERT_VECTOR_ONLY(TYPE) - passes if TYPE must be a vector type.
• EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(TYPE, SIZE) - passes if TYPE must be a vector of the given size.
• EIGEN_STATIC_ASSERT_MATRIX_SPECIFIC_SIZE(TYPE, ROWS, COLS) - passes if TYPE must be a matrix with given rows and columns.

Permissive assertions

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.

• EIGEN_STATIC_ASSERT_SAME_VECTOR_SIZE(TYPE0,TYPE1) - fails if the two vector expression types must have different sizes.
• EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE(TYPE0,TYPE1) - fails if the two matrix expression types must have different sizes.
• EIGEN_STATIC_ASSERT_SIZE_1x1(TYPE) - fails if TYPE cannot be an 1x1 expression.

See StaticAssert.h for details such as what messages they throw.

Disabling static assertions

If EIGEN_NO_STATIC_ASSERT is defined, the static assertions are removed entirely:

#define EIGEN_STATIC_ASSERT(CONDITION,MSG)

They are not downgraded to run-time checks, so the misuse they guard against is reported neither at compile time nor at run time. EIGEN_NO_STATIC_ASSERT is undefined by default.