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.
AGENTS.md take precedence)You don't have to write C++ to help.
decision needed. Issues labeled contributions welcome are good places to start.doc/; see .agents/docs.md. The project site has its own repository, https://gitlab.com/libeigen/libeigen.gitlab.io.libeigen/eigen as an upstream remote (use the https:// 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
master for your change:git fetch upstream git checkout -b my-topic upstream/master
clang-format-17 (see Coding standards).Area: Short imperative subject message (see Commit messages). Stage files by path — don't use git add -A.libeigen/eigen master.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=error
Other 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).
benchmarks/ or contrib/benchmarks/. Don't defer benchmarks to a follow-up MR.test/packetmath.cpp entry (or contrib/test/special_packetmath.cpp for 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 in Eigen/src/Core/GenericPacketMath.h and Eigen/src/Core/MathFunctions.h.uptime shows 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:
Eigen/Core, Eigen/Dense, Eigen/SVD, …), never files under Eigen/src/... or contrib/Eigen/src/.... Most of those files include InternalHeaderCheck.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.if constexpr (use EIGEN_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.EIGEN_DEVICE_FUNC on coefficient-level methods. Dropping it silently breaks CUDA / HIP / SYCL builds and rarely shows up in local testing.clang-format-17 exactly — Google style, 120 columns, configured in .clang-format. Other versions of clang-format produce 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 the checkformat:lint job 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 run git clang-format --binary clang-format-17 --force <base-sha> -- <files>; --force allows files with unstaged edits. Format new, untracked files with clang-format-17 -i <files>, because Git's diff omits them. .agents/ci.md describes the checks. scripts/format.sh reformats the whole tree; run it only when that is the intent.modernize-* / cppcoreguidelines-* clang-tidy fixes, no replacing EIGEN_STRONG_INLINE with inline, no reordering includes (.clang-format has SortIncludes: false). .clang-format lists Eigen‘s macros under StatementMacros and AttributeMacros, so the layout it produces around them is intended — don’t “fix” it.test/main.h, not gtest (for now; see the migration note above). VERIFY_* assertions, CALL_SUBTEST_N / EIGEN_TEST_PART_N for splitting, EIGEN_DECLARE_TEST(<name>) { ... } as the entry point.auto traps. 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 (so mat.noalias() = mat * mat is wrong).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:
Matrix, BDCSVD).coeffRef, applyOnTheLeft).EIGEN_UPPER_CASE (EIGEN_DEVICE_FUNC, EIGEN_STRONG_INLINE).static constexpr members, not enum blocks. kCamelCase is accepted alongside the older snake_case and SCREAMING_CASE spellings.Eigen::internal namespace; public API stays in Eigen:: or module namespaces.eigen_assert(cond) for runtime preconditions (not raw assert) and eigen_internal_assert for internal invariants, which are checked only when EIGEN_INTERNAL_DEBUGGING is defined. Check compile-time API preconditions with the appropriate EIGEN_STATIC_ASSERT_* helper or EIGEN_STATIC_ASSERT(cond, MSG_TOKEN), so that EIGEN_NO_STATIC_ASSERT and a user-provided EIGEN_STATIC_ASSERT still take effect. Use static_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:
template <typename Scalar_, ...> with using Scalar = Scalar_;. Prefer using to typedef in new code.m_ prefix (m_matrix, m_isInitialized).Eigen/src/... carry // IWYU pragma: private and #include "./InternalHeaderCheck.h", and their header guards follow EIGEN_<NAME>_H.namespace Eigen { namespace internal { ... } }.\class, \brief, \tparam, \sa) and link to runnable snippets from doc/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.0
Attributed 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.0
Use 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.
.agents/provenance.md.\note block is enough.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.
user.name and user.email in your git config are set to credit you correctly.The Eigen Authors attribution 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 supportKeep 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.
EIGEN_GEMM_THREADPOOL) and covers a subset of operations. The Tensor module is designed for multithreading through ThreadPoolDevice.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/Tensor and Eigen/ThreadPool together form TensorFlow's core compute backend. The contrib/ 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 the contrib/test/tensor_* tests before submitting, and call out any behavior change prominently in the MR description.AGENTS.md — guidance for AI coding agents: the repository-wide rules, the standard workflow, essential Eigen hazards, and links to the task guides.README.md — high-level project description and pointers to the websites.CHANGELOG.md — release-by-release notes.Thank you for contributing to Eigen!