| # CodeRabbit configuration for Eigen. |
| # Schema: https://docs.coderabbit.ai/reference/configuration |
| # |
| # Eigen is a header-only C++14 template library, GitLab-hosted, with a strict |
| # ABI policy and several major downstream consumers (notably TensorFlow). The |
| # settings below favor signal over volume: chill profile, minimal noise on |
| # auto-generated docs and vendored Fortran, and explicit guidance for the |
| # template-heavy core. |
| |
| language: en-US |
| |
| # CodeRabbit caps tone_instructions at 250 chars. Keep the essential |
| # focus areas here; the full reviewer guidance (provenance discipline, |
| # numerical-tolerance policy, GPU caveats, etc.) lives in AGENTS.md |
| # and is loaded via knowledge_base.code_guidelines.filePatterns below. |
| tone_instructions: >- |
| Eigen, header-only C++14. Focus: correctness, numerical accuracy |
| (LAPACK-level; flag regressions), ABI, performance, template pitfalls, |
| missing tests, uncited published algorithms (LAPACK, LAWN, Higham, |
| Golub & van Loan). Skip style nits and C++17+. |
| |
| early_access: false |
| enable_free_tier: true |
| |
| # Pull repo-level reviewer guidance from AGENTS.md (the agent-facing |
| # condensation of CONTRIBUTING + wiki). Set explicitly because the |
| # default filePatterns list may be inactive when no patterns are |
| # specified by the user. |
| knowledge_base: |
| code_guidelines: |
| enabled: true |
| filePatterns: |
| - "AGENTS.md" |
| |
| reviews: |
| profile: chill |
| request_changes_workflow: false |
| # Trim down the noise in the auto-posted comment: drop sections that don't |
| # carry weight on a numerics-heavy template library. Keep the walkthrough |
| # (file-by-file summary) but skip the high-level summary, the changed-files |
| # overview, and don't collapse the walkthrough so reviewers see it expanded. |
| high_level_summary: false |
| high_level_summary_in_walkthrough: false |
| poem: false |
| review_status: true |
| collapse_walkthrough: false |
| changed_files_summary: false |
| enable_prompt_for_ai_agents: true |
| sequence_diagrams: false |
| estimate_code_review_effort: false |
| assess_linked_issues: false |
| related_issues: false |
| related_prs: false |
| suggested_labels: false |
| suggested_reviewers: false |
| in_progress_fortune: false |
| |
| pre_merge_checks: |
| # Eigen is a header-only template library where docstring coverage |
| # has limited value; the docstrings precheck adds noise without signal. |
| docstrings: |
| mode: off |
| |
| auto_review: |
| enabled: true |
| drafts: false |
| # Eigen MRs often see many WIP pushes; reviewing every push burns the |
| # per-developer hourly rate limit on the free/OSS tier. Review the first |
| # diff only; further reviews can be requested with `@coderabbitai review`. |
| auto_incremental_review: false |
| base_branches: |
| - master |
| |
| path_filters: |
| - "!doc/snippets/**" |
| - "!doc/examples/**" |
| - "!lapack/*.f" |
| - "!blas/testing/**" |
| - "!**/*.png" |
| - "!**/*.bin" |
| - "!**/*.svg" |
| - "!**/*.pdf" |
| |
| path_instructions: |
| - path: "**" |
| instructions: | |
| Repo-wide conventions (apply across all paths): |
| - **SPDX / REUSE.** Every new source file (`.h`, `.cpp`, `.cu`, |
| `.inc`, `.cmake`, `CMakeLists.txt`, etc.) must carry the |
| standard Eigen MPL-2.0 SPDX + copyright header inline. The |
| `checkformat:reuse` CI job (`reuse lint`) blocks otherwise. |
| Files that can't carry inline headers (top-level docs, |
| generated/templated files, binary assets) are covered by |
| path-based annotations in `REUSE.toml` — add the path there |
| if creating one. |
| - **GitLab is upstream**; the GitHub mirror is read-only. Do |
| not suggest opening PRs / pushing to GitHub. |
| - **Commit messages** follow `Category: Short description` |
| (e.g. `GPU: Fix special-function test coverage`). |
| - path: "Eigen/src/**" |
| instructions: | |
| Eigen is a header-only C++14 template library with a strict ABI policy. |
| - **Numerical accuracy is a top priority.** Eigen targets accuracy |
| comparable to established numerical libraries such as LAPACK. Flag |
| any change that may degrade accuracy, condition handling, stability |
| under near-singular / ill-conditioned inputs, or behavior near |
| subnormals, infinities, NaNs, or extreme exponents. In general, |
| do not trade accuracy for speed. |
| - **Acceptable accuracy tradeoff on regular inputs only.** A faster |
| algorithm whose worst-case error on regular inputs is bounded to |
| a few ULPs by a principled analysis may be acceptable. Surface |
| the tradeoff and the bound clearly so a human reviewer can judge; |
| do not auto-approve or auto-reject these. **Special-value handling |
| is not subject to the few-ULP tradeoff** — IEEE-754 entities (NaN, |
| ±0, ±∞, subnormals) and standard-library edge cases (e.g. `log(0)`, |
| `pow(0, 0)`) must match the cppreference / IEEE 754 spec exactly. |
| - **Numerical changes require numerical tests.** Any new numerical |
| algorithm, kernel, or accuracy-sensitive change MUST come with |
| tests that exercise its accuracy claims: random ill-conditioned |
| inputs across a range of condition numbers, edge values, and |
| matrices structured for the algorithm (Hilbert, Vandermonde, |
| Pascal, Wilkinson's W, Frank, Lehmer, KMS / Toeplitz, banded, |
| rank-deficient, defective / near-defective Jordan blocks, |
| positive-definite-but-barely — MATLAB's `gallery()` is the |
| standard catalog; Higham's *Accuracy and Stability of Numerical |
| Algorithms* / *Functions of Matrices* and Golub & van Loan are |
| the references). For routines with a |
| LAPACK counterpart, match LAPACK's TESTING/ category coverage as |
| the bar. Quantify accuracy in ULPs against a scalar reference, |
| not just relative error. Sollya / MPFR are the standard tools |
| for ground-truth and polynomial generation; prefer in-C++ MPFR |
| verification over a Python reference. If such tests are missing, |
| request them. |
| - **Performance-sensitive changes ship with a benchmark** under |
| `benchmarks/` or `unsupported/benchmarks/`. Don't defer to a |
| follow-up MR. |
| - **Preserve `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 — flag any removal or omission on new methods. |
| - **Header-only contract.** Never include from `Eigen/src/...` (or |
| `unsupported/Eigen/src/...`) directly; reach implementation via |
| the umbrella module headers (`Eigen/Core`, `Eigen/Dense`, …). |
| `InternalHeaderCheck.h` makes direct internal includes a hard |
| error. Old internal headers do not get backward-compatibility |
| forwarding shims when moved/renamed; only the public umbrella |
| headers do. |
| - **Aliasing in fast paths.** Aliasing safety is not a uniform |
| invariant. The standard product path inserts an auto-temporary |
| so `mat = mat * mat` is safe, but optimized fast paths that |
| bypass the general assignment machinery have historically |
| introduced aliasing bugs. When a change modifies or adds such a |
| fast path, check whether LHS/RHS aliasing is handled and prefer |
| falling back to the general path when in doubt. |
| - Treat the public API surface as frozen: do not propose renames or |
| signature changes for non-internal types. |
| - Performance and inlining matter; flag possible regressions in hot |
| paths (products, packet kernels, evaluators, decompositions). |
| - Watch for accidental allocations in templates that should be |
| allocation-free. |
| - C++14 is the minimum; do not suggest C++17+ features. (A migration |
| to C++17 is planned on a separate branch; until it lands on master, |
| new code must compile under C++14.) |
| - **Skip "modernize" advice.** Do not propose `modernize-*` or |
| `cppcoreguidelines-*` clang-tidy fixes; do not suggest replacing |
| `EIGEN_STRONG_INLINE` with `inline`; do not propose reordering |
| internal includes (`SortIncludes: false` is intentional); and do |
| not "fix" Eigen's macro indentation (`.clang-format` registers |
| Eigen macros as `StatementMacros` / `AttributeMacros`). |
| Style is `clang-format-17` exactly — the CI diff is authoritative. |
| - **Assertions.** Prefer `eigen_assert` (and |
| `eigen_internal_assert` for internal-only invariants) over raw |
| `assert` for runtime preconditions; prefer `EIGEN_STATIC_ASSERT` |
| over plain `static_assert` for compile-time conditions. |
| - path: "Eigen/src/Core/arch/**" |
| instructions: | |
| Per-architecture packet math (SIMD vectorization) backends. In |
| addition to the general `Eigen/src/**` rules: |
| - **Guard intrinsics by ISA macro.** Each intrinsic must be wrapped |
| in its own `EIGEN_VECTORIZE_*` `#ifdef` — being inside `arch/AVX/` |
| does not imply AVX2 / FMA / AVX-512 are available. Wrap AVX2 in |
| `EIGEN_VECTORIZE_AVX2`, FMA in `EIGEN_VECTORIZE_FMA`, AVX-512DQ |
| in `EIGEN_VECTORIZE_AVX512DQ`, etc., and provide a fallback for |
| the un-guarded path. Same discipline applies on NEON |
| (`EIGEN_VECTORIZE_NEON_FP16`), VSX (`EIGEN_VECTORIZE_VSX`), etc. |
| Missing guards typically compile fine on the developer's machine |
| and break CI on narrower ISA targets — flag any unguarded |
| intrinsic. |
| - **Backend symmetry.** New packet operations should be specialized |
| across **every** backend that supports the type, with |
| `arch/Default/` providing scalar fallbacks. A missing or divergent |
| backend specialization usually shows up first in |
| `test/packetmath.cpp` or `unsupported/test/special_packetmath.cpp` |
| — flag PRs that add a packet op in one backend without the others. |
| - path: "{Eigen/ThreadPool,Eigen/src/ThreadPool/**}" |
| instructions: | |
| Eigen's work-stealing thread pool — umbrella header `Eigen/ThreadPool` |
| with sources under `Eigen/src/ThreadPool/` (`NonBlockingThreadPool`, |
| `RunQueue`, `EventCount`, `ForkJoin`, `CoreThreadPoolDevice`). Backs |
| `EIGEN_GEMM_THREADPOOL` and the Tensor module's `ThreadPoolDevice`. |
| Originally developed for TensorFlow and still depended on there — |
| signatures, semantics, and performance are load-bearing. Apply the |
| same caution as the Tensor module: prefer additive changes, keep |
| header layout stable, and call out behavior changes prominently. |
| - path: "test/**" |
| instructions: | |
| Tests use Eigen's custom framework defined in `test/main.h`: |
| `VERIFY_*` assertions, `CALL_SUBTEST_N` / `EIGEN_TEST_PART_N` to |
| split one `.cpp` into N per-shard executables, and |
| `EIGEN_DECLARE_TEST(<name>) { ... }` as the entry point. |
| `EIGEN_REPEAT` / `EIGEN_SEED` are runtime env vars, not the shard |
| mechanism. Do not suggest restructuring the harness, switching to |
| gtest assertions, or deduplicating shards. Numerical-tolerance |
| comparisons (`VERIFY_IS_APPROX`) are deliberate; do not push for |
| exact equality. Tests may be long and procedural. |
| **In-flight migration to Google Test:** |
| [MR 2159](https://gitlab.com/libeigen/eigen/-/merge_requests/2159) |
| replaces `EIGEN_DECLARE_TEST` / `CALL_SUBTEST_N` with gtest |
| `TEST` / `TYPED_TEST` while bridging `VERIFY_*` to gtest |
| expectations; once it lands, the "do not switch to gtest" rule |
| flips for new tests. |
| - path: "unsupported/Eigen/**" |
| instructions: | |
| "Unsupported" here means looser API-stability guarantees, **not** |
| low-traffic or low-stakes. The Tensor module |
| (`unsupported/Eigen/Tensor`, sources under |
| `unsupported/Eigen/src/Tensor/`) is TensorFlow's core compute |
| backend; treat its signatures, header layout, semantics, and |
| performance on contraction / reduction / morphing kernels as |
| load-bearing. Prefer additive changes, keep header paths stable, |
| and call out behavior changes prominently. Other modules |
| (`TensorSymmetry`, `AutoDiff`, `Polynomials`, `MatrixFunctions`, |
| `NNLS`, `FFT`, `GPU`, `Splines`, `NumericalDiff`, |
| `IterativeSolvers`) are genuinely more permissive but should still |
| preserve their public API. `unsupported/Eigen/CXX11/` is backward- |
| compatibility forwarding shims only — do not place new headers |
| there. |
| - path: "unsupported/Eigen/src/GPU/**" |
| instructions: | |
| Host-side dispatch to NVIDIA libraries (cuBLAS / cuSOLVER / cuFFT / |
| cuSPARSE / cuDSS) on device-resident operands (`gpu::DeviceMatrix`). |
| This is **not** an expression-template layer — every supported |
| expression maps to a single library call, and `DeviceMatrix` does |
| not inherit from `MatrixBase`. Do not suggest reshaping it into an |
| expression-template system. Tests are deliberately compiled as |
| `.cpp` (not `.cu`) so NVCC does not instantiate Eigen CPU packet |
| ops for CUDA vector types — do not propose moving them to `.cu`. |
| - path: "blas/**" |
| instructions: | |
| These are Reference BLAS API wrappers around Eigen. Match the BLAS |
| standard exactly; do not suggest deviating from netlib semantics. |
| - path: "lapack/**" |
| instructions: | |
| The .f sources are vendored netlib LAPACK reference; do not review |
| them. The C++ wrappers should faithfully implement the LAPACK |
| contract. |
| - path: "ci/**" |
| instructions: | |
| GitLab CI configuration. Be conservative -- do not suggest |
| restructuring the existing job graph or changing runner tags without |
| strong reason. |
| - path: "benchmarks/**" |
| instructions: | |
| Microbenchmarks built against Google Benchmark. Clarity matters less |
| than realistic measurement; flag only correctness or measurement |
| methodology issues, not style. |
| |
| chat: |
| auto_reply: true |
