Guidance for AI coding agents (Claude Code, Cursor, Copilot Workspace, Aider, OpenAI Codex, etc.) working in this repository. Human contributors should start from README.md and the project sites it links to (https://eigen.tuxfamily.org, https://libeigen.gitlab.io, and the upstream repo at https://gitlab.com/libeigen/eigen); this file is the agent-facing condensation.
If your tool also reads its own per-tool config file, treat that as a thin pointer and rely on this file for substance.
These are the cross-cutting rules that catch agents most often:
\note block suffices). Same discipline for AI-suggested code: cite the source, or rewrite from a known reference and cite that, or drop it. Ideas aren't copyrightable, specific expressions are — learn from the source, write your own, credit it.Eigen/src/... or unsupported/Eigen/src/... directly — InternalHeaderCheck.h makes that a hard compile error. User code reaches implementation only through the umbrella module headers (Eigen/Core, Eigen/Dense, Eigen/SVD, …). When moving or renaming files inside any src/ subtree, delete the old file outright; only the public umbrella headers ever get back-compat forwarding shims.EIGEN_DEVICE_FUNC. It is pervasive on coefficient-level methods so the same code compiles for host and CUDA / HIP / SYCL device. Dropping it silently breaks GPU builds and is rarely caught locally.modernize-* or cppcoreguidelines-* clang-tidy fixes, replace EIGEN_STRONG_INLINE with inline, “fix” Eigen's macro indentation, or reorder includes. Eigen has its own conventions encoded in .clang-format (SortIncludes: false, custom StatementMacros / AttributeMacros); CI will diff against them.clang-format-17 exactly (Google base, 120 cols). Other versions diff against CI. Run scripts/format.sh (whole tree) or clang-format-17 -i <file> (one file) before pushing. Format failures are the single most common reason an MR is red.test/main.h): VERIFY_* assertions, CALL_SUBTEST_N / EIGEN_TEST_PART_N for splitting, EIGEN_DECLARE_TEST(<name>) { ... } as the entry point. See “Adding a test” below. In-flight migration to Google Test: MR 2159 (draft) replaces EIGEN_DECLARE_TEST / CALL_SUBTEST_N with gtest TEST / TYPED_TEST, brings in gtest 1.15.2 via FetchContent, and bridges VERIFY / VERIFY_IS_APPROX to gtest expectations. When that lands, this rule flips — write new tests as gtest fixtures and use the bridged VERIFY_* macros.all target. Bare ninja builds nothing relevant. Use the named targets (buildtests, check, BuildOfficial, BuildUnsupported, buildsmoketests, buildtests_gpu, check_gpu).auto traps. auto x = A + B; captures a lazy expression holding references that can dangle. Use .eval() or an explicit type. Likewise be careful with .noalias() — it must only be used when the destination doesn't appear on the right side.git add -A / git add . inside an Eigen working copy. Repo roots commonly accumulate untracked dotfiles and tool config (.vscode/, .idea/, .claude/, etc.) that must not enter commits. Add files by path or with targeted globs (e.g. git add 'Eigen/src/Cholesky/').uptime shows a low load average, finish/cancel background builds, and never run two benchmark binaries in the same shell invocation (parallel or chained with &&) — run each in its own shell, take medians within a binary, and optionally alternate (A, B, A, B) across separate invocations to detect drift.unsupported/Eigen/Tensor and the work-stealing thread pool in Eigen/ThreadPool together form TensorFlow's core compute backend. “Unsupported” here means “looser API-stability guarantees” — it does not mean low-traffic or low-stakes. Breaking changes (signatures, header layout, semantics, or performance regressions on contraction / reduction / morphing kernels) ripple into every TensorFlow build and from there into every project that pulls TensorFlow as a dependency. Treat Tensor and ThreadPool as load-bearing: prefer additive changes, keep header paths stable, run downstream Tensor tests (unsupported/test/tensor_*), and call out any behavior change prominently in the MR description.Eigen is a header-only C++ template library for linear algebra: dense and sparse matrices, vectors, decompositions, geometry, iterative solvers. The library itself does not need to be built — consumers just #include <Eigen/Dense> (or other module headers). CMake is required only for tests, BLAS/LAPACK shims, demos, and docs.
Upstream is GitLab: https://gitlab.com/libeigen/eigen. Bug reports, feature requests, and merge requests go there — the GitHub mirror is read-only. Minimum standard is C++14 (target_compile_features(eigen INTERFACE cxx_std_14) in CMakeLists.txt); SYCL builds force C++17. The project aspires to bump the baseline to C++17 in a future release. The pace on baseline bumps is deliberately slow so that new Eigen improvements remain available to users on embedded platforms, whose toolchains are often several years behind mainline. License: MPL2 for the bulk, with a few files under other compatible licenses (COPYING.* at the root).
Eigen aspires to state-of-the-art results on two axes — performance and numerical accuracy / IEEE-754 conformance — and treats them as separate goals that are sometimes in tension.
Performance. Eigen Core emphasizes single-core throughput via two levers: SIMD through per-architecture packet backends (see “SIMD / packet math layer”), and memory-hierarchy use through blocked algorithms — cache-aware blocking and panel/kernel decompositions in Eigen/src/Core/products/, tile-based traversal in the Tensor module. Eigen Core is mostly optimized for single-core throughput; multi-core in Core is opt-in (OpenMP or EIGEN_GEMM_THREADPOOL) and covers a subset of operations. The Tensor module is the opposite — designed for multi-core via ThreadPoolDevice, which dispatches across worker threads of the work-stealing thread pool. See “Multi-threading” below.
Numerical accuracy. The bar is LAPACK-level for linear algebra (decompositions, solvers — backward stability, pivoting, conditioning) and C++ standard-library level for standard math functions (exp, log, sin, pow, …) on scalars. For special values — IEEE-754 entities (NaN, ±0, ±∞, subnormals) and function-specific edge cases (singularities, branch boundaries; e.g. log(0), pow(0, 0)) — the bar is exact conformance to IEEE 754 / ISO C / C++ specifications, with the cppreference page for each function as the authoritative spec (e.g. std::pow). On regular inputs a few ULPs of error in vectorized math in exchange for SIMD throughput is the long-standing trade-off; larger deviations need explicit justification. Special-value handling is not subject to the few-ULPs trade-off — it must match spec exactly.
When adding or modifying a numerical kernel:
log(0), log(-x), pow(0, 0)), values near overflow / underflow, denormalized results, signed-zero preservation, and ULP behavior near hard cases (e.g. argument-reduction breakdown for sin/cos at large arguments).gallery(), largely drawn from those books) and Golub & van Loan, Matrix Computations. Where the algorithm has a LAPACK counterpart, match its TESTING/ category coverage as the bar.test/packetmath.cpp and unsupported/test/special_packetmath.cpp are the canonical entry points; a missing or divergent backend specialization usually shows up there first.benchmarks/ or unsupported/benchmarks/). See “Benchmarking discipline” in the agent guidelines above.For decompositions and solvers: the bar is matching LAPACK on conditioning, pivoting strategy, and backward stability. Don't trade numerical robustness for speed in those code paths without explicit sign-off.
In-flight test-framework migration: MR 2159 migrates the test framework from Eigen's custom
EIGEN_DECLARE_TEST/CALL_SUBTEST_Nmacros to Google Test. The “Adding a test” and “Test split” subsections below describe the current framework on master. Once 2159 lands, tests become gtestTEST/TYPED_TESTfixtures, per-Nexecutable splitting goes away, andVERIFY_*survives as a bridge to gtest expectations.
Tests are intentionally not in the default all target — ninja (or make) on its own builds nothing relevant. Drive everything through the named targets:
mkdir -p build && cd build cmake -G Ninja .. # plain config ninja buildtests # build all unit tests ninja buildtests_gpu # GPU-only tests ninja BuildOfficial # only test/ (subproject "Official") ninja BuildUnsupported # only unsupported/test/ (subproject "Unsupported") ninja buildsmoketests # the MR smoke set ninja check # = buildtests + ctest ninja check_gpu # = buildtests_gpu + ctest -L gpu # generated wrappers (after `cmake` configure; run from inside the build dir): ./buildtests.sh <regex> # build tests whose name matches ./check.sh <regex> # build + run tests whose name matches
ISA / vectorization (turn on per-ISA test compile flags — see CMakeLists.txt and cmake/EigenTesting.cmake for the authoritative list):
EIGEN_TEST_SSE2, EIGEN_TEST_SSE3, EIGEN_TEST_SSSE3, EIGEN_TEST_SSE4_1, EIGEN_TEST_SSE4_2, EIGEN_TEST_AVX, EIGEN_TEST_AVX2, EIGEN_TEST_AVX512, EIGEN_TEST_AVX512DQ, EIGEN_TEST_AVX512FP16, EIGEN_TEST_FMA, EIGEN_TEST_F16C, EIGEN_TEST_X87, EIGEN_TEST_32BITEIGEN_TEST_NEON, EIGEN_TEST_NEON64EIGEN_TEST_VSX, EIGEN_TEST_ALTIVECEIGEN_TEST_Z13, EIGEN_TEST_Z14EIGEN_TEST_LSXEIGEN_TEST_MSAEIGEN_TEST_CUDA, EIGEN_TEST_CUDA_CLANG, EIGEN_TEST_CUDA_NVC (NVHPC), EIGEN_TEST_HIP, EIGEN_TEST_SYCLEIGEN_TEST_NO_EXPLICIT_VECTORIZATION, EIGEN_TEST_NO_EXPLICIT_ALIGNMENT, EIGEN_TEST_NO_EXCEPTIONSTest-wide knobs:
EIGEN_TEST_MAX_SIZE=320 (default) — clamp the random matrix sizes used by tests.EIGEN_SPLIT_LARGE_TESTS=ON (default) — splits any test using CALL_SUBTEST_N / EIGEN_TEST_PART_N into per-N executables (foo_1, foo_2, …); see “Test split” below.EIGEN_DEFAULT_TO_ROW_MAJOR=ON — re-runs the suite with row-major default storage.EIGEN_LEAVE_TEST_IN_ALL_TARGET=ON — adds tests back to all (used by some CI harnesses driving ctest's automatic build path).EIGEN_TEST_CUSTOM_CXX_FLAGS=…, EIGEN_TEST_CUSTOM_LINKER_FLAGS=… — extra flags applied only to test targets (handy for working around codegen bugs).EIGEN_TEST_OPENMP=ON — link tests against OpenMP.EIGEN_TEST_EXTERNAL_BLAS=ON — exercise the EIGEN_USE_BLAS path against an external BLAS implementation; without it, the in-tree eigen_blas from blas/ is used. (An external-LAPACK equivalent is not yet wired up — test/CMakeLists.txt carries a TODO do the same for EXTERNAL_LAPACK, so EIGEN_TEST_EXTERNAL_LAPACK currently has no effect.)Auxiliary trees:
EIGEN_BUILD_BLAS=ON / EIGEN_BUILD_LAPACK=ON (default ON only for top-level builds) — build the Eigen-backed BLAS/LAPACK shim libraries under blas/ and lapack/.EIGEN_BUILD_DOC=ON — Doxygen documentation (ninja doc).EIGEN_BUILD_DEMOS=ON — the small demos under demos/.ctest --parallel --output-on-failure # everything that's been built ctest -L Official # only tests under test/ ctest -L Unsupported # only tests under unsupported/test/ ctest -L gpu # GPU-tagged tests ctest -L smoketest # the MR smoke set ctest -R '^cholesky' # regex over test names ctest -R '^bdcsvd_3$' --output-on-failure -V # one specific split
Subproject labels come from set_property(GLOBAL PROPERTY EIGEN_CURRENT_SUBPROJECT "Official"|"Unsupported") in test/CMakeLists.txt and unsupported/test/CMakeLists.txt. Build-group targets (BuildOfficial, BuildUnsupported) are kept in sync with the ctest labels.
A test binary can be invoked directly to control seed / repeat:
./test/foo_3 r5 s1234 # repeat 5 times, fixed seed 1234 EIGEN_REPEAT=10 EIGEN_SEED=1 ./test/foo_3
A test source file containing CALL_SUBTEST_N(...) or EIGEN_TEST_PART_N macros is compiled into N separate executables named <testname>_1, <testname>_2, …, each built with -DEIGEN_TEST_PART_<N>=1 (logic in cmake/EigenTesting.cmake — ei_add_test). The umbrella <testname> target builds all parts. ctest -R ^<testname>$ does not match individual parts; use ctest -R <testname> for the regex form. Set EIGEN_SPLIT_LARGE_TESTS=OFF to fold them into a single binary if you need to debug across parts.
test/<name>.cpp (or unsupported/test/<name>.cpp). Include main.h. Use the VERIFY* macros (listed below). For multi-part tests, structure the body as CALL_SUBTEST_1(...) ... CALL_SUBTEST_N(...).EIGEN_DECLARE_TEST(<name>) { ... } — that macro expands to the per-binary main() (random seed / repeat handling, signal handlers, etc.). It is not gtest.ei_add_test(<name>) in the matching CMakeLists.txt near similar tests. The second/third args are extra compile flags / libraries (e.g. ei_add_test(packetmath "-DEIGEN_FAST_MATH=1")).buildtests and ctest.Test assertion macros (defined in test/main.h):
VERIFY(cond) — assert conditionVERIFY_IS_APPROX(a, b), VERIFY_IS_NOT_APPROX(a, b) — approximate floating-point equalityVERIFY_IS_EQUAL(a, b), VERIFY_IS_NOT_EQUAL(a, b) — exact equalityVERIFY_IS_MUCH_SMALLER_THAN(a, b)VERIFY_RAISES_ASSERT(expr) — assert that eigen_assert firesfailtest/ holds compile-failure tests: each has an _ok and _ko target — _ok must compile, _ko must fail to compile (driven via -DEIGEN_SHOULD_FAIL_TO_BUILD).
Benchmarks under benchmarks/ are not part of the main test build — benchmarks/CMakeLists.txt is a standalone CMake project (project(EigenBenchmarks CXX)) that depends on Google Benchmark (find_package(benchmark REQUIRED)) and finds Eigen as a sibling header-only include. Configure and build it separately (e.g. cmake -G Ninja -S benchmarks -B build-bench && ninja -C build-bench), not through the buildtests/check targets. CI builds them in the dedicated benchmark stage via ci/scripts/build.benchmark.sh. (See “Benchmarking discipline” in the agent guidelines for how to run them meaningfully.)
Specify arg grids declaratively with Args / Range / ArgsProduct, never a hand-written Apply() callback. Google Benchmark‘s Apply(fn) passes its registration object as benchmark::internal::Benchmark* — an internal type (note the internal namespace) that is not part of the public API and is easy to misname. The frequent mistake is writing void MyArgs(benchmark::Benchmark* b) or ::benchmark::Benchmark* (no such type — the public alias is only benchmark::internal::Benchmark), which fails to compile and broke the whole benchmark CI stage. Reach for the chainable macros on the registration itself instead: ->Args({a, b}) for one point, ->Range(lo, hi) / ->DenseRange(lo, hi, step) for one swept dimension, and ->ArgsProduct({{...}, {...}}) for the Cartesian product of several dimensions (the declarative form of nested for loops calling b->Args(...)). These keep the grid on the registration, need no internal types, and read more clearly. Only fall back to Apply() for genuinely computed grids that the macros can’t express, and then spell the parameter benchmark::internal::Benchmark*.
Style is clang-format-17 (Google base, 120 cols, see .clang-format). The version is hard-coded — newer or older clang-format will diff against CI.
scripts/format.sh # reformat the whole tree clang-format-17 -i <file> # reformat one file clang-format-17 --dry-run --Werror <file> # check (CI's `checkformat:clangformat`) git clang-format --diff --commit <base-sha> # diff what CI will diff codespell --config setup.cfg # spell-check (also a CI job)
.clang-format registers Eigen-specific macros (EIGEN_STATIC_ASSERT, EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED, EIGEN_INTERNAL_DENSE_STORAGE_CTOR_PLUGIN, etc.) as StatementMacros, and EIGEN_STRONG_INLINE / EIGEN_ALWAYS_INLINE / EIGEN_DEVICE_FUNC / EIGEN_DONT_INLINE / EIGEN_DEPRECATED / EIGEN_UNUSED as AttributeMacros. Don't “fix” their indentation or strip them. SortIncludes: false — include order is meaningful in this codebase.
clang-tidy runs in the checkformat:clangtidy MR job. Locally: cmake -G Ninja -S . -B .tidy-build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON && clang-tidy -p .tidy-build <files>. Eigen has its own conventions — do not apply modernize-* or cppcoreguidelines-* checks.
SPDX / REUSE. Every new source file (.h, .cpp, .cu, .inc, .cmake, CMakeLists.txt, etc.) must carry inline copyright + license headers; the checkformat:reuse CI job (reuse lint) blocks otherwise. The standard Eigen header is:
// This file is part of Eigen, a lightweight C++ template library // for linear algebra. // // Copyright (C) <year> <Your Name> <your.email@example.com> // // This Source Code Form is subject to the terms of the Mozilla // Public License v. 2.0. If a copy of the MPL was not distributed // with this file, You can obtain one at http://mozilla.org/MPL/2.0/. // SPDX-License-Identifier: MPL-2.0
An alternative SPDX-style header — // SPDX-FileCopyrightText: The Eigen Authors plus // SPDX-License-Identifier: MPL-2.0, with no individual Copyright (C) line — is also accepted and is in active use (e.g. files attributed to “The Eigen Authors” and some top-level umbrella headers). The Copyright (C) <year> <name> form above remains the dominant convention; either passes reuse lint.
Top-level docs (*.md), generated files (*.in), and binary assets that can‘t carry inline headers are covered by path annotations in REUSE.toml — add the path if you’re creating one.
In-flight rename: MR 2522 renames the top-level
unsupported/directory tocontrib/. Paths below track master (stillunsupported/). When 2522 lands, substitutecontrib/forunsupported/mechanically — it doesn't affect the canonical/forwarding-shim distinction on theunsupported/Eigen/bullet.
Eigen/ — supported public headers. Each filename without an extension (Eigen/Core, Eigen/Dense, Eigen/SVD, …) is the umbrella include for one module; implementation lives in Eigen/src/<Module>/. Never include anything under Eigen/src/... directly — that is a hard error (each implementation header includes InternalHeaderCheck.h to enforce it).Eigen/src/Core/arch/{SSE,AVX,AVX512,NEON,SVE,AltiVec,GPU,HIP,SYCL,LSX,RVV10,HVX,MSA,ZVector,clang,Default}/ — per-architecture packet-math (vectorization) backends. GenericPacketMath.h defines the internal::p* API each backend specializes. (PowerPC VSX support lives inside AltiVec/, no separate VSX/ directory.)Eigen/src/Core/products/ — gemm/gemv kernels (GeneralBlockPanelKernel.h, triangular / self-adjoint variants, BLAS bridges in *_BLAS.h).Eigen/src/Core/util/ — meta-programming, macros, memory, ForwardDeclarations.h. Macros.h and ConfigureVectorization.h set the compile-time feature flags.Eigen/ThreadPool (with Eigen/src/ThreadPool/) — work-stealing thread pool (NonBlockingThreadPool, RunQueue, EventCount, ForkJoin, CoreThreadPoolDevice). Originally developed for TensorFlow; now part of Core. It is the backend behind EIGEN_GEMM_THREADPOOL and the ThreadPoolDevice used by the Tensor module.unsupported/Eigen/ — modules with looser API-stability guarantees, but not low-traffic. The headliner is Tensor (umbrella unsupported/Eigen/Tensor, sources under unsupported/Eigen/src/Tensor/) — TensorFlow‘s core compute backend; treat as load-bearing (see agent guideline 13). Other modules: TensorSymmetry, AutoDiff, Polynomials, MatrixFunctions, NNLS, FFT, GPU (cuBLAS / cuSOLVER dispatch), Splines, NumericalDiff, etc. Tests go under unsupported/test/. Anything under unsupported/Eigen/CXX11/ is backward-compatibility forwarding shims only — don’t include those paths in new code or add new headers there.test/ — main test sources and test/main.h (the test framework: VERIFY_*, CALL_SUBTEST_N, EIGEN_TEST_PART_N, EIGEN_DECLARE_TEST).failtest/ — compile-failure tests.blas/, lapack/ — Eigen's BLAS/LAPACK shim libraries (eigen_blas, eigen_lapack), built only when EIGEN_BUILD_BLAS / EIGEN_BUILD_LAPACK are on. These get linked by sparse-solver tests (CHOLMOD, UMFPACK, KLU, SuperLU, …) when those packages are present.cmake/ — EigenTesting.cmake, EigenConfigureTesting.cmake define the ei_add_test / ei_add_failtest machinery. Also the Find*.cmake modules for optional backends.ci/ — GitLab CI (*.gitlab-ci.yml per stage) and shell drivers under ci/scripts/.| Module | Header | Contents |
|---|---|---|
| Core | Eigen/Core | Matrix, Array, basic linear algebra, Map, Block, Ref |
| LU | Eigen/LU | FullPivLU, PartialPivLU, inverse, determinant |
| Cholesky | Eigen/Cholesky | LLT, LDLT |
| QR | Eigen/QR | HouseholderQR, ColPivHouseholderQR, FullPivHouseholderQR |
| SVD | Eigen/SVD | JacobiSVD, BDCSVD |
| Eigenvalues | Eigen/Eigenvalues | SelfAdjointEigenSolver, EigenSolver, ComplexEigenSolver |
| Geometry | Eigen/Geometry | Quaternion, AngleAxis, Transform, Hyperplane, cross() |
| Sparse | Eigen/Sparse | SparseMatrix, sparse solvers (SparseLU, SparseQR, SimplicialCholesky) |
| IterativeLinearSolvers | Eigen/IterativeLinearSolvers | ConjugateGradient, BiCGSTAB, LeastSquaresConjugateGradient (additional iterative solvers — GMRES, DGMRES, IDRS, BiCGSTABL — live in unsupported/Eigen/IterativeSolvers) |
External backend umbrella headers (Eigen/<Pkg>Support): AccelerateSupport, CholmodSupport, KLUSupport, MetisSupport, PaStiXSupport, PardisoSupport, SPQRSupport, SuperLUSupport, UmfPackSupport. Intel MKL and AMD AOCL are not umbrella headers — activate them by defining EIGEN_USE_MKL_ALL / EIGEN_USE_AOCL_ALL (and friends like EIGEN_USE_BLAS, EIGEN_USE_LAPACKE, EIGEN_USE_AOCL_VML, EIGEN_USE_AOCL_BLAS) before including Core or Dense; glue in Eigen/src/Core/util/MKL_support.h and AOCL_Support.h. Convenience headers: Eigen/Dense = Core + all dense solvers; Eigen/Eigen = everything supported.
Eigen's central design pattern is expression templates with lazy evaluation. Arithmetic operations do not compute immediately — they return lightweight expression objects that store references to operands and encode the operation. Evaluation happens only on assignment:
// v + w returns CwiseBinaryOp<scalar_sum_op, VectorXf, VectorXf> // No computation until assigned — then fused into a single vectorized loop VectorXf u = v + w;
This eliminates temporaries and lets the compiler fuse operations into single-pass, SIMD-vectorized loops. Key expression types:
CwiseUnaryOp, CwiseBinaryOp, CwiseTernaryOp — element-wise operationsProduct — matrix product (special eager rules, see below)CwiseNullaryOp — procedural matrices (Zero, Identity, Random, custom functors)Block, Transpose, Diagonal, Reshaped, IndexedView, Map, Ref — view-style expressionsInverse, Solve — solver-result expressionsWhen Eigen evaluates eagerly into temporaries:
mat = mat * mat auto-creates a temporary to prevent aliasing. Use .noalias() to suppress when safe: m1.noalias() += m2 * m3;mat1 = mat2 * mat3 + mat4 * mat5, each product evaluates to a temporary before combining.mat1 = mat2 * (mat3 + mat4) evaluates the sum once).Use .eval() to force evaluation; .noalias() to override automatic temporary creation.
The expression-template engine is implemented through evaluator<> traits (in Eigen/src/Core/CoreEvaluators.h and Eigen/src/Core/ProductEvaluators.h). Assignment goes through Eigen/src/Core/AssignEvaluator.h and Assign.h. New expression types must specialize evaluator<> (and often assign_op / nested_eval). Operations are lazy by default — work happens at assignment time inside AssignEvaluator, which picks between scalar / vectorized / linear / inner / outer traversal strategies based on Flags.
Eigen avoids virtual functions. Polymorphism is compile-time via CRTP — each class inherits from a base templated on itself (e.g. Matrix inherits MatrixBase<Matrix>).
EigenBase — root for anything evaluable to a matrix
├── DenseCoeffsBase — coefficient accessors
│ └── DenseBase — shared dense ops (block, reshape, visitors)
│ ├── MatrixBase — linear algebra ops (all dense matrix/vector expressions)
│ │ └── PlainObjectBase — manages storage and resizing
│ │ ├── Matrix — concrete dense matrix (linear algebra semantics)
│ │ └── Array — concrete dense array (coefficient-wise semantics)
│ └── ArrayBase — coefficient-wise ops (all array expressions)
└── SparseMatrixBase — sparse matrix expressions
└── SparseCompressedBase — compressed sparse storage (CSC/CSR)
└── SparseMatrix, SparseVector
Every expression type (Block, Transpose, Map, CwiseBinaryOp, Product, …) inherits from MatrixBase<Derived> or ArrayBase<Derived> without owning storage. PlainObjectBase → DenseStorage manages actual memory for Matrix and Array.
Matrix vs Array: Matrix types live in MatrixBase-world (linear algebra semantics: * is matrix multiply). Array types live in ArrayBase-world (coefficient-wise semantics: * is element-wise multiply). Convert with .array() and .matrix().
Because each expression has a unique type, functions should accept base-class references to avoid forcing evaluation:
// Good: accepts any dense matrix expression, no temporaries template <typename Derived> void foo(const Eigen::MatrixBase<Derived>& x); // Also good: non-templated, uses Ref to avoid copies when layouts match void bar(const Eigen::Ref<const Eigen::MatrixXf>& x); // Hierarchy of genericity: // EigenBase > DenseBase > MatrixBase/ArrayBase > concrete types
For writable parameters, take const MatrixBase<Derived>& and const_cast internally — that is the standard Eigen pattern. The reason is that callers commonly want to pass expression arguments like m.row(i) or m.block(...) as out-params; those are temporaries whose const-ness is a language artifact, not a semantic restriction. The const-ref-plus-const_cast idiom lets you accept them without forcing the user to materialize a named lvalue.
src/Core/arch/)Vectorization is abstracted through a “packet” layer. Each scalar type maps to a platform-specific SIMD vector type via internal::packet_traits<Scalar>::type. Architecture backends provide specializations of packet operations (padd, pmul, pload, pstore, pblend, …):
GenericPacketMath.h — generic scalar fallback APIarch/Default/ — shared helpers (GenericPacketMathFunctions.h, BFloat16.h, Half.h)arch/SSE/, arch/AVX/, arch/AVX512/arch/NEON/, arch/SVE/arch/RVV10/ (scalable vector, multiple LMUL)arch/AltiVec/ (includes MMA support)arch/ZVector/arch/MSA/ (MIPS), arch/LSX/ (Loongson), arch/HVX/ (Qualcomm Hexagon)arch/GPU/ (CUDA), arch/HIP/, arch/SYCL/arch/clang/ — generic clang vector-extension backendPackets are selected at compile time; the assignment loop splits into an aligned vectorized path plus a scalar remainder. New packet-math intrinsics get added in every backend that supports the type. arch/Default/ holds generic SIMD implementations shared across backends; scalar fallbacks live in Eigen/src/Core/GenericPacketMath.h and Eigen/src/Core/MathFunctions.h. test/packetmath.cpp (and unsupported/test/special_packetmath.cpp) exercises them across all enabled backends — failures there often indicate a missing or divergent specialization.
Guard intrinsics by ISA feature macro. Inside a backend directory, an intrinsic is only available when its ISA is enabled — arch/AVX/ is compiled when EIGEN_VECTORIZE_AVX is set, but AVX2 / FMA / AVX512* intrinsics within those files must each be guarded by their own EIGEN_VECTORIZE_* macro (#ifdef EIGEN_VECTORIZE_AVX2, EIGEN_VECTORIZE_FMA, EIGEN_VECTORIZE_AVX512DQ, etc.), with a fallback for the un-guarded path. Full list in Eigen/src/Core/util/ConfigureVectorization.h. Same discipline applies elsewhere (EIGEN_VECTORIZE_NEON_FP16, EIGEN_VECTORIZE_VSX, …). Missing guards typically compile fine locally and break CI on narrower ISA targets.
Eigen has two independent GPU stories, and conflating them causes confusion:
.cu / HIP / SYCL files, most functions are automatically annotated __device__ __host__ via EIGEN_DEVICE_FUNC (unified under EIGEN_GPUCC for both CUDA and HIP). Only fixed-size types work in kernels. Host SIMD is disabled in .cu files — move expensive host-side Eigen code to .cpp. Define EIGEN_NO_CUDA or EIGEN_NO_HIP to suppress device annotations for the respective backend. On 64-bit systems, set EIGEN_DEFAULT_DENSE_INDEX_TYPE to int for device compatibility.unsupported/Eigen/GPU). Plain .cpp files orchestrating cuBLAS / cuSOLVER / cuFFT / cuSPARSE / cuDSS calls on device-resident gpu::DeviceMatrix<Scalar>. Public API in Eigen::gpu, internals in Eigen::gpu::internal; solvers (gpu::LLT, gpu::LU, gpu::QR, gpu::SVD, gpu::SelfAdjointEigenSolver) wrap cuSOLVER. Not an expression-template system — every supported expression maps to a single library call, and DeviceMatrix does not inherit from MatrixBase. Tests compile as .cpp (not .cu) so NVCC doesn't instantiate Eigen CPU packet ops for CUDA vector types. See unsupported/Eigen/src/GPU/README.md.Tensor GPU kernels live under unsupported/Eigen/src/Tensor/ (TensorReductionGpu.h, TensorContractionGpu.h, TensorDeviceGpu.h).
Eigen parallelizes general dense matrix-matrix products, PartialPivLU, row-major sparse-dense products, and some iterative solvers (CG, BiCGSTAB, LeastSquaresCG) via OpenMP or the EIGEN_GEMM_THREADPOOL backend (mutually exclusive with OpenMP). Enable OpenMP with -fopenmp (GCC) or equivalent. Control threads with Eigen::setNbThreads(n) or OMP_NUM_THREADS. Limit to physical cores — hyperthreading hurts Eigen's cache-bound kernels. Eigen::initParallel() is deprecated and no longer needed.
The EIGEN_GEMM_THREADPOOL backend is Eigen‘s own work-stealing thread pool: umbrella Eigen/ThreadPool, implementation under Eigen/src/ThreadPool/. Headline class NonBlockingThreadPool (work-stealing pool over RunQueue per-thread deques, EventCount for parking), with CoreThreadPoolDevice wiring it into Eigen’s parallel-for loops and ThreadPoolInterface as the abstract base. Originally developed for TensorFlow and used by the Tensor module via ThreadPoolDevice — changes are subject to the same caution as Tensor itself.
Performance / behavior (define before including Eigen):
EIGEN_DONT_VECTORIZE — disable explicit SIMD vectorizationEIGEN_DONT_PARALLELIZE — disable multi-threadingEIGEN_FAST_MATH — exists, default 1 (current usage across the codebase is uneven; a future cleanup will either standardize or remove it)EIGEN_NO_MALLOC / EIGEN_RUNTIME_NO_MALLOC — assert on heap allocationEIGEN_UNROLLING_LIMIT — loop unrolling threshold (default: 110)EIGEN_STACK_ALLOCATION_LIMIT — max stack buffer size (default: 128 KB)EIGEN_DEFAULT_TO_ROW_MAJOR — change default storage from column-major to row-majorEIGEN_MAX_ALIGN_BYTES — alignment for dynamic/static data (auto-detected: 64 for AVX-512, 32 for AVX, 16 default)EIGEN_USE_BLAS / EIGEN_USE_LAPACKE — delegate to external BLAS/LAPACKEIGEN_USE_MKL_ALL / EIGEN_USE_AOCL_ALL — delegate broadly to MKL / AOCLDebugging:
EIGEN_NO_DEBUG — disable runtime assertions (auto-set when NDEBUG is defined)EIGEN_INITIALIZE_MATRICES_BY_NAN — initialize all matrices to NaNEIGEN_INITIALIZE_MATRICES_BY_ZERO — initialize all matrices to zeroEIGEN_INTERNAL_DEBUGGING — enable assertions in internal routinesExtending Eigen:
EIGEN_MATRIXBASE_PLUGIN, EIGEN_MATRIX_PLUGIN, EIGEN_ARRAYBASE_PLUGIN, … — path to a header file #included inside the class body, adding custom methods to all expressions of that base.Compiler annotations (used in Eigen source code):
EIGEN_STRONG_INLINE — force inline (__forceinline on MSVC)EIGEN_ALWAYS_INLINE — stronger than STRONG_INLINEEIGEN_DEVICE_FUNC — marks functions callable from CUDA/HIP/SYCL device codeEIGEN_DONT_INLINE — prevent inliningEIGEN_DEPRECATED — deprecation marker(Header-only contract and EIGEN_DEVICE_FUNC: see agent guidelines 2 and 3.)
mat = mat * mat is safe; many other paths rely on the user being correct (.noalias() is a promise from the caller, not a check). Optimized fast paths that bypass the general assignment machinery have historically introduced aliasing bugs — when writing or modifying one, think explicitly about whether the LHS can alias the RHS, and prefer falling back to the general path when in doubt. User-facing rules are in “Common pitfalls” below.int Options carrying RowMajor / ColMajor. When writing new evaluators, propagate Flags & RowMajorBit correctly — it is the source of many subtle bugs.Eigen::internal namespace: all internal implementation lives there. Public-facing types and functions stay in Eigen:: (or specific module namespaces).Eigen::Index (alias for std::ptrdiff_t).EIGEN_UPPER_CASE.Eigen/src/Core/util/ForwardDeclarations.h is the canonical entry point for “where is type X declared?”. internal::traits<T> carries compile-time information (scalar type, dimensions, flags) without forward-declaration issues.eigen_assert(cond) (defined in Eigen/src/Core/util/Macros.h), not raw assert() / static_assert() for runtime preconditions in library code. The test harness redefines eigen_assert so VERIFY_RAISES_ASSERT(expr) can verify failures, and it honors EIGEN_NO_DEBUG / NDEBUG. For internal-only invariants, eigen_internal_assert(cond) is gated on EIGEN_INTERNAL_DEBUGGING. For compile-time conditions, EIGEN_STATIC_ASSERT(cond, MSG_TOKEN) is preferred over plain static_assert because it integrates with Eigen's diagnostic-token machinery.mat = mat * mat is safe (auto-temporary), but mat.noalias() = mat * mat is wrong. Only use .noalias() when the destination doesn't appear on the right side.auto with expressions: auto x = A + B; captures a lazy expression holding references — the references may dangle. Use auto x = (A + B).eval(); or an explicit type.cross() needs Eigen/Geometry).cond ? exprA : exprB can fail with expression types because the two branches have different types. Use if/else.template keyword: in dependent contexts, write x.template triangularView<Upper>() — without template, < is parsed as less-than.Random() not thread-safe: DenseBase::Random() and setRandom() use std::rand internally and are not re-entrant. Use C++11 <random> generators via NullaryExpr for multi-threaded code.Pipeline stages: checkformat → build → test → benchmark → deploy. Configuration in .gitlab-ci.yml and ci/*.gitlab-ci.yml; shell drivers under ci/scripts/.
build jobs produce a .build/ artifact (test binaries) consumed by the matching test job — the test job only runs ctest, it does not rebuild. A test job that runs ctest without restricting via -L or -R will report Could not find executable for everything outside the build job's target. Test-job and build-job names must stay paired (see needs: in ci/test.linux.gitlab-ci.yml).
Test jobs filter via EIGEN_CI_CTEST_LABEL (consumed in ci/scripts/test.linux.script.sh as ctest -L $LABEL). The :official and :unsupported job-name suffixes are convention only — actual filtering is through that variable. The top-level .gitlab-ci.yml variables: block declares these with empty/global defaults (EIGEN_CI_BUILDDIR=.build, EIGEN_CI_BUILD_TARGET="", EIGEN_CI_CTEST_LABEL=""); the meaningful values are set per-job in ci/*.gitlab-ci.yml (e.g. EIGEN_CI_BUILD_TARGET=buildtests/BuildOfficial/buildtests_gpu in ci/build.linux.gitlab-ci.yml, EIGEN_CI_CTEST_LABEL=Official in the matching test jobs).
MR pipelines build / run only a smoke subset; scheduled (nightly) pipelines exercise the full matrix. Format failures (scripts/format.sh diff) are the single most common reason an MR is red — run it before pushing.
Category: Short description (e.g. GPU: Fix special-function test coverage, TriangularView: alias-aware fallback for structured-diagonal product fast path).