doc/PreprocessorDirectives.dox

namespace Eigen {

/** \page TopicPreprocessorDirectives Preprocessor directives

You can control some aspects of %Eigen by defining the preprocessor tokens using \c \#define. These macros
should be defined before any %Eigen headers are included. Often they are best set in the project options.

This page lists the preprocessor tokens recognized by %Eigen.

\eigenAutoToc


\section TopicPreprocessorDirectivesMajor Macros with major effects

These macros have a major effect and typically break the API (Application Programming Interface) and/or the
ABI (Application Binary Interface). This can be rather dangerous: if parts of your program are compiled with
one option, and other parts (or libraries that you use) are compiled with another option, your program may
fail to link or exhibit subtle bugs. Nevertheless, these options can be useful for people who know what they
are doing.

 - \b EIGEN_DEFAULT_DENSE_INDEX_TYPE - the type for column and row indices in matrices, vectors and array
   (DenseBase::Index). Set to \c std::ptrdiff_t by default.
 - \b EIGEN_DEFAULT_IO_FORMAT - the IOFormat to use when printing a matrix if no %IOFormat is specified.
   Defaults to the %IOFormat constructed by the default constructor IOFormat::IOFormat().
 - \b EIGEN_INITIALIZE_MATRICES_BY_ZERO - if defined, all entries of newly constructed matrices and arrays are
   initialized to zero, as are new entries in matrices and arrays after resizing. Not defined by default.
   \warning The unary (resp. binary) constructor of \c 1x1 (resp. \c 2x1 or \c 1x2) fixed size matrices is
   always interpreted as an initialization constructor where the argument(s) are the coefficient values
   and not the sizes. For instance, \code Vector2d v(2,1); \endcode will create a vector with coefficients [2,1],
   and \b not a \c 2x1 vector initialized with zeros (i.e., [0,0]). If such cases might occur, then it is
   recommended to use the default constructor with a explicit call to resize:
   \code
   Matrix<?,SizeAtCompileTime,1> v;
   v.resize(size);
   Matrix<?,RowsAtCompileTime,ColsAtCompileTime> m;
   m.resize(rows,cols);
   \endcode
 - \b EIGEN_INITIALIZE_MATRICES_BY_NAN - if defined, all entries of newly constructed matrices and arrays are
   initialized to NaN, as are new entries in matrices and arrays after resizing. This option is especially
   useful for debugging purpose, though a memory tool like <a href="http://valgrind.org/">valgrind</a> is
   preferable. Not defined by default.
   \warning See the documentation of \c EIGEN_INITIALIZE_MATRICES_BY_ZERO for a discussion on a limitations
   of these macros when applied to \c 1x1, \c 1x2, and \c 2x1 fixed-size matrices.
 - \b EIGEN_NO_AUTOMATIC_RESIZING - if defined, the matrices (or arrays) on both sides of an assignment
   <tt>a = b</tt> have to be of the same size; otherwise, %Eigen automatically resizes \c a so that it is of
   the correct size. Not defined by default.


\section TopicPreprocessorDirectivesCppVersion C++ standard features

By default, %Eigen strives to automatically detect and enable language features at compile-time based on
the information provided by the compiler.

 - \b EIGEN_MAX_CPP_VER - disables usage of C++ features requiring a version greater than EIGEN_MAX_CPP_VER.
   Possible values are: 14, 17, etc. If not defined (the default), %Eigen enables all features supported
   by the compiler. For instance, one might limit the C++ version to C++14 by defining
   EIGEN_MAX_CPP_VER=14.

Individual features can be explicitly enabled or disabled by defining the following token to 0 or 1 respectively.
For instance, one might disable use of \c std::invoke_result by defining
EIGEN_HAS_STD_INVOKE_RESULT=0.

 - \b EIGEN_HAS_STD_INVOKE_RESULT - controls the usage of \c std::invoke_result (C++17). When disabled,
   \c std::result_of is used as a fallback.
 - \b EIGEN_HAS_C99_MATH - Deprecated and ignored. Defined to 1 by default for compatibility with downstream code
   that checks this token; defining it has no effect on %Eigen.
 - \b EIGEN_NO_IO - Disables any usage and support for `<iostreams>`.

\section TopicPreprocessorDirectivesAssertions Assertions

The %Eigen library contains many assertions to guard against programming errors, both at compile time and at
run time. However, these assertions do cost time and can thus be turned off.

 - \b EIGEN_NO_DEBUG - disables %Eigen's assertions if defined. Not defined by default, unless the
   \c NDEBUG macro is defined (this is a standard C++ macro which disables all asserts).
 - \b EIGEN_NO_STATIC_ASSERT - if defined, %Eigen's compile-time static assertions are removed rather than
   downgraded: the misuse they guard against is then reported neither at compile time nor at run time.
   Not defined by default.
 - \b eigen_assert - macro with one argument that is used inside %Eigen for assertions. By default, it is
   basically defined to be \c assert, which aborts the program if the assertion is violated. Redefine this
   macro if you want to do something else, like throwing an exception.

\section TopicPreprocessorDirectivesPerformance Alignment, vectorization and performance tweaking

 - \b \c EIGEN_MALLOC_ALREADY_ALIGNED - Can be set to 0 or 1 to tell whether default system \c malloc already
   returns aligned buffers. If not defined, then this information is automatically deduced from the compiler
   and system preprocessor tokens.
 - \b \c EIGEN_MAX_ALIGN_BYTES - Must be a power of two, or 0. Defines an upper bound on the memory boundary in bytes on which dynamically and statically allocated data may be aligned by %Eigen. If not defined, a default value is automatically computed based on architecture, compiler, and OS.
 This option is typically used to enforce binary compatibility between code/libraries compiled with different SIMD options. For instance, one may compile AVX code and enforce ABI compatibility with existing SSE code by defining \c EIGEN_MAX_ALIGN_BYTES=16. In the other way round, since by default AVX implies 32 bytes alignment for best performance, one can compile SSE code to be ABI compatible with AVX code by defining \c EIGEN_MAX_ALIGN_BYTES=32.
 - \b \c EIGEN_MAX_STATIC_ALIGN_BYTES - Same as \c EIGEN_MAX_ALIGN_BYTES but for statically allocated data only. By default, if only  \c EIGEN_MAX_ALIGN_BYTES is defined, then \c EIGEN_MAX_STATIC_ALIGN_BYTES == \c EIGEN_MAX_ALIGN_BYTES, otherwise a default value is automatically computed based on architecture, compiler, and OS (can be smaller than the default value of EIGEN_MAX_ALIGN_BYTES on architectures that do not support stack alignment).
 Let us emphasize that \c EIGEN_MAX_*_ALIGN_BYTES define only a desirable upper bound. In practice data is aligned to largest power-of-two common divisor of \c EIGEN_MAX_STATIC_ALIGN_BYTES and the size of the data, such that memory is not wasted.
 - \b \c EIGEN_DONT_PARALLELIZE - if defined, this disables multi-threading. This is only relevant if you enabled OpenMP.
   See \ref TopicMultiThreading for details.
 - \b \c EIGEN_GEMM_THREADPOOL - if defined, the general matrix-matrix product is parallelized using a user-provided
   \c Eigen::ThreadPool instead of OpenMP; register the pool with \c Eigen::setGemmThreadPool(). Mutually exclusive
   with OpenMP parallelization. See \ref TopicMultiThreading for details.
 - \b \c EIGEN_DONT_VECTORIZE - disables explicit vectorization when defined. Not defined by default, unless
   alignment is disabled by %Eigen's platform test or the user defining \c EIGEN_DONT_ALIGN. The implication also runs
   the other way outside GPU compilation: defining it sets the ideal alignment to zero, so \c EIGEN_MAX_ALIGN_BYTES and
   \c EIGEN_MAX_STATIC_ALIGN_BYTES default to 0 and fixed-size vectorizable types lose their over-alignment. It
   therefore affects the ABI and must be defined consistently across translation units. See \ref TopicVectorization.
 - \b \c EIGEN_UNALIGNED_VECTORIZE - disables/enables vectorization with unaligned stores. Default is 1 (enabled).
   If set to 0 (disabled), then expression for which the destination cannot be aligned are not vectorized (e.g., unaligned
   small fixed size vectors or matrices)
 - \b \c EIGEN_FAST_MATH - enables optimizations which might affect the accuracy of the result. On the SIMD
   backends where such faster but slightly less accurate implementations exist, this currently controls the
   vectorization of \c sin(), \c cos(), \c tan(), \c tanh(), \c erf(), \c erfc(), and reciprocal, and selects
   faster \c sqrt()/\c rsqrt() implementations (e.g., Newton-Raphson iterations on AVX512). Defined to 1 by
   default. Define it to 0 to disable.
 - \b \c EIGEN_UNROLLING_LIMIT - defines the size of a loop to enable meta unrolling. Set it to zero to disable
   unrolling. The size of a loop here is expressed in %Eigen's own notion of "number of FLOPS", it does not
   correspond to the number of iterations or the number of instructions. The default is value 110.
 - \b \c EIGEN_GEMM_TO_COEFFBASED_THRESHOLD - a matrix-matrix product that reaches the general (GEMM) product path
   falls back at run time to the coefficient-based product when rows + cols + depth is below this value. Default is 20.
   In an ARM SME build, the scalar types the SME GEMM kernel handles use \c EIGEN_SME_GEMM_TO_COEFFBASED_THRESHOLD
   instead when it is defined, and also fall back when the result is not a vector and has at most
   \c EIGEN_SME_GEMM_TO_COEFFBASED_OUTPUT_AREA_THRESHOLD(Scalar) coefficients (default 96 / sizeof(Scalar)).
 - \b \c EIGEN_FIXED_SIZE_GEMM_TO_COEFFBASED_THRESHOLD - a product that would take the GEMM path and whose three
   dimensions are all fixed at compile time uses the coefficient-based product instead, selected at compile time,
   when rows + cols + depth is below this value. Default is 40. It does not follow
   \c EIGEN_GEMM_TO_COEFFBASED_THRESHOLD, which still applies at run time to the fixed-size products this one sends to
   the GEMM path, so their crossover is the larger of the two values.
 - \b \c EIGEN_SME_FIXED_SIZE_GEMM_TO_COEFFBASED_THRESHOLD - the same compile-time bound for the scalar types the ARM
   SME GEMM kernel handles (\c float, \c std::complex<float>, and with FEAT_SME_F64F64 \c double and
   \c std::complex<double>). Default is 61, measured on Apple M4 Pro; other scalar types use
   \c EIGEN_FIXED_SIZE_GEMM_TO_COEFFBASED_THRESHOLD in an SME build too.
 - \b \c EIGEN_STACK_ALLOCATION_LIMIT - defines the maximum bytes for a buffer to be allocated on the stack. For internal
   temporary buffers, dynamic memory allocation is employed as a fall back; setting the limit to 0 disables stack
   allocation for them, so every such temporary is heap-allocated. For fixed-size matrices or arrays, exceeding this
   threshold raises a compile time assertion; there, 0 disables the check. Default is 128 KB.
 - \b \c EIGEN_STACK_ALIGN_BYTES - alignment of the internal temporary buffers: the ones on the stack, their heap
   fallback above \c EIGEN_STACK_ALLOCATION_LIMIT and the GEMM blocking buffers. Defaults to
   \c EIGEN_DEFAULT_ALIGN_BYTES, except in ARM SME builds where it is 64: the SME GEMM kernel reads its packed panels a
   streaming vector at a time and slows by 35-50% when they straddle 64-byte lines. It does not affect the ABI.
 - \b \c EIGEN_NO_CUDA - disables CUDA support when defined. Might be useful in .cu files for which Eigen is used on the host only,
   and never called from device code.
 - \b \c EIGEN_NO_HIP - disables HIP support when defined. Analogous to \c EIGEN_NO_CUDA for AMD's HIP compiler.
 - \b \c EIGEN_STRONG_INLINE - This macro is used to qualify critical functions and methods that we expect the compiler to inline.
   By default it is defined to \c __forceinline for MSVC and ICC, and to \c inline for other compilers. A typical usage is to
   define it to \c inline for MSVC users wanting faster compilation times, at the risk of performance degradations in some rare
   cases for which MSVC inliner fails to do a good job.
 - \b \c EIGEN_DEFAULT_L1_CACHE_SIZE - Sets the default L1 cache size that is used in Eigen's GEBP kernel when the correct cache size cannot be determined at runtime.
 - \b \c EIGEN_DEFAULT_L2_CACHE_SIZE - Sets the default L2 cache size that is used in Eigen's GEBP kernel when the correct cache size cannot be determined at runtime.
 - \b \c EIGEN_DEFAULT_L3_CACHE_SIZE - Sets the default L3 cache size that is used in Eigen's GEBP kernel when the correct cache size cannot be determined at runtime.
 - \b \c EIGEN_SME_MAX_KC - Maximum depth (k) blocking size used by the ARM SME GEMM kernel, expressed in \c float
   elements and scaled by the scalar width for wider types. The default (2048) is empirically tuned for Apple M4;
   override to retune for other SME implementations.
 - \b \c EIGEN_SME_NEON_MAX_DEPTH, \c EIGEN_SME_NEON_MAX_PANEL, \c EIGEN_SME_NEON_MAX_WIDTH, \c EIGEN_SME_NEON_SHALLOW_DEPTH,
   \c EIGEN_SME_NEON_SHALLOW_WIDTH, \c EIGEN_SME_NEON_THIN_DIM - Bounds below which the ARM SME GEMM backend packs
   and multiplies a block with NEON instead of the ZA tiles (panels no deeper than the depth bound and no wider than
   the panel bound; a block of such panels no wider than the width bound, or the shallow width up to the shallow
   depth, or narrower than the thin bound on one side). One value overrides the per-scalar defaults, which are fitted
   for Apple M4. \c EIGEN_SME_NO_NEON_SMALL_BLOCKS and \c EIGEN_SME_FORCE_NEON_SMALL_BLOCKS pin the path for A/B runs;
   both also turn off the NEON kernel for results of at most 8 x 8 (float) or 4 x 8 (double).
 - \b \c EIGEN_SME_UNITS - Number of ARM SME units a product on the SME GEMM kernel spreads over; more threads than
   units only contend for them. Detected from the core topology by default (see \c Eigen::nbSmeUnits() and
   \c Eigen::setNbSmeUnits()): on macOS from the performance clusters, and 0 (no cap) elsewhere. Define it on other
   systems whose SME units are shared by a cluster of cores, such as Linux on Apple silicon.
 - \b \c EIGEN_SME_MIN_TASK_SIZE - Minimum work per thread, in FP32 multiply-adds, before a product on the ARM SME
   GEMM kernel is split across threads. Other types count their kernel time in FP32 multiply-adds: double and
   complex<float> four each, complex<double> sixteen. The default (2^20) is tuned for Apple M4 and applies where the
   SME unit count is known (see \c EIGEN_SME_UNITS). There, when the maximum sizes of the result and of the inner
   dimension are not all fixed at compile time, each thread computes a disjoint part of the result.
 - \b \c EIGEN_SME_DIRECT_LHS_MAX_STRIDE_BYTES and \b \c EIGEN_SME_DIRECT_LHS_MAX_BLOCK_BYTES - Largest column stride
   and largest block (rows times depth, both in bytes) at which the ARM SME GEMM kernel reads a column-major real LHS
   block from its source instead of a packed panel, whatever its alignment. The defaults are 16 KB and 4 MB; strides
   that are a multiple of 4 KB always pack, since they alias in L1. 0 for either disables the in-place read. These
   limits do not apply when the RHS is a single panel (see \c EIGEN_SME_DIRECT_LHS_MAX_SPAN_BYTES).
 - \b \c EIGEN_SME_DIRECT_LHS_MAX_SPAN_BYTES - When the RHS is a single panel, each LHS element is read once, so the
   ARM SME GEMM kernel reads a column-major real LHS in place: always up to half a panel wide, and up to a full panel
   while depth times column stride (in bytes) stays within this limit, past which the panel spans more pages than
   the TLB covers. The default is 16 MB; 0 disables the in-place read for single-panel products.
 - \b \c EIGEN_ARM64_NO_SME_F64F64 - Disables the double-precision ARM SME kernels, which need the optional
   FEAT_SME_F64F64 extension. %Eigen enables it whenever the compiler reports that extension; define this macro when
   the build target is wider than the run target, so that \c double keeps the generic kernels for matrix products,
   matrix-vector products, dot products, and scaled vector additions.
 - \b \c EIGEN_SME_PACKED_RHS_BUDGET_BYTES - Byte budget for the packed RHS panel in the ARM SME GEMM kernel.
   The default (32 MB) is empirically tuned for Apple M4.
 - \b \c EIGEN_SME_LHS_WORKING_SET_BUDGET_BYTES - Byte budget for the LHS working set in the ARM SME GEMM kernel.
   The default (7 MB) is empirically tuned for Apple M4.
 - \b \c EIGEN_SME_SINGLE_PASS_RHS_BUDGET_BYTES - Byte budget for the packed RHS panel in the ARM SME GEMM kernel when
   all rows of the product fit one LHS block, so that each packed panel is read once and should stay in L2 between
   packing and the kernel. The default (4 MB) is empirically tuned for Apple M4 (16 MB L2 per cluster).

 - \b \c EIGEN_DONT_ALIGN - Deprecated, it is a synonym for \c EIGEN_MAX_ALIGN_BYTES=0. It disables alignment completely. %Eigen will not try to align its objects and does not expect that any objects passed to it are aligned. This will turn off vectorization if \b \c EIGEN_UNALIGNED_VECTORIZE=1. Not defined by default.
 - \b \c EIGEN_DONT_ALIGN_STATICALLY - Deprecated, it is a synonym for \c EIGEN_MAX_STATIC_ALIGN_BYTES=0. It disables alignment of arrays on the stack. Not defined by default, unless \c EIGEN_DONT_ALIGN is defined.
 - \b \c EIGEN_ALTIVEC_ENABLE_MMA_DYNAMIC_DISPATCH - Controls whether to use Eigen's dynamic dispatching for Altivec MMA or not.
 - \b \c EIGEN_ALTIVEC_DISABLE_MMA - Overrides the usage of Altivec MMA instructions.
 - \b \c EIGEN_ALTIVEC_USE_CUSTOM_PACK - Controls whether to use Eigen's custom packing for Altivec or not.


\section TopicPreprocessorDirectivesPlugins Plugins

It is possible to add new methods to many fundamental classes in %Eigen by writing a plugin. As explained in
the section \ref TopicCustomizing_Plugins, the plugin is specified by defining a \c EIGEN_xxx_PLUGIN macro. The
following macros are supported; none of them are defined by default.

 - \b EIGEN_ARRAY_PLUGIN - filename of plugin for extending the Array class.
 - \b EIGEN_ARRAYBASE_PLUGIN - filename of plugin for extending the ArrayBase class.
 - \b EIGEN_DENSEBASE_PLUGIN - filename of plugin for extending the DenseBase class.
 - \b EIGEN_FUNCTORS_PLUGIN - filename of plugin for adding new functors and specializations of functor_traits.
 - \b EIGEN_MAPBASE_PLUGIN - filename of plugin for extending the MapBase class.
 - \b EIGEN_MATRIX_PLUGIN - filename of plugin for extending the Matrix class.
 - \b EIGEN_MATRIXBASE_PLUGIN - filename of plugin for extending the MatrixBase class.
 - \b EIGEN_PLAINOBJECTBASE_PLUGIN - filename of plugin for extending the PlainObjectBase class.
 - \b EIGEN_QUATERNION_PLUGIN - filename of plugin for extending the Quaternion class.
 - \b EIGEN_QUATERNIONBASE_PLUGIN - filename of plugin for extending the QuaternionBase class.
 - \b EIGEN_SPARSEMATRIX_PLUGIN - filename of plugin for extending the SparseMatrix class.
 - \b EIGEN_SPARSEMATRIXBASE_PLUGIN - filename of plugin for extending the SparseMatrixBase class.
 - \b EIGEN_SPARSEVECTOR_PLUGIN - filename of plugin for extending the SparseVector class.
 - \b EIGEN_TRANSFORM_PLUGIN - filename of plugin for extending the Transform class.
 - \b EIGEN_VECTORWISEOP_PLUGIN - filename of plugin for extending the VectorwiseOp class.

\section TopicPreprocessorDirectivesDevelopers Macros for Eigen developers

These macros are mainly meant for people developing %Eigen and for testing purposes. Even though, they might be useful for power users and the curious for debugging and testing purpose, they \b should \b not \b be \b used by real-word code.

 - \b EIGEN_DEFAULT_TO_ROW_MAJOR - when defined, the default storage order for matrices becomes row-major
   instead of column-major. Not defined by default.
 - \b EIGEN_INTERNAL_DEBUGGING - if defined, enables assertions in %Eigen's internal routines. This is useful
   for debugging %Eigen itself. Not defined by default.
 - \b EIGEN_NO_MALLOC - if defined, any request from inside the %Eigen to allocate memory from the heap
   results in an assertion failure. This is useful to check that some routine does not allocate memory
   dynamically. Not defined by default.
 - \b EIGEN_RUNTIME_NO_MALLOC - if defined, a new switch is introduced which can be turned on and off by
   calling <tt>set_is_malloc_allowed(bool)</tt>. If malloc is not allowed and %Eigen tries to allocate memory
   dynamically anyway, an assertion failure results. Not defined by default.

*/

}