Eigen is written and maintained by volunteers. Contributions — code, documentation, bug triage, tests on uncommon platforms, design feedback — are all welcome.
This document is where human contributors should start. AGENTS.md holds the guidance written for AI
coding agents, and it links to focused guides for coding conventions, testing, numerical and sparse work, performance,
SIMD/GPU, Tensor/ThreadPool, documentation, CI, and merge requests. Those guides are also useful to human contributors
working in the corresponding areas.
- Upstream repository: https://gitlab.com/libeigen/eigen — bugs, merge requests, and discussion all happen here. The GitHub mirror is read-only.
- Issue tracker: https://gitlab.com/libeigen/eigen/-/issues
- CI pipelines: https://gitlab.com/libeigen/eigen/-/pipelines
- API documentation (weekly): https://libeigen.gitlab.io/eigen/docs-weekly
- Project site: https://libeigen.gitlab.io (some of its pages are out of date; this file and the guides
linked from
AGENTS.mdtake precedence) - Chat: Discord — the primary support and discussion channel.
You don't have to write C++ to help.
- Answer questions on Discord. New users often ask things that point at gaps in our documentation — patches to fill those gaps are very welcome.
- Triage bugs. Reproduce reports, ask reporters for missing details (compiler, OS, instruction set, minimal example), and weigh in on issues labeled
decision needed. Issues labeledcontributions welcomeare good places to start. - Run the test suite on rarely-tested compilers, OSes, or architectures and report failures. The CI pipelines page linked above shows which configurations the scheduled runs already cover.
- Improve documentation — the Doxygen reference (comments in headers) and the manual pages, snippets, and examples under
doc/; see.agents/docs.md. The project site has its own repository, https://gitlab.com/libeigen/libeigen.gitlab.io. - Contribute code — bug fixes, new features, new tests, new benchmarks. See below.
- Sign in to GitLab and fork https://gitlab.com/libeigen/eigen.
- Clone your fork and add
libeigen/eigenas an upstream remote (use thehttps://clone URL if you don't have an SSH key set up):git clone git@gitlab.com:<your-username>/eigen.git # or: https://gitlab.com/<your-username>/eigen.git cd eigen git remote add upstream https://gitlab.com/libeigen/eigen.git
- Create a topic branch off
masterfor your change:git fetch upstream git checkout -b my-topic upstream/master
- Make your changes, with tests (and a benchmark if it's a performance-sensitive change — see Tests and benchmarks).
- Format with
clang-format-17(see Coding standards). - Commit with an
Area: Short imperative subjectmessage (see Commit messages). Stage files by path — don't usegit add -A. - Push to your fork and open a merge request against
libeigen/eigenmaster. - Be patient and responsive. Reviewers are volunteers; reviews can take a while. If your MR is being ignored for a long time, don't be shy about leaving a comment to ask for a review.
If you're planning a large change (new module, API redesign, significant refactor), open an issue or start a discussion first. Agreeing on the approach before you write code saves everyone work.
Eigen is header-only, so consumers don't need to build the library itself — but contributors do need to build the test suite. Configure CMake in a separate build directory. The tests are deliberately not part of the default all target, so build them through the named targets below.
cmake -S . -B build -G Ninja
cmake --build build --target buildtests # build all unit tests
cmake --build build --target check # build + run all tests
cmake --build build --target buildsmoketests # the smoke tests an MR pipeline runs by default
ctest --test-dir build --parallel --output-on-failure --no-tests=errorOther useful targets: BuildOfficial (just test/), BuildContrib (just contrib/test/), buildtests_gpu, check_gpu. After configuring, the build directory also contains ./buildtests.sh <regex> and ./check.sh <regex>, which build or run only the tests whose names match.
.agents/testing.md explains how to build a single test, register a new one, split a test into
parts, and choose assertions. .agents/simd-gpu.md covers testing SIMD and GPU code. For the
current CMake options, read the CMake files themselves.
Migration in progress: MR 2159 is migrating the test framework from Eigen's own
EIGEN_DECLARE_TEST/CALL_SUBTEST_Nmacros to Google Test. Until it is merged, write new tests with the existing framework (test/main.h,VERIFY_*,EIGEN_DECLARE_TEST,ei_add_testin the matchingCMakeLists.txt).
- Every new feature comes with tests. Bug fixes should add a regression test that fails before the fix and passes after.
- Performance-sensitive changes come with a benchmark under
benchmarks/orcontrib/benchmarks/. Don't defer benchmarks to a follow-up MR. - Cover numerical corner cases, not just typical inputs: ±0, ±∞, NaN, subnormals, domain boundaries, near-overflow / underflow values. Decomposition and solver tests should exercise ill-conditioned and structured matrices (Hilbert, Vandermonde, rank-deficient, near-singular, Jordan blocks, …); see Quality bar. Standard references: Higham's Accuracy and Stability of Numerical Algorithms / Functions of Matrices, Golub & van Loan's Matrix Computations.
- New SIMD intrinsics need a
test/packetmath.cppentry (orcontrib/test/special_packetmath.cppfor special functions), and a specialization in every architecture backend that supports the type.Eigen/src/Core/arch/Default/holds generic SIMD implementations shared across backends; scalar fallbacks live inEigen/src/Core/GenericPacketMath.handEigen/src/Core/MathFunctions.h. - Benchmarking discipline. Benchmarks on a loaded system are meaningless. Before running one: check
uptimeshows a low load average, finish or 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.
A few rules trip up contributors more often than the rest. The full list is in
AGENTS.md, which also links to the task guides. In short:
- Include only the umbrella headers. User code, examples, and tests of public behavior include the umbrella headers (
Eigen/Core,Eigen/Dense,Eigen/SVD, …), never files underEigen/src/...orcontrib/Eigen/src/.... Most of those files includeInternalHeaderCheck.h, which raises a compile error when one is included without its module's umbrella header; the paths are private even where that guard is absent. - C++14 baseline. Supported headers must compile as C++14: no
if constexpr(useEIGEN_IF_CONSTEXPR), structured bindings, fold expressions, or class template argument deduction. The exception is backend code that is compiled only behind a preprocessor guard and documents that it needs a newer standard. See.agents/conventions.md. - Preserve
EIGEN_DEVICE_FUNCon coefficient-level methods. Dropping it silently breaks CUDA / HIP / SYCL builds and rarely shows up in local testing. - Format with
clang-format-17exactly — Google style, 120 columns, configured in.clang-format. Other versions ofclang-formatproduce different output. CI checks only the lines a merge request changes (git clang-format --diff --commit <base>), because older code in the tree is not all clang-format-17 clean. The check is advisory: a failure shows as a warning on thecheckformat:lintjob instead of blocking the pipeline. Fix it anyway before asking for review. To format your changed lines, first check that the files contain no unrelated edits, then rungit clang-format --binary clang-format-17 --force <base-sha> -- <files>;--forceallows files with unstaged edits. Format new, untracked files withclang-format-17 -i <files>, because Git's diff omits them..agents/ci.mddescribes the checks.scripts/format.shreformats the whole tree; run it only when that is the intent. - Don't apply general C++ "modernize" cleanups. No
modernize-*/cppcoreguidelines-*clang-tidy fixes, no replacingEIGEN_STRONG_INLINEwithinline, no reordering includes (.clang-formathasSortIncludes: false)..clang-formatlists Eigen's macros underStatementMacrosandAttributeMacros, so the layout it produces around them is intended — don't "fix" it. - Tests use
test/main.h, not gtest (for now; see the migration note above).VERIFY_*assertions,CALL_SUBTEST_N/EIGEN_TEST_PART_Nfor splitting,EIGEN_DECLARE_TEST(<name>) { ... }as the entry point. autotraps.auto x = A + B;captures a lazy expression holding references that can dangle. Use.eval()or an explicit type. Similarly,.noalias()is a promise from the caller — only use it when the destination doesn't appear on the right side (somat.noalias() = mat * matis wrong).- Stage commits explicitly. Don't
git add -A/git add .— the repo root accumulates.vscode/,.idea/,build*/, and other untracked files that must not enter commits. Add by path or with targeted globs.
Naming conventions:
- Classes: PascalCase (
Matrix,BDCSVD). - Methods: camelCase (
coeffRef,applyOnTheLeft). - Macros:
EIGEN_UPPER_CASE(EIGEN_DEVICE_FUNC,EIGEN_STRONG_INLINE). - Compile-time constants:
static constexprmembers, notenumblocks.kCamelCaseis accepted alongside the oldersnake_caseandSCREAMING_CASEspellings. - Internal implementation lives in the
Eigen::internalnamespace; public API stays inEigen::or module namespaces. - Use
eigen_assert(cond)for runtime preconditions (not rawassert) andeigen_internal_assertfor internal invariants, which are checked only whenEIGEN_INTERNAL_DEBUGGINGis defined. Check compile-time API preconditions with the appropriateEIGEN_STATIC_ASSERT_*helper orEIGEN_STATIC_ASSERT(cond, MSG_TOKEN), so thatEIGEN_NO_STATIC_ASSERTand a user-providedEIGEN_STATIC_ASSERTstill take effect. Usestatic_assert(cond, "message")for implementation invariants that must always be checked.
Recent additions such as contrib/Eigen/src/GPU/DeviceMatrix.h show the usual layout of a class and its header:
- A template parameter that the class also exposes as a public alias gets a trailing underscore:
template <typename Scalar_, ...>withusing Scalar = Scalar_;. Preferusingtotypedefin new code. - Member variables use an
m_prefix (m_matrix,m_isInitialized). - Implementation headers under
Eigen/src/...carry// IWYU pragma: privateand#include "./InternalHeaderCheck.h", and their header guards followEIGEN_<NAME>_H. - Implementation details go in the nested namespace,
namespace Eigen { namespace internal { ... } }. - Public classes carry Doxygen blocks (
\class,\brief,\tparam,\sa) and link to runnable snippets fromdoc/snippets/with\include/\verbinclude.
When in doubt, copy the style from a recent neighboring file rather than inventing a new convention.
Every new source file must carry an inline copyright + license header. Without one, the reuse lint check in the checkformat:lint CI job fails the pipeline. Two header styles are in active use; pick whichever fits.
Attributed collectively (the most common form in the tree; use it for files written by multiple contributors, or where individual attribution isn't useful):
// SPDX-FileCopyrightText: The Eigen Authors
// SPDX-License-Identifier: MPL-2.0Attributed to an individual contributor:
// 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.0Use the file's own comment syntax (# in CMake and shell). Markdown docs, generated files (*.in), and binary assets that can't carry inline headers are listed by path in REUSE.toml — add yours there if you create one.
This is non-negotiable.
- Eigen code must be original, or derived from publicly published MPL-2.0-compatible material.
- Do not copy — verbatim, paraphrased, or "translated" to another syntax — from incompatibly-licensed sources (proprietary, under NDA, internal to a previous employer, GPL/AGPL). A close paraphrase or a line-by-line translation can still infringe copyright, even when no line matches. The same applies to 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, and credit it.
- Do not look inside proprietary software. Proprietary libraries (Intel oneMKL, NVIDIA's cuBLAS, Arm Performance Libraries, Apple Accelerate, vendor binaries in general) are black boxes: use their documented interface and measure them as shipped. Copyright leaves ideas free, but looking inside can breach the license, and using what was learned can support a trade-secret claim, so code that uses an idea obtained that way is unacceptable even when nothing is copied. See
.agents/provenance.md. - Cite published references inline when they inform an implementation: LAPACK and the LAPACK Working Notes, ACM TOMS / SIAM papers, Higham, Golub & van Loan, textbook algorithms, Boost components, vendor application notes — by name (author, year, identifier). A comment or Doxygen
\noteblock is enough. - When copying permissively-licensed code into an MPL-2.0 file, follow Mozilla's Guidelines for Developers.
Show where a change comes from. We encourage you to link, in the merge request description, the publicly available sources that support your code: the instruction-set or architecture manual, the vendor's optimization guide or intrinsics reference, the paper or standard an algorithm follows, the documented API a backend relies on. Original research is just as welcome — your own microbenchmarks of the hardware, measurements of other libraries through their public interfaces, numerical experiments, new algorithms and derivations — provided you have the right to contribute it; include its evidence (the reproducer, the method and results, the derivation) instead of a link. This helps most with hardware-specific optimizations and new features, where it lets a reviewer check the change against its sources and see that everything it relies on is public or published with it.
- No copyright assignment. Everyone keeps copyright on their own contributions. There is no contributor license agreement (CLA).
- Commit under your own identity. Make sure
user.nameanduser.emailin your git config are set to credit you correctly. - When contributing on behalf of your employer, commit in your own name where possible rather than your employer's.
- For substantial improvements to a source file, feel free to add yourself to its copyright line — but it isn't required; you get copyright implicitly on the code you wrote. The collective
The Eigen Authorsattribution is fine when individual credit isn't useful.
Format: Area: Short imperative subject, with both the area and the subject capitalized.
Examples (from recent history):
Core: Bring the vectorized cbrt within 1 ULPSparseCore: Fix expressions on a sparse matrix diagonal under MSVCTests: Split numext into parts to bound its compile memoryCMake: Remove discontinued ComputeCpp support
Keep the subject under ~72 characters; use the body for the why, not the what — the diff already shows what changed. Reference issues by #<n> when relevant.
Eigen aims to be state of the art in two respects — performance and numerical accuracy / IEEE-754 conformance — which are separate goals and sometimes conflict.
- Performance. Eigen Core is mostly optimized for single-core throughput, through SIMD code for each architecture (the packet backends) and cache-aware blocking. Multithreading in Core is opt-in (OpenMP or
EIGEN_GEMM_THREADPOOL) and covers a subset of operations. The Tensor module is designed for multithreading throughThreadPoolDevice. - Numerical accuracy. Decompositions and solvers should match LAPACK in backward stability, pivoting strategy, and handling of ill-conditioned inputs. Don't trade their numerical robustness for speed without a maintainer's explicit agreement. Standard math functions on scalars should match the C++ standard library. For vectorized math functions on regular inputs, a few ULPs of error is the long-standing price of SIMD speed; larger deviations need explicit justification.
- IEEE-754 / special values. For special values (NaN, ±0, ±∞, subnormals, singularities, branch boundaries — e.g.
log(0),pow(0, 0)) the requirement is exact conformance to the IEEE 754, ISO C, and C++ specifications, as documented on cppreference. The few-ULPs allowance does not apply to special values.
Some contrib/ modules matter more than the directory name suggests:
contrib/Eigen/TensorandEigen/ThreadPooltogether form TensorFlow's core compute backend. Thecontrib/location means looser API-stability guarantees — it does not mean rarely used or unimportant. Breaking changes to header layout, signatures, semantics, or the performance of the contraction and reduction kernels affect every TensorFlow build. Prefer additive changes, keep header paths stable, run thecontrib/test/tensor_*tests before submitting, and call out any behavior change prominently in the MR description.
- Discord is the primary chat channel (link above). Most informal design discussion happens there.
- GitLab issues are the place for bug reports, feature requests, and threaded design discussions tied to a specific topic.
- For larger contributions, discuss the plan first to avoid duplicated effort and to agree on the API before implementing it.
AGENTS.md— guidance for AI coding agents: the repository-wide rules, the standard workflow, essential Eigen hazards, and links to the task guides.- Task guides: coding conventions, testing, numerical code, sparse, benchmarking, provenance, SIMD/GPU, Tensor/ThreadPool, documentation, formatting/CI, merge request descriptions, and answering review comments.
README.md— high-level project description and pointers to the websites.CHANGELOG.md— release-by-release notes.- API reference (weekly): https://libeigen.gitlab.io/eigen/docs-weekly.
Thank you for contributing to Eigen!